Difference between revisions of "Wiki grabber"

From The Battle for Wesnoth Wiki
(Remove deprecated tables)
(Brush)
Line 184: Line 184:
 
(Note the 1.5 version and the mandatory image are for testing only.)
 
(Note the 1.5 version and the mandatory image are for testing only.)
  
* '''''name''''' (string, default ''""'') Name for the brush (will possibly show up in the tooltip for the brush).{{DevFeature1.5}}
+
* '''''name''''' (string, default ''""'') Name for the brush (will possibly show up in the tooltip for the brush).
 
* '''''image''''' (filename, '''mandatory''') Icon for the brush to de displayed on the toolbar.  
 
* '''''image''''' (filename, '''mandatory''') Icon for the brush to de displayed on the toolbar.  
 
* '''''radius''''' (integer, default ''0'') Include in the brushall hexes that are this or closer to the center of the brush, excluding the (0,0) point.
 
* '''''radius''''' (integer, default ''0'') Include in the brushall hexes that are this or closer to the center of the brush, excluding the (0,0) point.

Revision as of 14:10, 1 May 2012

Introduction

The wiki grabber is a work in progress tool located at 'utils/wiki_grabber.py'. This tool can be used to extract specially formatted comment sections from a .cpp or .hpp and convert it to wiki format. At the moment it mainly helps to get a table into wiki format.

The grabber is writting to make documenting the new GUI code easier so this is the only part of the source where this type of comment is used, this might change in the future.

Details

The tool will look for properly formatted comment section. Every section has a page name and order. When no order number a default is set. The tool will per page a list with sections, after all files are processed the data is stored, with a stable sort. After that for every page a text file with the wiki data is generated. Note if data for the same page is stored in different files it's highly recommended to add a sort value since there's no guarantee on the sorting order of files.

Processing

The processing happens in two steps:

  • find all macros
  • process the data, where the macros are replaced

Macro format

The macros are stored in specially formatted block which look like:

/*WIKI_MACRO
 * @start_macro = name
 * macro text
 * @end_macro
 */

One block can have multiple start_macro sections. All macro names should be unique, if not it's undefined which version will be used. Names can contain all letters and numbers and an underscore. Like with the normal comment format strings will be merged if they have more as 8 spaces. eg

/*WIKI_MACRO
 * @start_macro = all_new_lines
 * line 1
 * line 2
 * @end_macro
 *
 * @start_macro = one_line
 * line 1
 *       rest of line 1.
 * @end_macro
 *
 * @start_macro = one_line_looking_less_ugly_notice_the_empty_line
 *
 *       line 1
 *       rest of line 1.
 * @end_macro
 */

Comment format

The grabber will only extract information which is inside specially formatted comment blocks. The format is the following:

/*WIKI
 * header data
 * header data
 *
 * body data
 * body data
 * body data
 *            line to be merged.
 */
  • The space after the * is mandatory.
  • The whiteline between header and body is also mandatory.
  • If a line starts with at least 8 spaces it's joined with the previous line, mainly interesting for tables.

Header

The header has key value pairs the following keys are reconized

  • @page the name of the page, mandatory
  • @order the sorting order (optional default value 10000 (subject to change))

Body

