ConventionsWML
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 your WML more readable by writing in the house style to begin with.
- Indent each level with 4 spaces. If your text editor doesn't support automatic indentation, you may want to use 2 spaces or tabs instead to make life easier for yourself.
- 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.