*WML* buffer can now be buried via 'q'.

[wesnoth-mode.git] / wesnoth-mode.texi

\input texinfo
@setfilename wesnoth-mode.info
@settitle Wesnoth Mode Manual

@set VERSION 1.3.5+git
@set WMLVERSION 1.5.14
@set DATE February 2009

@dircategory Emacs
@direntry
* Wesnoth Mode: (wesnoth-mode).         Major-mode for editing WML
@end direntry

@set MAINTAINERSITE @uref{http://www.wesnoth.org/forum/viewtopic.php?t=13798}
@set AUTHOR Chris Mann
@finalout

@copying
This manual is for Wesnoth Mode (version @value{VERSION}).

Copyright @copyright{} 2008, 2009 Chris Mann

@quotation
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
@end quotation
@end copying

@titlepage
@title Wesnoth Mode Manual
@subtitle Version @value{VERSION}
@author by @value{AUTHOR}
@page

@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@summarycontents

@ifnottex
@node Top, Introduction, (dir), (dir)
@top Wesnoth Mode Manual

@insertcopying
@end ifnottex

@menu
* Introduction::                Getting started
* Basic Usage::                 Moving around within WML
* Inserting Elements::          Insertion and completion of elements
* Validating WML::              Validating WML for common problems
* Customisation::               Available customisation options

@detailmenu
 --- Detailed Node Listing ---

Introduction

* Summary::                     Introduction to Wesnoth Mode
* Getting Started::             How to start Wesnoth Mode

Basic Usage

* Indentation::                 Indentation usage and styles
* Navigation::                  Common WML navigation
* Editing Extras::              Specialised editing commands

Inserting Elements

* Standard Completion::         Completion commands and functionality
* Tab Completion::              Element tab completion
* Wrapping Elements::           Wrapping elements around sets of tags
* Missing Elements::            Finding and inserting missing elements

Validating WML

* Usage and Capabilities::      What to expect when validating WML

Customisation

* Modifying Indentation::       Customising WML indentation
* Wesnoth Update::              Using and configuring Wesnoth Update
* Addition File::               Extending known WML
* Macro Definitions::           Making project-local macros known

@end detailmenu
@end menu

@node Introduction, Basic Usage, Top, Top
@chapter Introduction

@menu
* Summary::                     Introduction to Wesnoth Mode
* Getting Started::             How to start Wesnoth Mode
@end menu

@node Summary, Getting Started, Introduction, Introduction
@section 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, save files, and the user interface layout."
@footnote{@uref{http://www.wesnoth.org/wiki/ReferenceWML}}

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 more when editing WML.

This documentation attempts to provide a comprehensive guide to
functionality available within Wesnoth Mode @value{VERSION}, and assumes
you are familiar with basic usage, terminology and customisation of
Emacs.  For more information, please refer to the Emacs
manual. @footnote{@uref{http://www.gnu.org/software/emacs/manual/html_node/emacs/}}

@node Getting Started, , Summary, Introduction
@section Getting Started

To use Wesnoth Mode, add the following to your @file{.emacs}:
@lisp
(add-to-list 'load-path "path/to/wesnoth-mode")
(autoload 'wesnoth-mode "wesnoth-mode" "Major mode for editing WML." t)
@end lisp
Optionally adding:
@lisp
(add-to-list 'auto-mode-alist '("\\.cfg\\'" . wesnoth-mode))
@end lisp
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
@kbd{M-x wesnoth-mode}.

The latest release of Wesnoth Mode along with release notes can be found
at @uref{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:
@example
@code{git clone git://repo.or.cz/wesnoth-mode.git}.
@end example

@node Basic Usage, Inserting Elements, Introduction, Top
@chapter Basic Usage

@menu
* Indentation::                     Common WML navigation
* Navigation::                      Moving backward and forward across elements
* Editing Extras::                  Specialised editing commands
@end menu

@node Indentation, Navigation, Basic Usage, Basic Usage
@section Indentation
By default, Wesnoth Mode provides a style of indentation equivalent to
that provided by @code{wmlindent} tool distributed with Wesnoth.
@kbd{TAB} can be used to automatically indent the current line to the
correct depth.  Two actions can be performed depending on the context of
point.  When there is an incomplete element immediately preceding point,
completion will be attempted, otherwise indentation will be performed.
See @ref{Tab Completion}.

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

See @ref{Modifying Indentation} for information on how to customise the
behaviour of automatic indentation.

@node Navigation, Editing Extras, Indentation, Basic Usage
@section 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 @kbd{C-M-e}
and @kbd{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 @kbd{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 @kbd{C-M-n} and @kbd{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.  @kbd{C-M-d} will move to the child of the element
at point and @kbd{C-M-u} moving to the corresponding parent element.

@node Editing Extras,  , Navigation, Basic Usage
@section Editing Extras

Additional commands have been added to assist editing regions of WML.
@kbd{C-M-k} can be used to kill the element at point up to the
corresponding closing element, including all contents.  A prefix
argument can be provided to kill the next @i{n} blocks of elements.
Also, when point is at an opening element, the mark can be placed at the
end of the corresponding closing element using @kbd{C-M-SPC}.

@node Inserting Elements, Validating WML, Basic Usage, Top
@chapter Inserting Elements

@menu
* Standard Completion::         Completion commands and functionality
* Tab Completion::              Element tab completion
* Wrapping Elements::           Wrapping elements around sets of tags
* Missing Elements::            Finding and inserting missing elements
@end menu

@node Standard Completion, Tab Completion, Inserting Elements, Inserting Elements
@section Standard Completion

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

Attributes can be inserted via @kbd{C-c C-a}.  Any attribute entered at
the prompt will be inserted along with the `=', with point immediately
following.

Both tag and attribute completion is context-sensitive.  If an element
is available in WML and not listed for completion, it can be added to
the `addition file'.  See @ref{Addition File} for more information.

Macro insertion can be performed via @kbd{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, see @ref{Macro Definitions}.

Preprocessor statements are available for insertion via @kbd{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.

@node Tab Completion, Wrapping Elements, Standard Completion, Inserting Elements
@section Tab Completion

Completion can also be performed immediately within the buffer via
@kbd{TAB} on a partial element.  For example:
@example
[scenario]
    vil-!-
@end example
Where @code{-!-} is the position of point.  Using @kbd{TAB} in the
example will complete to @code{vil} to @code{village_gold=}.  Tags,
macros and preprocessor statements can be completed similarly.  When the
current line does not contain a partially completed element, @kbd{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.  @kbd{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 @i{n} blocks.  For
example, to wrap the completed opening and closing pair around the next
three blocks, @kbd{C-u 3 TAB} can be used.  See @ref{Wrapping Elements}
for more information.

@node Wrapping Elements, Missing Elements, Tab Completion, Inserting Elements
@section Wrapping Elements
When inserting tags and some preprocessor statements, either via their
respective insertion command or via @kbd{TAB}, an optional numeric
argument can be provided to specify the number of `blocks' to wrap the
element around.  For example:

@example
[multiplayer]
 -!-[part]
        ...
    [/part]
    [part]
        ...
    [/part]
    [event]
        ...
@end example

Where point is at the position indicated by @code{-!-}.  A pair of
@code{story} tags can be inserted around both existing @code{part} tags
using @kbd{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.

@node Missing Elements, , Wrapping Elements, Inserting Elements
@section Missing Elements
Missing closing elements can be inserted using @kbd{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.

@node Validating WML, Customisation, Inserting Elements, Top
@chapter Validating WML

@menu
* Usage and Capabilities::      What to expect when validating WML
@end menu

@node Usage and Capabilities, , Validating WML, Validating WML
@section Usage and Capabilities

Validating WML in the current buffer can be performed using @kbd{C-c C-c},
with a summary of all warnings found reported 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 will be underlined in red by default.  @i{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:
@itemize
@item Correct nesting of tags and preprocessor statements
@item Known macro definitions @footnote{see @ref{Macro Definitions}}
@item Availability of elements within the given context
@item Arguments are given to preprocessor statements when required
@item Attributes have a value
@item Corresponding FOREACH..NEXT pairs
@end itemize

WML validation is specific to the version of WML known by Wesnoth Mode.
See @ref{Wesnoth Update} for more information.

@node Customisation, , Validating WML, Top
@chapter Customisation

@menu
* Modifying Indentation::       Customising WML indentation
* Wesnoth Update::              Using and configuring Wesnoth Update
* Addition File::               Extending known WML
* Macro Definitions::           Making project-local macros known
@end menu

@node Modifying Indentation, Wesnoth Update, Customisation, Customisation
@section Modifying Indentation

The style of indentation can be customised using
@code{wesnoth-indent-savefile}.  The default value is @code{t},
which results in all children being indented a level deeper than their
parent.  When set to @code{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.

@code{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 @kbd{RET} or @kbd{C-j} are used.
@code{wesnoth-auto-indent-flag} controls whether Wesnoth Mode will
attempt to indent the current line automatically.  Setting this to
@code{nil} will prevent automatic indentation.  Note that this does not
affect the behaviour of @kbd{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 @kbd{RET} to automatically indent the
newline:
@lisp
(add-hook 'wesnoth-mode-hook
  '(lambda ()
    (define-key wesnoth-mode-map (kbd ``C-m'')
    'wesnoth-newline-and-indent)))
@end lisp

@code{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:
@lisp
(add-hook 'wesnoth-mode-hook
  '(lambda ()
    (setq indent-tabs-mode t
          tab-width wesnoth-base-indent)))
@end lisp

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

@node Wesnoth Update, Addition File, Modifying Indentation, Customisation
@section Wesnoth Update

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

@code{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.

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

For example:
@lisp
(setq wesnoth-root-directory "/usr/local/share/wesnoth/"
      wesnoth-update-output-directory "~/.emacs.d/wesnoth-mode/")
@end lisp

Once set, @kbd{M-x wesnoth-update} will generate and load a new cache of
WML data ready for use for the current and future sessions.  @i{Note:
'wesnoth-update' may take some time to run.}

Wesnoth Mode @value{VERSION} uses WML data retrieved from Wesnoth
@value{WMLVERSION}, by default.

@node Addition File, Macro Definitions, Wesnoth Update, Customisation
@section Addition File

@code{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 and validation by providing
access to elements which may not have been available when running
@code{wesnoth-update}.

The value of @code{wesnoth-addition-file} should 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:
@lisp
(setq wesnoth-addition-file
      "~/.emacs.d/wesnoth-mode/wesnoth-wml-additions.cfg")
@end lisp

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.

@node Macro Definitions, , Addition File, Customisation
@section 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. @kbd{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.)  @kbd{C-u C-c C-u} can be used to
clear known local macro definitions.

@bye

@c Local Variables: 
@c mode: texinfo
@c TeX-master: t
@c End: