# Aide Nelson

Comment rédiger des fichiers XML d'aide pour Nelson (éléments, attributs, exemples, conseils).

Ce document est la référence canonique pour la création de fichiers XML d'aide utilisés par Nelson. Il explique la structure requise par `nelson_help.xsd` et comment `nelson_html.xslt` transforme chaque élément en HTML. Utilisez ce fichier comme modèle et liste de contrôle lors de la création ou de la révision de pages de documentation.

## 📝 Syntaxe

* `<xmldoc>` (root) - Enfant OBLIGATOIRE : `<language>`
* Header: `<title>`, `<language>`, `<module_name>`, `<chapter>`, `<short_description>`
* Sections: `<syntax>`, `<param_input>`, `<param_output>`, `<description>`, `<examples>`, `<see_also>`, `<history>`, `<authors>`, `<bibliography>`

## 📥 Argument d'entrée

* language -

Localisation utilisée par le XSLT pour sélectionner les étiquettes et le texte localisé. Exemples : `en_US`, `fr_FR`. Cet élément est obligatoire dans la racine `<xmldoc>`.

* keyword -

Identifiant principal affiché comme titre de la page par le XSLT. En cas d'absence, le XSLT revient à `<chapter>` ou "Documentation".

## 📤 Argument de sortie

* html -

Le XSLT génère un fichier HTML en utilisant des ressources locales : `highlight.css`, `nelson_common.css` et `nelson_help.js`. Les images sont copiées via l'extension `ext:copy_img`.

## 📄 Description

Une référence lisible par l'homme et un ensemble d'exemples définitifs décrivant le format de fichier XML d'aide défini par `nelson_help.xsd`, et comment `nelson_html.xslt` transforme ses éléments en HTML.

Utilisez `<description>` pour fournir le corps principal de la documentation. Il accepte des paragraphes (`<p>`), des listes (`<ul>`, `<ol>`), des tableaux (`<table>`), des balisages en ligne (`<b>`, `<i>`, `<code>`), des images (`<img src="..."/>`) et LaTeX (`<latex>`).

Les éléments en ligne et leur rendu XSLT :

* `<b>` - texte en gras.
* `<i>` - texte en italique.
* `<code>` - rendu de code en ligne.
* `<a href="...">` - liens externes (rendus en tant qu'ancres HTML).
* `<link linkend="...">` - référence croisée interne. Si linkend contient un module entre accolades `{module}name`, il devient `../module/name.html`, sinon `name.html`.
* `<latex>` - expressions mathématiques ; rendues en tant que mathématiques d'affichage MathJax par le modèle XSLT (enveloppées avec `$$...$$`).
* `<img src="..."/>` - images. Le XSLT appelle `ext:copy_img(@src)`; les SVG sont rendus avec un cadre fixe large et les autres formats sont adaptables.

Éléments de bloc :

* `<ul>` et `<ol>` - listes. Utilisez `<li>` avec un balisage en ligne/de bloc imbriqué selon les besoins.
* `<table>` - utilisez `<thead>`, `<tbody>`, `<tr>`, `<th>` et `<td>`. Le XSD autorise les attributs communs `border`, `cellpadding` et `cellspacing`.

Conseils pour la rédaction : 2. Préférez des lignes de résumé courtes pour `<short_description>`. 4. Placez les exemples exécutables à l'intérieur de `<examples>` en utilisant `<example_item_data>` et définissez `runnable="cli"` si applicable ou `runnable="false"` (par défaut). 6. Enveloppez le code source de l'exemple dans CDATA pour éviter l'échappement (voir les exemples ci-dessous). 8. Utilisez `<link linkend="{module}name">` pour les références qualifiées par module ; sinon, utilisez des noms simples.

## 📚 Bibliographie

<https://github.com/nelson-lang/nelson/blob/master/modules/help\\_tools/help/fr\\_FR/xml/1\\_nelson\\_help\\_reference.xml>

## 💡 Exemples

Exemple minimal exécutable

```matlab

% Exemple simple
x = rand(1,10);
[y, info] = myfunc(x);
disp(info);

```

Exemple avec sortie d'image

```matlab

% Générer un graphique et l'enregistrer au format 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)

## 🔗 Voir aussi

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

## 🕔 Historique

| Version | 📄 Description   |
| ------- | ---------------- |
| 1.15.0  | version initiale |
