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 by nelson_help.xsd and how nelson_html.xslt transforms 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.css and nelson_help.js. Images are copied via the extension ext:copy_img.

📄 Description

A human-readable reference and definitive example set describing the XML help file format defined by nelson_help.xsd, and how nelson_html.xslt transforms 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}name it becomes ../module/name.html, otherwise name.html.

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

• <img src="..."/> — images. XSLT calls ext: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 attributes border, cellpadding and cellspacing.

Authoring tips: 2. Prefer short summary lines for <short_description>. 4. Place runnable examples inside <examples> using <example_item_data> and set runnable="cli" if applicable or runnable="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