Journal DocBook ou l'art d'écrire de la documentation

Posté par gusterhack le 01 février 2017 à 09:33. Licence CC By‑SA.

Étiquettes :

fév.

2017

Salut,
J'ai découvert récemment le pas très connue DocBook un langage utilisant le XML comme base et permettant de rédiger de la documentation sans se souciée de la présentation et en se concentrant uniquement sur le contenue.

J'aimerai connaitre votre avis sur ce langage ?

Pour ma part, je le test encore mais c'est vraiment plaisant de pouvoir convertir un seul fichier vers le format PDF, HTML, EPUB ou encore Open Document. Sans devoir tout réécrire pour chaque format. :)

# Pratique

Posté par Jice le 01 février 2017 à 09:55. Évalué à 6.

J'ai tendance à trouver XML beaucoup trop verbeux. En particulier, les documents docbook ne sont pas très faciles à lire en texte brut, ce qui reste à mon avis un handicap.

Par ailleurs, à quand j'en avais fait un peu, cela manquait d'éditeur wysiwyg ce qui rend plus difficile l'adoption par le plus grand nombre.

Néanmoins, cette approche présente des avantages vraiment décisifs. Outre la possibilité de générer différents formats, cela permet de considérer les documentations comme de véritables bases documentaires facilement interrogeables avec XSLT par exemple.
Dès lors que la documentation grossit, recouvre diverses applications ou processus, cette possibilité est un avantage très net. Il devient relativement simple d'extraire des parties pertinentes de différentes documentations pour en faire une autre plus pertinente pour un objectif donné (étude ou autre).
Par ailleurs, si les différents éléments (les noms de personnes, codes d'applications et autres) sont bien balisés on peut effectuer des recherches plus efficaces. Par exemple, dans notre SI, une des applis est codée "ET" (si, c'est possible. Le SI est très vieux). Chercher ce genre de motif dans une montagne de documents est un vrai problème. Si c'est balisé , cela n'en est plus un.
- [^] # Re: Pratique
  
  Posté par dourouc05 (site web personnel) le 01 février 2017 à 13:20. Évalué à 1.
  
  Il y a quand même une série d'éditeurs WYSIWYM plus que corrects, parfois gratuits, mais rarement libres… (Le WYSIWYG n'a pas de sens, puisque DocBook n'a pas d'indication concernant la mise en page.) oXygen est mon préféré, mais payant (et pas donné) ; XMLmind est français (bon, c'est pas une raison) et gratuit (l'export PDF depuis l'éditeur a quelques altérations, il faut bien que la version payante ait quelque chose de plus). Les deux sont écrits en Java et sont utilisables sous tous les systèmes d'exploitation majeurs (et même sur le Web).
  
  http://oxygenxml.com/
  http://www.xmlmind.com/
  
  Côté libre, j'ai entendu parler de Vex, une extension pour Eclipse, mais je n'ai jamais réussi à l'utiliser. (Problèmes d'installation.)
  
  https://marketplace.eclipse.org/content/vex-latest-milestone
  
  Sinon, oui, vraiment, pour moi, l'aspect sémantique est le gros avantage de DocBook par rapport à ces formats "modernes" : certes, pas besoin d'un éditeur spécifique, mais impossible de créer un premier index de manière automatisée (par exemple, en repérant tout le contenu des balises <firstterm>).
  - [^] # Re: Pratique
    
    Posté par vpoulailleau le 01 février 2017 à 19:01. Évalué à 4.
    
    Pour rédiger des documents de tout type en abstrayant le fond et la forme, le tout avec un outil graphique wysiwym open-source, il y a https://scenari.org/ que je trouve pratique après la période de prise en main.
    
    J'écris mes cours avec et je génère le pdf, le site web, le diaporama grâce à l'outil.
# Aaaah Docbook...

Posté par Guillaume Smet (site web personnel) le 01 février 2017 à 09:58. Évalué à 8.

Docbook a été très connu en fait. Il était énormément utilisé fut un temps. Je me rappelle même avoir fait quelques XSL simplifiées vers 2003 (ah ce petit plaisir coupable d'écrire du XSL…).

Il est relativement passé de mode maintenant, notamment à cause de son aspect verbeux qui le rend un peu pénible à écrire et assez pénible aussi à relire. Le temps de génération est aussi assez lourd comparé à l'outil dont je vais parler juste après.

Pour la documentation Hibernate, on est passé à AsciiDoctor (http://asciidoctor.org/) depuis quelques années pour la rédaction des documentations. On convertissait toujours la documentation en Docbook après pour avoir la sortie PDF, AsciiDoctor ne la proposant pas à l'époque. J'ai revisité le sujet récemment et AsciiDoctor a maintenant une chouette version PDF.

Pour les prochaines versions, on s'oriente donc maintenant vers une pure sortie AsciiDoctor (je vais pousser une nouvelle version d'Hibernate Validator dans l'aprèm avec le nouveau format de doc, je posterai des liens avant après).

Un exemple de bout de doc :
- version rendue par GitHub (c'est aussi un des avantages) : https://github.com/hibernate/hibernate-validator/blob/master/documentation/src/main/asciidoc/ch02.asciidoc
- version code : https://raw.githubusercontent.com/hibernate/hibernate-validator/master/documentation/src/main/asciidoc/ch02.asciidoc

La capacité à inclure facilement des bouts de code est vraiment chouette aussi. Il est également possible de relativement facilement ajouter des balisages complémentaires.

C'est en Ruby mais AsciiDoctor propose également un plugin Maven qui fonctionne par dessus JRuby. C'est ce dernier que nous utilisons.

Dans les moins par rapport à ce dont tu parlais, la sortie epub est encore assez perfectible pour des documentations du calibre de ce qu'on a. On a décidé de ne pas la publier pour l'instant.

Je conseille chaudement.
- [^] # Re: Aaaah Docbook...
  
  Posté par Nicolas Boulay (site web personnel) le 01 février 2017 à 10:35. Évalué à 5.
  
  Je n'ai jamais trouver de format qui gère à la fois HTML, PDF (voir docx), comme latex et qui permet d'avoir les liens hypertexte fonctionnel.
  
  "La première sécurité est la liberté"
  - [^] # Re: Aaaah Docbook...
    
    Posté par benoar le 01 février 2017 à 11:53. Évalué à 5.
    
    reStructuredText ? De mémoire, j'ai déjà utilisé des liens dans ces trois formats, et ça marche.
  - [^] # Re: Aaaah Docbook...
    
    Posté par zurvan le 01 février 2017 à 12:53. Évalué à 4.
    
    http://txt2tags.org/ gère ça bien, et on peut le customiser comme on veut pour rajouter des balises si nécessaire. Prendre la version de dev qui ajoute de nombreuses fonctionnalités : https://github.com/txt2tags/txt2tags ça permet notamment d'exporter en RTF et même en docbook.
    
    « Le pouvoir des Tripodes dépendait de la résignation des hommes à l'esclavage. » -- John Christopher
    - [^] # Re: Aaaah Docbook...
      
      Posté par Le Gab le 02 février 2017 à 12:55. Évalué à 1.
      
      Prendre la version de dev …
      
      Avec juste cette suggestion, c'est un no go!. :/
      
      ça permet notamment d'exporter en RTF et même en docbook.
      
      Pourquoi quoi faire RTF? Faciliter l'échange? Alors pourquoi ne pas l'utiliser comme format de base si on obtient une structure identique?
      - [^] # Re: Aaaah Docbook...
        
        Posté par pulkomandy (site web personnel, Mastodon) le 02 février 2017 à 16:41. Évalué à 5.
        
        RTF est un format de présentation, pas de structure. Et en plus il est à peu près aussi pénible que LaTeX à écrire à la main (c'est plein de \ et de commandes bizarres).
      - [^] # Re: Aaaah Docbook...
        
        Posté par zurvan le 02 février 2017 à 20:50. Évalué à 2. Dernière modification le 02 février 2017 à 20:51.
        
        pourquoi no go ? C'est si dur que ça de faire :
        wget https://raw.githubusercontent.com/txt2tags/txt2tags/master/txt2tags chmod +x txt2tags?
        
        Et si ça ne tenait qu'à moi, on aurait déjà sorti une nouvelle version, mais l'initiateur du projet est très perfectionniste, pas trop dans l'optique "release early, release often"…
        
        Pour rtf c'est juste un format d'export, parmi les nombreux existant.
        
        « Le pouvoir des Tripodes dépendait de la résignation des hommes à l'esclavage. » -- John Christopher
        
        [^] # Re: Aaaah Docbook...
        
        Posté par Le Gab le 02 février 2017 à 20:55. Évalué à 3.
        
        pourquoi no go ? C'est si dur que ça de faire :
        
        Stabilité, version de référence toussa…
  - [^] # Re: Aaaah Docbook...
    
    Posté par Marotte ⛧ le 02 février 2017 à 21:54. Évalué à 4.
    
    Personne ne parle de Asciidoc ?
    
    Je trouve le langage (la version texte donc) un peu moins naturelle que le markdown original pour les trucs de base mais au niveau des formats de sortie ça fait entre autre du HTML5 (c’est ce que j’utilise), ou du DocBook justement…
    
    Donc oui, il te faut un autre outil pour générer le PDF mais c’est pas la mort à ajouter à ton workflow.
    
    Pour le HTML5 il y a la possibilité d’intégrer les images directement (encodées en base64 dans la page), pour diffuser un document "normal" c’est parfait. Une autre chose que j’apprécie c’est qu’il y a une syntaxe qui permet de faire des tableaux aussi lisibles dans le source que dans le rendu, ou bien tu peux mettre directement du CSV (vive le contenu dynamique).
    
    Quelle galère d’utiliser un traitement de texte WYSIWYG quand tu as appris à utiliser Asciidoc, à chaque fois faut vraiment que je me force…
    - [^] # Re: Aaaah Docbook...
      
      Posté par pulkomandy (site web personnel, Mastodon) le 03 février 2017 à 09:20. Évalué à 2.
      
      Sinon, en format léger, il y a vimwiki (https://github.com/vimwiki/vimwiki) avec de l'export en HTML. Comme son nom l'indique, il est plutôt bien intégré dans vim.
    - [^] # Re: Aaaah Docbook...
      
      Posté par Guillaume Smet (site web personnel) le 03 février 2017 à 13:01. Évalué à 3.
      
      Ben si justement, cf le premier commentaire du thread :).
      
      Enfin, je parlais d'AsciiDoctor mais je pense que c'est ce qu'il faut utiliser maintenant plutôt pour manipuler de l'Asciidoc. Et comme je le disais, la sortie PDF est maintenant très acceptable et on n'a plus besoin d'autre chose.
      
      J'ai également posté des liens vers les sorties HTML et PDF de la doc d'Hibernate Validator faite avec AsciiDoctor dans un autre commentaire.
      - [^] # Re: Aaaah Docbook...
        
        Posté par Marotte ⛧ le 03 février 2017 à 20:29. Évalué à 3.
        
        Arf TL;DR, my bad, ~~god save the queen~~
        
        J’ai souvent entendu parler de AsciiDoctor en cherchant de l’info sur Asciidoc, j’ai cru comprendre qu’il s’agissait d’une sorte de sur-couche à Asciidoc. Je me suis orienté vers le premier plutôt que le deuxième en me disant qu’il valait mieux assimiler la base avant d’aborder un outil plus évolué. Je m’étais effectivement fait la réflexion qu’il faudrait sûrement que je m’oriente vers AsciiDoctor in fine, ton commentaire semble confirmer cette impression.
        
        Cela dit Asciidoc répond à mes besoins pour l’instant mais je vais quand même suivre d’un peu plus près Asciidoctor, pour voir ce qu’il peut éventuellement m’apporter. C’est sûr que s’il intègre la génération du PDF, pour son adoption par le plus grand nombre c’est un atout.
- [^] # Re: Aaaah Docbook...
  
  Posté par gusterhack le 01 février 2017 à 10:45. Évalué à 1.
  
  Ça à l'air pas mal ton truc faut que je teste. :)
  Après DocBook à des balise de type : <code>...</code>.
  Ce qui est pour mois plus lisible que de la syntaxe proche du markdown à près ça dépends des gens. J'ai regardée du coté de la documentation DocBook il y a énormément de balise différente autour de 380 pour la version 5 ce qui complexifie la chose.
  - [^] # Re: Aaaah Docbook...
    
    Posté par Marotte ⛧ le 03 février 2017 à 20:45. Évalué à 2. Dernière modification le 03 février 2017 à 20:49.
    ça dépends des gens
    
    Il y a moins de chance de faire une fôte de frappe sur ``` ou .... (et ça va plus vite à taper) qu’écrire <code>, je trouve :)
    
    Ensuite, en précisant le langage, pour profiter de la coloration syntaxique, qui est selon moi un must pour de la documentation technique, et bien tu sais en lisant le source que tu as affaire à du code (c’est même plus précis que le mot « code » lui même…)
    
    En asciidoc ça donne :
```
[source,ruby]
----
require 'sinatra' // <1>

get '/hi' do // <2>
  "Hello World!" // <3>
end
----
```
    et tu peux utiliser le nombre de tiret que tu veux, tu peux en mettre plein pour que ce soit plus lisible en texte brut (ou pouvoir avoir des lignes telles que '----' à l’intérieur du bloc…
    
    et là en markdown pour le coup c’est simplifié au maximum : ```ruby
    
    http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#source-code
    
    L’exemple m’a bien fait rire :
```
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual
absolutely fatal: operation initiation lost in the dodecahedron of doom
would you like to die again? y/n
```
- [^] # Re: Aaaah Docbook...
  
  Posté par Jice le 01 février 2017 à 11:04. Évalué à 1.
  
  Je ne connais pas asciidoctor mais une lecture en diagonale de la doc semble indiquer que c'est vraiment orienté "mise en page".
  Je ne vois pas comment on fait pour baliser une chaîne de caractères par son rôle (auteur, application, variable ou autre) pourtant, ce type d'information peut s'avérer très utile…
  - [^] # Re: Aaaah Docbook...
    
    Posté par Guillaume Smet (site web personnel) le 01 février 2017 à 11:11. Évalué à 3.
    
    Tu peux utiliser
    [rolename]`monospace text`
    avec rolename étant ce que tu souhaites. On a utilisé classname et methodname fut un temps. Mais c'était assez verbeux et ça avait assez peu d'intérêt donc on a abandonné.
    
    Chercher "Role-playing for text enclosed in backticks" dans http://asciidoctor.org/docs/user-manual/ .
    
    Je dois avouer que j'étais plutôt de ton avis fut un temps mais à l'usage on y gagne en lisibilité et en légèreté.
    - [^] # Re: Aaaah Docbook...
      
      Posté par Jice le 01 février 2017 à 11:37. Évalué à 3. Dernière modification le 01 février 2017 à 11:41.
      
      C'est clairement l'inconvénient de docbook (et du xml en général).
      L'avantage, c'est que ça marche bien avec xslt et que du coup, une documentation devient très facile à gérer automatiquement.
      Avec xml, c'est toujours le même truc. Des fonctionnalités loin devant la concurrence mais tellement verbeux qu'on finit pas laisser tomber.
- [^] # Re: Aaaah Docbook...
  
  Posté par Guillaume Smet (site web personnel) le 01 février 2017 à 11:06. Évalué à 6.
  
  Du coup, le résultat est là :
  - HTML : https://docs.jboss.org/hibernate/stable/validator/reference/en-US/html_single/
  - PDF : https://docs.jboss.org/hibernate/stable/validator/reference/en-US/pdf/hibernate_validator_reference.pdf
  
  Pour le HTML, en dehors du logo, c'est la sortie par défaut. Pour le PDF, on a configuré un peu les polices car la police de code par défaut était un peu étrange.
  - [^] # Re: Aaaah Docbook...
    
    Posté par gusterhack le 01 février 2017 à 11:31. Évalué à 3.
    
    Je doit l'avouer le rendue est vraiment pas mal. :)
- [^] # Re: Aaaah Docbook...
  
  Posté par mzf (site web personnel) le 01 février 2017 à 11:53. Évalué à 2.
  
  J'avais hésité à utiliser DocBook pour écrire une documentation commune qui serait ensuite transformé en html ou pdf. Mais la lourdeur des outils à mettre en place et la verbosité du xml m'a fait basculer vers AsciiDoctor qui est plus léger et utilise la syntaxe Markdown.
  
  Exemple de résultat avec AsciiDoctor: version html, version pdf, et sources markdown.
  
  Et les liens hypertextes sont conservés dans le html et le pdf !
# Pas très connu ?

Posté par Blackknight (site web personnel, Mastodon) le 01 février 2017 à 10:04. Évalué à 3. Dernière modification le 01 février 2017 à 10:05.

Il s'agit du système utilisé par FreeBSD depuis plus de 15 ans pour toute sa documentation, avec, certes, un passage de SGML à XML (cf la documentation du contributeur).
De ce que j'ai pu voir, NetBSD l'utilise aussi.

Debian utilise DebianDoc dont le format ressemble étrangement à DocBook.

On ne peut pas dire que ce ne soit pas connu.

Personnellement, hormis quelques contributions FreeBSD, je l'ai aussi utilisé au boulot pour pondre une ou deux documentations techniques liées à l'administration système.
J'avais aussi réécrit l'intégralité des articles sur les failles de sécurité de Fred Raynal, Christophe Grenier et Christophe Blaess.

Je trouve que c'est pas mal mais il faut l'environnement pour la rédaction parce que sinon, c'est assez barbant.

A l'époque, j'utilisais le mode Emacs PSGML en raison de l'utilisation de SGML sur la documentation FreeBSD mais il semble exister un mode XML spécifique DocBook que je n'ai pas essayé.

Après, il semble qu'il y ait aussi des plugins pour d'autres éditeurs (cf. là)
- [^] # Re: Pas très connu ?
  
  Posté par gusterhack le 01 février 2017 à 10:09. Évalué à 1.
  
  Honnêtement je le pensais peut utiliser car je n'en avais pas entendu parlé avant.
  - [^] # Re: Pas très connu ?
    
    Posté par Blackknight (site web personnel, Mastodon) le 01 février 2017 à 10:11. Évalué à 3.
    
    Comme dit plus haut, ce n'est juste plus à la mode :)
    Maintenant, c'est le Markdown et autres format simplifiés qui ont le vent en poupe.
  - [^] # Re: Pas très connu ?
    
    Posté par Albert_ le 01 février 2017 à 10:27. Évalué à 3.
    
    s/peut/peu/
# Sphinx

Posté par Albert_ le 01 février 2017 à 10:27. Évalué à 7. Dernière modification le 01 février 2017 à 10:29.

Utilise pour la documentation python et recemment par le kernel linux (si j'en crois les messages de Linus Torvalds)

http://www.sphinx-doc.org/en/stable/

Il n'y a pas de builder ODF par contre.

Et avec pandoc tu peux convertir dans pas mal de format.
- [^] # Re: Sphinx
  
  Posté par Blackknight (site web personnel, Mastodon) le 01 février 2017 à 10:38. Évalué à 1.
  
  J'avais effectivement pensé aussi à Sphinx mais en y regardant de plus près après mon dernier commentaire, je me suis rendu compte que DocBook est beaucoup plus descriptif que les langages Sphinx, Markdown et consorts.
  Je trouve ces derniers beaucoup plus bas niveau.
  
  Sphinx décrit la structure en termes de titres, paragraphes et code source là où DocBook peut aussi décrire des entités comme les personnes, les adresses mails, les codes ISBN, les lignes de commande…
  
  Au final, cela pas forcément d'importance sur le rendu mais cela peut permettre comme dit plus haut une meilleure gestion des recherches sur les documents qui portent à la fois de la forme et du sens.
  - [^] # Re: Sphinx
    
    Posté par Jice le 01 février 2017 à 11:09. Évalué à 1.
    
    De fait, si pour la documentation d'une application quelconque, cela n'a pas forcément grand intérêt, pour documenter des centaines voire milliers d'applications et processus présents dans un gros SI, ce marquage est un avantage considérable.
  - [^] # Re: Sphinx
    
    Posté par Albert_ le 01 février 2017 à 11:52. Évalué à 2.
    
    DocBook peut aussi décrire des entités comme les personnes, les adresses mails, les codes ISBN, les lignes de commande…
    
    Pour les personnes et ISBN je sais pas trop ce que tu veux dire mais pour les emails et les lignes de commandes ca existe pour markdown et reStructuredText (ie sphinx).
    
    Sphinx permet aussi l'utilisation de LaTeX pour les equations (tres appreciables).
    - [^] # Re: Sphinx
      
      Posté par Blackknight (site web personnel, Mastodon) le 01 février 2017 à 14:04. Évalué à 1.
      
      Pour les personnes et ISBN je sais pas trop ce que tu veux dire
      
      En gros, il y a des balises XML permettant de saisir ce genre d'information.
      Dans le cas de l'ISBN ( International Standard Book Number ) (mais pas que) pour donner l'identifiant d'un ouvrage, on peut utiliser le balise biblioid.
      Pour les personnes, la balise person permet de préciser l'adresse, le mail…
      - [^] # Re: Sphinx
        
        Posté par Jice le 02 février 2017 à 09:13. Évalué à 3.
        
        …Ce qui permet ensuite de parser les documents (avec XSLT par exemple) et de retrouver tous les ISBN des bouquins référencés. On n'est pas juste dans l'idée de mettre une adresse email en italique mais bien d'identifier des éléments en vue d'un traitement automatisé. Pour une documentation d'entreprise regroupant des milliers (millions ?) de fichiers, ça peut être un vrai plus lorsqu'il s'agit de retrouver ceux qui mentionnent un sujet en particulier (par exemple une personne nommée "Long" ou un organisme identifié par le code 352).
    - [^] # Re: Sphinx
      
      Posté par groumly le 03 février 2017 à 08:44. Évalué à 5.
      
      L'intérêt de docbook est qu'il structure les métadonnées de facon standard, et facile à extraire.
      L'idée c'est de constituer une base de données indexées sur les auteurs, les références, citations etc, y comprit entre document. L'idée étant de pouvoir trouver les articles citant un article donne, ou tous les articles auquels jean duschmol a contribué, ce genre de choses.
      T'ingeste les docbooks, tu remplit ton index, tu cherches et derrière t'as des feuilles xslt pour rendre les documents en forme présentable. Tout en un ('fin sauf le moteur de recherche, mais bon on va pas pousser mémé dans les orties quand même).
      
      Markdown et ses dérives sont des formats de mise en page. Tu peux pas en extraire les métadonnées, ou en tout cas, elle n'ont aucune semantique.
      
      Linuxfr, le portail francais du logiciel libre et du neo nazisme.
  - [^] # Re: Sphinx
    
    Posté par pulkomandy (site web personnel, Mastodon) le 01 février 2017 à 12:59. Évalué à 7.
    Ce sont pour moi les deux gros avantages de DocBook:
    - Enfin un vrai langage structuré pour écrire de la documentation. Tous les "concurrents", markdown et compagnie, sont en fait plus proches de HTML, très orientés formatage du texte. DocBook permet vraiment de gérer de grosses bases de documentation et de faire du vrai hypertexte (non seulement des liens, mais aussi de la recherche, des indexs, etc), et de vraiment séparer le rendu du contenu.
    - Il utilise XML, avec tous les outils qui vont autour. En particulier, XSLT avec des stylesheets pour générer à peu près tout et n'importe quoi et qui sont facilement personnalisables.
    Et aussi les deux gros défauts:
    - DocBook fait trop de choses. Il y a plusieurs centaines de balises, ce qui peut le rendre assez compliqué à manipuler quand on part de rien (si on fait des changements dans des documents existants, je pense que ça se passe mieux)
    - Il utilise XML, qui n'est pas la syntaxe la plus facile et confortable pour les humains. Et mettre en place la toolchain n'est pas toujours simple. DocBook vers HTML, ça va, mais DocBook vers PDF, il faut passer par LaTeX ou fop, qui sont tous les deux assez "usine à gaz". Mais l'idée de fop est pas mal (c'est un genre de concurrent à postscript, mais en XML).
    
    Bref, avec les bons outils, ça marche bien une fois que c'est mis en place.
    
    Et pour le "pas très connu": je crois que gtkdoc repose aussi sur docbook. En fait il est partout, mais il marche tellement bien que ça se voit pas!
    - [^] # Re: Sphinx
      
      Posté par Jice le 01 février 2017 à 13:33. Évalué à 1.
      
      Apparemment, dans le pas très connu :-) , on a aussi novell et sun qui sont de gros utilisateurs.
    - [^] # Re: Sphinx
      
      Posté par Blackknight (site web personnel, Mastodon) le 01 février 2017 à 14:07. Évalué à 2. Dernière modification le 01 février 2017 à 14:10.
      
      DocBook permet vraiment de gérer de grosses bases de documentation et de faire du vrai hypertexte (non seulement des liens, mais aussi de la recherche, des indexs, etc), et de vraiment séparer le rendu du contenu.
      
      On peut même imaginer faire de l'extraction et créer des bases de données sémantiques voire des bases de connaissances :D
      Enfin, là, je m'enflamme ;)
      - [^] # Re: Sphinx
        
        Posté par Jice le 02 février 2017 à 08:01. Évalué à 6.
        
        C'est sûr que si les entreprises, au lieu d'utiliser M$ Word utilisaient docbook, ce serait moins le merdier dans les documentations et la richesse de l'information exploitable serait sans aucune mesure.
        Cela entrainerait assurément la fin de la misère et la paix dans le monde.
        Alleluiah !!
        
        [^] # Re: Sphinx
        
        Posté par Reihar le 02 février 2017 à 08:19. Évalué à 2.
        
        Tu en demandes trop. Des liens et une table des matières, ce serait déjà pas mal.
        
        [^] # Re: Sphinx
        
        Posté par Jice le 02 février 2017 à 08:49. Évalué à 3.
        
        C'est la faute de Blackknight. Il s'enflamme, je m'enflamme et on finit par dire n'importe quoi.
      - [^] # Re: Sphinx
        
        Posté par Blackknight (site web personnel, Mastodon) le 02 février 2017 à 12:12. Évalué à 3.
        
        Du coup, je me suis amusé à chercher rapidement un système pour stocker les fichiers DocBook et finalement avec Lux qui est sur une base SolR/Lucene, il y a moyen de faire des requêtes XQuery sur un corpus documentaire.
        
        Intéressant tout ça ;)
# DocBook n'est plus très populaire

Posté par David Demelier (site web personnel) le 01 février 2017 à 14:47. Évalué à 4.
J'ai aussi longtemps cherché des outils permettant de faire de la documentation HTML et PDF. DocBook fait bien les deux mais c'est vieux et plus personne n'a envie de faire de XML.

Il y a plusieurs alternatives intéressantes :
- pandoc, je m'en sers couplé à CMake (car mon application est en C++) et c'est pratique. Par contre c'est très brut, donc il faut vraiment mettre les mains dedans pour avoir un résultat complet.
- mkdocs, pas testé mais ça avait l'air intéressant,
- hugo, plutôt fait pour faire des siteweb mais ça peut très bien convenir pour de la documentation avec un thème adéquat. Je compte y passer. Pas de PDF par contre.
git is great because linus did it, mercurial is better because he didn't
- [^] # Re: DocBook n'est plus très populaire
  
  Posté par gusterhack le 01 février 2017 à 15:01. Évalué à 0.
  
  Honnêtement le xml mois sa me convient.
- [^] # Re: DocBook n'est plus très populaire
  
  Posté par Blackknight (site web personnel, Mastodon) le 01 février 2017 à 15:14. Évalué à 2.
  
  mais c'est vieux et plus personne n'a envie de faire de XML.
  
  C'est moins vieux que le C++ ;)
  
  Mais comme il a été dit plus haut, ces formats s'intéressent autant à la forme qu'au fond (voire plus ?).
  
  Enfin, n'allez pas croire que je sois un fan du XML, loin s'en faut mais il s'agit là pour moi d'un des usages les plus intéressants.
- [^] # Re: DocBook n'est plus très populaire
  
  Posté par gouttegd (site web personnel) le 01 février 2017 à 15:26. Évalué à 7.
  
  DocBook fait bien les deux mais c'est vieux et plus personne n'a envie de faire de XML
  
  Franchement je ne vois pas trop le problème avec le XML ici. OK il y a eu une forte tendance pendant quelques années à mettre du XML partout (exactement comme aujourd’hui on met du JSON partout…), y compris là où il n’était pas forcément adapté et je conçois que certains ont pu en être dégoûté, mais si on s’en tient au XML comme langage de balisage de texte, il a encore parfaitement sa place à mon avis.
  
  Personnellement, je me sens rapidement limité quand je m’essaie à un des langages de balisage « léger » à la mode aujourd’hui (genre Markdown et assimilés).
  - [^] # Re: DocBook n'est plus très populaire
    
    Posté par Marotte ⛧ le 05 février 2017 à 21:24. Évalué à 2.
    
    XML est plus qu’un langage de balisage de texte. Il intègre surtout la notion de DTD (document type definition) qui permet de décrire la structure du document et donc de vérifier la conformité d’un document à un modèle.
    
    C’est très utile pour faire par exemple de la transformation de données (ETL) mais pour le tout venant de la documentation, voire même pour des corpus documentaires plus conséquents, XML me semble vraiment overkill.
    
    C’est comme pour un fichier de configuration, utiliser XML n’apporte rien (à part de la verbosité inutile) la plupart du temps.
    
    Si on prends HTML5, qui est si on veut une « application du XML », c’est pour moi un langage d’export, mais pas le format sous lequel on doit stocker lesdits documents.
    - [^] # Re: DocBook n'est plus très populaire
      
      Posté par Renault (site web personnel) le 06 février 2017 à 12:19. Évalué à 2.
      
      C’est comme pour un fichier de configuration, utiliser XML n’apporte rien (à part de la verbosité inutile) la plupart du temps.
      
      Bah justement, c'est super pertinent pour les fichiers de confs un peu complexes où tu souhaites t'assurer que tous les champs sont bien saisis et renseignés comme prévu.
      
      C'est assez puissant pour ce genre de cas d'usages.
  - [^] # Re: DocBook n'est plus très populaire
    
    Posté par David Demelier (site web personnel) le 06 février 2017 à 20:35. Évalué à 2.
    
    Personnellement, je me sens rapidement limité quand je m’essaie à un des langages de balisage « léger » à la mode aujourd’hui (genre Markdown et assimilés).
    
    je suis complètement d'accord avec ce point.
    
    J'étais intéressé par docbook aussi mais les 3/4 des documentations sur lequelles je tombe au moins 10 ans :/
    
    git is great because linus did it, mercurial is better because he didn't
    - [^] # Re: DocBook n'est plus très populaire
      
      Posté par Blackknight (site web personnel, Mastodon) le 07 février 2017 à 08:42. Évalué à 1.
      
      J'étais intéressé par docbook aussi mais les 3/4 des documentations sur lequelles je tombe au moins 10 ans :/
      
      Certes mais elles sont toujours d'actualité puisque le fonctionnement global n'a pas changé.
      On utilise toujours les mêmes technologies qui fonctionnent bien depuis plus de dix ans.
      Ce n'est donc pas vraiment un problème.
      - [^] # Re: DocBook n'est plus très populaire
        
        Posté par pulkomandy (site web personnel, Mastodon) le 07 février 2017 à 12:16. Évalué à 2. Dernière modification le 07 février 2017 à 12:17.
        
        Et puis comme elles sont écrites en DocBook, tu peux utiliser une feuille de style à jour pour les générer en HTML5 tout beau tout propre!
        
        Plus sérieusement: http://tdg.docbook.org/tdg/5.1/docbook.html mis à jour il y a à peine 3 mois, et la première édition n'a que 7 ans :)
        
        (il faut chercher "docbook 5" plutôt que juste docbook pour trouver plus facilement des informations à jour, je suppose?)
# XML et gestion de versions

Posté par Cyrille Pontvieux (site web personnel, Mastodon) le 02 février 2017 à 23:00. Évalué à 3.

Comme dit plus haut ce n'est plus très populaire mais ça a eu son heure de gloire et ça fait toujours le job.

Par contre la plaie avec les fichiers XML c'est les gestionnaires de versions (enfin l'outil permettant de détecter les changements entre deux versions). Impossible de faire un diff correct sur des fichiers XML. Certes c'est du texte mais les détections de blocs de changement se trompent souvent avec les balises ouvrantes ou fermantes. Alors quand en plus y'a du conflit au milieu c'est la mort. Le XML c'est tellement 2000 (ou moins d'ailleurs).

J'en profite au passage si quelqu'un connait un outil qui permettrait d'améliorer la détections de blocs de changements quand on sait que la source est du XML ? Et bonus si on pouvait brancher cet hypothétique outil avec git (en se basant sur l'extension de fichier en utilisant les attributes de git) ?
- [^] # Re: XML et gestion de versions
  
  Posté par Thomas Douillard le 03 février 2017 à 08:43. Évalué à 3. Dernière modification le 03 février 2017 à 08:43.
  
  Il y a plein de résultats pour https://www.google.fr/search?q=xmldiff A tester.
  - [^] # Re: XML et gestion de versions
    
    Posté par pulkomandy (site web personnel, Mastodon) le 03 février 2017 à 09:21. Évalué à 2.
    
    Et pour le brancher à git: http://staxmanade.com/2014/12/use-different-git-diff-tools-per-file-extension/
  - [^] # Re: XML et gestion de versions
    
    Posté par Nicolas Boulay (site web personnel) le 03 février 2017 à 10:33. Évalué à 3.
    
    Si tu regardes les différents liens, il n'y a rien de terrible ou d'évident.
    
    "La première sécurité est la liberté"
- [^] # Re: XML et gestion de versions
  
  Posté par gusterhack le 03 février 2017 à 13:23. Évalué à 1.
  
  Tout les site web sont en HTML ? Donc c'est pas trop 2000 étant donnée que le HTML est basée sur le XML.
  C'était mon instant troll :)
  - [^] # Re: XML et gestion de versions
    
    Posté par Benoît Sibaud (site web personnel) le 03 février 2017 à 13:35. Évalué à 9. Dernière modification le 03 février 2017 à 13:35.
    
    En même temps le XML n'est que du SGML simplifié pour les gens ayant du mal à embrasser la complexité dans sa froide intégralité et qui à force de chouiner ont obtenu une version plus abordable.
    
    C'est vrai que dit comme ça c'est encore moins flatteur pour la génération d'après qui a du mal à embrasser la simple complexité du XML…

Suivre le flux des commentaires

Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.