Aide Nelson

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

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

📥Arguments d'entrée

Paramètre	Description
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".

📤Arguments de sortie

Paramètre	Description
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 :

Préférez des lignes de résumé courtes pour `<short_description>`.

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

Enveloppez le code source de l'exemple dans CDATA pour éviter l'échappement (voir les exemples ci-dessous).

Utilisez `<link linkend="{module}name">` pour les références qualifiées par module ; sinon, utilisez des noms simples.

💡Exemples

Exemple minimal exécutable

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

Exemple avec sortie d'image

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

🔗Voir aussi

doc plot (module graphique)

📚Bibliographie

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

🕔Historique des versions

Version	Description
1.15.0	version initiale

Modifier cette page sur GitHub