Utroff : la renaissance de Troff

Posté par  (site web personnel) . Édité par ZeroHeure, Benoît Sibaud et palm123. Modéré par Florent Zara. Licence CC By‑SA.
Étiquettes :
42
4
nov.
2013
Doc

Troff est un vénérable logiciel de formatage de texte hérité d'Unix. Plusieurs versions de Troff coexistent aujourd'hui, dont celle du projet Heirloom, qui a ajouté à Troff des fonctionnalités typographiques modernes. Dans l'esprit du projet Heirloom, Utroff retravaille l'ensemble des logiciels qui accompagnent Troff pour nous permettre d'utiliser efficacement celui-ci aujourd'hui.

Pour la sortie de la première version publique d'Utroff, cette dépêche propose une réponse aux deux questions que vous ne manquerez pas de vous poser : « pourquoi utiliser Troff aujourd'hui ? » et « pourquoi choisir Utroff ? ».

Sommaire

Pourquoi utiliser Troff aujourd'hui ?

Le logiciel libre et le projet Heirloom

Alors que le logiciel libre est généralement plébiscité pour des raisons techniques ou éthiques, le projet Heirloom, dont Utroff est largement inspiré, a ceci de singulier qu'il utilise les libertés offertes par les licences libres pour des raisons esthétiques et nostalgiques. Le but du projet Heirloom n'est pas tant de donner à l'utilisateur plus de libertés ou de meilleurs outils que de lui offrir un petit moment de nostalgie en lui permettant d'utiliser les bons vieux outils d'Unix. Ce n'est pourtant pas un musée du logiciel, mais une mise à jour des outils d'antan :

« The Heirloom Project is not a software museum; it does not attempt to preserve utilities unmodified. Rather, it keeps stylistic, algorithmic, and interface aspects intact while modernizing the framework as appropriate. »

Ainsi, par-delà cette nostalgie, le projet Heirloom montre que ces antiques outils conservent des qualités non négligeables aujourd'hui, de sorte que ce projet nous invite à reconsidérer notre point de vue sur le progrès en matière informatique.

L'ergonomie d'Unix et le langage

L'ergonomie d'Unix consiste, selon certains, à utiliser le langage comme interface, et Troff exploite mieux que tout autre logiciel cette ergonomie : à chaque format de données (équation, diagramme, table, référence…) correspond un mini-langage. Ainsi Troff s'utilise en passant le fichier source à travers de multiples filtres qui interprètent chacun de ces mini-langages.

À l'usage, il apparaît que l'interface langagière qui est celle d'Unix est particulièrement adaptée au travail des textes. En effet, outre qu'elle nous donne accès à des possibilités technologiques, cette ergonomie structure la pensée. En apprenant à utiliser l'outil, on apprend quelque chose sur la structure des données qu'on manipule, et corrélativement, la pensée découvre de nouvelles façons de se structurer en découvrant de nouvelles structures symboliques. La pratique d'une interface texte aiguise ainsi le regard analytique que l'on doit porter sur le texte. Il y a donc un plaisir et un intérêt, pour qui aime l'analyse des textes, à travailler avec ces vieux outils pensés pour la ligne de commande.

La philosophie Unix et la question de la maîtrise

Le logiciel libre se donne pour objectif d'offrir à l'utilisateur la possibilité de maîtriser son outil informatique. Mais dans les faits, la complexité des logiciels d'aujourd'hui fait qu'il est difficile de mettre en pratique ces libertés de droit. Il se trouve que les vieux outils Unix souffrent moins de cette difficulté : marqués par l'idée « un programme, une tâche », ils sont construits à la manière d'un ensemble de multiples petits logiciels, aux dépendances minimales, et sont pour cela bien plus faciles à modifier que leurs équivalents contemporains. Ainsi, Troff est le seul logiciel de formatage de texte que je sois capable de maîtriser parfaitement.

Si Troff est susceptible d'être maîtrisé, ce n'est pas seulement parce qu'il est accompagné d'un ensemble d'outils hackables, c'est aussi parce que c'est un langage simple et bien documenté. La documentation exhaustive de Troff est claire et ne dépasse pas les soixante pages, quant au langage, quoique sa syntaxe puisse paraître étrange, il est tout à fait accessible, même aux débutants en programmation.

Pourquoi choisir Utroff ?

Le détail en typographie avec Heirloom Troff

Deux algorithmes permettent de composer des textes avec un rendu typographique de qualité : l'ajustement paragraphe par paragraphe, qui calcule l'espace inter-mots sur l'ensemble du paragraphe plutôt que ligne après ligne, et la micro-typographie, qui modifie d'un ou deux pour cent la taille des glyphes pour uniformiser visuellement l'espace inter-mots. Ces algorithmes ont été créés pour Tex et PdfTex, puis repris par les logiciels de PAO du marché, mais aussi par Heirloom Troff. C'est bien parce que Heirloom Troff incorpore ces algorithmes qu'il produit des textes dont la qualité typographique est, potentiellement, équivalente à celle de LaTex.

Cependant, Heirloom Troff ne fournit aucune macro qui permette d'utiliser ces algorithmes simplement. C'est d'abord pour combler ce manque que Utroff a été créé.

La simplicité des macros Utmac

S'il est possible de composer un document en Troff pur, il est bien plus simple d'utiliser des macros qui définissent le format des éléments les plus fréquents et s'occupent de la mise en page. Utmac, l'ensemble de macros créées pour Utroff, suit quelques principes ergonomiques :

  • Toutes les macros utilisent le même langage, de sorte qu'un même document peut être exporté en plusieurs formats et selon plusieurs mises en page, sans qu'il soit nécessaire d'en modifier les sources. Les formats d'export sont : postscript (donc pdf), README, man, xml, html, fodt (flat open document texts), markdown et tty (en cours). Deux mises en page sont actuellement disponibles : l'une est dédiée aux textes littéraires longs (les thèses), et l'autre à la documentation technique. Une macro dédiée aux lettres et aux CV est en cours de création.
  • Les macros gèrent d'office les besoins les plus fréquents : sommaire, table des matières, liens internes, index, références, coloration syntaxique, recto-verso.
  • Outre qu'elles utilisent les algorithmes d'Heirloom Troff dédiés à la typographie, elles respectent les bonnes pratiques en matière de mise en page : principe de grille, principe de ligne, et ortho-typographie. Elles repèrent et mentionnent veuves et orphelines et fournissent des outils pour les faire disparaître.
  • Elles n'ont que peu d'options de configuration. D'une part parce que leur mise en page est censée être adaptée au besoin, et d'autre part parce que pour un besoin spécifique la bonne pratique consiste à créer une macro spécifique, généralement en adaptant une macro existante.

Le format des macros est documenté dans le manuel d'Utmac.

Le formatage des références bibliographiques avec Refer

Il existe une norme internationale définissant la structure que doivent avoir les références bibliographiques, qu'elles soient indiquées en bas de page ou en fin d'ouvrage : la norme ISO-690, dont Rositza Kyheng propose un résumé. Largement ignorée, souvent confondue par les universitaires avec une norme réservée aux bibliothèques, cette norme est néanmoins la seule qu'éditeurs et universitaires devraient respecter. Refer, le logiciel dédié au formatage des références bibliographiques, a été modifié pour qu'il puisse respecter cette norme. En particulier, puisque la norme ne fait que définir l'ordre des champs, c'est l'algorithme de tri des références qui a été adapté.

À ces modifications s'ajoutent une macro (u-ref), incluse dans les macros Utmac, offrant la possibilité d'utiliser proprement une police contenant de vraies petites capitales, la gestion des champs dédiés aux références électroniques (url, format, date de consultation, …), le remplacement par « idem » ou « op. cit. p. xx », et la distinction entre notes de bas de pages et liste bibliographique de fin d'ouvrage.

Consulter le manuel de refer et celui de la macro u-ref.

Le grec polytonique avec Tchars, inspiré de Dchars

