View/Edit #87!xml-help-format

<help>
<text>
<p>
The XML help format allows help files to be rendered in a
variety of formats, including plain text, ANSI, and HTML; the
appropriate output is automatically generated from the markup.
This file contains a brief guide to creating XML help files.
</p>

<p>
All help files start with the &lt;help&gt; tag and end with the
&lt;/help&gt; tag.  There are two types of help texts: redirects
and actual texts.  A redirect contains only the tag
&lt;redirect&gt; with a required <eg>target</eg> attribute and an
optional <eg>database</eg> attribute; for instance,
the help file for <eg>@show</eg> redirects to <eg>@display</eg>:
</p>

<eg>
&lt;help&gt;&lt;redirect target="@display" /&gt;&lt;/help&gt;
</eg>

<p>Actual texts next have an optional list of usages.  MOO commands, for
instance, have usages summarizing the commands' syntax.  A usage may
have parameters for that command, some of which may be of type
optional.  There should be a usage for each alternative syntax for the
command.  Here is an example of a pair of &lt;usage&gt; declarations:</p>

<eg>
 &lt;usage&gt;@display &lt;param&gt;object&lt;/param&gt;.&lt;param type="optional"&gt;property&lt;/param&gt;&lt;/usage&gt;
 &lt;usage&gt;@display &lt;param&gt;object&lt;/param&gt;,&lt;param type="optional"&gt;inherited_property&lt;/param&gt;&lt;/usage&gt;
</eg>

<p>The &lt;text&gt; section follows the usage declarations.
It starts with a &lt;text&gt; tag and ends with a &lt;/text&gt; tag.
The following elements are allowed inside a &lt;text&gt; section:
&lt;p&gt;, &lt;pre&gt;, &lt;function&gt;,
&lt;list&gt;, &lt;topics&gt; and &lt;eg&gt;.</p>

<p>The &lt;p&gt; tag indicates a paragraph; most text will be between
&lt;p&gt; and &lt;/p&gt; tags.</p>

<p>The &lt;pre&gt; tag indicates preformatted text; the renderer
will not wordwrap or otherwise mess with the text between the &lt;pre&gt;
tags, and will render it in a monospace font.</p>

<p>The &lt;function&gt; tag is used in documentation of verbs
to indicate a MOO function.</p>

<p>The &lt;list&gt; tag indicates a list.  Each list element is
enclosed by &lt;li&gt; tags.  This tag also takes an
optional &lt;name&gt; parameter, as used in
<link target="@display-option" database="#89">@display-option</link>.
Here is an example of a list:</p>
<eg>
My favourite colors are:
&lt;list&gt;
 &lt;li&gt;blue&lt;/li&gt;
 &lt;li&gt;green&lt;/li&gt;
 &lt;li&gt;red&lt;/li&gt;
&lt;/list&gt;
</eg>

<p>A more specialized type of list is the &lt;topics&gt; list.
The &lt;topics&gt; list may contain an optional <eg>title</eg>
attribute.
It contains a list of &lt;topic&gt; elements (or a &lt;break&gt;,)
where each &lt;topic&gt; contains a name attribute,
and encloses some information on the topic of that name.
A topic named <eg>foo</eg> automatically links
to the help file on <eg>foo</eg> in appropriate renderers.
The topics listing from <eg>@dig</eg> is as follows:</p>
<eg>
&lt;topics&gt;
 &lt;topic name="topology"&gt;Information on building.&lt;/topic&gt;
 &lt;topic name="@digwith"&gt;Set your default object for building with.&lt;/topic&gt;
&lt;/topics&gt;
</eg>

<p>The &lt;eg&gt; tag indicates an example.  Spacing is preserved inside
&lt;eg&gt; tags.</p>

<p> Finally, text may always be marked up with the &lt;b&gt; (for <b>bold</b>)
and &lt;i&gt; (for <i>italic</i>) text; similarly, the
&lt;link&gt; tag indicating a link can appear anywhere in the text,
as can the &lt;eg&gt; tag indicating an example.  
If you want to put explicit angle brackets in your text, type &amp;lt; for
&lt; and &amp;gt; for &gt;.</p>

<p>The DTD for the XML help format can be found at <eg>http://www.moo.ca/xml!moo-help.dtd</eg>.</p>
<p>For questions on this help text, contact whiz (#3135).</p>
</text>
</help>