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, sinonname.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.

Prise en charge des sous-chapitres - Le système d'aide de Nelson prend en charge les sous-chapitres imbriqués. Pour en ajouter un :

Créez un sous-répertoire dans le dossier d'aide XML de votre module (par exemple plots).

Dans ce répertoire, ajoutez un chapter.xml contenant au minimum `<language>` et `<chapter>`, et éventuellement `<chapter_description>`.

Placez les fichiers de sujet XML (par exemple mesh.xml) dans le sous-répertoire ; les fichiers de sujet utilisent les éléments habituels comme `<keyword>` et `<short_description>`.

Liez les pages imbriquées en utilisant des chemins séparés par des slash : pour des liens dans le même module utilisez

`<link linkend="plots/mesh"
          >mesh</link>`

, pour des liens inter-modules utilisez

`<link linkend="{module}plots/mesh"
          >mesh</link>`

.

L'outil buildhelp et le XSLT résolvent ces chemins et généreront des pages HTML imbriquées (par exemple plots/mesh.html).

💡Exemples

Exemple minimal exécutable

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

Exemple de sous-chapitre (chapter.xml)

<?xml version="1.0" encoding="UTF-8"?>
<xmldoc>
  <language>en_US</language>
  <chapter>Plots</chapter>
  <chapter_description>
    <p>Plotting functions grouped in a subchapter.</p>
  </chapter_description>
</xmldoc>

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
1.17.0	ajout du support des sous-chapitres

Modifier cette page sur GitHub