==Introduction==

===Summary===

Wesnoth Mode is a major mode for Emacs which assists in the editing of
the markup language extensively used in Wesnoth, a turn-based fantasy
strategy game. From the Wesnoth Wiki: "The Wesnoth Markup Language
(WML) is used to code almost everything in Wesnoth, including
scenarios, units, savefiles, and the user interface layout." (1)

Wesnoth Mode is supported under GNU Emacs 21 onwards and (with some
minor limitations) XEmacs 21. Wesnoth Mode adds support for syntax
highlighting, automatic indentation, context-sensitive completion,
checking and much more when editing WML.

This documentation attempts to provide a comprehensive guide to
functionality available within Wesnoth Mode 1.3.3, and assumes you are
familiar with basic usage, terminology and customisation of Emacs. For
more information, please refer to the Emacs manual. (2)

Footnotes
(1) http://www.wesnoth.org/wiki/ReferenceWML
(2) http://www.gnu.org/software/emacs/manual/html_node/emacs/

===Getting Started===

To use Wesnoth Mode, add the following to your '.emacs':
(add-to-list 'load-path "path/to/wesnoth-mode")
(autoload 'wesnoth-mode "wesnoth-mode" "Major mode for editing WML." t)
Optionally adding:
(add-to-list 'auto-mode-alist '("\\.cfg\\'" . wesnoth-mode))
to automatically load Wesnoth Mode for all files with a .cfg
extension.

If Wesnoth Mode is not the currently active major-mode for the
current buffer, it can be started via 'M-x wesnoth-mode'.

The latest version of Wesnoth Mode along with release notes can be
found at http://www.wesnoth.org/forum/viewtopic.php?t=13798.

==Navigation==

===Navigation Introduction===

Emacs provides many powerful built-in navigation commands which are
ideal for editing WML. Common navigation commands, such as 'C-n',
'C-s', and (in recent Emacsen) 'M-g g', will behave as usual within
Wesnoth Mode. However, some navigation commands have been adjusted or
added for increased productivity. These will be explained in the
following sections.

===Moving Across Elements===

Next and previous opening elements can be navigated using 'C-M-e' and
'C-M-a', respectively. In each case, point will be positioned
immediately before the element. When there are no more elements are
available in that direction, point will not move.

===Matching Elements===

Moving to the matching element in a pair or locating the parent element
(depending on the position of point) can be performed via 'C-c C-o'.
When point is on the same line as an opening element, such as an opening
tag or opening preprocessor statement it will be moved to the start of
the matching closing element. Otherwise, the jump will position point
at the beginning of the corresponding opening element.

==Inserting Elements==

===Standard Completion===

Tags can be inserted via 'C-c C-t' and alternatively 'M-TAB' (when
this is not shadowed by the Window Manager, etc.). This will prompt
for the tag to add. The tag entered into the mini-buffer prompt and
its matching closing tag will be inserted and point positioned between.

Attributes can be inserted via 'C-c C-a'. The attribute entered at
the prompt will be inserted along with the '=', with point immediately
after.

Both tag and attribute completion is context-sensitive. If an
element is available in WML and not listed for completion, you may want
to add it to your 'addition file'. See [[#Wesnoth Update|Wesnoth Update]] for more
information.

Macro insertion can be performed via 'C-c C-m'. Any arguments known
to be required for the macro will be prompted and inserted in order.
Insertion will be aborted if no value for an argument is provided. When
within a macro definition, macro arguments are also available to be
inserted. Project-local macros will not be available until Wesnoth Mode
has scanned the buffer in which they are defined. For information on
completing project-local macros, see [[#Macro Definitions|Macro Definitions]].

Preprocessor statements are available for insertion via 'C-c C-p'.
Closing elements for preprocessor statements will be automatically
inserted where possible, with point positioned between. Otherwise,
point will be placed immediately after the inserted text.

===Tab-Completion===

Completion can also be performed immediately within the buffer via
'TAB' on a partial element. For example:
[scenario]
vil-!-
Where '-!-' is the position of point. Using 'TAB' in the example
will complete to 'vil' to 'village_gold='. Tags, macros and
preprocessor statements can be completed similarly. When the
current line does not contain a partially completed element, 'TAB'
will perform indentation on the current line.

When there is more than one possible completion, a minibuffer prompt
will be provided, with the partial element entered. 'TAB' can be used
here to perform completion. If multiple matches are available,
completion will be performed up to the smallest common substring with
further completion available via the minubuffer prompt. When no matches
are found, completion will not be prompted.

When completing opening preprocessor statements and tags, Wesnoth
Mode will also attempt to insert a matching closing element if one is
not already available, acting in much the same way as if the element was
added via the minibuffer prompt. However, if an matching closing
element is available, only the element at point will be completed.

A numeric argument can be provided when performing tab-completion of
opening elements to wrap around the following n blocks. For example,
to wrap the completed opening and closing pair around the next three
blocks, 'C-u 3 TAB' can be used. Refer to [[#Wrapping Elements|Wrapping Elements]] for more information.

===Wrapping Elements===

When inserting tags and some preprocessor statements, either via their
respective insertion command or via 'TAB', an optional numeric argument
can be provided to specify the number of 'blocks' to wrap the element
around. For example:

[multiplayer]
-!-[part]
...
[/part]
[part]
...
[/part]
[event]
...

Where point is at the position indicated by '-!-'. A pair of
'story' tags can be inserted around both existing 'part' tags using
'C-u 2 C-c C-t story'. When the number of blocks specified to wrap
around exceeds the number of blocks available, Wesnoth Mode will only
wrap around the number of available so that the nesting of elements is
correct.

===Missing Elements===

Missing closing elements can be inserted using 'C-c C-/'. By default,
this will insert the first missing closing element found in the current
buffer at point. If all elements appear to be matched or if there is
an excess of closing tags, an appropriate message will be displayed in
the echo area.

==Checking WML==

===Usage and Capabilities===

Checking of the current buffer can be performed using @kbd{C-c C-c}. A
summary of all warnings located will be provided in a separate buffer.
Point can be jumped to the next and previous warning using @kbd{C-c C-f}
(or @kbd{C-x `}) and @kbd{C-c C-b}, respectively. For visibility,
warnings in the checked WML buffer will be underlined in red by default.
Note: Warning underlines may not be available in XEmacs.

The WML checking built-in to Wesnoth Mode is not intended to
be an alternative to tools such as `wmllint', but may often be a
convenient substitute while editing WML.

The following conditions can be detected by WML checking in Wesnoth
Mode:
* Correct nesting of tags and preprocessor statements
* Known macro definitions (1)
* Availability of elements within the given context
* Arguments are given to preprocessor statements when required
* Attributes have a value assigned
* Corresponding FOREACH..NEXT pairs

WML checking is specific to the version of WML known by Wesnoth Mode. See [[#Wesnoth Update|Wesnoth Update]] for more information.

Footnotes
(1) [[#Macro Definitions|Macro Definitions]]

==Customisation==

===Indentation===

The style of indentation can be customised using
'wesnoth-indent-savefile'. The default value is 'non-nil', which
results in all children being indented a level deeper than their
parent. When set to 'nil', children will be indented to the same level
as their parent element. This option is provided only for consistency
when editing (very) old WML. It is recommended that all new code be
written using the new convention.

By default, Wesnoth Mode will attempt indentation of the current line
and create a newline and when 'RET' or 'C-j' are used.
'wesnoth-auto-indent-flag' controls whether Wesnoth Mode will attempt
to indent the current line automatically. Setting this to 'nil' will
prevent automatic indentation. Note that this does not affect the
behaviour of 'C-j' performing indentation following the newline; this
only determines whether indentation will be automatically performed on
the current line.

'wesnoth-base-indent' controls the depth of indentation for each
level. Its value should be an integer. This is set to '4' by default,
which is the convention used when indenting WML.

'wesnoth-warning-face' is the face used to display the overlay for
warnings detected when checking WML (See @ref{Checking WML}). By
default this is a red underline. Use of this face may not be supported
under XEmacs.

===Wesnoth Update===

By default, Wesnoth Mode uses WML as in Wesnoth 1.5.6, but the version of WML used can be changed using Wesnoth Update. Wesnoth Update controls the known WML data for Wesnoth Mode. To update this information, three variables need to be set appropriately:
'wesnoth-root-directory', 'wesnoth-update-output-directory' and
'wesnoth-addition-file'.

'wesnoth-root-directory' should be the path to the root directory of
a Wesnoth installation or Wesnoth source code. Wesnoth Update will
search recursively in this directory for WML, using the information
found to provide context-sensitive completion and WML checking.

'wesnoth-update-output-directory' specifies the path to store the
WML data found. This path should be within the 'load-path', and
preferably, in the same directory as Wesnoth Mode.

'wesnoth-addition-file' specifies the 'addition file' to use. An
addition file is an outline of a valid WML file which is processed for
additional element data. This should be set as the path a suitable
addition file. A sample addition file is included with Wesnoth Mode.

For example:
(setq wesnoth-root-directory "/usr/local/share/wesnoth/"
wesnoth-addition-file
"~/.emacs.d/wesnoth-mode/wesnoth-wml-additions.cfg"
wesnoth-update-output-directory "~/.emacs.d/wesnoth-mode/"

Once set, 'M-x wesnoth-update' will generate and load a new cache of
WML data ready for use for the current and future sessions. (Please
note, 'wesnoth-update' may take some time to run.)

===Macro Definitions===

While built-in macros are always available, local macro definitions are
automatically scanned and made known to Wesnoth Mode for each WML file
which is loaded in the session. 'C-c C-u' can be used to update the
known macro definitions for any buffer which has since been modified.
(Note that this is not required when the macro is defined in the WML
file currently being edited as such definitions will be automatically
updated when needed.) 'C-u C-c C-u' can be used to clear known local
macro definitions.

Wesnoth Mode

2008-11-02T02:11:50Z

Wildpenguin: New page: Wesnoth Mode documentation

==Introduction==

===Summary===

Wesnoth Mode is a major mode for Emacs which assists in the editing of
the markup language extensively used in Wesnoth, a turn-based fantasy
strategy game. From the Wesnoth Wiki: "The Wesnoth Markup Language
(WML) is used to code almost everything in Wesnoth, including
scenarios, units, savefiles, and the user interface layout." (1)

Wesnoth Mode is supported under GNU Emacs 22 and 21 and (with some
minor limitations) XEmacs 21. Wesnoth Mode adds support for syntax
highlighting, automatic indentation, context-sensitive completion,
checking and much more when editing WML.

This documentation attempts to provide a comprehensive guide to
functionality available within Wesnoth Mode, and assumes you are
familiar with basic usage, terminology and customisation of Emacs. For
more information, please refer to the Emacs manual. (2)

Footnotes
(1) http://www.wesnoth.org/wiki/ReferenceWML
(2) http://www.gnu.org/software/emacs/manual/html_node/emacs/

===Getting Started===

To use Wesnoth Mode, add the following to your '.emacs':
(add-to-list 'load-path "path/to/wesnoth-mode")
(autoload 'wesnoth-mode "wesnoth-mode" "Major mode for editing WML." t)
Optionally adding:
(add-to-list 'auto-mode-alist '("\\.cfg\\'" . wesnoth-mode))
to automatically load Wesnoth Mode for all files with a .cfg
extension.

If Wesnoth Mode is not the currently active major-mode for the
current buffer, it can be started via 'M-x wesnoth-mode'.

The latest version of Wesnoth Mode along with release notes can be
found at http://www.wesnoth.org/forum/viewtopic.php?t=13798.

==Navigation==

===Navigation Introduction===

Emacs provides many powerful built-in navigation commands which are
ideal for editing WML. Common navigation commands, such as 'C-n',
'C-s', and (in recent Emacsen) 'M-g g', will behave as usual within
Wesnoth Mode. However, some navigation commands have been adjusted or
added for increased productivity. These will be explained in the
following sections.

===Moving Across Elements===

Next and previous opening elements can be navigated using 'C-M-e' and
'C-M-a', respectively. In each case, point will be positioned
immediately before the element. When there are no more elements are
available in that direction, point will not move.

===Matching Elements===

Moving to the matching element in a pair or locating the parent element
(depending on the position of point) can be performed via 'C-c C-o'.
When point is on the same line as an opening element, such as an opening
tag or opening preprocessor statement it will be moved to the start of
the matching closing element. Otherwise, the jump will position point
at the beginning of the corresponding opening element.

==Inserting Elements==

===Standard Completion===

Tags can be inserted via 'C-c C-t' and alternatively 'M-TAB' (assuming
this is not shadowed by the Window Manager, etc.). This will prompt
for the tag to add. The tag entered into the mini-buffer prompt and
its matching closing tag will be inserted and point positioned between.

Attributes can be inserted via 'C-c C-a'. The attribute entered at
the prompt will be inserted along with the '=', with point immediately
after.

Both tag and attribute completion is context-sensitive. If an
element is available in WML and not listed for completion, you may want
to add it to your 'addition file'. See [[#Wesnoth Update|Wesnoth Update]] for more
information.

Macro insertion can be performed via C-c C-m. If the macro
entered is known to require arguments, point will be positioned before
the closing curly bracket ready to input any arguments, otherwise it
will be positioned immediately after. When within a macro definition,
macro arguments are also available to be inserted. Project-local macros
will not be available until Wesnoth Mode has scanned the buffer in which
they are defined. For information on completing project-local macros,
see [[#Macro Definitions|Macro Definitions]].

Preprocessor statements are available for insertion via 'C-c C-p'.
Closing elements for preprocessor statements will be automatically
inserted where possible, with point positioned between. Otherwise,
point will be placed immediately after the inserted text.

===Tab-Completion===

Completion can also be performed immediately within the buffer via
'TAB' on a partial element. For example:
[scenario]
vil-!-
Where '-!-' is the position of point. Using 'TAB' in the example
will complete to 'vil' to 'village_gold='. Tags, macros and
preprocessor statements can be completed similarly.

When there is more than one possible completion, a mini-buffer prompt
will be provided, with the partial element entered. 'TAB' can be used
here to perform completion, and if no unique match is available,
provide a list of possible completions.

When completing opening preprocessor statements and tags, Wesnoth
Mode will also attempt to insert a matching closing element if one is
not already available, acting in much the same way as if the element was
added via the mini-buffer prompt. However, if an matching closing
element is available, only the element at point will be completed.

A numeric argument can be provided when performing tab-completion of
opening elements to wrap around the following n blocks. For example,
to wrap the completed opening and closing pair around the next three
blocks, 'C-u 3 TAB' can be used. Refer to [[#Wrapping Elements|Wrapping Elements]] for more information.

===Wrapping Elements===

When inserting tags and some preprocessor statements, either via their
respective insertion command or via 'TAB', an optional numeric argument
can be provided to specify the number of 'blocks' to wrap the element
around. For example, this was an outline of the buffer:

[multiplayer]
-!-[part]
...
[/part]
[part]
...
[/part]
[event]
...

Where point is at the position indicated by '-!-'. A pair of
'story' tags can be inserted around both existing 'part' tags using
'C-u 2 C-c C-t story'. When the number of blocks specified to wrap
around exceeds the number of blocks available, Wesnoth Mode will only
wrap around the number of available so that the nesting of elements is
correct.

===Missing Elements===

Missing closing elements can be inserted using 'C-c C-/'. By default,
this will insert the first missing closing element found in the current
buffer at point. If all elements appear to be matched or if there is
an excess of closing tags, an appropriate message will be displayed in
the echo area.

Note: The following paragraph does not apply to XEmacs.

The region Wesnoth Mode checks for missing elements can be adjusted
enabling transient-mark-mode prior to inserting the missing element. To
narrow the region checked, move to the start of the region and enable
transient-mark-mode (this is bound to 'C-Space C-Space' by default) ato
point temporarily by default. Then move point to the location to insert
the missing element and use 'C-c C-/'. The first missing tag located
in the region will be inserted at point.

==Checking WML==

===Usage and Capabilities===

Checking of the current buffer can be performed using 'C-c C-c'. Any
potential problems found will be reported in a separate buffer named
"*WML*". The WML checking built-in to Wesnoth Mode is not intended to
act as an alternative to tools such as 'wmllint', but may often be a
convenient substitute while editing WML.

The following conditions can be detected by WML checking in Wesnoth
Mode:
* Correct tag / preprocessor nesting
* Known macro definitions (1)
* Availability of elements within the given context
* Arguments are given to preprocessor statements when required
* Whether attributes have been given a value

When a problem has been found, Wesnoth Mode will provide the line
number and a description of the problem in the report. WML checking is
specific to the version of WML known by Wesnoth Mode. See [[#Wesnoth Update|Wesnoth Update]] for more information.

Footnotes
(1) [[#Macro Definitions|Macro Definitions]]

==Customisation==

===Indentation===

The style of indentation can be customised using
'wesnoth-indent-savefile'. The default value is 'non-nil', which
results in all children being indented a level deeper than their
parent. When set to 'nil', children will be indented to the same level
as their parent element. This option is provided only for consistency
when editing (very) old WML. It is recommended that all new code be
written using the 'savefile style'.

By default, Wesnoth Mode will attempt indentation of the current line
and create a newline and when 'RET' or 'C-j' are used.
'wesnoth-auto-indent-flag' controls whether Wesnoth Mode will attempt
to indent the current line automatically. Setting this to 'nil' will
prevent automatic indentation. Note that this does not affect the
behaviour of 'C-j' performing indentation following the newline; this
only determines whether indentation will be automatically performed on
the current line.

'wesnoth-base-indent' controls the depth of indentation for each
level. Its value should be an integer. This is set to '4' by default,
which is the convention used when indenting WML.

===Wesnoth Update===

Wesnoth Update controls the known WML data for Wesnoth Mode. To update
this information, three variables need to be set appropriately:
'wesnoth-root-directory', 'wesnoth-update-output-directory' and
'wesnoth-addition-file'.

'wesnoth-root-directory' should be the path to the root directory of
a Wesnoth installation or Wesnoth source code. Wesnoth Update will
search recursively in this directory for WML, using the information
found to provide context-sensitive completion and WML checking.

'wesnoth-update-output-directory' specifies the path to store the
WML data found. This path should be within the 'load-path', and
preferably, in the same directory as Wesnoth Mode.

'wesnoth-addition-file' specifies the 'addition file' to use. An
addition file is an outline of a valid WML file which is processed for
additional element data. This should be set as the path a suitable
addition file. A sample addition file is included with Wesnoth Mode.

For example:
(setq wesnoth-root-directory "/usr/local/share/wesnoth/"
wesnoth-addition-file
"~/.emacs.d/wesnoth-mode/wesnoth-wml-additions.cfg"
wesnoth-update-output-directory "~/.emacs.d/wesnoth-mode/"

Once set, 'M-x wesnoth-update' will generate and load a new cache of
WML data ready for use for the current and future sessions. (Please
note, 'wesnoth-update' may take some time to run.)

===Macro Definitions===

While built-in macros are always available, local macro definitions are
automatically scanned and made known to Wesnoth Mode for each WML file
which is loaded in the session. 'C-c C-u' can be used to update the
known macro definitions for any buffer which has since been modified.
(Note that this is not required when the macro is defined in the WML
file currently being edited as such definitions will be automatically
updated when needed.) 'C-u C-c C-u' can be used to clear known local
macro definitions.