Difference between revisions of "HelpWML"

From The Battle for Wesnoth Wiki
(The toplevel [help] tag)
(Help System Topic Markup: Add more anchors that can be linked to)
 
(8 intermediate revisions by 5 users not shown)
Line 5: Line 5:
 
Each of the three subtags [toplevel], [section] and [topic] describe an element of the 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.
+
* {{anchor|toplevel|'''[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.
+
** '''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.
+
** '''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.
+
* {{anchor|section|'''[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.
+
** '''id''': is the unique ID for this section.
** ''title'' (translatable) is the title of the section. It is displayed in the left menu.
+
** '''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.
+
** '''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. Topics will be included in the order listed unless sorting is requested.
+
** '''topics''': is a list of IDs of the topics that should be included in this section. Topics will be included in the order listed unless sorting is requested.
** ''generator'' provides the name of a function that will generate a list of topics and include them in this section. These topics will be included after topics listed on the ''topics'' key unless ''sort_topics'' is ''yes''.
+
** '''generator''': provides the name of a function that will generate a list of topics and include them in this section. These topics will be included after topics listed on the '''topics''' key unless ''sort_topics'' is ''yes''.
** ''sort_topics'' specifies whether or not to list the topics sorted by title or in the order listed on the ''topics'' key. ''yes'' indicates fixed and generated topics should be sorted together by title. (Note: for this to work the generator must sort topics by title.) ''no'' indicates that topics should appear in the order listed with fixed topics appearing before generated topics. ''generated'' indicates that fixed topics should not be sorted and will be followed by generated topics sorted by the generator. The default is ''generated''.
+
** '''sort_topics''': specifies whether or not to list the topics sorted by title or in the order listed on the '''topics''' key. '''yes''' indicates fixed and generated topics should be sorted together by title. '''no''' indicates that topics should appear in the order listed with fixed topics appearing before generated topics. '''generated''' indicates that fixed topics should not be sorted and will be followed by generated topics sorted by the generator. The default is '''generated'''.
* '''[topic]''' The topic tag describes one topic, i.e, one help page.  The keys that are meaningful in the topic tag:
+
* {{anchor|topic|'''[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.
+
** '''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.
+
** '''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.
+
** '''text''': (translatable) is the contents of the topics. May contain markup described below.
  
 
== 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.  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:
+
The markup that is allowed in the text key within a topic tag is in a WML-like markup language with angle brackets.
  
- change brackets ('''[''', ''']''') into angle brackets('''<''', '''>''')
+
It consists of plain text, interrupted with markup tags. Between paired start and end tags (like '''<jump> ... </jump>''') you can give keys and values like in WML, separated by spaces instead of newlines. For values containing spaces, surround them with single quotes. The "text content" of a tag, if any, is usually given by a ''text'' key. You can't nest tags within another tag.
  
- change ''newline'' into space(''' ''')
+
The following key/tags are accepted inside '''text''' ([https://github.com/wesnoth/wesnoth/blob/c09c58a8c8892d5f8392de48520a4f1b0ae1f35f/src/help/help_text_area.cpp#L126-L139 source]):
 
+
* {{anchor|ref|'''&lt;ref&gt;'''}}: creates a cross reference to another topic, a cross reference will not show up if the topic it refers to is not visible.
- all values with spaces must be in quotes. This is because spaces are actually newlines.
+
** '''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.
Due to limitations of the wiki (it is coded using XML), the WML for the topic markup will be described rather than
+
** '''force''': shows the cross reference even though the referred topic is not shown.
the XML.  However, you still need to use XML to code the topic.
+
* {{anchor|jump|'''<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.
The following key/tags are accepted for ''text'':
+
** '''amount''': the number of pixels to jump forward
* '''[ref]''' creates a cross reference to another topic, a cross reference will not show up if the topic it refers to is not visible.
+
* {{anchor|img|'''<img>'''}}: insert an image in the topic
** ''dst'' the ID of the topic to reference.
+
** '''src''': the path to the image relative to the '''images/''' directory.
** ''text'' the text to display as a link to ''dst''; i.e. when ''text'' is clicked on the page ''dst'' will be linked to.
+
** '''align''': the position of the image with respect to the page. Values are '''here''', '''left''', '''middle''', and '''right'''.
** ''force'' shows the cross reference even though the referred topic is not shown.
+
** '''float''': whether the image should float(have text filled in around it) or not (be seen as included in a line).
* '''[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.
+
* {{anchor|format|'''<format>'''}}: describes a group of text in a different format.  Can be used to describe different colors and font sizes.
** ''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.
+
** '''bold''': whether the text should be displayed in bold('''bold''').
** ''amount'' the number of pixels to jump forward
+
** '''italic''': whether the text should be displayed in italics(''italics'').
* '''[img]''' insert an image in the topic
+
** '''color''': the color of the text.  Only a few colors are currently supported: '''white'''(default), '''green''', '''red''', '''yellow''', and '''black'''.
** ''src'' the path to the image relative to the '''images/''' directory.
+
** '''font_size''': the height of the text in pixels. Default 9(?)
** ''align'' the position of the image with respect to the page. Values are ''here'', ''left'', ''middle'', and ''right''.
+
** '''text''': the text to be displayed using this format.
** ''float'' whether the image should float(have text filled in around it) or not (be seen as included in a line).
+
* {{anchor|italic|'''<italic>'''}}: a shortcut to '''<format>''' which inputs only the '''text''' key.  Uses the attribute '''italic=yes'''
* '''[format]''' describes a group of text in a different format.  Can be used to describe different colors and font sizes.
+
* {{anchor|bold|'''<bold>'''}}: like <italic>, but uses '''bold=yes'''
** ''bold'' whether the text should be displayed in bold('''bold''').
+
* {{anchor|header|'''<header>'''}}: like <italic>, but uses both the attributes '''bold=yes''' and '''font_size=13'''(?)
** ''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:
 
Example:
[help]
+
<syntaxhighlight lang=wml>
[toplevel]
+
[help]
sections=introduction,gameplay
+
  [toplevel]
topics=about
+
    sections=introduction,gameplay
[/toplevel]
+
    topics=about
[section]
+
  [/toplevel]
id=gameplay
+
  [section]
sections=combat
+
    id=gameplay
topics=income_and_upkeep,time_of_day,terrain
+
    sections=combat
[/section]
+
    topics=income_and_upkeep,time_of_day,terrain,victory_and_defeat
[topic]
+
  [/section]
id=terrain
+
  [topic]
title=Terrain
+
    id=terrain
text="<ref>dst=income_and_upkeep text='Link to Income and Upkeep topic'</ref>"
+
    title=Terrain
[/topic]
+
    text="<ref>dst=income_and_upkeep text='Link to Income and Upkeep topic'</ref>"
[/help]
+
  [/topic]
 +
  [topic]
 +
    id=victory_and_defeat
 +
    title= _ "Victory and Defeat"
 +
    text= _ "Pay careful attention to the <bold>text='Objectives'</bold> pop-up
 +
            box at the beginning of each scenario. Usually you will achieve
 +
            victory by killing all enemy leaders, and only be defeated by having
 +
            your leader killed. But scenarios may have other victory objectives
 +
            — getting your leader to a designated point, say, or rescuing someone,
 +
            or solving a puzzle, or holding out against a siege until a certain
 +
            number of turns have elapsed." + _"
 +
           
 +
            When you win a scenario, the map grays over and the
 +
            <bold>text='End Turn'</bold> button changes to
 +
            <bold>text='End Scenario'</bold>. You can now do things like changing
 +
            your save options or (if you are in a multiplayer game) chatting with
 +
            other players before pressing that button to advance."
 +
   
 +
  [/topic]
 +
[/help]
 +
</syntaxhighlight>
  
 
== See Also ==
 
== See Also ==

Latest revision as of 05:57, 27 February 2024

[edit]WML Tags

A:

abilities, about, achievement, achievement_group, add_ai_behavior, advanced_preference, advancefrom, advancement, advances, affect_adjacent, ai, allied_with, allow_end_turn, allow_extra_recruit, allow_recruit, allow_undo, and, animate, animate_unit, animation, aspect, attack (replay, weapon), attack_anim, attacks (special, stats), avoid;

B:

base_unit, background_layer, berserk, binary_path, break, brush;

C:

campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, checkbox, choice, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_palette, color_range, command (action, replay), continue, credits_group, criteria;

D:

damage, death, deaths, default, defend, defends, defense, delay, deprecated_message, destination, difficulty, disable, disallow_end_turn, disallow_extra_recruit, disallow_recruit, do, do_command, drains, draw_weapon_anim;

E:

editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry (credits, options), era, event, experimental_filter_ability, experimental_filter_ability_active, experimental_filter_specials, extra_anim;

F:

facet, facing, fake_unit, false, feedback, female, filter (concept, event), filter_adjacent, filter_adjacent_location, filter_attack, filter_attacker, filter_base_value, filter_condition, filter_defender, filter_enemy, filter_location, filter_opponent, filter_own, filter_owner, filter_radius, filter_recall, filter_second, filter_second_attack, filter_self, filter_side, filter_student, filter_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, found_item, for, foreach, frame;

G:

game_config, get_global_variable, goal, gold, gold_carryover;

H:

harm_unit, has_ally, has_attack, has_unit, has_achievement, have_location, have_unit, heal_on_hit, heal_unit, healed_anim, healing_anim, heals, hide_help, hide_unit, hides;

I:

idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), init_side, insert_tag, inspect, item, item_group;

J:

jamming_costs, join;

K:

kill, killed;

L:

label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;

M:

male, menu_item, message, micro_ai, missile_frame, modification, modifications, modify_ai, modify_side, modify_turns, modify_unit, modify_unit_type, move, move_unit, move_unit_fake, move_units_fake, movement_anim, movement costs, movetype, multiplayer, multiplayer_side, music;

N:

not, note;

O:

object, objective, objectives, on_undo, open_help, option, options, or;

P:

part, petrifies, petrify, place_shroud, plague, poison, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, put_to_recall_list;

R:

race, random_placement, recall (action, replay), recalls, recruit, recruit_anim, recruiting_anim, recruits, redraw, regenerate, remove_event, remove_item, remove_object, remove_shroud, remove_sound_source, remove_time_area, remove_trait, remove_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resource, return, role, rule;

S:

save, scenario, screen_fade, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_achievement, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, objective, set_menu_item), show_objectives, side, skirmisher, slider, slow, snapshot, sound, sound_source, source (replay, teleport), special_note, specials, split, stage, standing_anim, statistics, status, store_gold, store_items, store_locations, store_map_dimensions, store_reachable_locations, store_relative_direction, store_side, store_starting_location, store_time_of_day, store_turns, store_unit, store_unit_defense, store_unit_defense_on, store_unit_type, store_unit_type_ids, store_villages, story, swarm, sub_achievement, switch, sync_variable;

T:

target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, test_do_attack_by_id, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel;

U:

unhide_unit, unit, unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;

V:

value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;

W:

while, wml_message, wml_schema;

Z:

zoom;

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. Topics will be included in the order listed unless sorting is requested.
    • generator: provides the name of a function that will generate a list of topics and include them in this section. These topics will be included after topics listed on the topics key unless sort_topics is yes.
    • sort_topics: specifies whether or not to list the topics sorted by title or in the order listed on the topics key. yes indicates fixed and generated topics should be sorted together by title. no indicates that topics should appear in the order listed with fixed topics appearing before generated topics. generated indicates that fixed topics should not be sorted and will be followed by generated topics sorted by the generator. The default is generated.
  • [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 a WML-like markup language with angle brackets.

It consists of plain text, interrupted with markup tags. Between paired start and end tags (like <jump> ... </jump>) you can give keys and values like in WML, separated by spaces instead of newlines. For values containing spaces, surround them with single quotes. The "text content" of a tag, if any, is usually given by a text key. You can't nest tags within another tag.

The following key/tags are accepted inside text (source):

  • <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,victory_and_defeat
  [/section]
  [topic]
    id=terrain
    title=Terrain
    text="<ref>dst=income_and_upkeep text='Link to Income and Upkeep topic'</ref>"
  [/topic]
  [topic]
    id=victory_and_defeat
    title= _ "Victory and Defeat"
    text= _ "Pay careful attention to the <bold>text='Objectives'</bold> pop-up
             box at the beginning of each scenario. Usually you will achieve
             victory by killing all enemy leaders, and only be defeated by having
             your leader killed. But scenarios may have other victory objectives
             — getting your leader to a designated point, say, or rescuing someone,
             or solving a puzzle, or holding out against a siege until a certain
             number of turns have elapsed." + _"
             
             When you win a scenario, the map grays over and the
             <bold>text='End Turn'</bold> button changes to
             <bold>text='End Scenario'</bold>. You can now do things like changing
             your save options or (if you are in a multiplayer game) chatting with
             other players before pressing that button to advance."
    
  [/topic]
[/help]

See Also

This page was last edited on 27 February 2024, at 05:57.