Difference between revisions of "Wesnoth Mode"

From The Battle for Wesnoth Wiki
(Documentation updated for upcoming release)
m (Summary: wikify)
 
(11 intermediate revisions by 2 users not shown)
Line 6: Line 6:
 
the markup language extensively used in Wesnoth, a turn-based fantasy
 
the markup language extensively used in Wesnoth, a turn-based fantasy
 
strategy game.  From the Wesnoth Wiki: "The Wesnoth Markup Language
 
strategy game.  From the Wesnoth Wiki: "The Wesnoth Markup Language
(WML) is used to code almost everything in Wesnoth, including
+
(WML) is used to code almost everything in Wesnoth, including scenarios,
scenarios, units, savefiles, and the user interface layout." (1)
+
units, savefiles, and the user interface layout." (1)
  
 
Wesnoth Mode is supported under GNU Emacs 21 onwards and (with some
 
Wesnoth Mode is supported under GNU Emacs 21 onwards and (with some
 
minor limitations) XEmacs 21.  Wesnoth Mode adds support for syntax
 
minor limitations) XEmacs 21.  Wesnoth Mode adds support for syntax
 
highlighting, automatic indentation, context-sensitive completion,
 
highlighting, automatic indentation, context-sensitive completion,
checking and much more when editing WML.
+
validation and much more when editing WML.
  
 
This documentation attempts to provide a comprehensive guide to
 
This documentation attempts to provide a comprehensive guide to
functionality available within Wesnoth Mode 1.3.3, and assumes you are
+
functionality available within Wesnoth Mode 1.3.4, and assumes you are
 
familiar with basic usage, terminology and customisation of Emacs.  For
 
familiar with basic usage, terminology and customisation of Emacs.  For
 
more information, please refer to the Emacs manual. (2)
 
more information, please refer to the Emacs manual. (2)
  
 
  Footnotes
 
  Footnotes
  (1) http://www.wesnoth.org/wiki/ReferenceWML
+
  (1) [[ReferenceWML]]
 
  (2) http://www.gnu.org/software/emacs/manual/html_node/emacs/
 
  (2) http://www.gnu.org/software/emacs/manual/html_node/emacs/
  
Line 33: Line 33:
 
extension.
 
extension.
  
If Wesnoth Mode is not the currently active major-mode for the
+
Wesnoth Mode can be activated as the current major-mode for a buffer via
current buffer, it can be started via 'M-x wesnoth-mode'.
+
'M-x wesnoth-mode'.
  
 
The latest version of Wesnoth Mode along with release notes can be
 
The latest version of Wesnoth Mode along with release notes can be
 
found at http://www.wesnoth.org/forum/viewtopic.php?t=13798.
 
found at http://www.wesnoth.org/forum/viewtopic.php?t=13798.
  
==Navigation==
+
Alternatively, the development version is available using git.  To checkout the latest changes, the following command can be used:
 +
  git clone git://repo.or.cz/wesnoth-mode.git
  
===Navigation Introduction===
+
==Basic Usage==
  
Emacs provides many powerful built-in navigation commands which are
+
===Indentation===
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===
+
By default, Wesnoth Mode provides a style of indentation equivalent to
 +
that provided by 'wmlindent' tool distributed with Wesnoth.
 +
'TAB' can be used to automatically indent the current line to the
 +
correct depth.  'TAB' can perform two actions depending on the
 +
context of point.  When there is an incomplete element immediately
 +
preceding point, completion will be attempted, otherwise 'TAB' will
 +
