Difference between revisions of "HelpWML"

From The Battle for Wesnoth Wiki
m (the toplevel [help] tag)
m (Help System Topic Markup)
Line 19: Line 19:
 
== Help System Topic Markup ==
 
== Help System Topic Markup ==
  
The markup that is allowed in the text key within a topic tag is in XML, a markup language similar to WML.
+
The markup that is allowed in the text key within a topic tag is in XML, a markup language similar to WML. Note that this is the only time that markup language is used as a value. To convert WML into XML, you need to make some changes:
Note that this is the only time that markup language is used as a value.
 
To convert WML into XML, you need to make some changes:
 
  
- change brackets ('''[||, ||]||) into angle brackets(||<||, ||>''')
+
- change brackets ('''[''', ''']''') into angle brackets('''<''', '''>''')
  
 
- change ''newline'' into space(''' ''')
 
- change ''newline'' into space(''' ''')
  
- all values with spaces must be in quotes. This is because spaces are actually newlines
+
- all values with spaces must be in quotes. This is because spaces are actually newlines.
  
 
Due to limitations of the wiki (it is coded using XML), the WML for the topic markup will be described rather than
 
Due to limitations of the wiki (it is coded using XML), the WML for the topic markup will be described rather than
the XML.
+
the XML. However, you still need to use XML to code the topic.
However, you still need to use XML to code the topic.
 
  
 
The following key/tags are accepted for ''text'':
 
The following key/tags are accepted for ''text'':
* '''[ref]''' create a cross reference to another topic, a cross reference will not show up if the topic it refers to not
+
* '''[ref]''' creates a cross reference to another topic, a cross reference will not show up if the topic it refers to is not visible.
is visible.
 
 
** ''dst'' the ID of the topic to reference.
 
** ''dst'' the ID of the topic to reference.
** ''text'' the text to display as a link to ''dst//;i.e. when ''text'' is clicked on the page ''dst'' will be linked to.
+
** ''text'' the text to display as a link to ''dst''; i.e. when ''text'' is clicked on the page ''dst'' will be linked to.
** ''force'' show the cross reference even though the referred topic is not shown.
+
** ''force'' shows the cross reference even though the referred topic is not shown.
* '''[jump]''' when this text is selected, the input position along the X axis is moved.
+
* '''[jump]''' when this text is selected, the input position along the X axis is moved. Can be used for example to create columns of things. A jump is ignored if it would bring the input position to an invalid position.
Can be used for example to create columns of things.
+
** ''to'' the X coordinate of the text area to jump to. If it can't be done on the current row, the input position is moved down one line.
A jump is ignored if it would bring the input position to an invalid position.
 
** ''to'' the X coordinate of the text area to jump to.
 
If it can't be done on the current row, the input position is moved down one line.
 
 
** ''amount'' the number of pixels to jump forward
 
** ''amount'' the number of pixels to jump forward
 
* '''[img]''' insert an image in the topic
 
* '''[img]''' insert an image in the topic
 
** ''src'' the path to the image relative to the '''images/''' directory.
 