The body text can have markup for the processor the rest of the text is put in the wiki as is. The following markup styles are defined:

  • @start_table and @end_table. The text between these tags is transformed into a wiki table. This format is deprecated and will be phased out.
  • @macro = name This text is replaced by the macro name, if the macro is not defined the text remains as-is.
  • @begin{type} and @end{type}. This is used to build several structured elements (at the moment only table is implemented.

Tables

This is the new way to define tables Tables start with

@start{table}{type}

type is the type of table, the following table types are recognized:

  • dialog_widgets, Contains the widgets used in a dialog (already in the new format except uses @start{table}[dialog_widgets] instead of @start{table}{dialog_widgets}
  • variable_types, Contains the variables types available to use, should be on the page GUIVariable. (Still in the old format)
  • config, Contains the data which can/should be used in the WML for a certain item. (Still in the old format)
  • formula, The variables available for certain formulas. (Still in the old format)
  • window_definition, The definition of a window and controls.

A table has one or more rows every column in separated by an ampersand every row is terminated by a dollar sign. Columns may not be omitted.

The table needs to end with

@end{table}

In the description column of a table a @* can be used to create a list. If there needs to be text after the list add a @- to indicate the end of the list.

dialog_widgets

Describes the widgets to be used in a dialog and contains the following columns:

  1. contains the optional id of the widget. In order to group widgets in a parent the id can be prefixed with a hyphen for the child items. (Most ids are mandatory, but some widgets can be defined by there return value.)
  2. The optional return value when the widget is clicked. (Mainly makes sense for buttons)
  3. The mandatory type of the widget. The string in this column is expected to be an anchor in GUIToolkitWML.
  4. The mandatory mandatory flag. This field contains a o for an optional field and a m for a mandatory one.
  5. The mandatory description. Explains what the task of the widget in the dialog is.

variable_type

Contains the variable types available and contains the following columns:

  1. The mandatory id of the type.
  2. The mandatory description of the type.

The output of the table can be seen here.

config

Contains the values for formula fields and contains the following columns:

  1. The mandatory id of the field.
  2. The mandatory type of the field. The string in this column is expected to be an anchor in GUIToolkitWML.
  3. The optional default value of the field. A string should be quoted here and an empty string thus only contains a pair of double quotes. A blank field indicates the config field is mandatory.
  4. The mandatory description of the field. Explains what the field is used for.

The output of the table can be seen here under keys:.

formula

Contains the variables in available for the formalas and contains the following columns:

  1. The mandatory id of the field.
  2. The mandatory type of the field. These types aren't linked to another table (yet).
  3. The mandatory description of the field.

The output of the table can be seen here under variable:.

widget_overview

Gives an overview of the available widgets and contains the following columns:

  1. The mandatory type of the widget.
  2. The mandatory description of the widget.

The output of the table can be seen here under List of available widgets:.

window_overview

Gives an overview of the available widgets and contains the following columns:

  1. The mandatory type of the window.
  2. The mandatory description of the window.

The output of the table can be seen here under List of available windows:.

Description lists

Description lists give an overview of tree based nodes.

Descriptions start with

@start{description}{type}

type is the type of table, the following table types are recognized:

  • wml_reference, Contains the information for the wml node trees

A description has one or more rows every column in separated by an ampersand every row is terminated by a dollar sign. Columns may not be omitted.

The table needs to end with

@end{description}

In the description column of a table a @* can be used to create a list. If there needs to be text after the list add a @- to indicate the end of the list.

wml_reference

  1. The mandatory key of the node or key. If the key is a node it should be between square brackets
  2. The mandatory type of the field. The string in this column is expected to be an anchor in some table later on.
if the field contains node it should be omitted.
  1. The optional default value of the field. A string should be quoted here and an empty string thus only contains a pair of double quotes. A blank field indicates the wml key is mandatory. When the field is a node the field is mandatory and should contain:
    • * zero or more times.
    • + one or more times.
    • ? zero or one times
    • 1 one time.
  2. The optional release series in which the was introduced.
  3. The mandatory description of the field. Explains what the field is used for.


test

THIS PAGE IS AUTOMATICALLY GENERATED, DO NOT MODIFY DIRECTLY !!!

Brush

Each brush tag defines one brush. (0,0) is the hotspot, that is, the brush is always moved so the mouse is over the brush's (0,0) coordinate. The following keys and tags are recognized:

(Note the 1.5 version and the mandatory image are for testing only.)

  • name (string, default "") Name for the brush (will possibly show up in the tooltip for the brush).
  • image (filename, mandatory) Icon for the brush to de displayed on the toolbar.
  • radius (integer, default 0) Include in the brushall hexes that are this or closer to the center of the brush, excluding the (0,0) point.
  • [relative] (zero or more times) Include in the brush a single hex with coordinates relative from the center of the brush.
    • x (int, default 0) The relative x coordinate.
    • y (int, default 0) The relative y coordinate.

A brush that has neither a radius nor any [relative] hexes will be empty which is not desired and a warning or error is to be expected.