* wesnoth-mode.el (wesnoth-complete-macro): No longer force macros to be
[wesnoth-mode.git] / wesnoth-mode.texi
blob54fb37c90b95a924f11fa73918dcd27499978ddb
1 \input texinfo
2 @setfilename wesnoth-mode.info
3 @settitle Wesnoth Mode Manual
5 @set VERSION 1.3.5
6 @set WMLVERSION 1.5.11
7 @set DATE February 2009
9 @dircategory Emacs
10 @direntry
11 * Wesnoth Mode: (wesnoth-mode).         Major-mode for editing WML
12 @end direntry
14 @set MAINTAINERSITE @uref{http://www.wesnoth.org/forum/viewtopic.php?t=13798}
15 @set AUTHOR Chris Mann
16 @finalout
18 @copying
19 This manual is for Wesnoth Mode (version @value{VERSION}).
21 Copyright @copyright{} 2008, 2009 Chris Mann
23 @quotation
24 This program is free software; you can redistribute it and/or modify it
25 under the terms of the GNU General Public License as published by the
26 Free Software Foundation; either version 2 of the License, or (at your
27 option) any later version.
29 This program is distributed in the hope that it will be useful, but
30 WITHOUT ANY WARRANTY; without even the implied warranty of
31 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
32 General Public License for more details.
34 You should have received a copy of the GNU General Public License along
35 with this program; if not, write to the Free Software Foundation, Inc.,
36 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
37 @end quotation
38 @end copying
40 @titlepage
41 @title Wesnoth Mode Manual
42 @subtitle Version @value{VERSION}
43 @author by @value{AUTHOR}
44 @page
46 @vskip 0pt plus 1filll
47 @insertcopying
48 @end titlepage
50 @summarycontents
52 @ifnottex
53 @node Top, Introduction, (dir), (dir)
54 @top Wesnoth Mode Manual
56 @insertcopying
57 @end ifnottex
59 @menu
60 * Introduction::                Getting started
61 * Basic Usage::                 Moving around within WML
62 * Inserting Elements::          Insertion and completion of elements
63 * Validating WML::              Validating WML for common problems
64 * Customisation::               Available customisation options
66 @detailmenu
67  --- Detailed Node Listing ---
69 Introduction
71 * Summary::                     Introduction to Wesnoth Mode
72 * Getting Started::             How to start Wesnoth Mode
74 Basic Usage
76 * Indentation::                 Indentation usage and styles
77 * Navigation::                  Common WML navigation
78 * Editing Extras::              Specialised editing commands
80 Inserting Elements
82 * Standard Completion::         Completion commands and functionality
83 * Tab Completion::              Element tab completion
84 * Wrapping Elements::           Wrapping elements around sets of tags
85 * Missing Elements::            Finding and inserting missing elements
87 Validating WML
89 * Usage and Capabilities::      What to expect when validating WML
91 Customisation
93 * Modifying Indentation::       Customising WML indentation
94 * Wesnoth Update::              Using and configuring Wesnoth Update
95 * Macro Definitions::           Making project-local macros known
97 @end detailmenu
98 @end menu
100 @node Introduction, Basic Usage, Top, Top
101 @chapter Introduction
103 @menu
104 * Summary::                     Introduction to Wesnoth Mode
105 * Getting Started::             How to start Wesnoth Mode
106 @end menu
108 @node Summary, Getting Started, Introduction, Introduction
109 @section Summary
111 Wesnoth Mode is a major mode for Emacs which assists in the editing of
112 the markup language extensively used in Wesnoth, a turn-based fantasy
113 strategy game.  From the Wesnoth Wiki: "The Wesnoth Markup Language
114 (WML) is used to code almost everything in Wesnoth, including scenarios,
115 units, savefiles, and the user interface layout."
116 @footnote{@uref{http://www.wesnoth.org/wiki/ReferenceWML}}
118 Wesnoth Mode is supported under GNU Emacs 21 onwards and (with some
119 minor limitations) XEmacs 21.  Wesnoth Mode adds support for syntax
120 highlighting, automatic indentation, context-sensitive completion,
121 validation and more when editing WML.
123 This documentation attempts to provide a comprehensive guide to
124 functionality available within Wesnoth Mode @value{VERSION}, and assumes
125 you are familiar with basic usage, terminology and customisation of
126 Emacs.  For more information, please refer to the Emacs
127 manual. @footnote{@uref{http://www.gnu.org/software/emacs/manual/html_node/emacs/}}
129 @node Getting Started, , Summary, Introduction
130 @section Getting Started
132 To use Wesnoth Mode, add the following to your @file{.emacs}:
133 @lisp
134 (add-to-list 'load-path "path/to/wesnoth-mode")
135 (autoload 'wesnoth-mode "wesnoth-mode" "Major mode for editing WML." t)
136 @end lisp
137 Optionally adding:
138 @lisp
139 (add-to-list 'auto-mode-alist '("\\.cfg\\'" . wesnoth-mode))
140 @end lisp
141 to automatically load Wesnoth Mode for all files with a `.cfg'
142 extension.
144 Wesnoth Mode can be activated as the current major-mode for a buffer via
145 @kbd{M-x wesnoth-mode}.
147 The latest release of Wesnoth Mode along with release notes can be found
148 at @uref{http://www.wesnoth.org/forum/viewtopic.php?t=13798}.
150 Alternatively, the development version is available using git.  To
151 checkout the latest changes, the following command can be used:
152 @example
153 @code{git clone git://repo.or.cz/wesnoth-mode.git}.
154 @end example
156 @node Basic Usage, Inserting Elements, Introduction, Top
157 @chapter Basic Usage
159 @menu
160 * Indentation::                     Common WML navigation
161 * Navigation::                      Moving backward and forward across elements
162 * Editing Extras::                  Specialised editing commands
163 @end menu
165 @node Indentation, Navigation, Basic Usage, Basic Usage
166 @section Indentation
167 By default, Wesnoth Mode provides a style of indentation equivalent to
168 that provided by @code{wmlindent} tool distributed with Wesnoth.
169 @kbd{TAB} can be used to automatically indent the current line to the
170 correct depth.  @kbd{TAB} can perform two actions depending on the
171 context of point.  When there is an incomplete element immediately
172 preceding point, completion will be attempted, otherwise @kbd{TAB} will
173 perform indentation.  See @ref{Tab Completion}.
175 Wesnoth Mode will, by default, indent the current line appropriately
176 before inserting a newline when @kbd{RET} or @kbd{C-j} is
177 used. (@kbd{C-j} will also attempt to indent the new line.)
179 See @ref{Modifying Indentation} for information on how to customise the
180 behaviour of automatic indentation.
182 @node Navigation, Editing Extras, Indentation, Basic Usage
183 @section Navigation
185 Built-in commands for navigation are available.  This section describes
186 additional or modified navigation commands specific to Wesnoth Mode.
188 Next and previous opening elements can be navigated using @kbd{C-M-e}
189 and @kbd{C-M-a}, respectively.  In each case, point will be positioned
190 immediately before the element.  When no more elements are available in
191 that direction, the position of point will not change.
193 Moving to the matching element in a pair or locating the parent element
194 (depending on the position of point) can be performed via @kbd{C-c C-o}.
195 When point is on the same line as an opening element, such as an opening
196 tag or opening preprocessor statement it will be moved to the start of
197 the matching closing element.  Otherwise, the jump will position point
198 at the beginning of the corresponding opening element.
200 Structured navigation is available with @kbd{C-M-n} and @kbd{C-M-p}
201 providing the ability to move to the next and previous blocks
202 (respectively) which are at the same depth as the element where the
203 command was invoked.  @kbd{C-M-d} will move to the child of the element
204 at point and @kbd{C-M-u} moving to the corresponding parent element.
206 @node Editing Extras,  , Navigation, Basic Usage
207 @section Editing Extras
209 Additional commands have been added to assist editing regions of WML.
210 @kbd{C-M-k} can be used to kill the element at point up to the
211 corresponding closing element, including all contents.  Also, when point
212 is at an opening element, the mark can be placed at the end of the
213 corresponding closing element using @kbd{C-M-SPC}.
215 @node Inserting Elements, Validating WML, Basic Usage, Top
216 @chapter Inserting Elements
218 @menu
219 * Standard Completion::         Completion commands and functionality
220 * Tab Completion::              Element tab completion
221 * Wrapping Elements::           Wrapping elements around sets of tags
222 * Missing Elements::            Finding and inserting missing elements
223 @end menu
225 @node Standard Completion, Tab Completion, Inserting Elements, Inserting Elements
226 @section Standard Completion
228 Tags can be inserted via @kbd{C-c C-t} and alternatively @kbd{M-TAB}
229 (when this is not shadowed by the Window Manager, etc.) which will
230 prompt for the tag to add.  The tag entered into the minibuffer prompt
231 and its matching closing tag will be inserted and point positioned
232 between.
234 Attributes can be inserted via @kbd{C-c C-a}.  Any attribute entered at
235 the prompt will be inserted along with the `=', with point immediately
236 following.
238 Both tag and attribute completion is context-sensitive.  If an element
239 is available in WML and not listed for completion, it can be added to
240 the `addition file'.  See @ref{Addition File} for more information.
242 Macro insertion can be performed via @kbd{C-c C-m}.  Any arguments known
243 to be required for the macro will be prompted and inserted in order.
244 Insertion will be aborted if no value for an argument is provided.  When
245 within a macro definition, the arguments for the current macro are also
246 available for completion.  Any project-local or custom macros can be
247 made available for completion by opening the file in which they are
248 defined.  For information, see @ref{Macro Definitions}.
250 Preprocessor statements are available for insertion via @kbd{C-c C-p}.
251 Closing elements for preprocessor statements will be automatically
252 inserted where possible, with point positioned between.  Otherwise,
253 point will be placed immediately after the inserted text.
255 @node Tab Completion, Wrapping Elements, Standard Completion, Inserting Elements
256 @section Tab Completion
258 Completion can also be performed immediately within the buffer via
259 @kbd{TAB} on a partial element.  For example:
260 @example
261 [scenario]
262     vil-!-
263 @end example
264 Where @code{-!-} is the position of point.  Using @kbd{TAB} in the
265 example will complete to @code{vil} to @code{village_gold=}.  Tags,
266 macros and preprocessor statements can be completed similarly.  When the
267 current line does not contain a partially completed element, @kbd{TAB}
268 will perform indentation on the current line.
270 When there is more than one possible completion, a minibuffer prompt
271 will be provided, with the partial element entered.  @kbd{TAB} can be
272 used here to perform completion.  If multiple matches are available,
273 completion will be performed up to the smallest common substring with
274 further completion available via the minibuffer prompt.  When no matches
275 are found for the partial element, completion will not be prompted.
277 When completing opening preprocessor statements and tags, Wesnoth Mode
278 will also attempt to insert a matching closing element if one is not
279 already available, acting in much the same way as if the element was
280 added via the minibuffer prompt.  However, if an matching closing
281 element is available, only the element at point will be completed.
283 A numeric argument can be provided when performing tab completion of
284 opening elements to wrap around the next @i{n} blocks.  For
285 example, to wrap the completed opening and closing pair around the next
286 three blocks, @kbd{C-u 3 TAB} can be used.  See @ref{Wrapping Elements}
287 for more information.
289 @node Wrapping Elements, Missing Elements, Tab Completion, Inserting Elements
290 @section Wrapping Elements
291 When inserting tags and some preprocessor statements, either via their
292 respective insertion command or via @kbd{TAB}, an optional numeric
293 argument can be provided to specify the number of `blocks' to wrap the
294 element around.  For example:
296 @example
297 [multiplayer]
298  -!-[part]
299         ...
300     [/part]
301     [part]
302         ...
303     [/part]
304     [event]
305         ...
306 @end example
308 Where point is at the position indicated by @code{-!-}.  A pair of
309 @code{story} tags can be inserted around both existing @code{part} tags
310 using @kbd{C-u 2 C-c C-t story}.  When the number of blocks specified to
311 wrap around exceeds the number of blocks available, Wesnoth Mode will
312 only wrap around the number of available so that the nesting of elements
313 is correct.
315 @node Missing Elements, , Wrapping Elements, Inserting Elements
316 @section Missing Elements
317 Missing closing elements can be inserted using @kbd{C-c C-/}.  By
318 default, this will insert the first missing closing element found in the
319 current buffer at point.  If all elements appear to be matched or if
320 there is an excess of closing tags, a notification will be displayed and
321 no element will be inserted.
323 @node Validating WML, Customisation, Inserting Elements, Top
324 @chapter Validating WML
326 @menu
327 * Usage and Capabilities::      What to expect when validating WML
328 @end menu
330 @node Usage and Capabilities, , Validating WML, Validating WML
331 @section Usage and Capabilities
333 Validating WML in the current buffer can be performed using @kbd{C-c C-c},
334 with a summary of all warnings found reported in a separate buffer.
335 Point can be jumped to the next and previous warning using @kbd{C-c C-f}
336 (or @kbd{C-x `}) and @kbd{C-c C-b}, respectively.  For visibility,
337 warnings will be underlined in red by default.  @i{Note: Warning
338 underlines may not be available in XEmacs.}
340 The WML validation built-in to Wesnoth Mode is not intended to be an
341 alternative to tools such as `wmllint', but may often be a convenient
342 substitute while editing WML.
344 The following conditions can be tested in Wesnoth Mode:
345 @itemize
346 @item Correct nesting of tags and preprocessor statements
347 @item Known macro definitions @footnote{see @ref{Macro Definitions}}
348 @item Availability of elements within the given context
349 @item Arguments are given to preprocessor statements when required
350 @item Attributes have a value assigned
351 @item Corresponding FOREACH..NEXT pairs
352 @end itemize
354 WML validation is specific to the version of WML known by Wesnoth Mode.
355 See @ref{Wesnoth Update} for more information.
357 @node Customisation, , Validating WML, Top
358 @chapter Customisation
360 @menu
361 * Modifying Indentation::       Customising WML indentation
362 * Wesnoth Update::              Using and configuring Wesnoth Update
363 * Macro Definitions::           making project-local macros known
364 @end menu
366 @node Modifying Indentation, Wesnoth Update, Customisation, Customisation
367 @section Modifying Indentation
369 The style of indentation can be customised using
370 @code{wesnoth-indent-savefile}.  The default value is @code{t},
371 which results in all children being indented a level deeper than their
372 parent.  When set to @code{nil}, children will be indented to the same
373 level as their parent element.  This option is provided only for
374 consistency when editing (very) old WML.  It is recommended that this be
375 non-nil for all new WML.
377 @code{wesnoth-indent-preprocessor-bol} controls how preprocessor
378 statements should be indented.  If non-nil, all preprocessor statements
379 will be indented to the beginning of the line.  Otherwise, preprocessor
380 statements will be indented as to the level indicated by its context.
382 By default, Wesnoth Mode will attempt indentation of the current line
383 and create a newline and when @kbd{RET} or @kbd{C-j} are used.
384 @code{wesnoth-auto-indent-flag} controls whether Wesnoth Mode will
385 attempt to indent the current line automatically.  Setting this to
386 @code{nil} will prevent automatic indentation.  Note that this does not
387 affect the behaviour of @kbd{C-j} performing indentation following the
388 newline; this only determines whether indentation will be automatically
389 performed on the current line.
391 The following can be used to change @kbd{RET} to automatically indent the
392 newline:
393 @example
394 (add-hook 'wesnoth-mode-hook
395   '(lambda ()
396     (define-key wesnoth-mode-map (kbd ``C-m'')
397     'wesnoth-newline-and-indent)))
398 @end example
400 @code{wesnoth-base-indent} controls the depth of indentation for each
401 level.  Its value should be an integer.  This is set to `4' by default,
402 which is the convention used when indenting WML.
404 By default, Wesnoth Mode will use spaces for indentation.  Tabs can instead be used with the following:
405 @example
406 (add-hook 'wesnoth-mode-hook
407   '(lambda ()
408     (setq indent-tabs-mode t
409           tab-width wesnoth-base-indent)))
410 @end example
412 @code{wesnoth-warning-face} is the face used to display the overlay for
413 warnings detected when Validating WML (See @ref{Validating WML}).  By
414 default this is a red underline.  @i{Note: use of this face may not be supported
415 under XEmacs.}
417 @node Wesnoth Update, Addition File, Modifying Indentation, Customisation
418 @section Wesnoth Update
420 Wesnoth Update is an extension to Wesnoth Mode which retrieves
421 information regarding valid WML structure using WML included with
422 Wesnoth.  To update WML data known to Wesnoth Mode, two variables need
423 to be set appropriately: @code{wesnoth-root-directory} and
424 @code{wesnoth-update-output-directory}.
426 @code{wesnoth-root-directory} should be the path to the root directory
427 of a Wesnoth installation or Wesnoth source code.  Wesnoth Update will
428 search recursively in this directory for WML, using the information
429 found to provide context-sensitive completion and WML validation.
431 @code{wesnoth-update-output-directory} specifies the path to store the
432 WML data found.  This path should be within the @code{load-path}, and
433 preferably, in the same directory as Wesnoth Mode.
435 For example:
436 @example
437 (setq wesnoth-root-directory "/usr/local/share/wesnoth/"
438       wesnoth-update-output-directory "~/.emacs.d/wesnoth-mode/")
439 @end example
441 Once set, @kbd{M-x wesnoth-update} will generate and load a new cache of
442 WML data ready for use for the current and future sessions.  @i{Note:
443 'wesnoth-update' may take some time to run.}
445 Wesnoth Mode @value{VERSION} uses WML data retrieved from Wesnoth
446 @value{WMLVERSION}, by default.
448 @node Addition File, Macro Definitions, Wesnoth Update, Customisation
449 @section Addition File
451 @code{wesnoth-addition-file} specifies the `addition file' to use.  An
452 addition file is an outline of a valid WML structure which is processed
453 to provide more comprehensive completion and validation by providing
454 access to elements which may not have been available when running
455 @code{wesnoth-update}.
457 The value of @code{wesnoth-addition-file} should be set as the path to a
458 suitable addition file.  A sample addition file is included with Wesnoth
459 Mode.
461 For example, the following could be used to specify an addition file:
462 @example
463 (setq wesnoth-addition-file
464       "~/.emacs.d/wesnoth-mode/wesnoth-wml-additions.cfg")
465 @end example
467 The addition file is read and information regarding WML structure
468 updated any time WML information is required.  Therefore, no further
469 action is required to use the updated WML data once any changes to the
470 addition file are saved to disk.
472 @node Macro Definitions, , Wesnoth Update, Customisation
473 @section Macro Definitions
475 While built-in macros are always available, local macro definitions are
476 automatically scanned and made known to Wesnoth Mode for each WML file
477 which is loaded in the session. @kbd{C-c C-u} can be used to update the
478 known macro definitions for any buffer which has since been
479 modified. (Note that this is not required when the macro is defined in
480 the WML file currently being edited as such definitions will be
481 automatically updated when needed.)  @kbd{C-u C-c C-u} can be used to
482 clear known local macro definitions.
484 @bye
486 @c Local Variables: 
487 @c mode: texinfo
488 @c TeX-master: t
489 @c End: