Journal Utroff est publié

Posté par (page perso) . Licence CC by-sa
46
5
avr.
2013

Sommaire

Comme vous le savez peut-être, je suis un fervent utilisateur du vénérable troff. Voilà des années que je l’utilise et que j’adapte son écosystème logiciel à mes besoins. Et aujourd’hui, est publiée la version bêta (l’interface est encore susceptible de changer) de ce travail.

Le mot d’ordre du projet est «Use Troff !», et ce mot d’ordre lui sert de nom: utroff.

Utroff

Histoire d’utroff

L’histoire d’utroff, c’est l’histoire de mon utilisation de troff. À l’origine, j’ai créé quelques macros pour mes besoins universitaires: formatage des références respectant la norme iso-690, mise en page élégante et prenant soin du détail typographique, gestion des index, etc.

Je pensais publier ce travail il y a neuf mois déjà. Mais je me suis alors aperçu que cela supposait de créer tout un tas de fichiers de documentation: README, pdf, manuels, changelog, pages html, etc. Utiliser un autre outil que troff pour formater ces documents aurait mis en cause la cohérence de mon projet, aussi j’ai décidé de tout faire avec cet ancestral logiciel, quels que soient les efforts de développement que cela demanderait.

Cela m’a effectivement demandé beaucoup d’efforts… Mais cette décision a aussi considérablement augmenté l’envergure de mon projet, qui, de fait, est maintenant auto-produit.

Pour vous faire une idée du rendu html, visitez donc le site. Pour voir le rendu pdf, jetez un coup d’œil à la documentation. Pour voir le rendu texte, ouvrez une archive, et lisez le README ou la license. Et remarquez comme il est simple, grâce à utroff, d’intégrer README, page de manuel, licence et ChangeLog dans un document pdf, ou de tout exporter en html.

Macros pour troff: utmac

Utmac est un ensemble de macros pour heirloom troff qui utilisent toutes la même syntaxe. Comparez, par exemple, comment l’unique fichier source est rendu par la macro uh, dédiée aux humanités, par la macro us, créée pour formatter la documentation technique, par la macro ux, qui produit des fichiers xml, et par la macro ut, qui produit des textes bruts (en utf-8). Utmac permet en outre de produire des pages de manuel (um), et des fichiers pour wiki (uw, qui suit la syntaxe markdown).

Les macros de utmac permettent d’insérer très simplement sommaires, index, liens internes et externes, et références bibliographiques (la syntaxe est décrite dans le manuel d’utmac):

.S2 \" Sommaire des titres de niveau 2
.H2 titre de niveau 2
.H2 autre titre de niveau 2
.XB biblio.ref \" Liste bibliographique
.XI N W R \" Index des noms, des mots et des références
.XT \" table des matières

Les macros produisant des fichiers pdf portent un soin particulier à la typogographie et en respectent les règles élémentaires. Les fonctions de micro-typographie de heirloom troff sont nativement supportées par utroff. Les veuves et orphelines sont repérées lors du formatage, et des macros minimisant ou agrandissant subtilement les paragraphes sont fournies pour pour les éradiquer à la demande.

Utilitaires utroff

Pour que ces macros aient des fonctionnalités modernes, il m’a fallu modifier certains logiciels de l’écosystème troff, et en créer de nouveaux.

  • Refer et sortbib ont été modifiés pour supporter l’ordre de tri des références imposé par la norme iso-690 et gérer plus proprement les petites capitales.
  • UGrind, un horrible hack de vGrind sert de colorateur syntaxique.
  • Idx gère la production d’index.
  • prexml, postxml et trxtr ont été créés pour permettre l’export vers différents formats xml (actuellement fodt et html).

Aide

Maintenant, si je vous écrit tout cela au risque de vous ennuyer, c’est que j’ai besoin d’un tout petit peu d’aide. Je n’ai pas été formé à la programmation, et j’aimerais recevoir quelques critiques de mon travail. Ce n’est donc pas un appel à contributions que je lance ici, mais un appel à explications et au partage d’expérience.

Si vous avez un peu de temps et de patience, n’hésitez donc pas m’écrire, soit en commentaire, soit à help, chez le nom de domaine de utroff.