Les plus assidus d'entre-vous auront suivi le développement de Dchars, de notre ami Xavier Faure, qui interprète du code ascii pour produire des caractères utf8 complexes. Utroff méritait d'avoir un tel interpréteur, mais ne pouvait se permettre d'ajouter python à ses dépendances. J'ai donc écrit un tout petit interpréteur en C, et l'ai nommé Tchars (Troff|Translate Characters) en référence à Dchars.

Un récent journal explique les détails de cette implémentation, quant à son utilisation elle est documentée dans le manuel de Tchars.

Les index avec Idx

Le travail d'indexation ne se limite pas à l'indexation du document en cours d'écriture, il concerne aussi l'indexation d'ouvrages de référence, dont bien souvent aucune version électronique n'est disponible. Idx est un script awk encapsulé dans du shell facilitant grandement l'indexation de textes papiers, et réalisant l'indexation des documents Troff.

Un journal propose un exemple d'utilisation d'idx (attention, l'interface a évolué depuis), et son utilisation est documentée dans le manuel d'idx.

La coloration syntaxique avec Ugrind

Voici le genre le commentaires que l'on trouve dans les sources des logiciels qui accompagnent Troff :

    /*
     * Vfontedpr.
     *
     * Dave Presotto 1/12/81 (adapted from an earlier version by
     * Bill Joy)
     *
     */

Au début des années 80, alors qu'il travaillait encore à l'université de Berkeley, Bill Joy a trouvé nécessaire d'ajouter un colorateur syntaxique à Troff. Il a pour cela créé Vfontedpr, que les membres de la liste de discussion de Groff comprennent comme signifiant « Visual Font Edit Print », un outil en C appelé par le bien nommé script Vgrind (la moulinette qui grince). Après bien des péripéties, Vgrind s'est retrouvé dans l'archive d'Heirloom Doctools, de sorte que, Vfontedpr, renommé Ugrind pour le projet Utroff, continue à colorer le code source pour Troff depuis plus de 30 ans.

Signe de son age avancé, la syntaxe du fichier de configuration (vgrindefs, renommé ugrindefs pour Utroff) où sont définies la structure des langages à colorer, est celle de Termcap :

    /*
     * grindcap - routines for dealing with the language
     * definitions data base
     * (code stolen almost totally from termcap)
     */

Puisque qu'il fallait à tout le moins qu'Ugrind puisse colorer les sources en Troff, et puisque la syntaxe de Troff est difficilement interprétable dans le langage de Termcap, Ugrind contient, entre autres modifications de Vfontedpr, un parseur codé en dur du langage Troff.

Le manuel d'ugrind décrit son utilisation.

L'export vers l'xml

Troff a commencé à péricliter au moment où apparaissait le web, l'HTML et l'XML. Il y a probablement là un lien causal : de nombreux scripts ont été créés pour produire de l'HTML à partir de Troff, mais aucune solution universelle n'a jamais été trouvée. En effet, seules les macros créées en langage Troff peuvent être interprétées car c'est en leur sein qu'est définie la sémantique du texte. De fait, il y a autant d'interpréteurs que de macros, et chaque interpréteur doit pouvoir en outre comprendre quelques fonctions Troff susceptibles d'être utilisées dans les fichiers sources.

Finalement, Eric. S. Raymond a su imposer doclifter, un interpréteur en python, qui reste néanmoins réservé aux macros historiques.

Une solution n'a pas été explorée jusqu'alors : si Troff produit des fichiers postscript, son grand frère, Nroff produit des fichiers textes, de sorte qu'il peut produire des fichiers XML sans en passer par un interpréteur. De fait l'une des macros Utmac a été écrite pour gérer l'export vers l'XML avec Nroff. Toutes les fonctions du langage Troff sont ainsi gérées nativement, et, si cette solution ne répond pas à tous les besoins, elle a l'avantage d'être très simple à mettre en œuvre.

Le site d'Utroff explique cette conversion vers l'XML.

Remerciements

Utroff est hébergé par Tuxfamily, et son développement a bénéficié de l'aide de quelques LinuxFr-iens : MrSpackMan, fmaz fmaz, et Xavier Faure, déjà cité. Qu'ils soient tous remerciés.

Post Scriptum

Dépêche rédigée avec Utroff :

    ugrind utroff-0.1.tr | nroff -muw > utroff-0.1.mkd

Aller plus loin

  • # Des styles ! Des systèmes de documentation automatique !

    Posté par  . Évalué à 3. Dernière modification le 04 novembre 2013 à 16:54.

    C'est cool de voir renaitre Troff. La sortie pour man et tty fait que c'est vraiment adapté pour la documentation logicielle.

    Personnellement ce qui me manque en général c'est un ensemble de modèles de qualité et je n'ai aucune compétence pour faire quoi que ce soit d'élégant. Le style par défaut de libreoffice est à vomir. Latex est très beau mais les modèles sont programmés dans le langage de TeX qui ne donne pas très envie à apprendre. On peut utiliser Lyx mais pas vraiment en fichier texte. Le style des pdfs produits par utroff est très élégant mais peut-on facilement le changer ?

    De nos jours les documentations sont extraites automatiquement ; seuls les plus petits projets écrivent leur page de man à la main. Travaillez-vous avec les mainteneurs de doxygen, Sphinx, etc. pour que ces logiciels produisent une sortie utilisable par utroff ?

    • [^] # Re: Des styles ! Des systèmes de documentation automatique !

      Posté par  (site web personnel) . Évalué à 7.

      Le style des pdfs produits par utroff est très élégant mais peut-on facilement le changer ?

      Les deux commandes suivantes, qui appellent deux macros différentes (uh et us) mettent en forme un même document de deux façons différentes, ce qui est une façon de changer de style:

      troff -muh doc.tr | dpost | ps2pdf - > doc-uh.pdf
      troff -mus doc.tr | dpost | ps2pdf - > doc-us.pdf

      Si vous voulez de plus nombreux styles de mise en page pour ces mêmes document sources, vous n'aurez pas d'autres choix que de modifier les sources de l'une de ces macros. Je travaille en ce moment sur une macro pour les CV et les lettres, et je m'aperçois qu'en fait, il n'y a que quelques lignes à modifier pour produire une mise en page vraiment différente. Mais rien que pour cela, il faut néanmoins être un peu familier avec le langage Troff…

      Travaillez-vous avec les mainteneurs de doxygen, Sphinx, etc. pour que ces logiciels produisent une sortie utilisable par utroff ?

      Non, je ne travaille pas avec eux. Et effectivement, si j'ai un peu travaillé pour exporter les documents Utroff vers divers formats, pour l'instant je n'ai rien fait pour l'import.

      À vue de nez, il faudrait créer des filtres d'export vers le format d'Utroff pour Text2tags, reStructeredText, et Markdown pour couvrir la majorité des potentiels usages. Ça ne doit pas être bien compliqué.

      • [^] # Re: Des styles ! Des systèmes de documentation automatique !

        Posté par  . Évalué à 4. Dernière modification le 05 novembre 2013 à 10:52.

        salut,

        puisque tu en parles, suite à ta dépêche j'avais justement commencé à travailler sur un export txt2tags vers troff. Quelques questions :

        • il existe déjà dans txt2tags des exports vers man et mom, qui semblent tout deux être des dialectes de (t)roff (mom étant une macro). Est-ce qu'il existe une sorte de (t)roff générique, sur les fonctionalités de base (titres, gras, souligné, italique…) qui pourrait être compris par mom, utroff etc ? Je ne crois pas, vu notre discussion lors de ta dernière dépêche (cf. https://linuxfr.org/news/a-la-recherche-des-sources-de-troff#comment-1375368). Dans le même ordre d'idée, Utroff comprend la syntaxe de la macro ms ou c'est complètement différent ?

        • si on doit le nommer, ça serait roff, troff ou utroff ? (cette réponse étant sans doute fortement conditionnée par la réponse à la question du dessus). Quelle extension ? .tr ? (ou .utr pour utroff ?), sachant qu'on ne peut avoir qu'une seule extension par cible (si on prévoit un export troff ms plus générique, ça pourrait s'appeler .tr)

        • tu conseillerais donc un export vers ms, vers utroff ou vers les 2 ?

        • Si je créé le canevas sur le svn de txt2tags, tu pourrais aider pour remplir la syntaxe qui va bien pour utroff, voire ms ?

        « I approve of any development that makes it more difficult for governments and criminals to monopolize the use of force. » Eric Raymond

        • [^] # Re: Des styles ! Des systèmes de documentation automatique !

          Posté par  (site web personnel) . Évalué à 5.

          Salut,

          Je suis heureux de voir que ta curiosité pour Troff ne fléchit pas !

          Il me semble utile, bien qu'un peu long, de commencer par donner quelques précisions pour pouvoir répondre simplement à tes questions.

          Précisions

          « Troff » désigne tant le langage que l'interpréteur du langage (il en va de même pour Tex). Le langage Troff est graphique: il indique comment afficher les éléments dans la page, et ne donne donc aucune indication sémantique sur ces éléments. On peut composer un document sans utiliser de macros:

          .sp 1v \" saute une ligne
          .ft R   \" utilise la police romane
          .ad b  \" alignement justifé
          lorem ipsum

          Les macros sont composées en langage Troff. Elles désignent d'abord une fonction troff, et par extension, un fichier rassemblant plusieurs fonctions. Elles définissent des raccourcis pour positionner les éléments dans la page. C'est donc au niveau des macros que peut être définie la sémantique du document (paragraphe, citation…), de sorte que la macro gère le rapport entre le fond et la forme:

          .de PP \" macro définissant les paragraphes
          .    sp 1v
          .    ft R
          .    ad b
          . .
          .PP
          lorem ipsum
          .PP
          lorem ipsum

          Historiquement, il existe plusieurs macros: ms, me, man, mdoc. Plus récemment, mom a été créé. Chacune des ces macros propose une syntaxe particulière. Par exemple ms commence les notes de bas de page par .FS (footnote start), utmac préfère .NS (note start). Outre qu'elles ont chacune une syntaxe, chaque macro a sa philosophie: man, très vieille macro, propose des fonctions graphiques plus que sémantiques, ms commence à être sémantique, mom est très hautement configurable, utmac sépare strictement le fond de la forme.

          Il n'est donc pas possible de créer un document interprétable par toutes les macros. Par contre, il est possible de créer un document interprétable sans avoir besoin d'une des macros existante: il suffit d'ajouter en entête du document les fonctions dont on a besoin.

          Maintenant, je peux répondre à tes questions…

          Réponses aux questions

          Est-ce qu'il existe une sorte de (t)roff générique, sur les fonctionalités de base (titres, gras, souligné, italique…) qui pourrait être compris par mom, utroff etc ?

          Placer ses propres macros en tête de son document est une façon de créer un fichier troff générique: il sera interprétable par troff sans avoir besoin de macros. Mais les macros existantes ne pourront pas être utilisées pour mettre en forme ce document.

          Utroff comprend la syntaxe de la macro ms ou c'est complètement différent ?

          C'est complètement différent, même si, en bricolant une macro interface, on pourrait imaginer qu'Utroff puisse interpréter la syntaxe de ms.

          Quelle extension ?

          les macros historiques ont un type mime et une extension: .ms, .man, .me, peut-être .mom. Sinon, l'extension des documents troff est .tr ou .t (vieille époque des extensions à une lettre !). Pour les macros .tmac tend à s'imposer. Pour utroff, faute de type mime spécifique, il faut utiliser .tr.

          tu conseillerais donc un export vers ms, vers utroff ou vers les 2 ?

          Je conseillerais les deux, mais tout dépend de l'usage final. Et pourquoi ne pas utiliser mom si l'export vers mom est déjà implémenté ?

          La macro ms a l'avantage d'être installée par défaut avec toutes les versions de troff, ce qui est loin d'être le cas d'utroff. C'est la macro qui fut utilisée pour toute la documentation d'Unix, et plus récemment pour celle de Plan9. Elle est simple et efficace. Je l'ai utilisée pendant longtemps.

          Les macros Utmac apportent une meilleure qualité typographique, et des fonctions avancées (sommaires, index, etc.). Il faudra par contre les installer manuellement, et gérer l'utilisation d'Heirloom Troff (que les distributions installent généralement dans un répertoire qui n'est pas dans le PATH). Il faudra aussi assumer la jeunesse et la fragilité du projet.

          Si je créé le canevas sur le svn de txt2tags, tu pourrais aider pour remplir la syntaxe qui va bien pour utroff, voire ms ?

          Avec grand plaisir, tant pour utroff que pour ms. En plus, si je me souviens bien, txt2tags est en python, que j'apprécie.

          • [^] # Re: Des styles ! Des systèmes de documentation automatique !

            Posté par  . Évalué à 2.

            merci des précisions et de ta réponse.

            J'ai pu compiler utroff sans problème, en revanche heirloom pose des problèmes : j'ai essayé d'installer ça chez moi, pour me rendre compte que pour le compiler il fallait installer les heirloom-devtools, qui n'ont pas été touchés depuis plusieurs années (à récupérer avec cvs).

            J'ai réussi à les compiler et installer à force de tâtonnement (bonjour les chemins façon vieux unix, avec des /sbin/sh, /usr/ucb/) mais quand j'essaye de compiler les heirloom-doctools avec leurs outils de dev, j'obtiens cela :

            yacc -d picy.y 
            *** buffer overflow detected ***: yacc terminated
            ======= Backtrace: =========
            /lib/x86_64-linux-gnu/libc.so.6(__fortify_fail+0x5c)[0x2b313af8f83c]
            

            possible que ça soit lié à mon processeur 64 bit. Il n'y a pas d'autre moyen ? Qu'utilises-tu toi-même ? Parce que sans paquet disponible ni facilement installable de heirloom-doctools, ça limite la diffusion de ce bel outil.

            « I approve of any development that makes it more difficult for governments and criminals to monopolize the use of force. » Eric Raymond

            • [^] # Re: Des styles ! Des systèmes de documentation automatique !

              Posté par  . Évalué à 3.

              Salut, j'ai pas encore essayé mais gentoo supporte heirloom-devtools et ce pour exactement deux architectures : amd64 et x64-solaris. Donc c'est censé marcher en 64 bits… En revanche il y a un patch de la distro. Tu peux consulter http://sources.gentoo.org/cgi-bin/viewvc.cgi/gentoo-x86/sys-devel/heirloom-devtools/ le répertoire comporte heirloom-devtools-070525-r1.ebuild (le script de compilation). Le sous-répertoire files/ comporte heirloom-devtools-070527-64-bit.patch auquel tu veux peut-être jeter un œil.

              • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                Posté par  . Évalué à 2.

                je viens d'essayer le patch, j'ai pu l'appliquer, en revanche j'ai toujours la même erreur à la compilation de doctools.

                Après, mes connaissances dans le domaine s'arrêtent là.

                « I approve of any development that makes it more difficult for governments and criminals to monopolize the use of force. » Eric Raymond

            • [^] # Re: Des styles ! Des systèmes de documentation automatique !

              Posté par  . Évalué à 1.

              Je n'ai pas eu ce problème pour installer les heirloom-doctools sur ma arch. Je suis parti de
              https://aur.archlinux.org/packages/heirloom-doctools-cvs, pas eu besoin des devtools.
              J'ai juste modifié config.diff pour avoir une installation dans /opt/heirloom.

            • [^] # Re: Des styles ! Des systèmes de documentation automatique !

              Posté par  (site web personnel) . Évalué à 3.

              heirloom pose des problèmes

              Quelle distribution utilises-tu qui n'empaquette pas la suite Heirloom ? Elle est dans debian, archlinux (aur), et NetBSD. J'ai du mal à croire qu'elle ne soit pas présente à peu près partout.

              La dépendance de compilation avec heirloom-devtools n'est pas stricte: chez moi heirloom doctools compile très bien avec les outils Gnu de ma distribution. Je viens de réessayer par trois fois.

              Je le configure, compile, et installe (dans /tmp/, pour le test) ainsi:

              mv mk.config mk.config.bak
              echo "
              PREFIX=/tmp/hlm/
              BINDIR=\$(PREFIX)/bin
              LIBDIR=\$(PREFIX)/lib
              PUBDIR=\$(PREFIX)/pub
              MANDIR=\$(PREFIX)/man
              MACDIR=\$(LIBDIR)/doctools/tmac
              FNTDIR=\$(LIBDIR)/doctools/font
              PSTDIR=\$(FNTDIR)/devpost/postscript
              TABDIR=\$(LIBDIR)/doctools/nterm
              HYPDIR=\$(LIBDIR)/doctools/hyphen
              REFDIR=\$(LIBDIR)/reftools
              INSTALL=/bin/install
              EUC=-DEUC
              STRIP=strip -s -R .comment -R .note
              CC=cc
              CCC=c++
              CFLAGS=-O
              CPPFLAGS=-D_GNU_SOURCE
              LDFLAGS=
              LIBS=
              SHELL=/bin/sh
              RANLIB=(hash ranlib) >/dev/null 2>&1 || exit 0; ranlib
              " >> mk.config
              
              make
              make install
              # pour créer un paquet:
              # make ROOT="/tmp/paquet/" install

              Si tu veux faire simple, tu configures Utroff de la même façon. Lors de l'installation, Utroff écrasera heirloom refer et heirloom soelim, mais normalement, tu gagnes au change :).
              Pour utiliser les outils d'heirloom et d'utroff sans ruiner ton path, utilises ce petit script, nommé h:

              #! /bin/sh
              
              # h: run heirloom binaries.
              # usage:
              # h troff f.tr | h dpost | ps2pdf - > f.pdf
              
              HLM=/tmp/hlm/bin/
              
              $HLM/$@

              Si tu es content, tu recompiles et installes tout avec, plutôt que /tmp/hlm/ comme prefixe, /opt/hlm/ ou n'importe quel autre répertoire de ton choix.

              • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                Posté par  . Évalué à 2.

                Merci, ça compile avec ton mk.config et les outils de ma distribution (bison, flex), à la place des heirloom-devtools.

                Sans doute que la première fois, les chemins et les paramètres ne lui convenaient pas, et en lisant la doc de heirloom-doctools, ça disait qu'en utilisant autre chose il y avait un risque que ça ne compile pas, d'où ma recherche d'une autre piste.

                Ma distribution est linux mint, et ça ne contient que heirloom-mailx, comme Debian apparemment :
                http://packages.debian.org/search?keywords=Heirloom&searchon=names&suite=all&section=all

                Malgré tout, je n'ai pas réussi à compiler l'exemple de ton README :

                less demo.tr |ugrind |refer | troff -muh etc
                

                ça bloque en disant

                troff: fatal error: can't find macro file uh
                

                encore un problème de chemin, j'ai pourtant copié en désespoir de chause les tmac de /usr/local/share/utroff/tmac/ (et en particulier /usr/local/share/utroff/tmac/uh) vers /usr/share/groff/1.21/tmac/ de ma distribution, mais rien n'y fait.

                « I approve of any development that makes it more difficult for governments and criminals to monopolize the use of force. » Eric Raymond

                • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                  Posté par  (site web personnel) . Évalué à 3.

                  troff: fatal error: can't find macro file uh

                  Aah, on entre dans le vif du sujet !

                  Tu n'as probablement pas défini la variable d'environnement TROFFMACS, nécessaire à heirloom troff: export TROFFMACS='/usr/local/share/utroff/tmac/

                  Il te faut aussi définir la variable d'environnement TROFFFONTS, pour y mettre le chemin vers la police libertine opentype (que tu auras préalablement installé): export TROFFFONTS='/path/to/libertine/dir/'

                  Tu devrais aussi définir la variable UTMAC, pour charger une macro locale définissant ta langue:

                  echo "so \\V[TROFFMACS]/u-fr" > ~/.utmac
                  export UTMAC='~/.utmac'

                  La macro u-locale distribuée avec les macros utmac est un exemple un poil plus complexe de macro locale.

                  Te disant cela, je m'aperçois que ces informations importantes mériteraient de remonter en haut du README, car il est vrai que si je les laisse en bas, tout le monde va passer à côté.

                  less demo.tr | ugrind | refer | troff -muh …

                  Attention, car selon ce qu'il y a dans ton path, cette commande utiliseras gnu refer et gnu troff, et ça ne marchera pas. Indique les chemins absolus si tu as un doute, simplifie toi la vie en enlevant less, et n'oublie pas les options de la commande refer (ou définit la variable d'environnement REFER):

                  /usr/local/bin/ugrind demo.tr \
                  | /usr/local/bin/refer -p biblio.ref \
                  | /opt/hlm/bin/troff -muh \
                  | /opt/hlm/bin/dpost \
                  | ps2pdf - > demo.pdf

                  À l'avenir, tu pourras configurer ton installation aux petits oignons pour ne plus galérer avec le path.

                  Jusqu'ici je m'en sors bien, mais je ne serais pas étonné qu'au prochain coup ce soit moi qui doive travailler ;)

                  • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                    Posté par  . Évalué à 2.

                    merci, il y a du mieux, tout semble être maintenant pris en compte, sauf pour la police. J'ai fait un "export TROFFFONTS='/usr/share/fonts/opentype/linux-libertine/'" (là où j'ai cette police, c'est du style LinLibertine_aZL.otf etc) et ça me donne cette erreur :

                    /opt/hlm/bin/troff: font:text: no such request; line 861, file /usr/local/share/utroff/tmac/uh; page 1
                    par:init doc:start 
                    /opt/hlm/bin/troff: RRN: no such font; line 861, file /usr/local/share/utroff/tmac/uh; page 1
                    typo:text par:init doc:start 
                    

                    je vais regarder dans le fichier /usr/local/share/utroff/tmac/u-libertine il faudra peut-être que je les renomme ou fasse un lien symbolique.

                    À noter un petit fait étrange, si je tape :

                    export UTMAC='~/.utmac'
                    

                    Ça me dit :
                    /opt/hlm/bin/troff: can't open file ~/.utmac; line 861, file /usr/local/share/utroff/tmac/uh

                    alors que si j'appelle export UTMAC='/home/mon_login/.utmac' ça fonctionne pour le coup.

                    « I approve of any development that makes it more difficult for governments and criminals to monopolize the use of force. » Eric Raymond

                    • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                      Posté par  (site web personnel) . Évalué à 3.

                      /opt/hlm/bin/troff: font:text: no such request;

                      Ah, là, l'erreur est de mon fait: si la variable d'environnement UTMAC est définie, les macros uh et us ne chargent aucune police, considérant qu'il revient à la macro locale de le faire. C'est là la solution que j'ai trouvée pour permettre à tout un chacun de choisir des polices particulières.

                      Il faut donc que tu charges la macro u-libertine dans le fichier ~/.utmac:

                      .so \V[TROFFMACS]/u-fr
                      .so \V[TROFFMACS]/u-libertine

                      Quant à moi, il faut à tout le moins que je documente ce comportement, ou que je m'arrange pour que ça fonctionne quand bien même l'utilisateur final ne charge aucune police.

                      can't open file ~/.utmac;

                      Je me souviens maintenant avoir rencontré ça moi aussi. Bug ou feature, je n'en sais rien, il est fort possible que le raccourci ~ soit plus récent que Troff… Il faudrait là aussi que je le documente, et que j'en parle upstream.

                      Enfin, suite à ton précédent commentaire, j'ai reconstruit l'archive d'utroff-0.1, car les sources du fichier de démonstration avaient été oubliées. Plus généralement, je crois qu'un tutoriel d'installation un peu détaillé serait bienvenue…

                      C'est chouette d'avoir un beta-testeur si patient que toi !

                      • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                        Posté par  . Évalué à 3. Dernière modification le 06 novembre 2013 à 08:44.

                        j'ai reconstruit l'archive d'utroff-0.1, car les sources du fichier de démonstration avaient été oubliées.

                        Il me semble qu'il manque aussi de quoi obtenir les licenses. En tout cas ni make pub, ni cd share; make ne fonctionnent chez moi.

                        % make pub
                        for i in share demo dpage frog idx refer share soelim sophia tchars troffxml ug
                        rind utmac www; do \
                        (if [ -d "$i" ]; then cd "$i" && make pub; fi) || exit; \
                        done
                        make[1]: Entering directory '/home/pkgusr/abs/utroff/src/utroff-0.1/share'
                        co RCS/*
                        co: RCS/RCS/*,v: No such file or directory
                        ../include.mk:217: recipe for target 'co' failed
                        make[1]: *** [co] Error 1
                        make[1]: Leaving directory '/home/pkgusr/abs/utroff/src/utroff-0.1/share'
                        makefile:17: recipe for target 'pub' failed
                        make: *** [pub] Error 2
                        
                        % cd share
                        % make    
                        make: *** No rule to make target 'readme.t', needed by 'README'. Arrêt.
                        

                        S'il s'avère que tu doives reconstruire l'archive – s'il te plait – incrémente son numéro de version. Ça permet à ceux qui ne suivent pas linuxfr de savoir qu'il y a du nouveau et ça évite des alertes sécu du genre :

                        % makepkg -o
                        ==> Création du paquet utroff 0.1-1 (mer. nov.  6 08:29:35 CET 2013)
                        ==> Récupération des sources...
                          -> utroff-0.1.tar.gz trouvé
                          -> config.diff trouvé
                        ==> Validation des fichiers sources avec md5sums...
                            utroff-0.1.tar.gz ... ÉCHEC
                            config.diff ... Réussite
                        ==> ERREUR : Un ou plusieurs fichiers sont invalides !
                        
                        • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                          Posté par  (site web personnel) . Évalué à 2.

                          Il me semble qu'il manque aussi de quoi obtenir les licenses. En tout cas ni make pub, ni cd share; make ne fonctionnent chez moi.

                          Les licences sont présentes dans chacun des sous-répertoires (idx/bsd2-LICENSE par ex.), ce qui me semble plus simple pour s'y retrouver. Quant à la commande make pub, elle ne fait sens que pour l'archive de développement (utroff.tar.gz). Le README n'est probablement pas assez clair sur ce point.

                          S'il s'avère que tu doives reconstruire l'archive – s'il te plait – incrémente son numéro de version.

                          Je ne suis, décidément, pas familier avec les usages en matière de versionnement, et j'étais loin d'imaginer qu'une modification de la seule archive méritait d'être versionnée. Mais il est vrai que ça fait sens. Je vais pousser une nouvelle version bientôt, avec un README plus clair, un tutoriel d'installation, et une gestion moins sujette à erreur des macros de polices.

                          Je vous remercie tous pour vos tests, car c'est très difficile pour moi de faire comme si je découvrais l'archive et l'installais naïvement. Vous mettez en évidence tout un ensemble de petites choses que je ne voyais pas, et qui méritent d'être corrigées.

                          • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                            Posté par  . Évalué à 2.

                            Effectivement dans archlinux la source est récupérée directement depuis le site officiel, et la compilation et l'installation se font de là. Avant lorsque le checksum était différent de celui lors de la création de la recette de compilation, ça demandait si on voulait vraiment construire le paquet malgré la différence, ce qui pouvait par exemple présenter un risque de hack de la source etc.

                            Ça devait effectivement représenter 0,000001 % de risque réel, mais malgré cela, dans les nouvelles versions d'archlinux ça refuse la compilation (il faut indique le nouveau checksum), en maternant l'utilisateur qui pourtant devrait savoir ce qu'il fait, genre si ça arrive à Truecrypt ou gpg ça peut valoir le coup de regarder le code ou se renseigner, pour utroff le risque est quand même moins grand. Mais bon, c'était avant le virus ~hoax~badbios.

                            Quoi qu'il en soit, c'est quand même une bonne idée d'incrémenter le numéro de version à chaque modification de l'archive. Je trouve que le meilleur nommage est par rapport à la date (genre 2013-11-06), comme ça au moins on sait si la dernière version du logiciel date de 6 mois ou 2 ans, c'est plus parlant que v0.04 (les dév unix/linux sont si modestes, à côté de ça windows en est à la version 8.1)

                            « I approve of any development that makes it more difficult for governments and criminals to monopolize the use of force. » Eric Raymond

                            • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                              Posté par  . Évalué à 2.

                              Qu'Arch compile ou pas n'est pas un gros problème (c'est le problème des utilisateurs de cette distribution), le fait d'incrémenter toujours le numéros de version permet de s'y retrouver que ce soit le (ou les) développeurs ou les utilisateurs. En plus ça permet de stocker sans problème toutes les versions existantes.

                              Utiliser la date avec seulement le jour il faut être sur de ne pas sortir 2 versions le même jour.

                              Tous les contenus que j'écris ici sont sous licence CC0 (j'abandonne autant que possible mes droits d'auteur sur mes écrits)

                              • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                                Posté par  . Évalué à 3.

                                je suis bien d'accord voir renommer une nouvelle version à chaque nouvelle sortie.

                                Au niveau de la date, en mettant une simple date type 2013-11-06, en cas de sortie d'une autre version le même jour (cas relativement rare), soit :
                                - on ne fait rien et tant pis pour les 2 pelés et 3 tondus que ça risque de potentiellement perturber
                                - on ne sort pas 2 versions par jour, au pire des cas on sort une nouvelle version le lendemain (sauf faille de sécu grave etc)
                                - on sort une version 2013-11-06b, 2013-11-06c etc (on est limité à 26 versions par jour)
                                - on indique la date + l'heure (voire les secondes), comme sur les photos. Pas d'ambiguité comme ça (mais c'est moins lisible).

                                « I approve of any development that makes it more difficult for governments and criminals to monopolize the use of force. » Eric Raymond

                      • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                        Posté par  . Évalué à 2.

                        ouf, ça fonctionne :)

                        merci bien pour tes explications éclairées. J'ai donc pu compiler le fichier de démo. J'ai juste eu un petit problème, lors de la première compilation, ça ne trouvait pas les polices dans /usr/ucblib/doctools/font/devps/ alors que j'avais bien rajouté
                        export TROFFFONTS='/usr/share/fonts/opentype/linux-libertine/'

                        J'ai donc recopié le contenu de /usr/share/fonts/opentype/linux-libertine/ vers /usr/ucblib/doctools/font/devps/ sans trop chercher à comprendre.

                        Au niveau de la mise en place d'utroff, vu les difficultés que l'on peut avoir, ça serait peut-être pertinent de rajouter dans l'archive de ton programme :
                        - une version de Heirloom-doctools, fonctionnelle, avec un bon mk.config préparé pour des systems unix/linux modernes (c'est à dire qui s'installe par défaut dans /usr/local au lieu des chemins exotiques qu'il y avait)
                        - éventuellement les polices linux-libertine
                        - un makefile ou un fichier shell qui contient par exemple les

                        export TROFFMACS='/usr/local/share/utroff/tmac/'
                        export UTMAC='/home/login/.utmac' (voire un utmac dans /usr/local/share/utroff)
                        export TROFFFONTS='/usr/share/fonts/opentype/linux-libertine/'
                        

                        bref, un truc qui se lance clé en main sans avoir à batailler pour installer heirloom.

                        Pour textallion que j'essaye de développer (basé sur txt2tags et latex), normalement une fois l'archive décompressée, si on a latex et divers outils facilement installables sur toutes les distributions modernes, avec un petit "make pdf" ça génère le fichier pdf à partir des chemins relatifs (et sinon ça s'installe dans /usr/share ou /usr/local/share)

                        Bon, maintenant qu'utroff est opérationnel, je vais regarder pour l'export dans txt2tags et je te retiens au courant.

                        « I approve of any development that makes it more difficult for governments and criminals to monopolize the use of force. » Eric Raymond

                        • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                          Posté par  . Évalué à 2.

                          export TROFFFONTS=

                          Il y a un F en trop, d'où le soucis avec la fonte.

                          • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                            Posté par  . Évalué à 2.

                            2 F pour troff, 1 F pour fonts, le compte me semble bon…

                            « I approve of any development that makes it more difficult for governments and criminals to monopolize the use of force. » Eric Raymond

                            • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                              Posté par  . Évalué à 1.

                              C'est aussi ce que j'ai cru au début. Mais la page de man de troff (heirloom) n'est pas d'accord.

                              • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                                Posté par  . Évalué à 2.

                                bon, je regarderai ça à l'occasion alors. Vu que j'ai remis toutes les polices dans l'autre dossier, il faudra que je réinstalle tout sur un système neuf pour tester ça. Si c'est le cas (supprimer un F arbitrairement dans la variable), c'est pas très logique et particulièrement vicieux.

                                « I approve of any development that makes it more difficult for governments and criminals to monopolize the use of force. » Eric Raymond

                        • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                          Posté par  (site web personnel) . Évalué à 3. Dernière modification le 06 novembre 2013 à 22:26.

                          Mille merci ! Et je suis très heureux de voir que ça fonctionne.

                          export TROFFFONTS='/usr/share/fonts/opentype/linux-libertine/'

                          J'ai trouvé le problème: j'ai mis un F de trop, il faut écrire TROFFONTS. [edit: grilled]

                          Suite à tes remarques, je vais effectivement ajouter un script shell qui initialise les variables d'environnement, et qui va chercher les exécutables dans le bon répertoire, pour que ça puisse fonctionner sans configuration.

                          Quant à Heirloom doctools, je préfère me contenter de distribuer un fichier de configuration adapté à utroff, et un guide d'installation. J'ai beaucoup de respect pour le projet Heirloom.

                          Je vais aussi modifier la gestion des polices, pour éviter le bug que tu as rencontré.

                          Dis moi, puis-je mentionner ton pseudo « Fravashyo » dans les logs, ou préfères tu que je mentionne un autre pseudo ou ton vrai nom ?

                          PS: Textallion, mais oui bien sur ! J'ai vu les dépêches, mais sans grand amour pour Latex, je ne me suis jamais vraiment penché dessus… Mais où est passé f*******n ?

                          • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                            Posté par  . Évalué à 2.

                            cool, impatient de voir la nouvelle version.

                            Dis moi, puis-je mentionner ton pseudo « Fravashyo » dans les logs

                            oui pas de problème

                            J'ai vu les dépêches, mais sans grand amour pour Latex, je ne me suis jamais vraiment penché dessus…

                            l'avantage c'est qu'on peut potentiellement passer de LaTeX à utroff (ou autre) au niveau rendu vu que c'est basé sur la même syntaxe de base en txt2tags

                            Mais où est passé f*******n

                            bah c'est la même chose :)

                            « I approve of any development that makes it more difficult for governments and criminals to monopolize the use of force. » Eric Raymond

                          • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                            Posté par  . Évalué à 2.

                            Bon, ça avance un peu.

                            J'ai rajouté un modèle de base pour l'exportation vers utroff depuis txt2tags sur
                            https://code.google.com/p/txt2tags/source/detail?r=1173

                            J'ai essayé de rajouter la syntaxe que j'ai pu (titre 1, titre 2, gras, italique etc). Je bloque sur le souligné ainsi que le barré (strike). J'ai consulté la doc de heirloom, mais les diverses syntaxes que j'ai testées (pour underline .ul .uf, pour strike \o) ne m'ont pas aidé à ce niveau, dans utroff. Je m'y perd un peu entre les déclarations avec un point et les autres avec un anti-slash.

                            C'est pas vraiment évident dans (t)roff de savoir quel est le socle commun entre différentes macros, et voir ce qui diffère.

                            Je bloque aussi pour du gras + italique, il y a une balise spéciale dans utroff, alors qu'en txt2tags, latex, html etc, on peut les emboîter.
                            (au pire des cas on peut utiliser le préprocesseur de txt2tags pour interpréter '**//' comme du '*(BI') mais ce n'est pas une solution idéale puisqu'il faudra le renseigner sur chaque document)

                            Si tu veux contribuer à cet export, il suffit de récupérer le code sur le svn indiqué plus haut, et de modifier le fichier

                            /trunk/targets/utroff.py

                            en suivant les noms des balises. J'ai copié le modèle pour les pages de man, pensant que c'était ce qui se rapprochait le plus d'utroff.

                            Il manque quelques balises, tu en trouveras plus dans le modèle du html si nécessaire : /trunk/targets/html.py

                            Ensuite pour tester le rendu, la génération du fichier utroff se fera ainsi :

                            ./txt2tagslite -t utroff samples/sample.t2t
                            

                            et ça générera un fichier nommé samples/sample.utroff

                            En extension, j'ai préféré garder le suffixe complet .utroff que .tr, qui pourrait être pris pour une autre variante de troff.

                            Historiquement, le programme est /trunk/txt2tags, mais comme il y a une migration vers une version plus modulaire, il est conseillé de travailler uniquement avec targets/utroff.py et txt2tagslite

                            Je réintègrerai ensuite ton travail dans le fichier complet txt2tags, puis sur le svn si tu envoies un patch

                            bon courage :)

                            « I approve of any development that makes it more difficult for governments and criminals to monopolize the use of force. » Eric Raymond

                            • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                              Posté par  (site web personnel) . Évalué à 3.

                              Je regarde tout ça, et je reviens vers toi. Il va me falloir un peu de temps…

                              La gestion fine des polices va être un peu compliquée. J'ai regardé vite fait comment l'export vers mom gère ça, et il me semble qu'il ne gère pas l'emboitement…

                              underline et strike: on peut bricoler quelque chose, mais je crais que ça ne fonctionne pas bien si un saut de ligne survient au milieu. L'idéal serait que ça ne dépasse pas un mot, ou alors faire en sorte que txt2tag le gère lettre après lettre. Plus fondamentalement, on touche là à une différence de philosophie: j'ai tendance à croire que plutôt que la forme graphique, c'est la sémantique qu'il faudrait traduire. En gros, on pourrait dire italique et teletype, ou bleu et rouge.

                              C'est pas vraiment évident dans (t)roff de savoir quel est le socle commun entre différentes macros, et voir ce qui diffère.

                              Historiquement, les commandes troff sont composées de deux lettres minuscules, et par convention, les majuscules sont réservées aux macros. Mais il y a plein de nuances.

                              Je m'y perd un peu entre les déclarations avec un point et les autres avec un anti-slash.

                              Les séquences d'échappement s'utilisent en milieu de ligne. Ce sont soit des raccourcis commodes pour des commandes, soit des fonctions de dessin.

                              bah …

                              Heureux de te revoir !

                            • [^] # Re: Des styles ! Des systèmes de documentation automatique !

                              Posté par  (site web personnel) . Évalué à 3.

                              J'ai fini la première version du filtre d'export de txt2tag vers le format utmac. Où puis-je la publier?

                              J'ai du faire plusieurs choix d'implémentation, dont je crois qu'il faudrait discuter.

      • [^] # Re: Des styles ! Des systèmes de documentation automatique !

        Posté par  . Évalué à 6.

        À vue de nez, il faudrait créer des filtres d'export vers le format d'Utroff pour […] Markdown […]. Ça ne doit pas être bien compliqué.

        Markdown c'est compliqué: entre le Markdown de base, Markdown 2, Markdown Extra, Github Flavoured Markdown, les différentes extensions de Markdown, etc.

        Écrit en Bépo selon l’orthographe de 1990

  • # Dépêche rédigée avec Utroff 

    Posté par  . Évalué à 4.

    mais où peut on trouver cette source ?

    • [^] # Re: Dépêche rédigée avec Utroff 

      Posté par  (site web personnel) . Évalué à 4.

      La voilà (version non modérée par l'équipe de DLFP) :

      .H1 Utroff: la renaissance de Troff
      .PP
      Troff est un vénérable logiciel de formatage de texte hérité
      d'Unix. Plusieurs versions de Troff coexistent aujourd'hui,
      dont celle du
      .LP "projet Heirloom" ,
      .LU http://heirloom.sourceforge.net
      qui a ajouté à Troff des fonctionnalités typographiques
      modernes. Dans l'esprit du projet Heirloom,
      .LP Utroff
      .LU http://utroff.org
      retravaille l'ensemble des logiciels qui accompagnent Troff
      pour nous permettre d'utiliser efficacement celui-ci
      aujourd'hui.
      .PP
      Pour la sortie de la première version publique d'Utroff,
      cette dépêche propose une réponse aux deux questions que
      vous ne manquerez pas de vous poser: «pourquoi utiliser
      Troff aujourd'hui?», et «pourquoi choisir Utroff?».
      .PP
      .LP "Le site d'Utroff"
      .LU http://utroff.org
      .br
      .LP Utroff-0.1.tar.gz
      .LU http://download.tuxfamily.org/utroff/pub/utroff-0.1.tar.gz
      .br
      .LP "Journal annonçant la beta d'Utroff"
      .LU https://linuxfr.org/users/sygne/journaux/utroff-est-publie
      .br
      .LP "Dépêche sur l'histoire de Troff"
      .LU https://linuxfr.org/news/a-la-recherche-des-sources-de-troff
      .
      .
      .
      .
      .H1 Pourquoi utiliser Troff aujourd'hui?
      .H2 Le logiciel libre et le projet Heirloom
      .PP
      Alors que logiciel libre est généralement plébiscité pour des
      raisons techniques ou éthiques, le
      .LP "projet Heirloom" ,
      .LU http://heirloom.sourceforge.net
      dont Utroff est largement inspiré, a ceci de singulier qu'il
      utilise les libertés offertes par les licences libres pour
      des raisons esthétiques et nostalgiques. Le but du projet
      Heirloom n'est pas tant de donner à l'utilisateur plus de
      libertés ou de meilleurs outils que de lui offrir un petit
      moment de nostalgie en lui permettant d'utiliser les bons
      vieux outils d'Unix. Ce n'est pourtant pas un musée du
      logiciel, mais une mise à jour des outils d'antan:
      .PQ
      «The Heirloom Project is not a software museum\|; it does not
      attempt to preserve utilities unmodified. Rather, it keeps
      stylistic, algorithmic, and interface aspects intact while
      modernizing the framework as appropriate.»
      .PP
      Ainsi, par delà cette nostalgie, le projet Heirloom montre que
      ces antiques outils conservent des qualités non négligeables
      aujourd'hui, de sorte que ce projet nous invite à
      reconsidérer notre point de vue sur le progrès en matière
      informatique.
      .
      .
      .H2 L'ergonomie d'Unix et le langage
      .PP
      L'ergonomie d'Unix consiste, selon certains, à utiliser le
      .LP "langage comme interface" ,
      .LU http://theody.net/elements.html
      et Troff exploite mieux que tout autre logiciel cette
      ergonomie: à chaque format de données (équation, diagramme,
      table, référence...) correspond un
      .LP mini-langage .
      .LU http://www.faqs.org/docs/artu/ch08s02.html#id2934197
      Ainsi Troff s'utilise en passant le fichier source à travers
      de multiples filtres qui interprètent chacun de ces
      mini-langages.
      .PP
      À l'usage, il apparaît que l'interface langagière qui est
      celle d'Unix est particulièrement adaptée au travail des
      textes. En effet, outre qu'elle nous donne accès à des
      possibilités technologiques, cette ergonomie structure la
      pensée. En apprenant à utiliser l'outil, on apprend quelque
      chose sur la structure des données qu'on manipule, et
      corrélativement, la pensée découvre de nouvelles façons de
      se structurer en découvrant de nouvelles structures
      symboliques. La pratique d'une interface texte aiguise ainsi
      le regard analytique que l'on doit porter sur le texte. Il y
      a donc un plaisir et un intérêt, pour qui aime l'analyse des
      textes, à travailler avec ces vieux outils pensés pour la
      ligne de commande.
      .
      .
      .H2 La philosophie Unix et la question de la maîtrise
      .PP
      Le logiciel libre se donne pour objectif d'offrir à
      l'utilisateur la possibilité de maîtriser son outil
      informatique. Mais dans les faits, la complexité des
      logiciels d'aujourd'hui fait qu'il est difficile de mettre
      en pratique ces libertés de droit. Il se trouve que les
      vieux outils Unix souffrent moins de cette difficulté:
      marqués par l'idée «un programme, une tâche», ils sont
      construits à la manière d'un ensemble de multiples petits
      logiciels, aux dépendances minimales, et sont pour cela bien
      plus faciles à modifier que leurs équivalents contemporains.
      Ainsi, Troff est le seul logiciel de formatage de texte que
      je sois capable de maîtriser parfaitement.
      .PP
      Si Troff est susceptible d'être maîtrisé, ce n'est pas
      seulement parce qu'il est accompagné d'un ensemble d'outils
      hackables, c'est aussi parce que c'est un langage simple et
      bien documenté. La
      .LP "documentation exhaustive de Troff"
      .LU http://heirloom.sourceforge.net/doctools/troff.pdf
      est claire et ne dépasse pas les soixante pages, quant au
      langage, quoi que sa syntaxe puisse paraître étrange, il est
      tout à fait accessible, même aux débutants en programmation.
      .
      .
      .
      .H1 Pourquoi choisir Utroff?
      .H2 Le détail en typographie avec Heirloom Troff
      .PP
      Deux algorithmes permettent de composer des textes avec un
      rendu typographique de qualité: l'ajustement paragraphe par
      paragraphe, qui calcule l'espace inter-mots sur l'ensemble
      du paragraphe plutôt que ligne après ligne, et la
      micro-typographie, qui modifie d'un ou deux pour cent la
      taille des glyphes pour uniformiser visuellement l'espace
      inter-mots. Ces algorithmes ont été créés pour Tex et PdfTex,
      puis repris par les logiciels de PAO du marché, mais aussi
      par
      .LP "Heirloom Troff" .
      .LU http://heirloom.sourceforge.net/doctools.html
      C'est bien parce que Heirloom Troff incorpore ces
      algorithmes qu'il produit des textes dont la qualité
      typographique est, potentiellement, équivalente à celle de
      LaTex.
      .PP
      Cependant, Heirloom Troff ne fournit aucune macro qui
      permette d'utiliser ces algorithmes simplement. C'est
      d'abord pour combler ce manque que Utroff a été
      créé.
      .
      .
      .H2 La simplicité des macros Utmac
      .PP
      S'il est possible de composer un document en Troff pur, il
      est bien plus simple d'utiliser des macros qui définissent
      le format des éléments les plus fréquents et s'occupent de
      la mise en page.
      .LP Utmac ,
      .LU htpp://utroff.org/tmac.html
      l'ensemble de macros créées pour Utroff, suit quelques
      principes ergonomiques:
      .PI
      Toutes les macros utilisent le même langage, de sorte qu'un
      même document peut être exporté en plusieurs formats et
      selon plusieurs mises en page, sans qu'il soit nécessaire
      d'en modifier les sources. Les formats d'export sont:
      postscript (donc pdf), README, man, xml, html, fodt,
      markdown et tty (en cours). Deux mises en page sont
      actuellement disponibles: l'une est dédiée aux textes
      littéraires longs (les thèses), et l'autre à la
      documentation technique. Une macro dédiée aux lettres et aux
      CV est en cours de création.
      .PI
      Les macros gèrent d'office les besoins les plus fréquents:
      sommaire, table des matières, liens internes, index,
      références, coloration syntaxique, recto-verso.
      .PI
      Outre qu'elles utilisent les algorithmes d'Heirloom Troff
      dédiés à la typographie, elles respectent les bonnes
      pratiques en matière de mise en page: principe de grille,
      principe de ligne, et ortho-typographie. Elles repèrent et
      mentionnent veuves et orphelines et fournissent des outils
      pour les faire disparaître.
      .PI
      Elles n'ont que peu d'options de configuration. D'une part
      parce que leur mise en page est censée être adaptée au
      besoin, et d'autre part parce parce qu'il est considéré que
      pour un besoin spécifique, la bonne pratique consiste à
      créer une macro spécifique, généralement en adaptant une
      macro existante.
      .PP
      Le format des macros est documenté dans le
      .LP "manuel d'Utmac" .
      .LU http://utroff.org/man/utmac.html
      .
      .
      .H2 Le formatage des références bibliographiques avec Refer
      .PP
      Il existe une norme internationale définissant la structure
      que doivent avoir les références bibliographiques, qu'elles
      soient indiquées en bas de page ou en fin d'ouvrage: la
      norme
      .LP ISO-690 ,
      .LU http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=43320
      dont Rositza Kyheng propose un
      .LP résumé .
      .LU http://www.revue-texto.net/Reperes/Themes/Kyheng_References.html
      Largement ignorée, souvent confondue par les
      universitaires avec une norme réservée aux bibliothèques,
      cette norme est néanmoins la seule qu'éditeurs et
      universitaires devraient respecter. Refer, le logiciel
      dédié au formatage des références bibliographiques,
      a été modifié pour qu'il puisse respecter cette norme. En
      particulier, puisque la norme ne fait que définir l'ordre
      des champs, c'est l'algorithme de tri des références qui a
      été adapté.
      .PP
      À ces modifications s'ajoutent une macro (u-ref), incluse dans les
      macros Utmac, offrant la possibilité d'utiliser proprement
      une police contenant de vraies petites capitales, la gestion
      des champs dédiés aux références électroniques (url, format,
      date de consultation...), le remplacement par «idem» ou «op.
      cit. p.\~xx», et la distinction entre notes de bas de pages
      et liste bibliographique de fin d'ouvrage.
      .PP
      Consulter le
      .LP "manuel de refer" 
      .LU http://utroff.org/man/refer.html
      et celui de la macro
      .LP u-ref .
      .LU http://utroff.org/man/u-ref.html
      .
      .
      .H2 Le grec polytonique avec Tchars, inspiré de Dchars
      .PP
      Les plus assidus d'entre-vous auront suivi
      .LP "le développement de Dchars" ,
      .LU https://linuxfr.org/news/dchars-pour-lire-ecrire-et-modifier-des-caracteres-unicodes-complexes
      de notre ami
      .LP "Xavier Faure" ,
      .LU https://linuxfr.org/users/suizokukan
      qui interprète du code ascii pour produire des caractères
      utf8 complexes. Utroff méritait d'avoir un tel interpréteur,
      mais ne pouvait se permettre d'ajouter python à ses
      dépendances. J'ai donc écrit un tout petit interpréteur en
      C, et l'ai nommé Tchars (Troff|Translate Characters) en
      référence à Dchars.
      .PP
      Un récent
      .LP journal
      .LU https://linuxfr.org/users/sygne/journaux/jouons-avec-unicode-tchars-un-dchars-pour-troff
      explique les détails de cette implémentation, quant à
      son utilisation elle est documentée dans le
      .LP "manuel de Tchars" .
      .LU http://utroff.org/man/tchars.html
      .
      .
      .H2 Les index avec Idx
      .PP
      Le travail d'indexation ne se limite pas à l'indexation du
      document en cours d'écriture, il concerne aussi l'indexation
      d'ouvrages de référence, dont bien souvent aucune version
      électronique n'est disponible. Idx est un script awk
      encapsulé dans du shell facilitant grandement l'indexation
      de textes papiers, et réalisant l'indexation des documents
      Troff.
      .PP
      Un journal propose
      .LP "exemple d'utilisation d'idx" 
      .LU https://linuxfr.org/users/sygne/journaux/exemple-d-interface-en-ligne-de-commande
      (attention, l'interface a évolué depuis),
      et son utilisation est documentée dans le
      .LP "manuel d'idx" .
      .LU http://utroff.org/man/idx.html
      .
      .
      .H2 La coloration syntaxique avec Ugrind
      .PP
      Voici le genre le commentaires que l'on trouve dans les
      sources des logiciels qui accompagnent Troff:
      .vS C
      /*
       * Vfontedpr.
       *
       * Dave Presotto 1/12/81 (adapted from an earlier version by
       * Bill Joy)
       *
       */
      .vE
      .PP
      Au début des années 80, alors qu'il travaillait encore à
      l'université de Berkeley,
      .LP "Bill Joy"
      .LU http://fr.wikipedia.org/wiki/Bill_Joy
      a donc trouvé nécessaire d'ajouter un colorateur syntaxique
      à Troff. Il a pour cela créé Vfontedpr, que les
      membres de la liste de discussion de Groff comprennent comme
      signifiant «Visual Font Edit Print», un outil en C appelé
      par le bien nommé script Vgrind (la moulinette qui grince).
      Après bien des péripéties, Vgrind s'est retrouvé dans
      l'archive d'Heirloom Doctools, de sorte que, Vfontedpr,
      renommé Ugrind pour le projet Utroff, continue à colorer le
      code source pour Troff depuis plus de 30 ans.
      .PP
      Signe de son age avancé la syntaxe de son fichier de
      configuration (vgrindefs, renommé ugrindefs pour Utroff) où
      sont définies la structure des langages à colorer, est celle
      de Termcap:
      .vS C
      /*
       * grindcap - routines for dealing with the language
       * definitions data base
       * (code stolen almost totally from termcap)
       */
      .vE
      .PP
      Puisque qu'il fallait à tout le moins qu'Ugrind puisse
      colorer le sources en Troff, et puisque la syntaxe de Troff
      est difficilement interprétable dans le langage de Termcap,
      Ugrind contient, entre autres modifications de Vfontedpr, un
      parseur codé en dur du langage Troff.
      .PP
      Le
      .LP "manuel d'ugrind"
      .LU http://utroff.org/man/ugrind.html
      décrit son utilisation.
      .
      .
      .H2 L'export vers l'xml
      .PP
      Troff a commencé à péricliter au moment ou apparaissait le
      web, l'html et l'xml. Il y a probablement là un lien causal:
      de nombreux scripts ont été créés pour produire de l'html à
      partir de Troff, mais aucune solution universelle n'a jamais
      été trouvée. En effet, seules les macros créées en langage
      Troff peuvent être interprétées en tant que c'est en leur
      sein qu'est définie la sémantique du texte. De fait, il y a
      autant d'interpréteur que de macros, et chaque interpréteur
      doit pouvoir en outre comprendre quelques fonction Troff
      susceptibles d'être utilisées dans les fichiers sources.
      .PP
      Finalement,
      .LP "Eric.\~S. Raymond"
      .LU http://fr.wikipedia.org/wiki/Eric_Raymond
      a su imposer
      .LP doclifter ,
      .LU http://www.catb.org/~esr/doclifter
      un interpréteur en python, qui reste néanmoins réservé aux
      macros historiques.
      .PP
      Une solution n'a pas été explorée jusqu'alors: si Troff
      produit des fichiers postscripts, son grand frère, Nroff
      produit des fichiers textes, de sorte qu'il peut produire
      des fichiers xml sans en passer par un interpréteur. De fait
      l'une des macros Utmac a été écrite pour gérer l'export vers
      l'xml avec Nroff. Toutes les fonctions du langage Troff sont
      ainsi gérées nativement, et, si cette solution ne répond pas
      à tous les besoins, elle a l'avantage d'être très simple à
      mettre en œuvre.
      .PP
      Le site d'Utroff explique cette
      .LP "conversion vers l'xml" .
      .LU http://utroff.org/xml.html
      .
      .
      .H1 Remerciements
      .PP
      Utroff est hébergé par
      .LP Tuxfamily ,
      .LU http://tuxfamily.org
      et son développement a bénéficié de l'aide de quelques
      LinuxFr-iens:
      .LP MrSpackMan , 
      .LU https://linuxfr.org/users/mrspackman
      .LP "fmaz fmaz" ,
      .LU https://linuxfr.org/users/fmaz
      et
      .LP "Xavier Faure" ,
      .LU https://linuxfr.org/users/suizokukan
      déjà cité. Qu'ils soient tous remerciés.
      .H2 Post Scriptum
      .PP
      Dépêche rédigée avec Utroff:
      .vS sh
      ugrind utroff-0.1.tr | nroff -muw > utroff-0.1.mkd
      .vE

      :)

Suivre le flux des commentaires

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