[Users-fr] Documenter l'aide en ligne d'une fonction

[Samuel Gougeon]

Bonjour,

Le 20/04/2017 à 09:59, Vincent Flutet a écrit :
> Bonjour,
>
> J'ai écrit un grand nombre de fonctions et j'ai du mal à comprendre comment les documenter.
>
> Si je comprends bien, help_from_sci crée un fichier .xml à partir des  commentaires d'en-tête de chacune des fonction d'un fichier .sci. Mais cela ne semble fonctionner qu'en anglais.
> Par contre help_skeleton peut prendre en compte le français mais le  fichier .xml créé est vierge et il faut appeler help_skeleton pour chaque fonction.
>
> Existe-t-il un moyen d'écrire un fichier .xml en français à partir des commentaires d'en-tête des fonctions d'un fichier .sci ?
>
> Une fois le .xml créé, comment l'intégrer à l'aide de scilab ?

Il est possible -- voire préférable -- de rédiger les pages d'aides 
directement en XML.
Pour ma part, je n'utilise pas du tout help_from_sci().

En téléchargeant le code source de Scilab, vous avez accès à tous les 
fichiers sources
XML des pages d'aide de Scilab, lesquels constituent autant d'exemples 
qui peuvent
être de bons points de départ ou de dépannage : si vous repérez une page 
d'aide
avec un élément qui vous intéresse mais que vous ne savez pas formater 
en XML,
il suffit d'éditer le fichier source XML correspondant pour voir comment 
faire.
Apprendre en prenant exemple, imitant et testant, est très efficace.

Si "./" représente la racine de votre module,

  * les fichiers sources XML en version anglaise doivent être stockés
    dans le dossier ./help/en_US/
  * les fichiers sources XML en version française doivent être stockés
    dans le dossier ./help/fr_FR/

Par ailleurs,

  * Toutes les versions linguistiques d'une page doivent avoir
    exactement le même nom de fichier source. Exemple : la page d'aide
    en français de la fonction linspace() est écrite dans le fichier
    linspace.xml. Sa version anglaise est écrite dans un fichier source
    obligatoirement nommé linspace.xml, mais stocké dans ./help/en_US/
    au lieu de ./help/fr_FR/
    Si cette contrainte n'est pas respectée, les pages ne seront pas
    (toutes) compilées.

  * Il faut a minima que le fichier existe dans ./help/en_US. Si vous ne
    souhaitez pas traduire vos pages en anglais, il faudra par exemple
    copier le fichier en français dans ./help/en_US/ ((en plus de
    l'avoir dans ./help/fr_FR).

Scinotes n'est pas adapté pour éditer et modifier les fichiers XML. Pour 
ma part, j'utilise Notepad++ et son module XML externe (lequel aide 
beaucoup).

En espérant que ces quelques indications vous aideront,

Cordialement
Samuel Gougeon

-------------- section suivante --------------
Une pièce jointe HTML a été nettoyée...
URL: <https://lists.scilab.org/pipermail/users-fr/attachments/20170422/30e4ed6f/attachment.htm>