Difference between revisions of "ConventionsWML"

Revision as of 13:04, 29 June 2007

The purpose of this page is to list conventions of WML -- that is, things that make WML more readable and flexible. Note that this page is not official; in fact most mainline campaigns do not follow this.

Macros

Using macros is useful for decreasing the size of a file, and for making it clear that you are doing the same thing several times. A good rule for when to use macros is to use them whenever information is being repeated. For information on how to create and use macros, see PreprocessorRef.

Also, if you are writing a campaign, you should use campaign macros. These are macros in the main .cfg file of your campaign; i.e. the one with the [campaign] tag. They can be used in any scenario of your campaign. One useful campaign macro is a "deaths" macro, which describes events that should occur in all scenarios of your campaign; for example an event causing you to lose when your hero dies. Refer to this macro in each of your scenarios.

Put campaign macros after the #ifdef of your campaign; that way they will not conflict with other campaign's macros.

Indentation

We used to have complicated recommendations for indentation. Now we have a WML indenting program and much simpler rules.

Be aware that no matter how you indent your WML, if it's accepted into mainline we are going to run wmlindent on it and smash it into the house style. We do this so our WML maintainers won't have to cope with lots of idiosyncratic indentation variants. You can make life easier by writing in the house style to begin with.

Indent each level with 4 spaces. Don't use 8 spaces or any other number, and don't use tabs. Especially don't mix tabs and spaces (Emacs users may need to be careful about this.)
Indent attributes a level deeper than their parent tag.
Indent macros as though the #define/#enddef are an outermost level; that is, the macro body starts with one level of indenting.
Don't indent #ifdef/#else/#endif at all
Indent comments at the same level as the text they go with.

When in doubt, run wmlindent on your code. See Maintenance tools for more description of this program.

Naming files

First of all, don't put spaces in filenames; this causes errors on some systems. Use underscores(_) instead.

If the IDs of your scenarios are different from their names, name the files after the IDs, not the names. That way it is easier to tell which scenario is next.

If files are named in a numerical order, put 0 at the beginning of single-digit numbers. This makes the alphabetical sorting also a numerical sorting. For example if you have 20 different maps, you can name them 'MAP_01', 'MAP_02'...., 'MAP_20'.

WML variables

(For information about what WML variables are, see VariablesWML.) These shouldn't be used except when necessary. [have_unit] tags can often be used instead. Also, make sure that your scenarios clear meaningless variables using [clear_variable].

For variable values, use 'yes' and 'no' for boolean values rather than 1 and 0. It's clearer to people who don't know programming.

@@ Line 28: / Line 28: @@
 == Indentation ==
-In indentation, every subtag is indented 1 level outward of its parent tag.
+We used to have complicated recommendations for indentation.  Now we have a WML indenting program and much simpler rules.
-Toplevel tags are not indented;
-neither are the direct subtags of macros and files.
-For example, in unit files [unit] is not indented,
-and every macro should have at least 1 unindented tag or attribute.
-A macro references should be indented
-as though it were the contents of the macro it refers to.
-Some macros require the use of another macro later;
-in this case the macro should be considered as a tag,
-with its counterpart as the closing tag.
-Example:
+Be aware that no matter how you indent your WML, if it's accepted into mainline we are going to run <tt>wmlindent</tt> on it and smash it into the house style. We do this so our WML maintainers won't have to cope with lots of idiosyncratic indentation variants.  You can make life easier by writing in the house style to begin with.
- [scenario]
+# Indent each level with '''4 spaces'''. Don't use 8 spaces or any other number, and don't use tabs. Especially don't mix tabs and spaces (Emacs users may need to be careful about this.)
-  [event]
+# Indent attributes a level deeper than their parent tag.
- #define START_STORE_UNIT
+# Indent macros as though the <tt>#define/#enddef</tt> are an outermost level; that is, the macro body starts with one level of indenting.
- [store_unit]
+# Don't indent <tt>#ifdef</tt>/<tt>#else</tt>/<tt>#endif</tt> at all
-  [unit]
+# Indent comments at the same level as the text they go with.
- #enddef
- #define END_STORE_UNIT
-  [/unit]
- variable=temp
- [/store_unit]
- #enddef
-   {START_STORE_UNIT}
-   type=Elvish Fighter
-    [not]
-    x,y=$x1,$y1
-    [/not]
-   {END_STORE_UNIT}
-  [/event]
- [/scenario]
-Although spaces can substitute for tabs (as done in this wiki),
+When in doubt, run <tt>wmlindent</tt> on your code.  See [[Maintenance tools]] for more description of this program.
-it is generally not advisable to use a series of spaces
-to substitute for a single tab - one is enough.
-Some writers don't indent subtags of [if]
-because of the way these tags are used recursively;
-indenting these tags fully could cause line wraps
-to make the code incomprehensible.
-There are two ways to indent keys:
-normal indentation, and savefile indentation.
-In normal indentation, a key is indented
-on the same level as the tag containing it,
-and in savefile indentation a key is indented
-level outward of that.
-Examples:
-Normal indentation:
- [scenario]
- turns=16
-  [side]
-  side=1
-  [/side]
-  [/scenario]
-Savefile indenatation:
- [scenario]
-  turns=16
-  [side]
-   side=1
-  [/side]
- [/scenario]
-It doesn't matter what indentation format you use,
-but if a file is not indented
-then it is harder to tell what is going on;
-for example it is difficult to catch errors in tag matchups.
 == Naming files ==