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 là — dans les forums — ici, là, ici, et là — ainsi que ceux qui ont bien voulu discuter de troff en général — ici, ici, et là.
# dépêche
Posté par François Chaix (site web personnel) . Évalué à 8.
Je pense qu’au delà de la demande de conseils, ce journal mérite une dépêche.
La lumière pense voyager plus vite que quoi que ce soit d'autre, mais c'est faux. Peu importe à quelle vitesse voyage la lumière, l'obscurité arrive toujours la première, et elle l'attend.
[^] # Re: dépêche
Posté par Sygne (site web personnel) . É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 fravashyo (site web personnel) . É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 Sygne (site web personnel) . Évalué à 6.
Merci pour les louanges, qui sont toujours constructifs, quoi qu'on en dise, car ils donnent du cœur à l'ouvrage. :)
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.
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 fmaz fmaz . É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 Sygne (site web personnel) . Évalué à 3. Dernière modification le 07 avril 2013 à 23:09.
Merci pour tes remarques :)
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.
Pourquoi s'arrêter sur une si bonne lancée ?
[^] # Re: Quelques commentaires en passant.
Posté par fmaz fmaz . É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 Sygne (site web personnel) . Évalué à 2.
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:
Encore merci, et si tu as un peu de temps, je lirai avec enthousiasme tes autres remarques.
[^] # Re: Quelques commentaires en passant.
Posté par barmic . Évalué à 2.
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 Sygne (site web personnel) . Évalué à 2.
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.
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 fmaz fmaz . É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 Sygne (site web personnel) . Évalué à 4.
Merci (bis) pour tes remarques !
Cf. macro .RV du manuel de utmac :)
En vérité, cela dépend du type de reliure. C'est configurable dans les sources pour l'instant.
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.
Bien vu, c'était un bug, corrigé maintenant.
Cf. macro .RP du manuel de utmac :) Pour l'instant, je laisse cela au choix de l'utilisateur, mais cette décision peut changer.
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.
Pour le coup, c'est probable. Les fleurs sont la trace d'une ancienne version de la mise en page.
Oui, cela fait partie de ma todo list.
Cf. ci dessus. En outre, le gras est hérité des conventions des pages de manuel.
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 fmaz fmaz . É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.
Bref. Je t'ai donné mon avis.
En tout cas, beau boulot.
[^] # Re: Quelques commentaires en passant.
Posté par Sygne (site web personnel) . Évalué à 3.
Merci pour le lien, c'est corrigé maintenant.
Pour les questions du détail en typographie:
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.
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:
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 Sygne (site web personnel) . Évalué à 2.
J'ai poussé la version 0.6 de Utmac suite à tes remarques (changelog). Encore merci !
[^] # Re: Quelques commentaires en passant.
Posté par fmaz fmaz . Évalué à 1.
Ça me paraît sans doute pas mal.
Suivre le flux des commentaires
Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.