NML:Manual of style - Revision history

FooBar: do not invite people to edit the docs

2011-08-21T18:43:29Z

do not invite people to edit the docs

← Older revision		Revision as of 18:43, 21 August 2011
Line 1:		Line 1:
	<div style="float:right; padding-left:12px; background:none;">{{NMLNavMain}}</div>		<div style="float:right; padding-left:12px; background:none;">{{NMLNavMain}}</div>

	This page describes some general rules in order to achieve a uniform style throughout the NML documentation pages~~. If you see discrepancies to these rules in the NML documentation, feel free to fix them~~.		This page describes some general rules in order to achieve a uniform style throughout the NML documentation pages.


Line 52:		Line 52:

	Possible values are <code style="color:darkgreen">bool</code> for on/off statements or <code style="color:darkgreen">int</code> for positive integer values.		Possible values are <code style="color:darkgreen">bool</code> for on/off statements or <code style="color:darkgreen">int</code> for positive integer values.


	== Other ==

	Other than that there are not that many things that can go wrong. Just make sure to view the preview before saving. As long as you keep the documentation clear and unambiguous, you should be fine. Feel free to add things that are missing, improve descriptions that are unclear or add more examples.

FooBar: Add nav template for quick access and generally make the page look nicer and consistent with the other NML pages.

2011-08-21T18:24:32Z

Add nav template for quick access and generally make the page look nicer and consistent with the other NML pages.

← Older revision		Revision as of 18:24, 21 August 2011
Line 1:		Line 1:
			<div style="float:right; padding-left:12px; background:none;">{{NMLNavMain}}</div>

	This page describes some general rules in order to achieve a uniform style throughout the NML documentation pages. If you see discrepancies to these rules in the NML documentation, feel free to fix them.		This page describes some general rules in order to achieve a uniform style throughout the NML documentation pages. If you see discrepancies to these rules in the NML documentation, feel free to fix them.

FooBar: some general notes on NML documentation layout/style

2011-08-21T14:46:26Z

some general notes on NML documentation layout/style

New page

This page describes some general rules in order to achieve a uniform style throughout the NML documentation pages. If you see discrepancies to these rules in the NML documentation, feel free to fix them.

== 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 <code>NML:</code>. 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 <code>NML:</code> before saving. When linking to NML documentation pages, you need to use the long internal link syntax to hide the NML prefix, e.g. <code><nowiki>[[NML:page name|page name]]</nowiki></code>

== 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 <code><nowiki><pre></nowiki></code> and closing it with <code><nowiki></pre></nowiki></code>.

It will look like this:

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

=== 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 <code><nowiki><pre style="color:blue"></nowiki></code> and closing it with <code><nowiki></pre></nowiki></code>.

It will look like this:

<pre style="color:blue">
grf {
grfid: "AB\03\02";
name: string(STR_GRF_NAME);
desc: string(STR_GRF_DESC);
version: 1;
min_compatible_version: 1;
}
</pre>

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><nowiki><code style="color:darkgreen"></nowiki></code> and <code><nowiki></code></nowiki></code>.

It will look like this:

Possible values are <code style="color:darkgreen">bool</code> for on/off statements or <code style="color:darkgreen">int</code> for positive integer values.

== Other ==

Other than that there are not that many things that can go wrong. Just make sure to view the preview before saving. As long as you keep the documentation clear and unambiguous, you should be fine. Feel free to add things that are missing, improve descriptions that are unclear or add more examples.