nelson help reference

How to write help XML files for Nelson (elements, attributes, examples, tips).

This document is the canonical authoring reference for help XML files used by Nelson. It explains the structure required bynelson_help.xsdand hownelson_html.xslttransforms each element into HTML. Use this file as a template and checklist when creating or reviewing documentation pages.

📝 Syntax

• <xmldoc> (root) — REQUIRED child: <language>

• Header: <title>, <language>, <module\_name>, <chapter>, <short\_description>

• Sections: <syntax>, <param\_input>, <param\_output>, <description>, <examples>, <see\_also>, <history>, <authors>, <bibliography>

📥 Input argument

• language -

Locale used by the XSLT to select labels and localized text. Examples:en_US,fr_FR. This element is required on the root<xmldoc>.

• keyword -

Main identifier shown as the page title by the XSLT. If absent, the XSLT falls back to<chapter>or "Documentation".

📤 Output argument

• html -

The XSLT generates an HTML file using local assets:highlight.css,nelson_common.cssandnelson_help.js. Images are copied via the extensionext:copy_img.

📄 Description

A human-readable reference and definitive example set describing the XML help file format defined bynelson_help.xsd, and hownelson_html.xslttransforms its elements into HTML.

Use<description>to provide the main documentation body. It accepts paragraphs (<p>), lists (<ul>,<ol>), tables (<table>), inline markup (<b>,<i>,<code>), images (<img src="..."/>) and LaTeX (<latex>).

Inline elements and their XSLT rendering:

• <b> — bold text.

• <i> — italic text.

• <code> — inline code rendering.

• <a href="..."> — external links (rendered as HTML anchors).

• <link linkend="..."> — internal cross reference. If linkend contains a module in braces{module}nameit becomes../module/name.html, otherwisename.html.

• <latex> — math expressions; rendered as MathJax display math by the XSLT template (wrapped with$$...$$).

• <img src="..."/> — images. XSLT callsext:copy_img(@src); SVGs are rendered with a large fixed frame and other formats are responsive.

Block elements:

• <ul>and<ol>— lists. Use<li>with nested inline/block markup as needed.

• <table>— use<thead>,<tbody>,<tr>,<th>and<td>. The XSD allows common attributesborder,cellpaddingandcellspacing.

Authoring tips: 2. Prefer short summary lines for<short_description>. 4. Place runnable examples inside<examples>using<example_item_data>and setrunnable="cli"if applicable orrunnable="false"(default). 6. Wrap example source in CDATA to avoid escaping (see examples below). 8. Use<link linkend="{module}name">for module-qualified references; otherwise use plain names.

📚 Bibliography

https://github.com/nelson-lang/nelson/blob/master/modules/help_tools/help/en_US/xml/1_nelson_help_reference.xml

💡 Examples

Minimal runnable example

% Simple one-line example
x = rand(1,10);
[y, info] = myfunc(x);
disp(info);

Example with image output

% Generate a plot and save as SVG
x = 0:0.1:2*pi;
y = sin(x);
plot(x,y);
saveas(gcf(), [tempdir(),'example_plot.svg']);

🔗 See also

doc, plot (graphics module).

🕔 History

Version	📄 Description
1.15.0	initial version