** ''src'' the path to the image relative to the '''images/''' directory.
** ''align'' the position of the image with respect to the page. Values are 'left', 'middle', and 'right'.
+
** ''align'' the position of the image with respect to the page. Values are ''here'', ''left'', ''middle'', and ''right''.
** ''float'' whether the image should float(have text filled in around it) or not(be seen as included in a line).
+
** ''float'' whether the image should float(have text filled in around it) or not (be seen as included in a line).
* '''[format]''' describes a group of text in a different format.
+
* '''[format]''' describes a group of text in a different format. Can be used to describe different colors and font sizes.
Can be used to describe different colors and font sizes
+
** ''bold'' whether the text should be displayed in bold('''bold''').
** ''bold'' whether the text should be displayed in bold('''bold''')
+
** ''italic'' whether the text should be displayed in italics(''italics'').
** ''italic'' whether the text should be displayed in italics(//italics'')
+
** ''color'' the color of the text. Only a few colors are currently supported: ''white''(default), ''green'', ''red'', ''yellow'', and ''black''.
** ''color'' the color of the text.
 
Only a few colors are currently supported: 'white'(default), 'green', 'red', 'yellow', and 'black'.
 
 
** ''font_size'' the height of the text in pixels. Default 9(?)
 
** ''font_size'' the height of the text in pixels. Default 9(?)
** ''text'' the text to be displayed using this format
+
** ''text'' the text to be displayed using this format.
* '''[italic]|| a shortcut to ||[format]''' which inputs only the ''text'' key.
+
* '''[italic]''' a shortcut to '''[format]''' which inputs only the ''text'' key. Uses the attribute '''italic=yes'''
Uses the attribute '''italic=yes'''
+
* '''[bold]''' like [italic], but uses '''bold=yes'''
* '''[bold]|| like [italic], but uses ||bold=yes'''
+
* '''[header]''' like [italic], but uses both the attributes '''bold=yes''' and '''font_size=13'''(?)
* '''[header]|| like [italic], but uses both the attributes ||bold=yes|| and ||font_size=13(?)'''
 
  
 
Example:
 
Example:

Revision as of 16:47, 11 November 2005

the toplevel [help] tag

The [help] tag describes the Wesnoth help system. Each of the three subtags [toplevel], [section] and [topic] describe an element of the help system.

  • [toplevel] The toplevel tag denotes sections and topics that should be shown immediately when the "Help" button is clicked on (see the "help" action, ThemeWML). The sections referenced within this tag are read recursively, including all subsections.
    • sections a list of IDs of the sections to include recursively.
    • topics a list of IDs of the topics to show as not being included in a section; i.e. top-level topics.
  • [section] The section tag describes a section in the help browser. A section contains subsections and/or topics.
    • id is the unique ID for this section.
    • title (translatable) is the title of the section. It is displayed in the left menu.
    • sections is a list of IDs of the sections that should be this section's subsections.
    • topics is a list of IDs of the topics that should be included in this section.
  • [topic] The topic tag describes one topic, i.e, one help page. The keys that are meaningful in the topic tag:
    • id is the unique ID for this topic.
    • title (translatable) is the title of the topic. It is displayed in the left menu and as a header in the text area.
    • text (translatable) is the contents of the topics. May contain markup described below

Help System Topic Markup

The markup that is allowed in the text key within a topic tag is in XML, a markup language similar to WML. Note that this is the only time that markup language is used as a value. To convert WML into XML, you need to make some changes:

- change brackets ([, ]) into angle brackets(<, >)

- change newline into space( )

- all values with spaces must be in quotes. This is because spaces are actually newlines.

Due to limitations of the wiki (it is coded using XML), the WML for the topic markup will be described rather than the XML. However, you still need to use XML to code the topic.

The following key/tags are accepted for text:

  • [ref] creates a cross reference to another topic, a cross reference will not show up if the topic it refers to is not visible.
    • dst the ID of the topic to reference.
    • text the text to display as a link to dst; i.e. when text is clicked on the page dst will be linked to.
    • force shows the cross reference even though the referred topic is not shown.
  • [jump] when this text is selected, the input position along the X axis is moved. Can be used for example to create columns of things. A jump is ignored if it would bring the input position to an invalid position.
    • to the X coordinate of the text area to jump to. If it can't be done on the current row, the input position is moved down one line.
    • amount the number of pixels to jump forward
  • [img] insert an image in the topic
    • src the path to the image relative to the images/ directory.
    • align the position of the image with respect to the page. Values are here, left, middle, and right.
    • float whether the image should float(have text filled in around it) or not (be seen as included in a line).
  • [format] describes a group of text in a different format. Can be used to describe different colors and font sizes.
    • bold whether the text should be displayed in bold(bold).
    • italic whether the text should be displayed in italics(italics).
    • color the color of the text. Only a few colors are currently supported: white(default), green, red, yellow, and black.
    • font_size the height of the text in pixels. Default 9(?)
    • text the text to be displayed using this format.
  • [italic] a shortcut to [format] which inputs only the text key. Uses the attribute italic=yes
  • [bold] like [italic], but uses bold=yes
  • [header] like [italic], but uses both the attributes bold=yes and font_size=13(?)

Example:

[help]
[toplevel]
sections=introduction,gameplay
topics=about
[/toplevel]
[section]
id=gameplay
sections=combat
topics=income_and_upkeep,time_of_day,terrain
[/section]
[topic]
id=terrain
title=Terrain
text="[1]"
[/topic]
[/help]

See Also

  • dst=income_and_upkeep text='Link to Income and Upkeep topic'