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

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

🕔 Historique

Version	📄 Description
1.15.0	version initiale