nelson help reference

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

📝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 Arguments

Parameter	Description
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 Arguments

Parameter	Description
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:

Prefer short summary lines for `<short_description>`.

Place runnable examples inside `<examples>` using `<example_item_data>` and set `runnable="cli"` if applicable or `runnable="false"` (default).

Wrap example source in CDATA to avoid escaping (see examples below).

Use `<link linkend="{module}name">` for module-qualified references; otherwise use plain names.

💡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)

📚Bibliography

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

🕔Version History

Version	Description
1.15.0	initial version

Edit this page on GitHub