Re: Doc d'APIs en SGML?

Page principale

Répondre à ce message
Auteur: Christian Fabre
Date:  
À: guilde
Sujet: Re: Doc d'APIs en SGML?

Bonjour à tous,

Voici un résumé de mes aventures pour écrire des docs d'API en SGML.
Mercredi, je postais la demande suivante:

| Bonjour à tous,
| 
| Je cherche un package SGML -ou XML, ou LaTeX- pour écrire de la doc
| d'APIs en C. L'idée est d'écrire ces docs dans un format donnée, et de
| pouvoir générer au moins du HTML et du postscript.
| 
| Jusquà présent j'ai trouvé:
| 
|  - Des outils SGML sur http://www.sgmltools.org
| 
|  - Une DDT nomée DocBook sur http://www.oreilly.com/davenport/
| 
| Ayant trouvé les explication sur ces sites difficiles pour un SGML
| newbee comme moi, j'aurais quelques questions:
| 
|  - Est-ce que quelqu'un ici aurait déjà installé une telle
|    configuration? Si oui, quelle est-il possible d'en avoir les
|    détails?
| 
|  - Est-ce que la DDT DocBook dispose de tout ce qu'il faut pour écrire
|    des docs d'API en C (style C Man pages)?
| 
|  - Si non, ou si DocBook est trop compliquée, Existe-t-il une autre
|    DDT pour ce type d'usage?
| 
|  - Existe-t-il des outils pour créer des documents SGML/DocBook en
|    WYSIWYG? Ou quasi WYSIWYG, juste que je ne veut pas éditer le SGML
|    à la main...
| 
|  - Existe-til une autre solution à mon problème? Par exemple un
|    package XML ou LaTeX?
| 
| 
| Merci d'avance,
| 
| Christian.


Un collègue de travail avait déjà installé les outils DocBook chez
nous. Il en a fait une page nomée "Setup Instructions For A Coherent
SGML/DocBook Environment", disponible à:

    http://www.gr.opengroup.org/adl/papers/sgml_setup.html


Mais tous ceci ne fait que le traitement et le "rendu" des documents
SGML.

Pour les écrire, Stéphane BONHOMME recommande d'utiliser Thot (voir
mail ci-joint) de l'INRIA Rhône-Alpes mais cela suppose un travail
préalable de configuration de Thot pour qu'il puisse éditer le format
DocBook. Ce travail devrai n'être que de quelques jours, et peut se
baser sur les exemples fournis dans la distrib de Thot (voir mail
ci-dessous).

Pour l'instant, j'écris du SGML sous emacs, et utilise les outils
DocBook décris à l'URL ci-dessus.

À+,

Christian.

>
> Bonjour à tous,
>

Salut,

> Je cherche un package SGML -ou XML, ou LaTeX- pour écrire de la doc
> d'APIs en C. L'idée est d'écrire ces docs dans un format donnée, et de
> pouvoir générer au moins du HTML et du postscript.
>


Je saute sur l'occasion pour te conseiller Thot !

- C'est un editeur de documents structure qui n'est pas (encore) xml mais on
travaille dessus en ce moment (version xml disponible fin septembre) -
C'est un e'diteur de documents structur'es (presque) wisiwig qui comporte
lui-meme une api pour developper des applis documentaires. La doc de cette api
a ete ecrite avec Thot tu peux y jeter un oeil.
L'avantage est qu'on le developpe ici (on etait meme voisins y'a 2 ans).

- Thot est un logiciel libre et rien ne t'empeche de developper des schemas de
document (<=> DTD) specifiques a ta doc.

- Thot gere des m'ecanismes de references, d'inclusions, il permet aussi une
presentation graphique homogene ou localisee des elements

- Thot comprend un langage pour specifier des filtre d'export, ainsi le schema
rapport permet l'export en HTML (un ou plusieurs fichiers), LaTeX, ISO-Latin
(texte)

- Thot permet la generation de PostScript (et l'impression)

quelques pointeurs :

projet Opera : http://opera.inrialpes.fr/
Thot : http://opera.inrialpes.fr/OPERA/Thot.fr.html
Manuel API (ecrit avec Thot et exporte en html) :
http://opera.inrialpes.fr/thot/doc/APIman.toc.html
Manuel utilisateur Thot (idem) :
http://opera.inrialpes.fr/thot/doc/Thotman-E.html
Mailing-list :
linux-thot@???
(archive : http://opera.inrialpes.fr/thot/messages/ )

D'autre part, `a Orleans, une équipe travaille sur un environnement de
developpement logiciel base sur thot, profitant du m'ecanisme multi-vues pour
proposer une visualisation synchro du code et de la doc.
http://www.univ-orleans.fr/SCIENCES/LIFO/Membres/eddbali/Hyperpro.html

Si tu veux plus de renseignements n'hesites pas a me contacter.

> =====
>          Christian Fabre         (TOG-RI was OSF-RI)
> The Open Group Research Institute    Net: c.fabre@???
>        2 avenue de Vignate           Tel: +33 4 76.63.48.90
>       38610 Gieres - France            Fax: +33 4 76.51.05.32     

>
>


    Stéphane.
-----------------------------------------
Stéphane BONHOMME  - PhD Student
Projet Opéra


Unité de Recherche INRIA Rhône-Alpes
655 avenue de l'Europe
38330 Montbonnot Saint-Martin

email: Stephane.Bonhomme@???
Phone: (33)76.61.53.81 Fax: (33) 76.61.52.52

-----------------------------------------
La liberte des uns commence ou s'arrete la coupe
du monde de football. 
                                   W.Allen