# 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

```matlab

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

```

Example with image output

```matlab

% 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']);

```

![](https://160667757-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LdPvJ6mJve3gz5MU4d1%2Fuploads%2Fgit-blob-f0b61793a404d3aafd6ab69dc2a9b37ed3949794%2Fexample_plot.svg?alt=media)

## 🔗 See also

[doc](https://nelson-9.gitbook.io/Nelson/markdown/en/help_tools/doc), [plot (graphics module)](https://nelson-9.gitbook.io/Nelson/markdown/en/graphics/plot).

## 🕔 History

| Version | 📄 Description  |
| ------- | --------------- |
| 1.15.0  | initial version |