Pour être un peu précis, voici une liste non exhaustive des choses sur lesquelles j’apprécierais quelques remarques.

  • La syntaxe des macros utmac: La page de manuel de utmac décrit cette syntaxe. Je la modifierai volontiers si vous trouvez qu’elle peut-être améliorée.
  • Les archives: Ouvrez une archive au hasard, et dites moi si makefile, versions, changes, readme conviennent, bref, si c’est suffisamment propre pour être empaqueté par une distribution.
  • Typographie et mise en page: Je sais qu’il y a ici des gens qui apprennent, voire qui pratiquent la typographie, et qui ont peut-être dans leur bibliothèque Hochuli, Lawson et Bringhurst. Au-delà des goûts et des couleurs, vos remarques sur la typographie et la mise en page des pdf est la bienvenue.
  • Le site: Css n’est pas mon fort, html non plus. Si le site est propre en apparence sur mon navigateur, la feuille de style ne l’est pas, et n’est certainement pas très portable. Je serais heureux d’avoir quelques remarques à ce sujet.
  • Les médias sociaux: Ceux d’entre vous qui sont branchés jusque chez leur boulangère peuvent me donner quelques conseils, s’ils en ont l’envie, voire (soyons fou) me faire un peu de pub.

Bien sur, si vous avez le courage de jeter un coup d’œil aux sources pour me faire des remarques, n’hésitez pas, j’ai d’ailleurs préparé quelques archives pour vous faciliter la tâche: dans les archives listées ci-dessous, vous trouverez un fichier HELPME, qu’il vous suffit de lire, de compléter et de m’envoyer pour m’aider. Il y en a pour tous les goûts et pour tous les niveaux:

  • Dans utroff-idx, le fichier HELPME questionne l’architecture du programme et ma pratique du awk.
  • Dans utroff-soelim, c’est l’utilisation d’un array en C qui est en question.
  • Dans utroff-ugrind, c’est la façon dont une structure en C est copiée qui est en question.

Remerciements

