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.2
   7 @set DATE October 2008
   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 @c Subheadings inside a table.
  21 @macro tsubheading{text}
  22 @ifinfo
  23 @subsubheading \text\
  24 @end ifinfo
  25 @ifnotinfo
  26 @item @b{\text\}
  27 @end ifnotinfo
  28 @end macro
  29
  30 @copying
  31 This manual is for Wesnoth Mode (version @value{VERSION}).
  32
  33 Copyright @copyright{} 2008 Chris Mann
  34
  35 @quotation
  36 This program is free software; you can redistribute it and/or modify it
  37 under the terms of the GNU General Public License as published by the
  38 Free Software Foundation; either version 2 of the License, or (at your
  39 option) any later version.
  40
  41 This program is distributed in the hope that it will be useful, but
  42 WITHOUT ANY WARRANTY; without even the implied warranty of
  43 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  44 General Public License for more details.
  45
  46 You should have received a copy of the GNU General Public License along
  47 with this program; if not, write to the Free Software Foundation, Inc.,
  48 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  49 @end quotation
  50 @end copying
  51
  52 @titlepage
  53 @title Wesnoth Mode Manual
  54 @subtitle Version @value{VERSION}
  55 @author by Chris Mann
  56
  57 @page
  58
  59 @vskip 0pt plus 1fill
  60 @insertcopying
  61 @end titlepage
  62
  63 @contents
  64 @ifnottex
  65 @node Top, Introduction, (dir), (dir)
  66 @top Wesnoth Mode Manual
  67
  68 @insertcopying
  69 @end ifnottex
  70
  71 @menu
  72 * Introduction::                Getting started
  73 * Navigation::                  Moving around within WML
  74 * Inserting Elements::
  75 * Checking WML::
  76 * Customisation::               Available customisation options
  77 * Index::                       Documentation Index
  78 * Key Index::                   Index for Key-Bindings
  79
  80 @detailmenu
  81  --- Detailed Node Listing ---
  82
  83 Introduction
  84
  85 * Summary::
  86 * Getting Started::
  87
  88 Navigation
  89
  90 * Moving Across Elements::
  91 * Matching Elements::
  92
  93 Inserting Elements
  94
  95 * Inserting Tags::
  96 * Inserting Attributes::
  97 * Inserting Macros::
  98 * Inserting Preprocessor Statements::
  99 * Wrapping Elements::
 100 * Tab-Completion::
 101 * Missing Elements::
 102
 103 Checking WML
 104
 105 * Usage and Capabilities::
 106
 107 Customisation
 108
 109 * Indentation::
 110 * Wesnoth Update::
 111 * Macro Definitions::
 112
 113 @end detailmenu
 114 @end menu
 115
 116 @node Introduction, Navigation, Top, Top
 117 @comment  node-name,  next,  previous,  up
 118 @chapter Introduction
 119 @cindex Introduction
 120
 121 @menu
 122 * Summary::
 123 * Getting Started::
 124 @end menu
 125
 126 @node Summary, Getting Started, Introduction, Introduction
 127 @comment  node-name,  next,  previous,  up
 128 @section Summary
 129 @cindex Summary
 130
 131 Wesnoth Mode is a major mode for Emacs which assists in the editing of the
 132 markup language extensively used in Wesnoth, a turn-based fantasy strategy
 133 game.  From the Wesnoth Wiki: "The Wesnoth Markup Language (WML) is used to
 134 code almost everything in Wesnoth, including scenarios, units, savefiles, and
 135 the user interface layout." @footnote{@uref{http://www.wesnoth.org/wiki/ReferenceWML}}
 136
 137 Wesnoth Mode is supported under GNU Emacs 22 and 21 and (with some minor
 138 limitations) XEmacs 21.  Wesnoth Mode adds support for syntax
 139 highlighting, automatic indentation, context-sensitive completion,
 140 checking and much more when editing WML.
 141
 142 This documentation attempts to provide a comprehensive guide to
 143 functionality available within Wesnoth Mode, and assumes you are
 144 familiar with basic usage, terminology and customisation of Emacs.  For
 145 more information, please refer to the Emacs
 146 manual. @footnote{@uref{http://www.gnu.org/software/emacs/manual/html_node/emacs/}}
 147
 148 @node Getting Started, , Summary, Introduction
 149 @comment  node-name,  next,  previous,  up
 150 @section Getting Started
 151 @cindex Getting Started
 152
 153 To use Wesnoth Mode, add the following to your @file{.emacs}:
 154 @lisp
 155 (add-to-list 'load-path "path/to/wesnoth-mode")
 156 (autoload 'wesnoth-mode "wesnoth-mode" "Major mode for editing WML." t)
 157 @end lisp
 158 Optionally adding:
 159 @lisp
 160 (add-to-list 'auto-mode-alist '("\\.cfg\\'" . wesnoth-mode))
 161 @end lisp
 162 to automatically load Wesnoth Mode for all files with a `.cfg' extension.
 163
 164 If Wesnoth Mode is not the currently active major-mode for the current
 165 buffer, it can be started via @kbd{M-x wesnoth-mode}.
 166
 167 The latest version of Wesnoth Mode along with release notes can be found at
 168 @uref{http://www.wesnoth.org/forum/viewtopic.php?t=13798}.
 169
 170 @c TODO: Add more here.
 171
 172 @node Navigation, Inserting Elements, Introduction, Top
 173 @comment  node-name,  next,  previous,  up
 174 @chapter Navigation
 175 @cindex Navigation
 176
 177 @menu
 178 * Moving Across Elements::
 179 * Matching Elements::
 180 @end menu
 181
 182 @node Moving Across Elements, Matching Elements, Navigation, Navigation
 183 @comment  node-name,  next,  previous,  up
 184 @section Moving Across Elements
 185 @cindex Moving Across Elements
 186 @kindex @kbd{C-M-a}
 187 @kindex @kbd{C-M-e}
 188 @kindex @kbd{C-M-p}
 189 @kindex @kbd{C-M-n}
 190
 191 Next and previous opening elements can be navigated using @kbd{C-M-e}
 192 and @kbd{C-M-a}, respectively.  In each case, point will be positioned
 193 immediately before the element.
 194
 195 In addition to this, @kbd{C-M-p} and @kbd{C-M-n} can be used to jump to
 196 the previous and following tags, regardless of whether they are opening
 197 or closing.
 198
 199 @node Matching Elements,  , Moving Across Elements, Navigation
 200 @comment  node-name,  next,  previous,  up
 201 @section Matching Elements
 202 @cindex Matching Elements
 203 @kindex @kbd{C-c C-o}
 204
 205 Moving to the matching element in a pair or locating the parent element
 206 (depending on the position of point) can be performed via @kbd{C-c C-o}.
 207 When point is on the same line as an opening element, such as an opening
 208 tag or opening preprocessor statement it will be moved to the start of
 209 the matching closing element.  Otherwise, the jump will position point
 210 at the beginning of the corresponding opening element.
 211
 212 @node Inserting Elements, Checking WML, Navigation, Top
 213 @comment  node-name,  next,  previous,  up
 214 @chapter Inserting Elements
 215 @cindex Inserting Elements
 216
 217 @menu
 218 * Inserting Tags::
 219 * Inserting Attributes::
 220 * Inserting Macros::
 221 * Inserting Preprocessor Statements::
 222 * Wrapping Elements::
 223 * Tab-Completion::
 224 * Missing Elements::
 225 @end menu
 226
 227 @node Inserting Tags, Inserting Attributes, Inserting Elements, Inserting Elements
 228 @comment  node-name,  next,  previous,  up
 229 @section Inserting Tags
 230 @cindex Inserting Tags
 231 @kindex @kbd{C-c C-t}
 232 @kindex @kbd{M-TAB}
 233 Tags can be inserted via @kbd{C-c C-t} and alternatively @kbd{M-TAB} (assuming
 234 this is not shadowed by the Window Manager, etc.).  This will prompt
 235 for the tag to add.  The tag entered into the mini-buffer prompt and its
 236 matching closing tag will be inserted and point positioned between.
 237
 238 @node Inserting Attributes, Inserting Macros, Inserting Tags, Inserting Elements
 239 @comment  node-name,  next,  previous,  up
 240 @section Inserting Attributes
 241 @cindex Inserting Attributes
 242 @kindex @kbd{C-c C-a}
 243 Attributes can be inserted via @kbd{C-c C-a}.  The attribute entered at the prompt
 244 will be inserted along with the `=', with point immediately after.
 245
 246 @node Inserting Macros, Inserting Preprocessor Statements, Inserting Attributes, Inserting Elements
 247 @comment  node-name,  next,  previous,  up
 248 @section Inserting Macros
 249 @cindex Inserting Macros
 250 @kindex @kbd{C-c C-m}
 251 Macro insertion can be performed via @kbd{C-c C-m}.  If the macro
 252 entered is known to require arguments, point will be positioned before
 253 the closing curly brace ready to input any arguments, otherwise it will
 254 be positioned immediately after.  For information on completing
 255 project-local macros, see @ref{Macro Definitions}.
 256
 257 @node Inserting Preprocessor Statements, Wrapping Elements, Inserting Macros, Inserting Elements
 258 @comment  node-name,  next,  previous,  up
 259 @section Inserting Preprocessor Statements
 260 @cindex Inserting Preprocessor Statements
 261 @kindex @kbd{C-c C-p}
 262 Preprocessor statements are available for insertion via @kbd{C-c C-p}.
 263 Closing elements for preprocessor statements will be automatically
 264 inserted where possible, with point positioned between.  Otherwise,
 265 point will be placed immediately after the inserted text.
 266
 267 @node Wrapping Elements, Tab-Completion, Inserting Preprocessor Statements, Inserting Elements
 268 @comment  node-name,  next,  previous,  up
 269 @section Wrapping Elements
 270 @cindex 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, this was an outline of the buffer:
 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 `-!-'.  A pair of
 289 @code{story} tags can be inserted around both existing @code{part} tags using
 290 @kbd{C-u 2 C-c C-t story}.  When the number of blocks specified to wrap
 291 around exceeds the number of blocks available, Wesnoth Mode will only
 292 wrap around the number of available so that the nesting of elements is
 293 correct.
 294
 295 @node Tab-Completion, Missing Elements, Wrapping Elements, Inserting Elements
 296 @comment  node-name,  next,  previous,  up
 297 @section Tab-Completion
 298 @cindex Tab-Completion
 299 @kindex @kbd{TAB}
 300 Completion can also be performed immediately within the buffer via
 301 @kbd{TAB} on a partial element.  For example, typing @kbd{v i l TAB}
 302 within a @code{scenario} tag, will insert @code{village_gold=} at point.
 303 Tags, macros and preprocessor statements can be completed similarly,
 304 with opening preprocessor statements and tags also inserting a matching
 305 closing element when one is not already available.
 306
 307 A numeric argument can be provided when performing tab-completion of
 308 some elements to wrap around the following @i{n} blocks.  See
 309 @ref{Wrapping Elements}.
 310
 311 @node Missing Elements, , Tab-Completion, Inserting Elements
 312 @section Missing Elements
 313 @cindex Missing Elements, Inserting
 314 @kindex @kbd{C-c C-/}
 315 Missing closing elements can be inserted using @kbd{C-c C-/}.  By
 316 default, this will insert the first missing closing element found in the
 317 current buffer at point.  If all elements appear to be matched or if
 318 there is an excess of closing tags, an appropriate message will be
 319 displayed in the echo area.
 320
 321 @i{Note: The following does not apply to XEmacs.}
 322
 323 The region Wesnoth Mode checks for missing elements can be adjusted
 324 enabling transient-mark-mode prior to inserting the missing element.  To
 325 narrow the region checked, move to the start of the region and enable
 326 transient-mark-mode (this is bound to C-Space C-space by default) at
 327 point temporarily by default.  Then move point to the location to insert
 328 the missing element and use @kbd{C-c C-/}.  The first missing
 329 tag located in the region will be inserted at point.
 330
 331 @node Checking WML,  Customisation, Inserting Elements, Top
 332 @comment  node-name,  next,  previous,  up
 333 @chapter Checking WML
 334 @cindex Checking WML
 335
 336 @menu
 337 * Usage and Capabilities::
 338 @end menu
 339
 340 @node Usage and Capabilities, , Checking WML, Checking WML
 341 @comment  node-name,  next,  previous,  up
 342 @section Usage and Capabilities
 343 @kindex @kbd{C-c C-c}
 344 Checking of the current buffer can be performed using @kbd{C-c C-c}.
 345 Any potential problems found will be reported in a separate buffer named
 346 ``*WML*''.  The WML checking built-in to Wesnoth Mode is not intended to
 347 act as an alternative to tools such as wmllint, but may often be a
 348 convenient substitute while editing WML.
 349
 350 The following conditions can be detected by WML checking in Wesnoth Mode:
 351 @itemize
 352 @item Correct tag / preprocessor nesting
 353 @item Known macro definitions @footnote{see @ref{Macro Definitions}}
 354 @item Availability of elements within the given context
 355 @item Arguments are given to preprocessor statements when required
 356 @item Whether attributes have been given a value
 357 @end itemize
 358
 359 When a problem has been found, Wesnoth Mode will provide the line number
 360 and a description of the problem in the report.  WML checking is
 361 specific to the version of WML known by Wesnoth Mode.  See @ref{Wesnoth
 362 Update} for more information.
 363
 364 @node Customisation, Index, Checking WML, Top
 365 @comment  node-name,  next,  previous,  up
 366 @chapter Customisation
 367 @cindex Customisation
 368
 369 @menu
 370 * Indentation::
 371 * Wesnoth Update::
 372 * Macro Definitions::
 373 @end menu
 374
 375 @node Indentation, Wesnoth Update, Customisation, Customisation
 376 @comment  node-name,  next,  previous,  up
 377 @section Indentation
 378 @cindex Indentation
 379
 380 The style of indentation can be customised using
 381 @code{wesnoth-indent-savefile}.  The default value is @code{t}, which
 382 results in all children being indented a level deeper than their
 383 parent.  When set to @code{nil}, children will be indented to the same
 384 level as their parent element.
 385
 386 @node Wesnoth Update, Macro Definitions, Indentation, Customisation
 387 @comment  node-name,  next,  previous,  up
 388 @section Wesnoth Update
 389 @cindex Wesnoth Update
 390
 391 Wesnoth Update controls the known WML data for Wesnoth Mode.  To update
 392 this information, three variables need to be set appropriately:
 393 @code{wesnoth-root-directory}, @code{wesnoth-update-output-directory}
 394 and @code{wesnoth-addition-file}.
 395
 396 @code{wesnoth-root-directory} should be the path to the root directory
 397 of a Wesnoth installation or Wesnoth source code.  Wesnoth Update will
 398 search recursively in this directory for WML, using the information
 399 found to provide context-sensitive completion and WML checking.
 400
 401 @code{wesnoth-update-output-directory} specifies the path to store the
 402 WML data found.  This path should be within the @code{load-path}, and
 403 preferably, in the same directory as Wesnoth Mode.
 404
 405 @code{wesnoth-addition-file} specifies the `addition file' to use.  An
 406 addition file is an outline of a valid WML file which is processed for
 407 additional element data.  This should be set as the path a suitable
 408 addition file.  A sample addition file is included with Wesnoth Mode.
 409
 410 For example, following to your @file{.emacs}
 411 @example
 412 (setq wesnoth-root-directory "/usr/local/share/wesnoth/"
 413       wesnoth-addition-file
 414       "~/.emacs.d/wesnoth-mode/wesnoth-wml-additions.cfg"
 415       wesnoth-update-output-directory "~/.emacs.d/wesnoth-mode/"
 416 @end example
 417
 418 Once set, @kbd{M-x wesnoth-update} will generate and load a new cache of
 419 WML data ready for use for the current and future sessions.
 420
 421 @node Macro Definitions, , Wesnoth Update, Customisation
 422 @section Macro Definitions
 423 @cindex Macro Definitions
 424 @kindex @kbd{C-c C-u}
 425
 426 While built-in macros are always available, local macro definitions are
 427 automatically made known to wesnoth-mode for each WML file which is
 428 loaded in the session. @kbd{C-c C-u} can be used to update the known
 429 macro definitions for any buffer which has since been modified. (Note
 430 that this is not required when the macro is defined in the WML file
 431 currently being edited as such definitions will be automatically updated
 432 when needed.).
 433
 434 @node Index, Key Index, Customisation, Top
 435 @comment  node-name,  next,  previous,  up
 436 @unnumbered Index
 437 @printindex cp
 438
 439 @node Key Index,  , Index, Top
 440 @comment  node-name,  next,  previous,  up
 441 @unnumbered Key Index
 442 @printindex ky
 443
 444 @bye
 445
 446 @c Local Variables:
 447 @c mode: texinfo
 448 @c TeX-master: t
 449 @c End: