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

7
1
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 . É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 (page perso) . É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 . É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 (page perso) . É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 . É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 . É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 . É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.

        • [^] # Re: Aaaah Docbook...

          Posté par . É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 (page perso) . É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 . Évalué à 2. Dernière modification le 02/02/17 à 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.

            • [^] # Re: Aaaah Docbook...

              Posté par . É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 . É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 (page perso) . É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 (page perso) . É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 . É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 . É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 . Évalué à 2. Dernière modification le 03/02/17 à 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 . É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 (page perso) . É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 . Évalué à 3. Dernière modification le 01/02/17 à 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 (page perso) . É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 (page perso) . É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 (page perso) . Évalué à 3. Dernière modification le 01/02/17 à 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. )

  • # Sphinx

    Posté par . Évalué à 7. Dernière modification le 01/02/17 à 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 (page perso) . É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 . É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 . É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 (page perso) . É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 . É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 . É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 (page perso) . É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 . Évalué à 1.

          Apparemment, dans le pas très connu :-) , on a aussi novell et sun qui sont de gros utilisateurs.

        • [^] # Re: Sphinx

          Posté par (page perso) . Évalué à 2. Dernière modification le 01/02/17 à 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 . É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 . Évalué à 2.

              Tu en demandes trop. Des liens et une table des matières, ce serait déjà pas mal.

              • [^] # Re: Sphinx

                Posté par . É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 (page perso) . É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 (page perso) . É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.

    svn is the IE6 of version control

    • [^] # Re: DocBook n'est plus très populaire

      Posté par . Évalué à 0.

      Honnêtement le xml mois sa me convient.

    • [^] # Re: DocBook n'est plus très populaire

      Posté par (page perso) . É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 (page perso) . É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 . É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 (page perso) . É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 (page perso) . É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 :/

        svn is the IE6 of version control

        • [^] # Re: DocBook n'est plus très populaire

          Posté par (page perso) . É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 (page perso) . Évalué à 2. Dernière modification le 07/02/17 à 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 (page perso) . É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) ?

Suivre le flux des commentaires

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