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.mkdAller plus loin
- Le site d'Utroff (597 clics)
- Télécharger Utroff-0.1.tar.gz (33 clics)
- Journal annonçant la beta d'Utroff (37 clics)
- Dépêche sur l'histoire de Troff (80 clics)
# Des styles ! Des systèmes de documentation automatique !
Posté par JGO . É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 Sygne (site web personnel) . Évalué à 7.
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:
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…
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 fravashyo (site web personnel) . É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 Sygne (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:
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:
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
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.
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.
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.
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.
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 fravashyo (site web personnel) . É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 :
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 JGO . É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 fravashyo (site web personnel) . É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 fusible . É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 Sygne (site web personnel) . Évalué à 3.
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:
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:
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 fravashyo (site web personnel) . É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§ion=all
Malgré tout, je n'ai pas réussi à compiler l'exemple de ton README :
ça bloque en disant
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 Sygne (site web personnel) . Évalué à 3.
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:
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é.
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):
À 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 fravashyo (site web personnel) . É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 :
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 :
Ç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 Sygne (site web personnel) . Évalué à 3.
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:
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.
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 fusible . Évalué à 3. Dernière modification le 06 novembre 2013 à 08:44.
Il me semble qu'il manque aussi de quoi obtenir les licenses. En tout cas ni
make pub, nicd share; makene fonctionnent chez moi.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 :
[^] # Re: Des styles ! Des systèmes de documentation automatique !
Posté par Sygne (site web personnel) . Évalué à 2.
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.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 fravashyo (site web personnel) . É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 barmic . É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 fravashyo (site web personnel) . É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 fravashyo (site web personnel) . É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
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 fusible . Évalué à 2.
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 fravashyo (site web personnel) . É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 fusible . É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 fravashyo (site web personnel) . É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 Sygne (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.
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 fravashyo (site web personnel) . Évalué à 2.
cool, impatient de voir la nouvelle version.
oui pas de problème
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
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 fravashyo (site web personnel) . É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 :
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 Sygne (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.
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.
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.
Heureux de te revoir !
[^] # Re: Des styles ! Des systèmes de documentation automatique !
Posté par Sygne (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 fravashyo (site web personnel) . Évalué à 2.
bonne nouvelle ça.
Tu peux poster un patch sur notre svn, ici :
http://code.google.com/p/txt2tags/source/detail?r=1173
ou ailleurs.
Ensuite, je pourrai sans doute t'obtenir un droit d'écriture dans le dépôt (il n'est pas nécessaire d'avoir un compte gmail je crois).
Sinon je n'ai pas trouvé de formulaire de contact sur ton site.
« 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 Sygne (site web personnel) . Évalué à 3.
Merci, mais je ne vois pas bien comment faire… Le seul lien qui me semble pertinent me demande de créer un compte gmail, et je n'ai pas l'impression que le dépôt svn soit ouvert en écriture (et si c'est le cas, ce ne serait pas du luxe de m'indiquer la commande qui va bien, car je n'ai jamais utilisé svn).
Je suis un peu old school, et j'ai indiqué une adresse mail dans les readme et les manuels: help, chez utroff (.org).
[^] # Re: Des styles ! Des systèmes de documentation automatique !
Posté par fravashyo (site web personnel) . Évalué à 2.
ok, je t'ai envoyé un courriel donc
« 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 fravashyo (site web personnel) . Évalué à 3.
pour ceux que ça intéresse, utmac, la macro d'utroff fait maintenant partie de txt2tags, donc on peut écrire avec la syntaxe txt2tags et convertir en utroff, ou encore convertir du html vers utroff via txt2tags (et grâce à cet outil) :
http://code.google.com/p/txt2tags/source/browse/trunk
« 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 ariasuni . Évalué à 6.
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 steph1978 . Évalué à 4.
mais où peut on trouver cette source ?
[^] # Re: Dépêche rédigée avec Utroff
Posté par Sygne (site web personnel) . Évalué à 4.
La voilà (version non modérée par l'équipe de DLFP) :
:)
Suivre le flux des commentaires
Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.