groff - interface principale du système de formatage de documents GNU roff
Synopsis
groff [-abcCeEgGijklNpRsStUVXzZ] [-d ctext] [-d string=text] [-D fallback-encoding] [-f fontfamily] [-F font-directory] [-I inclusion-directory] [-K input-encoding] [-L spoolerargument] [-m macro-package] [-M macro-directory] [-n page-number] [-o page-list]
[-P postprocessor-argument] [-r cnumeric-expression] [-r register=numeric-expression]
[-T output-device] [-w warning-category] [-W warning-category] [file ...]
groff -h
groff --help
groff -v [option ...] [file ...]
groff --version [option ...] [file ...]
Description
groff est l’interface principale du système de formatage de documents GNU roff. GNU roff est un système de composition typographique qui lit des fichiers d’entrée en texte brut contenant des commandes de formatage pour produire une sortie au format PostScript, PDF, HTML, DVI ou d’autres formats, ou pour l’affichage sur un terminal. Les commandes de formatage peuvent être des primitives de composition typographique de bas niveau, des macros provenant d’un paquetage fourni ou des macros définies par l’utilisateur. Les trois approches peuvent être combinées. Si aucun fichier n’est spécifié en tant qu’opérand, ou si le fichier est « - », groff lit le flux d’entrée standard.
Réimplémentation et extension du formateur d’AT&T Unix, groff est présent sur la plupart des systèmes POSIX en raison de son association de longue date avec les manuels Unix (y compris les pages de manuel). Lui et son prédécesseur sont connus pour avoir produit plusieurs ouvrages d’ingénierie logicielle à succès. groff est capable de produire des documents typographiquement sophistiqués tout en consommant des ressources système minimales.
La commande groff orchestre l’exécution des préprocesseurs, la transformation des documents d’entrée en un langage de description de page indépendant du périphérique et la production de la sortie à partir de ce langage.
Options
-h et --help affichent un message d’utilisation et se terminent.
Comme groff est destiné à remplacer la plupart des invocations directes du formateur troff(1) par les utilisateurs, les deux programmes partagent un ensemble d’options. Cependant, groff a des options que troff n’a pas, et d’autres que groff interprète différemment. En même temps, toutes les options valides de troff ne peuvent pas être données à groff.
Options spécifiques à groff
Les options suivantes n’existent pas dans GNU troff ou sont interprétées différemment par groff.
-D enc Définir l’encodage d’entrée de secours utilisé par preconv(1) sur enc ; implique -k.
-e Exécuter le préprocesseur eqn(1).
-g Exécuter le préprocesseur grn(1).
-G Exécuter le préprocesseur grap(1) ; implique -p.
-I dir Fonctionne comme l’option de troff (voir ci-dessous), mais implique également -g et -s. Il est transmis à soelim(1) et au pilote de sortie, et grn reçoit une option -M avec dir comme argument.
-j Exécute le préprocesseur chem(1) ; implique -p.
-k Exécute le préprocesseur preconv(1). Reportez-vous à sa page de manuel pour connaître son comportement si ni l’option -K ni l’option -D de groff n’est également spécifiée.
-K enc Définit l’encodage d’entrée utilisé par le préprocesseur preconv(1) à enc ; implique -k.
-l Envoie la sortie vers un programme de mise en file d’attente pour l’impression. La directive « print » dans le fichier de description du périphérique spécifie la commande par défaut à utiliser ; voir groff_font(5). Si aucune directive de ce type n’est présente pour le périphérique de sortie, la sortie est redirigée vers lpr(1). Voir les options -L et -X.
-L arg Transmet arg au programme de mise en file d’attente d’impression. Si plusieurs arguments sont requis, transmettez chacun avec une option -L distincte. groff n’ajoute pas de tiret à l’option avant de la transmettre au programme de mise en file d’attente.
-M Fonctionne comme l’option de troff (voir ci-dessous), mais est également transmise à eqn(1), grap(1) et grn(1).
-N Interdit les sauts de ligne entre les délimiteurs eqn : transmet l’option -N à eqn(1).
-p Exécute le préprocesseur pic(1).
-P arg Transmet arg au postprocesseur. Si plusieurs arguments sont requis, transmettez chacun avec une option -P distincte. groff n’ajoute pas de tiret à l’option avant de la transmettre au postprocesseur.
-R Exécute le préprocesseur refer(1). Aucun mécanisme n’est fourni pour transmettre des arguments à refer, car la plupart des options de refer ont des éléments de langage équivalents qui peuvent être spécifiés dans le document.
-s Exécute le préprocesseur soelim(1).
-S Fonctionne en mode « plus sûr » ; voir -U ci-dessous pour son opposé. Pour des raisons de sécurité, le mode plus sûr est activé par défaut.
-t Exécute le préprocesseur tbl(1).
-T dev Indique à troff de formater l’entrée pour le périphérique de sortie dev. groff appelle ensuite un pilote de sortie pour convertir la sortie de troff dans un format approprié pour dev ; voir la sous-section « Périphériques de sortie » ci-dessous.
-U Fonctionne en mode non sécurisé : transmet l’option -U à pic et troff.
-v
--version
Écrit les informations de version pour groff et tous les programmes qu’il exécute sur le flux de sortie standard ; c’est-à-dire que la ligne de commande donnée est traitée de la manière habituelle, en transmettant -v au formateur et à tous les pré- ou post-processeurs appelés.
-V Affiche la chaîne de traitement que groff exécuterait sur la sortie standard, mais ne l’exécute pas. Si cette option est donnée plus d’une fois, groff affiche et exécute la chaîne de traitement.
-X Utilise gxditview(1) au lieu du postprocesseur habituel pour prévisualiser un document sur un écran X11. Combiner cette option avec -Tps utilise les métriques de police du périphérique PostScript, tandis que les options -TX75 et -TX100 utilisent les métriques des polices X11.
-Z Désactive le post-traitement. La sortie de troff apparaîtra sur le flux de sortie standard (sauf si elle est supprimée avec -z) ; voir groff_out(5) pour une description de ce format.
Options transparentes
Les options suivantes sont transmises telles quelles au programme de formatage troff(1) et sont décrites plus en détail dans sa page de manuel.
-a Générer une approximation en texte brut de la sortie typographiée.
-b Écrire une trace de pile sur le flux d’erreur standard pour chaque erreur ou avertissement.
-c Désactiver la sortie en couleur.
-C Activer le mode de compatibilité AT&T troff ; implique -c.
-d cs
-d name=string
Définir une chaîne de caractères.
-E Supprimer les messages d’erreur troff ; implique -Ww.
-f fam Définir la famille de polices par défaut.
-F dir Rechercher dans le répertoire dir le répertoire des fichiers de description des périphériques et des polices du périphérique de sortie sélectionné.
-i Traiter l’entrée standard après les fichiers d’entrée spécifiés.
-I dir Rechercher les fichiers d’entrée dans le répertoire dir.
-m name
Traiter le fichier name.tmac avant les fichiers d’entrée.
-M dir Rechercher les fichiers macro dans le répertoire dir.
-n num Numéroter la première page avec le nombre num.
-o list
Afficher uniquement les pages de la liste.
-r cnumeric-expression
-r register=numeric-expression
Définir un registre.
-w name
-W name
Activer (-w) ou supprimer (-W) l’émission d’avertissements dans la catégorie name.
-z Supprimer la sortie formatée indépendante du périphérique de troff.
Utilisation
L’architecture du système GNU roff suit celle des autres implémentations roff indépendantes des périphériques, comprenant des préprocesseurs, des ensembles de macros, des pilotes de sortie (ou « postprocesseurs »), une suite d’utilitaires et le formateur troff au cœur du système. Voir roff(7) pour un aperçu du fonctionnement d’un système roff.
Les programmes de façade disponibles dans le système GNU roff facilitent son utilisation par rapport aux systèmes roff traditionnels qui nécessitaient la construction de chaînes de commandes ou l’utilisation de fichiers temporaires pour transmettre un document source de sa forme modifiable à sa sortie prête pour le périphérique. La discussion ci-dessous résume les parties constitutives du système GNU roff. Elle complète roff(7) avec des informations spécifiques à groff.
Démarrage
Ceux qui préfèrent apprendre en expérimentant ou qui souhaitent obtenir rapidement des commentaires du système peuvent commencer par un document « Bonjour, monde ! ».
$ echo "Bonjour, monde !" | groff -Tascii | sed '/^$/d'
Bonjour, monde !
Nous avons utilisé une commande sed uniquement pour supprimer les 65 lignes vides qui inonderaient autrement l’écran du terminal. (Les systèmes roff ont été développés à l’époque des terminaux à base de papier avec 66 lignes par page).
Les utilisateurs d’aujourd’hui peuvent préférer une sortie vers un terminal compatible UTF-8.
$ echo "Bonjour, monde !" | groff -Tutf8 | sed '/^$/d'
La production de PDF, HTML ou du DVI de TeX est également simple. Le plus difficile pourrait être de choisir un programme de visualisation pour la sortie.
$ echo "Bonjour, monde !" | groff -Tpdf > bonjour.pdf
$ evince bonjour.pdf
$ echo "Bonjour, monde !" | groff -Thtml > bonjour.html
$ firefox bonjour.html
$ echo "Bonjour, monde !" | groff -Tdvi > bonjour.dvi
$ xdvi bonjour.html
Utiliser groff comme REPL
Ceux qui ont un penchant pour la programmation peuvent être heureux de constater qu’ils peuvent utiliser groff dans une boucle d’évaluation-impression (REPL). Cela peut être utile pour vérifier sa compréhension du comportement du formateur et/ou de la syntaxe qu’il accepte. Activer tous les avertissements avec -ww peut aider à atteindre cet objectif.
$ groff -ww -Tutf8
# Ceci est un commentaire. Définissons un registre.
.nr a 1
# Effectuons des opérations arithmétiques entières avec des opérateurs évalués de gauche à droite.
.nr b \n[a]+5/2
# Affichons le résultat sur le flux d’erreur standard.
.tm \n[b]
3 # Définissons maintenant une chaîne de caractères.
.ds name Leslie\" Ceci est une autre forme de commentaire.
.nr b (\n[a] + (7/2))
# Centrons les deux prochaines lignes de texte.
.ce 2
Bonjour, \\*[name].
Votre numéro secret est \n[b].
# Nous allons constater que la division est arrondie vers zéro.
C’est
# Voici une structure de contrôle if-else.
.ie (\n[b] % 2) odd.
.el even.
# Cette astuce définit la longueur de la page à la position verticale actuelle, de sorte que les lignes vides ne soient pas affichées lorsque nous avons terminé.
.pl \n[nl]u
<Control-D>
Bonjour, Leslie.
Votre numéro secret est 4.
C’est pair.
Format du document
Dans GNU roff, les dimensions de la page pour le formateur troff et pour les périphériques de sortie sont gérées séparément. Dans le formateur, des requêtes sont utilisées pour définir la longueur de la page (.pl), le décalage de la page (ou la marge gauche, .po) et la longueur de la ligne (.ll). La marge droite n’est pas configurée explicitement ; la combinaison du décalage de la page et de la longueur de la ligne fournit les informations nécessaires pour la déduire. Le paquet de macros papersize, chargé automatiquement par troff, fournit une interface pour configurer les dimensions de la page à l’aide de noms pratiques, tels que « letter » ou « A4 » ; voir groff_tmac(5). La valeur par défaut du formateur dans cette installation est « A4 ».
Il appartient à chaque paquet de macros de respecter les dimensions de page configurées de cette manière. Certains offrent des mécanismes alternatifs.
Pour chaque périphérique de sortie, la taille du support de sortie peut être définie dans son fichier DESC. La plupart des pilotes de sortie reconnaissent également une option de ligne de commande -p pour remplacer les dimensions par défaut et une option -l pour utiliser l’orientation paysage. Voir groff_font(5) pour une description de la directive papersize, qui prend un argument de la même forme que -p. La page de manuel du pilote de sortie, telle que grops(1), peut également être utile. groff utilise l’option de ligne de commande -P pour transmettre des options aux périphériques de sortie ; par exemple, utilisez ce qui suit pour la sortie PostScript sur du papier A4 en orientation paysage.
groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
Interface
Le programme groff est une enveloppe autour du programme troff(1). Il permet de spécifier des préprocesseurs via des options de ligne de commande et exécute automatiquement le postprocesseur approprié pour le périphérique de sortie sélectionné. Ainsi, la construction manuelle de pipelines ou la gestion de fichiers temporaires requises par les utilisateurs des systèmes roff(7) traditionnels peuvent être évitées. Utilisez le programme grog(1) pour déduire une ligne de commande groff appropriée pour formater un document.
Langage
L’entrée d’un système roff est un texte brut entrelacé avec des lignes de contrôle et des séquences d’échappement. La combinaison constitue un document dans une famille de langages que nous appelons également roff ; voir roff(7) pour plus d’informations. Une vue d’ensemble de la syntaxe et des fonctionnalités du langage GNU roff, y compris des listes de toutes les séquences d’échappement, requêtes et registres prédéfinis pris en charge, peut être trouvée dans groff(7). Les extensions GNU roff au langage AT&T troff, un sous-ensemble courant des dialectes roff existants aujourd’hui, sont détaillées dans groff_diff(7).
Préprocesseurs
Un préprocesseur interprète un langage spécifique à un domaine, qui produit une sortie au format roff. Fréquemment, cette entrée est limitée à des sections ou des régions d’un fichier d’entrée roff (délimitées par des appels de macro spécifiques à chaque préprocesseur), qu’il remplace. Les préprocesseurs interprètent donc souvent un sous-ensemble de la syntaxe roff, ainsi que leur propre langage. GNU roff fournit des réimplémentations de la plupart des préprocesseurs connus des utilisateurs d’AT&T troff ; ceux-ci disposent généralement de fonctionnalités étendues et/ou nécessitent GNU troff pour formater leur sortie.
tbl formate des tableaux ; eqn met en forme des équations mathématiques ; pic dessine des diagrammes ; refer traite des références bibliographiques ; soelim pré-traite les fichiers d’entrée « sourcés » ; grn affiche des diagrammes gremlin(1) ; chem dessine des formules de structures chimiques en utilisant pic ; gperl remplit les registres et les chaînes groff à l’aide de perl(1) ; glilypond intègre des partitions musicales LilyPond ; et gpinyin facilite la saisie en mandarin en utilisant Hanyu Pinyin.
Un préprocesseur unique à GNU roff est preconv(1), qui convertit divers encodages d’entrée en un format que GNU troff peut comprendre. Lorsqu’il est utilisé, il s’exécute avant tout autre préprocesseur.
La plupart des préprocesseurs encadrent le contenu entre une paire de jetons caractéristiques. Un tel jeton doit apparaître au début d’une ligne d’entrée et utiliser le caractère de contrôle point. Il ne doit pas y avoir d’espaces ou de tabulations après le caractère de contrôle ou avant la fin de la ligne d’entrée. Le non-respect de ces règles empêche le préprocesseur de reconnaître un jeton. Les jetons sont généralement préservés dans la sortie du préprocesseur et interprétés en tant qu’appels de macro par troff. Le préprocesseur idéal n’est pas encore disponible dans groff.
┌──────────────┬─────────────────┬────────────────┐ │ préprocesseur │ jeton de début │ jeton de fin │ ├──────────────┼─────────────────┼────────────────┤ │ chem │ .cstart │ .cend │ │ eqn │ .EQ │ .EN │ │ grap │ .G1 │ .G2 │ │ grn │ .GS │ .GE │ │ ideal │ .IS │ .IE │ │ │ │ .IF │ │ pic │ .PS │ .PE │ │ │ │ .PF │ │ │ │ .PY │ │ refer │ .R1 │ .R2 │ │ tbl │ .TS │ .TE │ ├──────────────┼─────────────────┼────────────────┤ │ glilypond │ .lilypond start │ .lilypond stop │ │ gperl │ .Perl start │ .Perl stop │ │ gpinyin │ .pinyin start │ .pinyin stop │ └──────────────┴─────────────────┴────────────────┘
Packs de macros
Les fichiers de macros sont des fichiers d’entrée roff conçus pour ne pas produire de sortie en eux-mêmes, mais plutôt pour faciliter la préparation d’autres documents roff. Lorsqu’un fichier de macros est installé dans un emplacement standard et qu’il est adapté à un public général, il est appelé pack de macros.
Les packs de macros peuvent être chargés avant tous les documents d’entrée roff à l’aide de l’option -m. Le système GNU roff implémente la plupart des packs de macros bien connus d’AT&T troff d’une manière compatible et les étend. Ils ont des noms d’une ou deux lettres, résultat des pratiques intensives d’économie de nom dans la culture Unix ancienne, une approche laconique qui a conduit à ce que de nombreux packs soient identifiés dans l’usage général par la lettre d’option nroff et troff utilisée pour les invoquer, parfois avec un effet humoristique, comme avec « man » (abréviation de « manuel »), et même avec le tiret de l’option, comme dans le cas du pack s, beaucoup mieux connu sous le nom de ms ou même -ms.
Les packs de macros servent à diverses fins. Certains sont des packs « tout-en-un », qui assument la responsabilité de la mise en page, entre autres tâches fondamentales, et qui définissent leur propre lexique de macros pour la composition de documents ; chaque pack de ce type est autonome, et un document donné ne peut en utiliser qu’un seul.
an est utilisé pour composer des pages de manuel dans le format créé dans Version 7 Unix (1979) ; voir groff_man(7). Il peut être spécifié sur la ligne de commande sous la forme -man.
doc est utilisé pour composer des pages de manuel dans le format créé dans 4.3BSD-Reno (1990) ; voir groff_mdoc(7). Il peut être spécifié sur la ligne de commande sous la forme -mdoc.
e est la suite de macros générale de Berkeley, développée comme alternative à la suite s d’AT&T ; voir groff_me(7). Il peut être spécifié sur la ligne de commande sous la forme -me.
m implémente le format utilisé par la suite de macros de deuxième génération d’AT&T pour les documents généraux, un successeur de s ; voir groff_mm(7). Il peut être spécifié sur la ligne de commande sous la forme -mm.
om (appelé invariablement « mom ») est un pack moderne écrit par Peter Schaffter spécialement pour GNU roff. Consultez le manuel HTML de mom pour une documentation complète. Elle — car mom prend le pronom féminin — peut être spécifiée sur la ligne de commande sous la forme -mom.
s est le format de documents général d’origine d’AT&T ; voir groff_ms(7). Il peut être spécifié sur la ligne de commande sous la forme -ms.
D’autres sont complémentaires. Par exemple, andoc est un pack d’enveloppe spécifique à GNU roff qui reconnaît si un document utilise le format man ou mdoc et charge le pack de macros correspondant. Il peut être spécifié sur la ligne de commande sous la forme -mandoc. Un programme de bibliothèque man(1) peut utiliser ce fichier de macros pour déléguer le chargement du pack de macros approprié ; il n’est donc pas nécessaire que man lui-même analyse le contenu d’un document pour décider.
De nombreux fichiers macro augmentent la fonctionnalité des ensembles de paquets complets ou des documents roff qui n’utilisent pas ces paquets ; ces derniers sont parfois qualifiés de « bruts ». Ces paquets auxiliaires sont décrits, ainsi que les détails de la dénomination et du placement des fichiers macro, dans groff_tmac(5).
Formatteurs
Le formateur, le programme qui interprète les entrées du langage roff, est troff(1). Il fournit les fonctionnalités des programmes AT&T troff et nroff ainsi que de nombreuses extensions. L’option de ligne de commande -C fait passer troff en mode de compatibilité, qui tente d’émuler AT&T troff aussi fidèlement que possible afin de permettre le formatage de documents écrits pour l’ancien système.
Un script shell, nroff(1), émule le comportement d’AT&T nroff. Il tente d’encoder correctement la sortie en fonction de la locale, ce qui évite à l’utilisateur de devoir spécifier un périphérique de sortie avec l’option -T et est donc pratique pour une utilisation avec les périphériques de sortie de terminal, décrits dans la sous-section suivante.
GNU troff génère une sortie dans un langage de description de page indépendant du périphérique, mais pas agnostique du périphérique, décrit dans groff_out(5).
Périphériques de sortie
La sortie de troff est formatée pour un périphérique de sortie particulier, généralement spécifié par l’option -T du formateur ou d’une interface. Si ni cette option ni la variable d’environnement GROFF_TYPESETTER n’est utilisée, le périphérique de sortie par défaut est ps. Un périphérique de sortie peut être l’un des suivants.
ascii pour les terminaux utilisant le jeu de caractères et l’encodage ISO 646 1991 :IRV, également connu sous le nom d’USASCII.
cp1047 pour les terminaux utilisant le jeu de caractères et l’encodage IBM code page 1047.
dvi pour le format TeX DVI.
html
xhtml pour les sorties HTML et XHTML, respectivement.
latin1 pour les terminaux utilisant le jeu de caractères et l’encodage ISO Latin-1 (ISO 8859-1).
lbp pour les imprimantes Canon CaPSL (séries LBP-4 et LBP-8).
lj4 pour les imprimantes compatibles HP LaserJet4 (ou autres imprimantes compatibles PCL5).
pdf pour la sortie PDF.
ps pour la sortie PostScript.
utf8 pour les terminaux utilisant le jeu de caractères ISO 10646 (« Unicode ») avec l’encodage UTF-8.
X75 pour la prévisualisation avec gxditview avec une résolution de 75 dpi et une taille de police de base de 10 points.
X75-12 pour la prévisualisation avec gxditview avec une résolution de 75 dpi et une taille de police de base de 12 points.
X100 pour la prévisualisation avec gxditview avec une résolution de 100 dpi et une taille de police de base de 10 points.
X100-12 pour la prévisualisation avec gxditview avec une résolution de 100 dpi et une taille de police de base de 12 points.
Post-processeurs
Tout programme qui interprète la sortie de GNU troff est un post-processeur. Les post-processeurs fournis par GNU roff sont des pilotes de sortie, qui préparent un document pour l’affichage ou l’impression. Des post-processeurs à d’autres fins, tels que le réordonnancement des pages ou la mesure statistique d’un document, sont concevables.
Un pilote de sortie prend en charge un ou plusieurs périphériques de sortie, chacun ayant son propre fichier de description de périphérique.
Un périphérique détermine son postprocesseur grâce à la directive postpro dans son fichier de description de périphérique ;
voir groff_font(5). L’option -X annule cette sélection, ce qui fait que gxditview sert de
pilote de sortie.
`grodvi(1)`
fournit dvi.
`grohtml(1)`
fournit html et xhtml.
`grolbp(1)`
fournit lbp.
`grolj4(1)`
fournit lj4.
`gropdf(1)`
fournit pdf.
`grops(1)`
fournit ps.
`grotty(1)`
fournit ascii, cp1047, latin1 et utf8.
`gxditview(1)`
fournit X75, X75-12, X100 et X100-12, et peut également servir à prévisualiser des fichiers ps.
Utilitaires
GNU roff comprend une suite d’utilitaires.
`gdiffmk(1)`
met en évidence les différences entre deux fichiers d’entrée roff.
`grog(1)`
détermine la commande groff requise pour un document.
Plusieurs utilitaires préparent des descriptions de polices, ce qui permet au formateur de les utiliser lors de la création de la sortie pour un périphérique donné.
`addftinfo(1)`
ajoute des informations aux fichiers de description de polices AT&T troff pour permettre leur utilisation avec GNU troff.
`afmtodit(1)`
crée des fichiers de description de polices pour les polices PostScript Type 1.
`pfbtops(1)`
convertit une police PostScript Type 1 au format PFB (Printer Font Binary) en PFA (Printer Font ASCII), qui peut ensuite être interprétée par `afmtodit`.
`hpftodit(1)`
crée des fichiers de description de polices pour la famille d’imprimantes HP LaserJet 4.
`tfmtodit(1)`
crée des fichiers de description de polices pour le périphérique DVI TeX.
`xtotroff(1)`
crée des fichiers de description de polices pour les polices principales du système X Window.
Un trio d’outils transforme du contenu créé à l’aide des langages de préprocesseur roff en fichiers d’image graphiques.
`eqn2graph(1)`
convertit une équation eqn en une image découpée.
`grap2graph(1)`
convertit un diagramme grap en une image découpée.
`pic2graph(1)`
convertit un diagramme pic en une image découpée.
Un autre ensemble de programmes fonctionne avec les fichiers de données bibliographiques utilisés par le préprocesseur refer(1).
`indxbib(1)`
crée des index inversés pour les bases de données bibliographiques, ce qui accélère les opérations de recherche.
`lkbib(1)`
effectue des recherches dans les bases de données.
`lookbib(1)`
effectue des recherches interactives dans les bases de données.
Code de sortie
`groff` quitte avec un code d’erreur si un problème est survenu lors de l’analyse de ses arguments et avec un code de succès si l’une des options `-h` ou `--help` a été spécifiée. Sinon, `groff` exécute une série de commandes pour traiter son entrée ; si toutes les commandes de la série s’exécutent avec succès, `groff` fait de même.
Si ce n’est pas le cas, le code de sortie de groff encode un résumé des problèmes rencontrés, en définissant le bit 0 si une commande a quitté avec un code d’erreur, le bit 1 si une commande a été interrompue par un signal et le bit 2 si une commande n’a pas pu être exécutée. (Ainsi, si les trois problèmes se sont produits dans la série, groff quitterait avec le code 2^0 + 2^1 + 2^2 = 1+2+4 = 7.) Pour résoudre les problèmes de la série, vous pouvez souhaiter réexécuter la commande groff avec l’option -V et diviser la série signalée en étapes distinctes, en inspectant le code de sortie et les messages de diagnostic émis par chaque commande.
Environnement
Normalement, le séparateur de chemin dans les variables d'environnement se terminant par PATH est le deux-points ; cela peut varier en fonction du système d'exploitation. Par exemple, Windows utilise un point-virgule.
GROFF_BIN_PATH
Ce chemin de recherche, suivi de PATH, est utilisé pour localiser les commandes exécutées par groff. S'il n'est pas défini, le répertoire d'installation des exécutables GNU roff, /usr/bin, est recherché avant PATH.
GROFF_COMMAND_PREFIX
GNU roff peut être configuré au moment de la compilation pour appliquer un préfixe aux noms des programmes qu'il fournit et qui avaient un équivalent dans AT&T troff, afin d'éviter les conflits de noms lors de l'exécution. Le préfixe par défaut est vide.
Lorsqu'il est utilisé, ce préfixe est conventionnellement la lettre « g ». Par exemple, GNU troff serait installé sous le nom de gtroff. En plus de troff, le préfixe s'applique aux formateurs nroff, aux préprocesseurs eqn, grn, pic, refer, tbl et soelim, ainsi qu'aux utilitaires indxbib et lookbib.
GROFF_ENCODING
La valeur de cette variable est transmise à l'option -e du préprocesseur preconv(1) afin de sélectionner l'encodage des caractères des fichiers d'entrée. L'existence de cette variable implique l'option groff -k. Si elle est définie mais vide, groff appelle preconv sans l'option -e. L'option -K de groff remplace GROFF_ENCODING.
GROFF_FONT_PATH
Rechercher le répertoire des fichiers de description des polices et des périphériques de sortie dans cette liste de répertoires. Voir troff(1) et groff_font(5).
GROFF_TMAC_PATH
Rechercher les fichiers de macros dans cette liste de répertoires. Voir troff(1) et groff_tmac(5).
GROFF_TMPDIR
Créer des fichiers temporaires dans ce répertoire. S'il n'est pas défini, mais que la variable d'environnement TMPDIR est définie, les fichiers temporaires sont créés dans ce répertoire. Sur les systèmes Windows, si ni l'un ni l'autre des éléments précédents n'est défini, les variables d'environnement TMP et TEMP (dans cet ordre) sont également vérifiées. Sinon, les fichiers temporaires sont créés dans /tmp. Les commandes refer(1), grohtml(1) et grops(1) utilisent des fichiers temporaires.
GROFF_TYPESETTER
Définir le périphérique de sortie par défaut. S'il est vide ou non défini, ps est utilisé. L'option -T remplace GROFF_TYPESETTER.
SOURCE_DATE_EPOCH
Un horodatage (exprimé en secondes depuis l'époque Unix) à utiliser comme horodatage de création de la sortie, en remplacement de l'heure actuelle. L'heure est convertie en un format lisible par l'homme à l'aide de gmtime(3) et asctime(3) lorsque le formateur démarre et stockée dans des registres utilisables par les documents et les packages de macros.
TZ La zone horaire à utiliser lors de la conversion de l'heure actuelle en un format lisible par l'homme ; voir tzset(3). Si SOURCE_DATE_EPOCH est utilisé, il est toujours converti en un format lisible par l'homme en utilisant UTC.
Exemples
Les systèmes roff sont surtout connus pour le formatage des pages de manuel. Une fois qu'un programme de bibliothèque man(1) a localisé une page de manuel, il peut exécuter une commande groff similaire à la suivante. groff -t -man -Tutf8 /usr/share/man/man1/groff.1 La bibliothèque transmettra également la sortie à un paginateur, qui peut ne pas interpréter les séquences d'échappement de terminal SGR que groff émet pour le gras, le soulignement ou l'italique ; voir la section « Limitations » ci-dessous.
Pour traiter un fichier d’entrée roff en utilisant les préprocesseurs tbl et pic et le paquet de macros me, de la manière à laquelle les utilisateurs d’AT&T troff étaient habitués, on taperait (ou écrirait un script) une chaîne de commandes.
pic foo.me | tbl | troff -me -Tutf8 | grotty
Avec groff, cette chaîne de commandes peut être raccourcie en une commande équivalente.
groff -p -t -me -T utf8 foo.me
Une manière encore plus simple de faire cela est d’utiliser grog(1) pour deviner les options du préprocesseur et des macros, puis d’exécuter le résultat en utilisant la fonction de substitution de commandes du shell.
$(grog -Tutf8 foo.me)
Chaque option de ligne de commande pour un postprocesseur doit être spécifiée avec tous les tirets initiaux requis « - », car groff transmet les arguments tels quels au postprocesseur ; cela permet de transmettre des arguments arbitraires. Par exemple, pour transmettre un titre au postprocesseur gxditview, les commandes shell suivantes groff -X -P -title -P 'essai' mydoc.t et groff -X -Z mydoc.t | gxditview -title 'essai' sont équivalentes.
Limitations
Lorsque la sortie est paginée pour les périphériques ascii, cp1047, latin1 et utf8, des programmes comme more(1) et less(1) peuvent nécessiter des options de ligne de commande pour gérer correctement certaines séquences d’échappement du terminal ; voir grotty(1).
Sur les hôtes EBCDIC tels que OS/390 Unix, les périphériques de sortie ascii et latin1 ne sont pas disponibles. Inversement, le périphérique de sortie cp1047 n’est pas disponible sur les systèmes basés sur les normes de codage de caractères ISO 646 ou ISO 8859.
Répertoires d’installation
GNU roff installe des fichiers à différents endroits en fonction de sa configuration au moment de la compilation. Pour cette installation, les emplacements suivants sont utilisés.
/etc/X11/app-defaults
Répertoire des valeurs par défaut des applications pour gxditview(1).
/usr/bin
Répertoire contenant les commandes exécutables de groff.
/usr/share/groff/1.23.0/eign
Liste des mots courants pour indxbib(1).
/usr/share/groff/1.23.0
Répertoire pour les fichiers de données.
/usr/dict/papers/Ind
Index par défaut pour lkbib(1) et refer(1).
/usr/share/doc/groff-base
Répertoire de documentation.
/usr/share/doc/groff-base/examples
Répertoire des exemples.
/usr/share/groff/1.23.0/font
Répertoire des polices.
/usr/share/doc/groff-base/html
Répertoire de la documentation HTML.
/usr/lib/font
Répertoire des polices hérité.
/usr/share/groff/site-font
Répertoire local des polices.
/usr/share/groff/site-tmac
Répertoire local du paquet de macros (fichier tmac).
/usr/share/groff/1.23.0/tmac
Répertoire du paquet de macros (fichier tmac).
/usr/share/groff/1.23.0/oldfont
Répertoire des polices pour la compatibilité avec les anciennes versions de groff ; voir grops(1).
/usr/share/doc/groff-base/pdf
Répertoire de la documentation PDF.
Répertoire des macros groff
La plupart des fichiers de macros fournis avec GNU roff sont stockés dans /usr/share/groff/1.23.0/tmac pour l’installation correspondant à ce document. En règle générale, plusieurs répertoires sont recherchés pour les fichiers de macros ; voir troff(1). Pour un catalogue des fichiers de macros fournis par GNU roff, voir groff_tmac(5).
Répertoire de description des périphériques et des polices groff
Les fichiers de description des périphériques et des polices fournis avec GNU roff sont stockés dans /usr/share/groff/1.23.0/. police pour l’installation correspondant à ce document. En règle générale, plusieurs répertoires sont recherchés pour les fichiers de description des périphériques et des polices ; voir troff(1). Pour les formats de ces fichiers, voir groff_font(5).
Disponibilité
Obtenez des liens vers les versions de groff téléchargeables, son dépôt de code source, les listes de diffusion de discussion, un système de suivi des tickets d’assistance et des informations complémentaires sur la page groff du site web GNU.
Une implémentation gratuite du préprocesseur grap, écrite par Ted Faber, est disponible sur le site web grap.
groff ne prend en charge que ce grap.
Auteurs
groff (à la fois la commande frontale et l’ensemble du système) a été principalement écrit par James Clark.
Les contributeurs à ce document incluent Clark, Trent A. Fisher, Werner Lemberg, Bernd Warken et G. Branden Robinson.
Voir aussi
Groff : l’implémentation GNU de troff, de Trent A. Fisher et Werner Lemberg, est le manuel principal
de groff. Vous pouvez le consulter en ligne avec « info groff ».
Introduction, historique et lecture complémentaire : roff(7)
Visualiseur pour les documents groff (et AT&T device-independent troff) : gxditview(1)
Préprocesseurs :
chem(1), eqn(1), neqn(1), glilypond(1), grn(1), preconv(1), gperl(1), pic(1), gpinyin(1),
refer(1), soelim(1), tbl(1)
Packs de macros et utilitaires spécifiques aux packs : groff_hdtbl(7), groff_man(7), groff_man_style(7), groff_mdoc(7), groff_me(7), groff_mm(7), groff_mmse(7) (uniquement dans les locales suédoises), mmroff(1), groff_mom(7), pdfmom(1), groff_ms(7), groff_rfc1345(7), groff_trace(7), groff_www(7)
Outils de gestion de bases de données bibliographiques : indxbib(1), lkbib(1), lookbib(1)
Langue, conventions et extensions GNU : groff(7), groff_char(7), groff_diff(7), groff_font(5), groff_tmac(5)
Langue de sortie intermédiaire : groff_out(5)
Programme de formatage : troff(1)
Enveloppes de formatage : nroff(1), pdfroff(1)
Postprocesseurs pour les périphériques de sortie : grodvi(1), grohtml(1), grolbp(1), grolj4(1), gropdf(1), grops(1), grotty(1)
Utilitaires de prise en charge des polices : addftinfo(1), afmtodit(1), hpftodit(1), pfbtops(1), tfmtodit(1), xtotroff(1)
Utilitaires de conversion graphique : eqn2graph(1), grap2graph(1), pic2graph(1)
Utilitaire de marquage des différences : gdiffmk(1)
Utilitaire « groff guess » :
grog(1)