Utroff est hébergé par les bons soins de Tuxfamily que je remercie sincèrement, ainsi que tous ceux qui m’ont aidés dans les journaux — ici et — dans les forums — ici, , ici, et — ainsi que ceux qui ont bien voulu discuter de troff en général — ici, ici, et .

  • # dépêche

    Posté par (page perso) . Évalué à 8.

    Je pense qu’au delà de la demande de conseils, ce journal mérite une dépêche.

    De ses yeux vastes comme des océans, encroûtés de chassie et de poussière d'astéroïdes, Elle fixe le But Ultime.

    • [^] # Re: dépêche

      Posté par (page perso) . Évalué à 3.

      Je pensais aux dépêches pour annoncer une version un peu moins bêta. Pour l'instant, tout bouge tout le temps… J'apprécie la proposition, mais je trouve que c'est un peu prématuré.

      • [^] # Re: dépêche

        Posté par (page perso) . Évalué à 5.

        Je me souviens de ta très intéressante dépêche : https://linuxfr.org/news/a-la-recherche-des-sources-de-troff

        Le rendu que tu présentes sur ton site, que cela soit au niveau rendu HTML ou PDF, est vraiment impeccable. Bien entendu, la critique ne va pas être très constructive si ce n'est que pour faire des louages, mais je ne trouve rien à redire (même si je ne suis pas expert non plus), à part que j'ai un peu de mal avec la syntaxe de troff de façon générale.

        Au niveau rendu, troff c'est équivalent à LaTeX en qualité ? (on dirait en tout cas)

        Félicitation pour ce projet.

        Au fait, tu utilises toujours Archlinux malgré son tournant que tu regrettais dans un journal d'il y a quelques mois ?

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

        • [^] # Re: dépêche

          Posté par (page perso) . Évalué à 6.

          Merci pour les louanges, qui sont toujours constructifs, quoi qu'on en dise, car ils donnent du cœur à l'ouvrage. :)

          Au niveau rendu, troff c'est équivalent à LaTeX en qualité ?

          Au point de vue typographique, à mon avis, oui, étant donné que la version heirloom de Troff reprend l'algorythme de création de paragraphe créé pour Tex par Knuth & Plass cf word wrap, ainsi que l'amélioration micro-typographique de ces algorythmes créée pour PdfTex par Hàn Thế Thành cf micro-typography.

          Il y a aussi dans Tex une fonction pour placer les paragraphes dans la page (afin d'éviter veuves et orphelines), que Heirloom Troff ne reprend pas. Cette fonction est de toute manière problématique de mon point de vue, car elle peut conduire à créer des sauts de ligne non proportionnels à la taille de lignes, et du coup, on voit par transparence que les lignes ne se recouvrent pas du recto au verso. Utroff, se contente donc de les indiquer, et fournit des solutions pour les supprimer proprement, mais cela suppose une intervention manuelle.

          Au fait, tu utilises toujours Archlinux malgré son tournant que tu regrettais dans un journal d'il y a quelques mois ?

          Où je me demande s'il n'y a pas, avec ces questions, une tentative de donner à ce fil de discussion moribond la vivacité d'un bon troll comme on les aime ici…

          J'aimerais faire le saut vers NetBSD, dont j'apprécie beaucoup l'esprit, mais comme je suis en train de finir ma thèse, ce n'est pas le bon moment pour chambouler mon espace de travail. Après plusieurs mois de résistance, j'ai donc fait la mise à jour vers systemd la semaine dernière. Le boot est un peu ralenti mais sans grandes conséquences, devenu très laid, mais je ferme les yeux, et /etc/ est bloated, mais il l'était déjà.

  • # Quelques commentaires en passant.

    Posté par . Évalué à 4.

    Je vais faire des remarques typographique sur la version pdf du manuel de ugrind. Attention, j'ai fait attention à ne surtout pas lire le texte pour ne pas me laisser influencer. Pour moi, la typographie doit aider à la lecture et pas l'inverse.

    Page 3.

    Je trouve dommage que les sections « NAME », « SYNOPSIS »… soient entièrement en majuscule. Le cas échéant, elles auraient pu si être en petites majuscule.

    Dans la section « Description », je ne comprends pas le sens des tirets et du retrait important avant « In regular mode, ugrind only… »

    Dans la section « Programming style », je la mise en forme peu lisible: « C and C++ », « PASCAL » avec un retour à la ligne contrairement à « MODEL » et « TROFF ».

    Si j'ai bien compris l'intention, j'aurais:
    1. éviter d'aligner les débuts de textes—Functions names…—pour éviter de forcer le retour à la ligne. J'aurais mis des espaces verticales pour séparer clairement les paragraphes.

    J'arrête pour l'instant, je suis sûr que je pourrais trouver encore plein de trucs à critiquer.

    • [^] # Re: Quelques commentaires en passant.

      Posté par (page perso) . Évalué à 3. Dernière modification le 07/04/13 à 23:09.

      Merci pour tes remarques :)

      Je trouve dommage que les sections « NAME », « SYNOPSIS »… soient entièrement en majuscule. Le cas échéant, elles auraient pu si être en petites majuscule.

      Les majuscules sont une convention pour les titres des pages de manuel, et le pdf est composé à partir des sources du manuel, d'où les majuscules. Il y aurait plusieurs moyens de forcer l'usage des minuscules lors de la composition des pdf, mais j'hésite encore tant sur le bon moyen technique de faire cela, tant sur la nécessité de le faire (parce qu'il me semble cohérent que même sur le pdf la mise en page ressemble à une page de manuel).

      Tes autres remarques concernent les listes. Dans la page que tu cites, c'est la même macro .PI qui gère les listes à tirets du paragraphe « DESCRIPTION », la liste des options dans le paragraphe qui leur est dédié, ainsi que la liste des différents langage de programmation, et, autre cas singulier, les listes bibliographiques, comme p. 9 de demo-us.pdf.

      J'ai eu du mal à trouver une façon de faire qui convienne à cette variété de situations, et tu as raison, la solution n'est toujours pas optimale. J'avais essayé l'espace entre les paragraphes, mais ça ne donnait pas de bons résultats. Ne pas aligner les débuts de textes donne des résultats étranges dans certaines situations. En tout cas, tu m'as convaincu d'y réfléchir à nouveau.

      J'arrête pour l'instant, je suis sûr que je pourrais trouver encore plein de trucs à critiquer.

      Pourquoi s'arrêter sur une si bonne lancée ?

      • [^] # Re: Quelques commentaires en passant.

        Posté par . Évalué à 2.

        Je regarderai donc de plus près demain.

        Pour ce qui est des listes de la section « Programming style », j'aime justement bien la solution de la biblio de la page 9 du document que tu pointes. « lastname, firstname » est inliné avec le reste de la référence mais celle-ci est indentée après le passage à la ligne.

        Je trouve que ça serait plus lisible. De plus, dans les listes par défaut de LaTeX, les différents item sont séparés par des espaces verticales fine ou moyenne, je ne sais plus. Et je trouve que ça aide à la lecture. Tout comme j'aime bien la convention -- anglo-saxonne je crois -- de séparer les paragraphes de la même façon.

        • [^] # Re: Quelques commentaires en passant.

          Posté par (page perso) . Évalué à 2.

          « lastname, firstname » est inliné avec le reste de la référence mais celle-ci est indentée après le passage à la ligne.

          C'est une autre macro (**.PB**) qui fait cela. Les lignes suivantes, où, malgré le long tiret, le début des paragraphes est toujours aligné sont mises en forme par la macro .PI.

          À ce problème des listes, j'entrevoie maintenant la solution suivante:

          • soit l'item n'est pas précisé, et dans ce cas un tiret est ajouté, non pas au début de la ligne comme c'est le cas pour l'instant (cf. paragraphe « DESCRIPTION » de ugrind.pdf), mais avec une indentation de 2em. Le texte commençant toujours à 3em.
          • soit l'item est précisé en argument par l'utilisateur, et dans ce cas il est ajouté en début de ligne (sans indentation, comme dans la liste des options de la même page). Il y a alors deux solutions:
            • soit l'item est inférieur à 3em, et dans ce cas le texte commence à 3em.
            • soit l'item est supérieur à 3em, et dans ce cas le texte commence à la ligne suivante.
          • Je préciserai dans la documentation que la macro .PB donnera de meilleurs résultats que la macro .PI pour les listes dont les items ont une taille oscillant autour de 3em (cf. liste des langages de programmation du manuel d'ugrind).

          Encore merci, et si tu as un peu de temps, je lirai avec enthousiasme tes autres remarques.

          • [^] # Re: Quelques commentaires en passant.

            Posté par . Évalué à 2.

            • soit l'item est précisé en argument par l'utilisateur, et dans ce cas il est ajouté en début de ligne (sans indentation, comme dans la liste des options de la même page). Il y a alors deux solutions:

              • soit l'item est inférieur à 3em, et dans ce cas le texte commence à 3em.
              • soit l'item est supérieur à 3em, et dans ce cas le texte commence à la ligne suivante.

            Je ne m'y connais pas énormément en typographie, mais personnellement quand au moins l'un des items de la liste fait plus de 3em, je préfèrerais qu'ils passent tous à la ligne. Ça permet d'avoir plus de cohérence sur l'ensemble de la liste. On a entre autre tout les paragraphe qui commencent au même endroit (avec la même indentation). Je pense que c'est plus confortable à lire (mais ça doit être bien plus compliqué) à créer.


            Merci pour ton travail et pour le partage que tu en fait. Je n'utilise pas troff, mais ça me fait plaisir de voir un concurrent à LaTeX (autre que Lout qui m'a l'air plus limité (si c'est pas le cas je serais heureux de découvrir l'étendu de mon erreur soit dis en passant)).

            Je trouve super que tu prenne en compte une série de format de sorti (texte/man, html et pdf).

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

            • [^] # Re: Quelques commentaires en passant.

              Posté par (page perso) . Évalué à 2.

              quand au moins l'un des items de la liste fait plus de 3em, je préfèrerais qu'ils passent tous à la ligne.

              Cela semble idéal, d'autant plus que j'ai fait plusieurs essais comparatifs, et aucune solution ne convient pour l'instant à toutes les situations. Mais c'est en effet un algorythme plus complexe, qui n'a peut-être pas sa place dans cette macro us.

              Je n'utilise pas troff, mais ça me fait plaisir de voir un concurrent à LaTeX. […] Je trouve super que tu prenne en compte une série de format de sorti (texte/man, html et pdf).

              C'est peut-être la niche inexplorée de troff, qui sait faire de la typographie de détail tout en se rapprochant des générateurs de format comme txt2tag et markdown.

          • [^] # Re: Quelques commentaires en passant.

            Posté par . Évalué à 3.

            C'est donc parti pour plus de commentaires.
            N'ayant aucune idée de la logique derrière la mise en forme, je vais me contenter de remarques sur les documents.

            Pour rester concis, je fais des commentaires à l'emporte pièce mais bien évidemment, la typographie est pour beaucoup une question de goûts. Merci de rajouter des « À mon avis… » et des « Je trouve que… » un peu partout.

            Marges et entête

            Pour un document conçu pour être imprimé comme un pdf, le numéro de page doit être à gauche sur les pages paires et la marge intérieure doit être légèrement plus importante.

            Espaces verticales

            Il en manque. Notamment pour écarter les items des listes et après les titres des (sous-)sections. Il n'y a pas besoin de grand chose, voir même il ne faut pas que ces espaces soient trop grand. En LaTeX, je mettrais un \smallskip. Pour les listes, j'en ai déjà parlé mais pour les sections, je trouve par exemple que la page 10 Section 3. et sous-section 3.1 du fichier ugrind.pdf illustrent bien cela.

            La première de couverture

            Elle ne doit pas avoir de numéro de page, d'entête et de pied de page.

            Pieds de page

            Il faut retirer les traits en bas de page.

            Ceux du haut se justifient pour séparer le numéro de page et le titre du document mais ceux du bas sont gratuits et alourdissent inutilement le document. C'est particulièrement moche avec les « petites fleurs » qui servent de séparateurs.

            Les titres et sous-titres

            Ils doivent être légèrement plus gros pour être plus mis en valeur.

            C'est d'autant plus important que le gras est beaucoup (trop) utilisé et donc simplement graisser ces titres n'est pas suffisant. C'est particulièrement flagrant sur les pages 4 et 5 du fichier utmac.pdf.

            Utilisation du gras

            Trop de choses sont graissées.

            Si j'ai bien compris, c'est notamment le cas des switchs et des options de la ligne de commande. Ça entre en collision avec le gras des titres et des (sous-)sections et ça donne une impression un peu fouillis. De plus, c'est une mise en valeur trop importante. C'est flagrant page 3. du fichier ugrind.pdf dans le paragraphe juste avant la section « Programming style ». Pour cette utilisation, j'utiliserais une police « type writer ».

            Le lien sur refer.pdf est cassé

            • [^] # Re: Quelques commentaires en passant.

              Posté par (page perso) . Évalué à 4.

              Merci (bis) pour tes remarques !

              le numéro de page doit être à gauche sur les pages paires.

              Cf. macro .RV du manuel de utmac :)

              la marge intérieure doit être légèrement plus importante.

              En vérité, cela dépend du type de reliure. C'est configurable dans les sources pour l'instant.

              En LaTeX, je mettrais un \smallskip

              C'est une solution courante, mais mauvaise, car elle contrevient à l'alignement des lignes sur une grille stricte, ce qui devient problématique pour du recto verso, car selon la transparence du papier, on peut voir les lignes du verso entre les lignes du recto.

              Espaces verticales après les titres des (sous-)sections

              Bien vu, c'était un bug, corrigé maintenant.

              La première de couverture […] ne doit pas avoir de numéro de page.

              Cf. macro .RP du manuel de utmac :) Pour l'instant, je laisse cela au choix de l'utilisateur, mais cette décision peut changer.

              La première de couverture […] ne doit pas avoir […] d'entête et de pied de page. Il faut retirer les traits en bas de page.

              Tout cela relève d'un choix esthétique. D'une part, j'avais envie d'une page généralement assez sombre et dense. En outre, comme les manuels sont des documents assez chaotiques, il fallait renforcer la structure de la page, et les lignes le font très bien. J'ai beaucoup tatonné pour la mise en page des documents techniques, et finalement, sans trop y croire, j'ai essayé les lignes épaisses, et j'ai été moi-même surpris que ça fonctionne. Je laisse donc les choses en l'état pour cette macro, quitte à faire mieux avec une autre macro.

              C'est particulièrement moche avec les « petites fleurs » qui servent de séparateurs.

              Pour le coup, c'est probable. Les fleurs sont la trace d'une ancienne version de la mise en page.

              Les titres et sous-titres […] doivent être légèrement plus gros pour être plus mis en valeur.

              Oui, cela fait partie de ma todo list.

              Trop de choses sont graissées.

              Cf. ci dessus. En outre, le gras est hérité des conventions des pages de manuel.

              Le lien sur refer.pdf est cassé

              Je n'ai pas trouvé de quel lien tu parles. Pourrais-tu préciser s'il te plaît?

              PS: j'ai ajouté dans les logs « bug report by fmaz fmaz », est-ce que cette mention te convient ?

              • [^] # Re: Quelques commentaires en passant.

                Posté par . Évalué à 2.

                Pour le lien cassé, c'est dans http://utroff.org/doc.html
                après « Software documentation » le lien refer.pdf

                Pour le bug report, tu peux mettre « Frédéric Mazoit ».

                Comme je l'ai dis, les goûts personnels sont importants. Mais je vais tenter de justifier un peu plus mon histoire d'espaces entre les items.

                1. Il faut vraiment un papier fin ou lire en transparence pour voir le décalage. Je pense que le désagrément est minime en comparaison du gain.
                2. Tu considères qu'il faut ajouter des espaces pour les (sous-)sections. Pourtant, ça participe aussi au décalage. Et puis augmenter la taille des polices pour mettre en valeur des titres décale aussi le texte.

                Bref. Je t'ai donné mon avis.

                En tout cas, beau boulot.

                • [^] # Re: Quelques commentaires en passant.

                  Posté par (page perso) . Évalué à 3.

                  Merci pour le lien, c'est corrigé maintenant.

                  Pour les questions du détail en typographie:

                  Il faut vraiment un papier fin ou lire en transparence pour voir le décalage. Je pense que le désagrément est minime en comparaison du gain.

                  Pas seulement. Lorsque le document est relié il est plus élégant que les lignes soient alignées de la page gauche à la page droite. En outre, dans le cas d'une mise en page en colonnes (par exemple avec des notes marginales), le défaut d'alignement saute aux yeux.

                  Mais comme beaucoup de bonnes pratiques typographiques, allègrement oubliées durant quelques années, le défaut de celles-ci n'apparaît plus qu'aux yeux un minimum exercés.

                  Tu considères qu'il faut ajouter des espaces pour les (sous-)sections. Pourtant, ça participe aussi au décalage. Et puis augmenter la taille des polices pour mettre en valeur des titres décale aussi le texte.

                  En fait, non. Augmenter la taille des polices ne change rien si l'interligne reste le même (du moins avec troff). Quant à l'interligne, c'est l'unité de base du document, toutes les distances y sont proportionnelles, et je ne le modifie qu'en prenant soin de retomber sur mes pieds:

                  • Par exemple, dans la macro uh, les notes marginales ont un interligne tel que trois lignes de notes correspondent à deux lignes de texte: l'alignement est respecté.
                  • Quant aux titres, on peut utiliser des fractions d'interligne pour les séparer du texte, mais dans ce cas, on veille à ce que l'addition de l'espace avant le titre et après le titre forme un nombre entier d'interlignes. Par exemple 1.7 avant et 0.3 après, de sorte que l'alignement est respecté.

                  Mais tu as raison, pour les listes, cela peut-être problématique. Il faudrait que je me replonge dans mes manuels pour voir quelles solutions ils préconisent.

                  Encore merci, cela fait longtemps que j'ai les yeux plongés dans ces documents, et je finis par ne plus rien voir. Un regard extérieur est extrêmement bienvenue.

                • [^] # Re: Quelques commentaires en passant.

                  Posté par (page perso) . Évalué à 2.

                  J'ai poussé la version 0.6 de Utmac suite à tes remarques (changelog). Encore merci !

          • [^] # Re: Quelques commentaires en passant.

            Posté par . Évalué à 1.

            Ça me paraît sans doute pas mal.

Suivre le flux des commentaires

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