wesnoth-mode.texi

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