perform indentation.  See [[#Tab Completion|Tab Completion]].
  
Next and previous opening elements can be navigated using 'C-M-e' and
+
Wesnoth Mode will, by default, indent the current line appropriately
'C-M-a', respectively.  In each case, point will be positioned
+
before inserting a newline when 'RET' or 'C-j' is
immediately before the elementWhen there are no more elements are
+
used. ('C-j' will also attempt to indent the new line.)
available in that direction, point will not move.
+
   
 +
See [[#Modifying Indentation|Modifying Indentation]] for information on how to customise the behaviour of automatic indentation.
  
===Matching Elements===
+
===Navigation===
 +
 
 +
Built-in commands for navigation are available.  This section describes
 +
additional or modified navigation commands specific to Wesnoth Mode.
 +
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 no more elements are available in
 +
that direction, the position of point will not change.
  
 
Moving to the matching element in a pair or locating the parent element
 
Moving to the matching element in a pair or locating the parent element
Line 65: Line 75:
 
the matching closing element.  Otherwise, the jump will position point
 
the matching closing element.  Otherwise, the jump will position point
 
at the beginning of the corresponding opening element.
 
at the beginning of the corresponding opening element.
 +
 +
Structured navigation is available with 'C-M-n' and 'C-M-p'
 +
providing the ability to move to the next and previous blocks
 +
(respectively) which are at the same depth as the element where the
 +
command was invoked.  'C-M-d' will move to the child of the element
 +
at point and 'C-M-u' moving to the corresponding parent element.
 +
 +
===Editing Extras===
 +
 +
Additional commands have been added to assist editing regions of WML.
 +
'C-M-k' can be used to kill the element at point up to the
 +
corresponding closing element, including all contents.  Also, when point
 +
is at an opening element, the mark can be placed at the end of the
 +
corresponding closing element using 'C-M-SPC'.
  
 
==Inserting Elements==
 
==Inserting Elements==
Line 87: Line 111:
 
to be required for the macro will be prompted and inserted in order.
 
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
 
Insertion will be aborted if no value for an argument is provided.  When
within a macro definition, macro arguments are also available to be
+
within a macro definition, the arguments for the current macro are also
insertedProject-local macros will not be available until Wesnoth Mode
+
available for completionAny project-local or custom macros can be
has scanned the buffer in which they are defined. For information on
+
made available for completion by opening the file in which they are
completing project-local macros, see [[#Macro Definitions|Macro Definitions]].
+
defined. For information on completing project-local macros, see [[#Macro Definitions|Macro Definitions]].
  
 
Preprocessor statements are available for insertion via 'C-c C-p'.
 
Preprocessor statements are available for insertion via 'C-c C-p'.
Line 97: Line 121:
 
point will be placed immediately after the inserted text.
 
point will be placed immediately after the inserted text.
  
===Tab-Completion===
+
===Tab Completion===
  
 
Completion can also be performed immediately within the buffer via
 
Completion can also be performed immediately within the buffer via
Line 113: Line 137:
 
here to perform completion.  If multiple matches are available,
 
here to perform completion.  If multiple matches are available,
 
completion will be performed up to the smallest common substring with
 
completion will be performed up to the smallest common substring with
further completion available via the minubuffer prompt.  When no matches
+
further completion available via the minibuffer prompt.  When no matches
are found, completion will not be prompted.
+
are found for the partial element, completion will not be prompted.
  
 
When completing opening preprocessor statements and tags, Wesnoth
 
When completing opening preprocessor statements and tags, Wesnoth
Line 122: Line 146:
 
element is available, only the element at point will be completed.
 
element is available, only the element at point will be completed.
  
A numeric argument can be provided when performing tab-completion of
+
A numeric argument can be provided when performing tab completion of
opening elements to wrap around the following n blocks.  For example,
+
opening elements to wrap around the next 'n' blocks.  For example,
 
to wrap the completed opening and closing pair around the next three
 
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.
 
blocks, 'C-u 3 TAB' can be used.  Refer to [[#Wrapping Elements|Wrapping Elements]] for more information.
Line 155: Line 179:
 
Missing closing elements can be inserted using 'C-c C-/'.  By default,
 
Missing closing elements can be inserted using 'C-c C-/'.  By default,
 
this will insert the first missing closing element found in the current
 
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
+
buffer at point.  If all elements appear to be matched or if there is an excess of closing tags, a notification will be displayed and no element will be inserted.
an excess of closing tags, an appropriate message will be displayed in
 
the echo area.
 
  
==Checking WML==
+
==Validating WML==
  
 
===Usage and Capabilities===
 
===Usage and Capabilities===
  
Checking of the current buffer can be performed using @kbd{C-c C-c}.  A
+
Validating WML in the current buffer can be performed using 'C-c C-c'.  A
 
summary of all warnings located will be provided in a separate buffer.
 
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}
+
Point can be jumped to the next and previous warning using 'C-c C-f'
(or @kbd{C-x `}) and @kbd{C-c C-b}, respectively.  For visibility,
+
(or 'C-x `') and 'C-c C-b', respectively.  For visibility,
warnings in the checked WML buffer will be underlined in red by default.
+
warnings will be underlined in red by default. Note: Warning underlines may not be available in XEmacs.
Note: Warning underlines may not be available in XEmacs.
 
  
The WML checking built-in to Wesnoth Mode is not intended to
+
The WML validation built-in to Wesnoth Mode is not intended to
 
be an alternative to tools such as `wmllint', but may often be a
 
be an alternative to tools such as `wmllint', but may often be a
 
convenient substitute while editing WML.
 
convenient substitute while editing WML.
  
The following conditions can be detected by WML checking in Wesnoth
+
The following conditions can be tested in Wesnoth Mode:
Mode:
 
 
* Correct nesting of tags and preprocessor statements
 
* Correct nesting of tags and preprocessor statements
 
* Known macro definitions (1)
 
* Known macro definitions (1)
Line 183: Line 203:
 
* Corresponding FOREACH..NEXT pairs
 
* 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.
+
WML validation is specific to the version of WML known by Wesnoth Mode. See [[#Wesnoth Update|Wesnoth Update]] for more information.
  
 
  Footnotes
 
  Footnotes
Line 190: Line 210:
 
==Customisation==
 
==Customisation==
  
===Indentation===
+
===Modifying Indentation===
  
 
The style of indentation can be customised using
 
The style of indentation can be customised using
Line 196: Line 216:
 
results in all children being indented a level deeper than their
 
results in all children being indented a level deeper than their
 
parent.  When set to 'nil', children will be indented to the same level
 
parent.  When set to 'nil', children will be indented to the same level
as their parent element.  This option is provided only for consistency
+
as their parent element.  This option is provided only for +consistency when editing (very) old WML.  It is recommended that this be non-nil for all new WML.
when editing (very) old WML.  It is recommended that all new code be
+
 
written using the new convention.
+
'wesnoth-indent-preprocessor-bol' controls how preprocessor
 +
statements should be indented.  If non-nil, all preprocessor statements
 +
will be indented to the beginning of the line.  Otherwise, preprocessor
 +
statements will be indented as to the level indicated by its context.
  
 
By default, Wesnoth Mode will attempt indentation of the current line
 
By default, Wesnoth Mode will attempt indentation of the current line
Line 208: Line 231:
 
only determines whether indentation will be automatically performed on
 
only determines whether indentation will be automatically performed on
 
the current line.
 
the current line.
 +
 +
The following can be used to change 'RET' to automatically indent the
 +
newline:
 +
 +
(add-hook 'wesnoth-mode-hook
 +
  '(lambda ()
 +
    (define-key wesnoth-mode-map (kbd "C-m")
 +
    'wesnoth-newline-and-indent)))
  
 
'wesnoth-base-indent' controls the depth of indentation for each
 
'wesnoth-base-indent' controls the depth of indentation for each
 
level.  Its value should be an integer.  This is set to '4' by default,
 
level.  Its value should be an integer.  This is set to '4' by default,
 
which is the convention used when indenting WML.
 
which is the convention used when indenting WML.
 +
 +
By default, Wesnoth Mode will use spaces for indentation.  Tabs can instead be used with the following:
 +
 +
(add-hook 'wesnoth-mode-hook
 +
  '(lambda ()
 +
    (setq indent-tabs-mode t
 +
          tab-width wesnoth-base-indent)))
 +
  
 
'wesnoth-warning-face' is the face used to display the overlay for
 
'wesnoth-warning-face' is the face used to display the overlay for
warnings detected when checking WML (See @ref{Checking WML}).  By
+
warnings detected when checking WML (See [[#Validating WML|Validating WML]]).  By
default this is a red underline.  Use of this face may not be supported
+
default this is a red underline.  Note: use of this face may not be supported
 
under XEmacs.
 
under XEmacs.
  
 
===Wesnoth Update===
 
===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 Update is an extension to Wesnoth Mode which retrieves information regarding valid WML structure using WML included with Wesnoth.  To update this information, two variables need to be set appropriately:
'wesnoth-root-directory', 'wesnoth-update-output-directory' and
+
'wesnoth-root-directory' and 'wesnoth-update-output-directory'.
'wesnoth-addition-file'.
 
  
 
'wesnoth-root-directory' should be the path to the root directory of
 
'wesnoth-root-directory' should be the path to the root directory of
 
a Wesnoth installation or Wesnoth source code.  Wesnoth Update will
 
a Wesnoth installation or Wesnoth source code.  Wesnoth Update will
 
search recursively in this directory for WML, using the information
 
search recursively in this directory for WML, using the information
found to provide context-sensitive completion and WML checking.
+
found to provide context-sensitive completion and WML validation.
  
 
'wesnoth-update-output-directory' specifies the path to store the
 
'wesnoth-update-output-directory' specifies the path to store the
 
WML data found.  This path should be within the 'load-path', and
 
WML data found.  This path should be within the 'load-path', and
 
preferably, in the same directory as Wesnoth Mode.
 
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:
 
For example:
 
  (setq wesnoth-root-directory "/usr/local/share/wesnoth/"
 
  (setq wesnoth-root-directory "/usr/local/share/wesnoth/"
      wesnoth-addition-file
+
       wesnoth-update-output-directory "~/.emacs.d/wesnoth-mode/")
      "~/.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
 
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
+
WML data ready for use for the current and future sessions.  Note:
note, 'wesnoth-update' may take some time to run.)
+
'wesnoth-update' may take some time to run.
 +
 
 +
Wesnoth Mode 1.3.6 uses WML data retrieved from Wesnoth 1.5.11, by default.
 +
 
 +
===Addition File===
 +
'wesnoth-addition-file' specifies the `addition file' to use.  An
 +
addition file is an outline of a valid WML structure which is processed to provide more comprehensive completion of validation by providing access to element which may not have been available when running [[#Wesnoth Update|Wesnoth Update]]
 +
 
 +
The value of 'wesnoth-addition-file' shield be set as the path to a suitable addition file.  A sample addition file is included with Wesnoth Mode.
 +
 
 +
For example, the following could be used to specify an addition file:
 +
 
 +
(setq wesnoth-addition-file
 +
      "~/.emacs.d/wesnoth-mode/wesnoth-wml-additions.cfg")
 +
 
 +
The addition file is read and information regarding WML structure
 +
updated any time WML information is required.  Therefore, no further
 +
action is required to use the updated WML data once any changes to the
 +
addition file are saved to disk.
  
 
===Macro Definitions===
 
===Macro Definitions===
Line 258: Line 307:
 
updated when needed.)  'C-u C-c C-u' can be used to clear known local
 
updated when needed.)  'C-u C-c C-u' can be used to clear known local
 
macro definitions.
 
macro definitions.
 +
 +
[[Category:Development]]
 +
[[Category:WML_Reference]]

Latest revision as of 03:24, 7 May 2023

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, validation and much more when editing WML.

This documentation attempts to provide a comprehensive guide to functionality available within Wesnoth Mode 1.3.4, 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) 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.

Wesnoth Mode can be activated as the current major-mode for a buffer 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.

Alternatively, the development version is available using git. To checkout the latest changes, the following command can be used:

 git clone git://repo.or.cz/wesnoth-mode.git

Basic Usage

Indentation

By default, Wesnoth Mode provides a style of indentation equivalent to that provided by 'wmlindent' tool distributed with Wesnoth. 'TAB' can be used to automatically indent the current line to the correct depth. 'TAB' can perform two actions depending on the context of point. When there is an incomplete element immediately preceding point, completion will be attempted, otherwise 'TAB' will perform indentation. See Tab Completion.

Wesnoth Mode will, by default, indent the current line appropriately before inserting a newline when 'RET' or 'C-j' is used. ('C-j' will also attempt to indent the new line.)

See Modifying Indentation for information on how to customise the behaviour of automatic indentation.

Navigation

Built-in commands for navigation are available. This section describes additional or modified navigation commands specific to Wesnoth Mode. 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 no more elements are available in that direction, the position of point will not change.

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.

Structured navigation is available with 'C-M-n' and 'C-M-p' providing the ability to move to the next and previous blocks (respectively) which are at the same depth as the element where the command was invoked. 'C-M-d' will move to the child of the element at point and 'C-M-u' moving to the corresponding parent element.

Editing Extras

Additional commands have been added to assist editing regions of WML. 'C-M-k' can be used to kill the element at point up to the corresponding closing element, including all contents. Also, when point is at an opening element, the mark can be placed at the end of the corresponding closing element using 'C-M-SPC'.

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 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, the arguments for the current macro are also available for completion. Any project-local or custom macros can be made available for completion by opening the file in which they are defined. For information on completing project-local macros, see 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 minibuffer prompt. When no matches are found for the partial element, 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 next '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 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, a notification will be displayed and no element will be inserted.

Validating WML

Usage and Capabilities

Validating WML in the current buffer can be performed using '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 'C-c C-f' (or 'C-x `') and 'C-c C-b', respectively. For visibility, warnings will be underlined in red by default. Note: Warning underlines may not be available in XEmacs.

The WML validation 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 tested 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 validation is specific to the version of WML known by Wesnoth Mode. See Wesnoth Update for more information.

Footnotes
(1) Macro Definitions

Customisation

Modifying 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 this be non-nil for all new WML.

'wesnoth-indent-preprocessor-bol' controls how preprocessor statements should be indented. If non-nil, all preprocessor statements will be indented to the beginning of the line. Otherwise, preprocessor statements will be indented as to the level indicated by its context.

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.

The following can be used to change 'RET' to automatically indent the newline:

(add-hook 'wesnoth-mode-hook
  '(lambda ()
    (define-key wesnoth-mode-map (kbd "C-m")
    'wesnoth-newline-and-indent)))

'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.

By default, Wesnoth Mode will use spaces for indentation. Tabs can instead be used with the following:

(add-hook 'wesnoth-mode-hook
  '(lambda ()
    (setq indent-tabs-mode t
          tab-width wesnoth-base-indent)))


'wesnoth-warning-face' is the face used to display the overlay for warnings detected when checking WML (See Validating WML). By default this is a red underline. Note: use of this face may not be supported under XEmacs.

Wesnoth Update

Wesnoth Update is an extension to Wesnoth Mode which retrieves information regarding valid WML structure using WML included with Wesnoth. To update this information, two variables need to be set appropriately: 'wesnoth-root-directory' and 'wesnoth-update-output-directory'.

'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 validation.

'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.

For example:

(setq wesnoth-root-directory "/usr/local/share/wesnoth/"
      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. Note: 'wesnoth-update' may take some time to run.

Wesnoth Mode 1.3.6 uses WML data retrieved from Wesnoth 1.5.11, by default.

Addition File

'wesnoth-addition-file' specifies the `addition file' to use. An addition file is an outline of a valid WML structure which is processed to provide more comprehensive completion of validation by providing access to element which may not have been available when running Wesnoth Update

The value of 'wesnoth-addition-file' shield be set as the path to a suitable addition file. A sample addition file is included with Wesnoth Mode.

For example, the following could be used to specify an addition file:

(setq wesnoth-addition-file
     "~/.emacs.d/wesnoth-mode/wesnoth-wml-additions.cfg")

The addition file is read and information regarding WML structure updated any time WML information is required. Therefore, no further action is required to use the updated WML data once any changes to the addition file are saved to disk.

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.

This page was last edited on 7 May 2023, at 03:24.