NML:Manual of style

From GRFSpecs
Revision as of 18:43, 21 August 2011 by FooBar (talk | contribs) (do not invite people to edit the docs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

This page describes some general rules in order to achieve a uniform style throughout the NML documentation pages.


Use the NML namespace

All NML pages are contained within the NML namespace. In simple words, this means that every page name is prefixed with NML:. This keeps the NML documentation separate from the NewGRF specification while allowing them to be in the same wiki.

If you create a new page, make sure it's prefixed with NML: before saving. When linking to NML documentation pages, you need to use the long internal link syntax to hide the NML prefix, e.g. [[NML:page name|page name]]


Code

There are three ways to display NML code in the NML documentation: syntax descriptions, code examples and inline code.

Syntax descriptions

Syntax descriptions show the syntax of a certain code block in a general way. These are contained within a code block and have a black font colour. You can make these either by indenting each rule of the code block with (at least) one space, or by preceding the block with <pre> and closing it with </pre>.

It will look like this:

grf {
	grfid: <literal-string>;
	name: <string>;
	desc: <string>;
	version: <expression>;
	min_compatible_version: <expression>;
	<param { ... }>
}

Code examples

Code examples are similar to the syntax description, but show actual NML code. Examples are again contained within a code block and have a blue font colour. You can make these by preceding the block with <pre style="color:blue"> and closing it with </pre>.

It will look like this:

 grf {
 	grfid: "AB\03\02";
 	name: string(STR_GRF_NAME);
 	desc: string(STR_GRF_DESC);
 	version: 1;
 	min_compatible_version: 1;
 }

Note: A template for this has been considered, but doesn't make thinks less complicated, so for now there's no template to do this.

Inline code

Inline code is using a very small piece of code or just a single keyword, function name, etc. in the regular text. Inline code is shown in a fixed-width font and has a dark green font colour. You can make these by enclosing the inline code in <code style="color:darkgreen"> and </code>.

It will look like this:

Possible values are bool for on/off statements or int for positive integer values.