README

   1 1. Introduction
   2
   3 Wesnoth-mode is a major mode for Emacs which assists in the editing of the
   4 markup language extensively used in Wesnoth, a turn-based fantasy strategy
   5 game.  From the Wesnoth Wiki: "The Wesnoth Markup Language (WML) is used to
   6 code almost everything in Wesnoth, including scenarios, units, savefiles, and
   7 the user interface layout." [1]
   8
   9 Wesnoth-mode is supported under GNU Emacs 22 and 21 and (with some minor
  10 limitations) XEmacs 21 and adds support for syntax highlighting, automatic
  11 indentation, context-sensitive completion, checking and much more for WML.
  12
  13 The following documentation attempts to provide a comprehensive guide to
  14 functionality available within wesnoth-mode, and assumes you are familiar with
  15 basic usage, terminology and customisation of Emacs.  For more information,
  16 please refer to the Emacs manual. [2]
  17
  18 To use wesnoth-mode, add the following to your .emacs:
  19    (add-to-list 'load-path "path/to/wesnoth-mode")
  20    (autoload 'wesnoth-mode "wesnoth-mode" "Major mode for editing WML." t)
  21 Optionally adding:
  22    (add-to-list 'auto-mode-alist '("\\.cfg\\'" . wesnoth-mode))
  23 to automatically load wesnoth-mode for all files with a '.cfg' extension.
  24
  25 For the latest updates to wesnoth-mode, visit
  26 http://www.wesnoth.org/forum/viewtopic.php?t=13798
  27
  28
  29 2. Usage and Functionality
  30
  31 The following will describe the basic usage as well as some of the more
  32 advanced functionality available within wesnoth-mode.  If wesnoth-mode is not
  33 the currently active major-mode for the current buffer, it can be started via
  34 'M-x wesnoth-mode'.
  35
  36 2.1. Insertion and Completion
  37
  38 Tags can be inserted via 'C-c C-t' and alternatively 'M-TAB' (assuming this is
  39 not shadowed by your Window Manager, etc.).  This will prompt for the tag you
  40 would like to add.  The tag entered into the minibuffer prompt and its
  41 matching closing tag will be inserted and point positioned between.
  42
  43 Attributes can be inserted via 'C-c C-a'.  The attribute entered at the prompt
  44 will be inserted along with the '=', with point immediately after.
  45
  46 Macro insertion can be performed via 'C-c C-m'.  If the macro entered is known
  47 to require arguments, point will be positioned before the closing curly brace
  48 ready to input any arguments, otherwise it will be positioned immediately
  49 after.
  50
  51 Preprocessor statements are available for insertion via 'C-c C-p'.  Closing
  52 elements for preprocessor statements will be automatically inserted where
  53 possible, with point positioned between.  Otherwise, point will be placed
  54 immediately after the inserted text.
  55
  56 Completion for tags, attributes, macros and preprocessor statements is
  57 provided at the minibuffer prompt via 'TAB'.  The unique portion of the match
  58 will be inserted directly into the minibuffer.  If multiple completions are
  59 available for the current input, a list of possibilities will be displayed.
  60
  61 Completion can also be performed immediately within the buffer via 'TAB' on a
  62 partial element.  For example, typing 'v i l TAB' immediately within a
  63 'scenario' tag, will insert 'village_gold=' at point.  Tags, macros and
  64 preprocessor statements can be completed similarly, with opening preprocessor
  65 statements and tags also inserting a matching closing element when one is not
  66 already available.
  67
  68 When inserting tags and some preprocessor statements, either via their
  69 respective insertion command or via 'TAB', an optional numeric argument can be
  70 provided to specify the number of 'blocks' to wrap the element around.  For
  71 example, assume you have the following:
  72
  73 "[multiplayer]
  74     ...
  75  -!-[part]
  76         ...
  77     [/part]
  78     [part]
  79         ...
  80     [/part]
  81     [part]
  82         ...
  83     [/part]
  84     [event]
  85         ...
  86     [/event]
  87 [/multiplayer]"
  88
  89 and point is at the position indicated by '-!-'.  You can insert the missing
  90 'story' tags which should surround all 'part' tags using 'M-3 C-c C-t story'.
  91 The resulting text will appear as:
  92
  93 "[multiplayer]
  94     ...
  95     [story]
  96         [part]
  97             ...
  98         [/part]
  99         [part]
 100             ...
 101         [/part]
 102         [part]
 103             ...
 104         [/part]
 105     [/story]
 106     [event]
 107         ...
 108     [/event]
 109 [/multiplayer]"
 110
 111 Footnotes:
 112 [1]  http://www.wesnoth.org/wiki/ReferenceWML
 113 [2]  http://www.gnu.org/software/emacs/manual/html_node/emacs/index.html