{{tag>tutoriel Bionic editeur_de_texte}}
----

====== Groff  tutoriel======

 {{:doc:groff-head.png?200|}}

**[[:groff|Groff]]** demande à  son utilisateur une bonne dose de "prise en main".  Faciliter cette prise en main est le but de ce tutoriel. Il devrait permettre à un utilisateur moyen, formé à la ligne de commande, de faire ses premiers vols d'essai dans ce logi**ciel** :-). 

Nous allons voir que Groff est accompagné d'un ensemble de 5 "paquets de macros", sortes de boîtes à outils qui facilitent l'écriture de documents en apportant des commandes toutes faites (par exemple pour définir des chapitres, paragraphes, listes...), plus simples à utiliser que les requêtes générales de Groff. Parmi ces paquets de macros, le paquet **Mom** est certainement le mieux documenté et le plus simple à utiliser, il est donc tout à fait recommandé pour débuter avec Groff. D'une certaine manière on peut faire un parallèle entre Groff/Mom et Tex/Latex: Mom offre la même facilité d'utilisation de Groff que Latex; [[:Latex]] étant un ensemble de macros du processeur de texte Tex.

=====Rédiger en mode graphique=====

Tout d'abord, voici la manière classique de rédiger avec Groff. Pour garder une certaine clarté, répartissez le travail sur 3 bureaux virtuels.

Sur le premier bureau, placez un [[:éditeur de texte]] ( [[:gedit]], [[:mousepad]], [[:leafpad]]...) où vous pouvez taper votre texte d'entrée. N'oubliez pas d'__enregistrer__ le texte d'entrée et de __nommer__ le fichier d'entrée. Le plus pratique est de placer votre fichier d'entrée dans votre répertoire utilisateur.

Sur un deuxième bureau virtuel, ouvrez un terminal où vous transformez votre fichier d'entrée avec la commande groff.
<code>groff votre_fichier > votre_fichier.ps</code>

Sur le troisième bureau virtuel, allez dans votre répertoire personnel, vous y trouverez votre_fichier.ps, que vous pouvez lire avec le visionneur de documents.

Le tout en image. Ici, le fichier a été nommé "michao".

{{:doc:groff_precise_01.png?220|}} {{:doc:groff_precise_02.png?220|}} {{:doc:groff_precise_03.png?220|}}

Par défaut, groff ne tient pas compte des changements de ligne.\\
Pour éditer un poème, comme c'est le cas ici, commencer simplement chaque ligne par un espace.

Si vous avez utilisé des caractères accentués ou spéciaux (tels que le ç), vous aller retrouver dans votre fichier de sortie des signes kabalistiques! Ne vous en faites pas: il suffit d'ajouter l'option -k, comme on peut le voir sur l'image du milieu.\\
Groff travaille sur un jeu de caractères restreint. L'option -k (preconv),  préconvertit les caractères spéciaux en quelque chose que groff peut comprendre. (Pour en savoir plus: man preconv).

Si vous avez des corrections à apporter,  retournez sur le premier bureau virtuel, apportez vos corrections, enregistrez. Sur le deuxième bureau, repassez la commande groff. Vos corrections passent sur le fichier de sortie sans qu'il soit nécessaire de fermer et de réouvrir celui-ci   8-).

 Si vous avez commis des erreurs, groff vous le signalera en indiquant le No de la ligne concernée. Il convient donc d'activer la numérotaiton des lignes dans l'éditeur de texte que vous utilisez.\\
(Menu > Vue ou Affichage > numéros de lignes).\\
Groff n' indique bien sûr que les erreurs de commandes, pas les erreurs d'orthographe ou de grammaire.

En cas de pépin dans le terminal, Ctrl+c donne un nouveau prompt.


====où placer le fichier?====

Par défaut, groff travaille dans le répertoire courant, c'est à dire la racine de votre dossier personnel. Il est donc pratique de placer les fichiers sur lesquels vous travaillez directement dans votre dossier personnel,  et non dans un sous-répertoire.

Si vous voulez placer vos fichier destinés à groff ailleurs, par exemple dans le sous-répertoire "Documents", deux solutions se présentent:

1. Indiquer à groff le chemin complet du fichier, par ex.
<code>groff /home/utilisateur/Documents/votre_fichier > /home/utilisateur/Documents/votre_fichier.ps</code> 
Ce qui fait quand même de longues commandes à taper  :-\ .

2. Se placer dans le sous-répertoire voulu avec la commande **cd**.
<code>cd /home/utilisateur/Documents
groff votre_fichier > votre_fichier.ps</code>
Ayant achevé votre travail, quitter le sous-répertoire avec
<code>cd</code>


====gedit====
L'avantage de [[:gedit]] est qu'il offre une console intégrée en-dessous de la fenêtre d'édition.
Cela vous permet de travailler sur deux bureaux virtuels seulement au lieu de trois.

Pour avoir la console intégrée, installez tout d'abord **[[apt>gedit-plugins|gedit-plugins]]**\\
Puis ouvrez gedit: \\
Edition > Préférences  > Greffons, cochez "Terminal intégré"\\
Ensuite allez à "affichage" et cochez "panneau inférieur".

Gedit avec console intégrée:

{{:doc:groff_04.png?300|}}

Une fois la console installée, il est possible de copier-coller les commandes par clic droit sur celle-ci. Cela peut être pratique quand on effectue des corrections et que l'on répète une commande plusieurs fois d'affilée.

<note tip>Il  est possible que votre terminal intégré écrive blanc sur blanc, ce qui n'est pas très lisible :-/. Il y a de quoi réparer ce bug ici:
https://askubuntu.com/questions/67593/make-gedit-embedded-terminal-colours-the-same-as-the-default-terminal.
Veillez à faire rigoureusement ce qui est décrit. Abstenez-vous si vous n'êtes pas tout à fait sûr(e) d'avoir compris.</note>

Un autre avantage de gedit est qu'il peut vérifier l'orthographe: Outils > Vérification orthographique.


====emacs====

Sur [[:emacs]], la situation ressemble à celle de gedit.  Taper simplement le texte d'entrée sur un nouveau fichier, __enregistrez__ et  __nommez__ le fichier. Ensuite par Tool > shell command, il est possible, sans rien avoir installé, d'avoir une console intégrée sous la fenêtre de l'éditeur de texte. Là, vous pouvez taper votre commande groff et récupérer le fichier de sortie dans votre dossier personnel. 

{{:doc:groff_05.png?300|}}

Par "Tool > shell command on Region" il est même possible d'appliquer la commande groff à une sélection seulement. Il n'est même pas nécessaire de mettre la sélection en argument de la commande groff, entrez simplement
<code>groff  > sel.ps</code>
et récupérez le fichier sel.ps dans votre dossier personnel.

=====Requêtes générales=====
Nous sommes prêts maintenant à formater des textes. Pour commencer, il sera très utile  de  connaître quelques unes des requêtes générales, qui sont valables quelque soit la "boîte à outils" que vous choisirez (voir chap. 3). Ces requêtes générales permettront déjà entre autre de
  * varier la taille ou la police de caractère
  * sauter une ou plusieurs lignes
  * justifier ou non les lignes
  * indenter le texte
  * changer l'espacement des lignes

Ces requêtes sont décrites au chapitre 4 de cet ouvrage:\\
[[http://oreilly.com/openbook/utp/|UTP]] [en]\\
Comme groff est un troff (GNU-troff), vous pouvez sauter tous les passages relatifs à nroff, ditroff...

<note>A partir d'ici, les balises (requêtes) seront indiquées en caractères machine comme ''ceci''</note>.

====Polices====
Comment changer la police de caractères dans groff? Cette question mérite d'être développée.
Tout d'abord, il existe une dizaine de familles de polices. Par famille de police (font-family), on entend: une police normale (Roman), sa variante en gras (Bold), sa variante italique (Oblique) et bien sûr sa variante gras-oblique (BoldOblique). Si vous choisissez la famille Palatino, la famille est consitiuée de :
  * PR: Palatino-Roman
  * PB: Palatino-Bold
  * PI: Palatino-Italic
  * PBI: Palatino_BoldItalic

Vous trouverez la description complète des polices disponibles dans:\\
usr/share/doc/groff/examples/hdtbl/fonts_x.ps.gz

Dans votre texte, vous pouvez à tout moment changer de police avec la balise ''.ft''.

===Changer de famille de polices===
Vous pouvez changer de famille de police à l'aide de la requête ''.fam''. Par exemple:\\
Passer en Helvetica:  ''.fam H''  \\
Revenir au réglage par défaut: ''.fam''

Vous pouvez changer de famille et de police avec la requête ''.ft'' . \\
Par exemple, en restant dans la même famille: \\
Passer en italique :'' .ft I''\\
Revenir à roman: ''.ft'' (''.ft'' sans argument revient au réglage précédent).

En changeant de famille et de police\\
Passer en Helvetica Italique: ''.ft HI''\\
Revenir à Times Italique:'' .ft  TI''\\
Revenir à Times Roman: ''.ft TR''


===Changer de variante en restant dans la même famille===
À l'intérieur d'un mot ou d'une phrase, vous pouvez changer à l'intérieur d'une famille à l'aide d'une **séquence d'échappement** . Pour passer en carctères gras '' \fB'' et pour retourner sur "roman"  ''\fP''


===== Choisir sa boîte à outils =====

Ce chapitre présente les "outils" qui vont vous rendre véritablement capable de donner forme à un texte: faire des titres, des chapitres, des sous-chapitres,  faire des notes en bas de pages, des en-têtes, des références, etc..

Il y a 5 "boîtes à outils" à choix: -me, -ms, -mm, -mom  ou -man. On les appelle aussi "paquets de macros". Les [[wp>macros]] sont des macro-instructions indiquant au système comment formater un texte. Un paquet de macros est un ensemble de macro-instructions cohérent, permettant de formater des textes.

Maîtriser une de ces 5 "boîte à outils" vous suffira amplement. Deux d'entre-elles sont bien documentées en français, d'autres malheureusement ne le sont pas encore...Choisissez celle qui vous correspond le mieux!

==== -mom ====
C'est le paquet de macros le plus jeune. Très général, largement configurable, conçu entre autres dans le but de  rédiger un roman, -mom est un bon choix pour tout ceux qui trouvent les paquets de macros traditionnels (-me,-ms, -mm) trop austères.

On en trouve une courte présentation en français [[https://ftp.traduc.org/doc-vf/gazette-linux/html/2004/107/lg107-F.html|ici]] .

Pour apprendre à travailler vraiment avec -mom, c'est [[http://www.schaffter.ca/mom/mom-04.html|ici]] [en] ou téléchargez [[http://www.schaffter.ca/shared/groff-and-mom.pdf|ce pdf]] [en]

Ajouter l'option** -mom** à votre commande groff
<code>groff -mom -k foo > foo.ps</code>

Voyez aussi  l'exemple concret au chap.4


==== -me ====
Paquet classique, bien documenté, conçu pour rédiger des documents universitaires.

Le document meintro_fr.ps vous permettra d'apprendre les principaux outils de -me:
Si vous avez installé groff, vous le trouvez dans votre système de fichiers sous:\\
/usr/share/doc/groff\\
ou, si vous êtes sur une autre distribution, avec la fonction de recherche.\\
Pour aller plus loin avec -me, vous trouverez au même endroit meref.ps, qui est la reférence de -me [en].\\
Ouvrez les fichiers .ps simplement avec votre visionneur de documents ;-)


Ajouter l'option **-me** à votre commande groff.\\
(À partir d' ici, votre fichier s'appelle simplement "foo"):
<code>groff -me -k foo > foo.ps</code>




==== -ms====
Lettres, livres, rapports techniques.
Les requêtes -ms sont décrites au chapitre 5 de\\
[[http://oreilly.com/openbook/utp/|UTP]] [en].

Ajouter l'option **-ms** à votre commande groff:
<code>groff -ms -k foo > foo.ps</code>

====-mm====
Lettres, mémos, rapports techniques.
Les requêtes -mm soint décrites au chapitre 6 de\\
[[http://oreilly.com/openbook/utp/|UTP]] [en].

Ajouter l'option **-mm** à votre commande groff:
<code>groff -mm -k foo > foo.ps</code>


==== -man====

 Est spécialement conçu pour créer des pages man. Quelques liens utiles [fr]:
  *[[http://manpagesfr.free.fr/man/man7/man.7.html]]
  *[[http://www.linuxfocus.org/Francais/November2003/article309.shtml]]
  *[[http://manpages.ubuntu.com/manpages/lucid/fr/man7/man-pages.7.html]]
  *[[http://culot.org/public/Docs/manpage.html]]

Ajouter l'option **-man** à votre commande groff
<code>groff -man -k foo > foo.ps</code>

=====Premier exemple complet avec Mom=====

Nous allons maintenant utiliser de manière concrète le paquet Mom pour produire un .pdf. Groff est installé avec un certain nombre d'exemples que vous pouvez déjà consulter. Sous /usr/share/doc/groff-base/examples/mom/ se trouvent 4 examples:

  * letter.mom
  * mom-pdf.mom
  * sample_docs.mom
  * typesetting.mom

Notez également qu'un 5e exemple sera présent dans la prochaine version officielle de groff: mon_premier_doc.mom, un exemple en français pour le moment disponible dans les sources uniquement et qui servira de base à ce tutoriel.

Ces fichiers sont bien commentés et vous donnerons déjà de nombreuses indications sur comment formatter vos documents et résoudre vos problèmes typographiques (typesetting.mom) ou d'organisation générale du document (sample_docs.mom).  Notez que mom-pdf.mom est également un manuel expliquant le support dans Groff/Mom de liens clickable dans un fichier pdf.

Tout d'abord essayons de regénérer un de ces exemples:

  * Copier sample_docs.mom dans un répertoire de travail.
  * Exécutez:
<code>groff -Tpdf -mom sample_docs.mom > sample_docs.pdf</code>

Notez qu'il existe également le script pdfmom qui permet de simplifier encore l'utilisation de groff, par exemple pour gérer les documents avec liens clickables (voir les explications dans mom-pdf.mom) qui peuvent nécessiter plusieurs passes successives de groff, notamment si un lien clickable fait référence à quelque chose plus loin dans le texte. L'invocation de pdfmom est simple et ne nécessite pas de passer les options -Tpdf -mom:

<code>pdfmom sample_docs.mom > sample_docs.pdf</code>

Les exemples fournis sont très complets, voire complexes. Nous allons faire un exemple simple avec quelque éléments courants: des paragraphes, des listes, une table des matière, des liens clickables. Afin de remplir les pages de texte alors que l'inspiration nous manque, nous allons utiliser le fameux texte en faux latin Lorem Ipsum (http://fr.wikipedia.org/wiki/Faux-texte)..

Ouvrez votre éditeur préféré et commencez par copier les lignes suivantes dans un fichier mon_premier_doc.mom:
<code>
.\" -*- mode: troff; coding: utf-8; -*-
.TITLE "Mon Premier Document"
.AUTHOR "Cicéron"
.DOCTYPE    DEFAULT
.PRINTSTYLE TYPESET
.PAPER      A4
.START
</code>

La toute première ligne est un commentaire (qui peuvent débuter par .\" ou par \#) indiquant que le fichier est encodé en utf8, ce qui sera nécessaire à la génération du pdf du fait de la présence de caractère accentués (et donc non-ascii).

Nous n'avons rempli pour le moment que quelques champs obligatoires (placés avant la commande .START) pour définir l'auteur, le titre (qui peuvent être utilisés non seulement pour la mise en forme de la première page mais aussi pour les entêtes et pieds de page). La commande .DOCTYPE est inutile puisque nous avons choisi l'option par défaut, vous pouvez la changer en "LETTER" comme dans l'exemple letter.mom si votre document est une lettre, avec donc des réglages par défaut différents (pas d'entête ou de numéro de page par exemple).
.PRINTSTYLE est réglé à "TYPESET", ce qui est le réglage usuel pour un document, l'autre option étant TYPEWRITE qui fera un document de style "dactylographié, avec espace double".
Enfin .PAPER définit les dimensions du documents pour l'impression. Ce n'est qu'après la commande .START que l'on écrit le texte du document. Complétez abondamment par du "Lorem Ipsum". Puis tapez:

<code>pdfmom -k mon_premier_doc.mom > mon_premier_doc.pdf</code>

Notez l'utilisation de l'option -k pour gérer les caractères spéciaux (le é de Cicéron).  Si les options -mom et -Tpdf peuvent être omises, toutes les autres options devant être passées à groff peuvent être passées à pdfmom.

Rajoutons quelques éléments: des titres, des paragraphes, des listes, avec de copieux ajouts de textes (signalés ci-dessous par Lorem ipsum (...))

Rajoutez après .START:
<code>
.HEADING 1 "Les différentes versions"
.HEADING 2 "Version originale"
Lorem ipsum (...)
.PP
Lorem ipsum (...)
.PP
Lorem ipsum (...)
.HEADING 2 "Version moderne"
.PP
Lorem ipsum (...)
.PP
Lorem ipsum (...)
.HEADING 1 "Les évolutions du Lorem"
</code>

Quelques explications: .HEADING indique un titre de section, suivi par le niveau de ce titre comme argument (1 pour les titre de chapitre, 2 pour les sections, 3 pour les sous-sections etc...) et
enfin le titre à proprement parlé entre côtes. .PP sert à délimiter le début d'un nouveau paragraphe.

Vous aurez remarqué que les titres ne sont pas numérotés. Si vous souhaitez qu'ils le soient, vous pouvez rajouter les réglages suivants avant .START:
<code>
.HEADING_STYLE 1 NUMBER
.HEADING_STYLE 2 NUMBER
</code>

Poursuivons par l'ajout d'une liste. Les listes sont délimitées par les commandes
.LIST et .LIST OFF, chaque élément de la liste devant être défini par .ITEM.
Rajoutez par exemple après
<code>.HEADING 1 "Les évolutions"</code>
le code suivant:
<code>
.LIST
.ITEM
Lorem ipsum dolor sit amet.
.ITEM
Consectetur adipiscing elit.
.ITEM
Sed non risus.
.LIST OFF
</code>

Poursuivons par quelques raffinements supplémentaires. Vous aurez constaté que le document commence directement par la première page de texte et ne contient pas de couverture.
Nous pouvons changer cela en ajouter les 3 lignes suivantes avant .START:

<code>
.DOC_COVERTITLE "Mon Premier Document"
.DOC_COVER DOC_COVERTITLE
.COVER TITLE AUTHOR DOCTYPE
</code>

Il nous manque une table des matières avec des liens clickables. Ajouter:
<code>
.AUTO_RELOCATE_TOC
.TOC_HEADER_STRING "Table des matières"
</code>

avant .START, et:

<code>
.TOC_RV_SWITCH
.TOC
</code>
à la fin du document.

Si .TOC_HEADER_STRING est omis, mom mettra par défaut "Contents" en
titre de la table des matières, ce qui ne sied pas à notre document
franco-(faux)latin... En passant, corrigeons le "by" qui précède le nom de l'auteur en ajoutant:

<code>
.ATTRIBUTE_STRING "par"
</code>

toujours avant la commande .START.

Et pour finir nous allons rajouter dans le premier chapitre du texte et un lien clickable vers le deuxième chapitre. Commençons par changer le titre du deuxième chapitre en:

<code>
.HEADING 1 NAMED evolution "Les évolutions du Lorem"
</code>

Le paramètre après le champ NAMED est un identifiant qui peut être réutilisé dans d'autres parties du texte.
Rajoutez maintenant dans le premier chapitre:

<code>
Voir également le chapitre sur 
.PDF_LINK evolution "les évolutions".
possibles.
</code>

Et vous verrez qu'un lien clickable sur le second chapitre est apparu.

Dernière remarque: si vous téléchargez le fichier complet correspondant à cet exemple vous verrez que parfois des commentaires vides
(les symboles \# sur une ligne) ont été mis entre les paragraphes ou les têtes de sections. Ils n'ont d'autre but que d'améliorer la lisibilité du fichier .mom, en effet si vous ajoutiez une ligne blanche elle se retrouverait également sur le pdf généré.

Et voilà, ce premier exemple est terminé. Vous pouvez le trouver si vous récupérez les sources de groff:
<code>
git clone git://git.savannah.gnu.org/groff.git
</code>
dans contrib/mom/examples/mon_premier_doc.mom,
ou sinon vous pouvez naviguer directement dans l'arborescence du source code de groff via votre browser; cet exemple est récupérable à l'adresse suivante:
 http://git.savannah.gnu.org/cgit/groff.git/tree/contrib/mom/examples/mon_premier_doc.mom

Nous avons pu voir quelques éléments simple de composition d'un document mais également aperçu les vastes possibilités du paquet mom. Pour en savoir plus consulter le site officiel de Mom et les exemples fournis dans le paquet groff.

===== Intégrer des éléments graphiques =====

==== tableaux====
Vous pouvez inclure des tableaux à l'aide du logiciel tbl. Vous trouverez la documentation sur eqn à cette adresse\\
www.cs.bell-labs.com/10thEdMan/tbl.pdf [en]

ou au chapitre 8 de [[http://home.windstream.net/kollar/utp/utp-1.0.pdf|UTP]] [en]

<note tip>Pour séparer les colonnes, on utilise un caractère spécial tel que @, |, &...   pourvu qu'il ne soit pas utilisé à l'intérieur des cellules. Notez bien que c'est à vous de définir, en début de fichier, quel caractère va fonctionner comme tabulateur. Si par exemple, vous avez choisi @ , entrez \\
''tab (@);'' \\
au début du fichier d'entrée, tout de suite après ''.TS''.
</note>
Si vous avez utlisé tbl, ajoutez l'option **-t** à votre commande groff.
<code>groff -me -k -t foo > foo.ps</code>
Vous pouvez bien sûr remplacer -me par un autre paquet de macros.


==== formules de maths====

Vous pouvez inclure des formules mathémathiques dans  votre texte grâce au pré-processeur eqn. Son fonctionnement est expliqué dans ce document\\
www.kohala.com/start/troff/v7man/eqn/eqn2e.ps [en],\\
ou au chapitre 9 de[[http://home.windstream.net/kollar/utp/utp-1.0.pdf|UTP]] [en]

Si vous avez utlisé eqn, ajoutez l'option **-e** à votre commande groff.
<code>groff -me -k -e foo > foo.ps</code>


==== images====
===produire des images: pic===

Vous pouvez produire vous-même des images à l'aide du logiciel pic.
La doc se trouve sur votre machine dans le document pic.ps.gz sous /usr/share/doc/groff ou encore au chap. 10 de
[[http://home.windstream.net/kollar/utp/utp-1.0.pdf|UTP]] [en]

=== Intégrer une image ===

Pour  intégrer une image dans votre texte, il faudra tout d'abord la convertir au format .eps.

==En ligne de commande==
Sans rien installer:
<code>convert image.png image.eps</code>
vous pouvez remplacer .png par tout autre format d'image.
Placez l'image dans votre dossier personnel.

==Méthode graphique==
  - Installer ImageMagick.
  - Clic droit sur l'image.  "Ouvrir votre image avec ImageMagick".
  - Une fois l'image ouverte, cliquer dessus: Commands > Enhance > Map.
  - Choisir un nom pour l'image ainsi que le nouveau format (.eps).

Intégrez ensuite votre image au texte grâce à la requête ''.PSPIC'':\\
'' .PSPIC image.eps''.


Pour que groff tienne compte de votre image, le fichier image.eps devra être situé dans le répertoire personnel.

Souvent, il sera pratique d'inclure l'image dans un clos (keep) ou un bloc pour pouvoir la placer dans le texte avec précision.

Si vous avez eu recours à pic  ou à la requête ''.PSPIC'', ajoutez l'option **-p** à la commande groff:
<code>groff -me -k -p foo > foo.ps</code>

====musique====

===avec Lilypond===

Vous pouvez insérer quelques lignes de musique à votre texte. Lilypond doit être installé.

**Glilypond** est un script qui permet d'intégrer du code Lilypond dans un texte d'entrée groff.
Principe: glilypond prend tout le texte compris entre les requêtes
''.lilypond start'' et ''.lilypond end'' . Il en fait une image au format .eps, que vous pouvez placer dans votre fichier d'entrée de manière analogue à celles du sous-chapitre précédent.
 

Procédons par l'exemple:

<code>
asdf

.lilypond start
\version "2.16.2" 	# on commence par indiquer la version de lilypond utilisée

  \header {		# les lignes suivantes permettent de supprimer 
    footer = ""		# le "footer" de lilypond. Sans elles, lilypond place les  
    tagline = ""	# lignes de musique sur une page entière
  }			# avec une note en bas de page (footer).

  \paper {
    indent = 0
  }

  { c' e' g' e' }	# texte d'entrée lilypond
.lilypond end


Et voilà :-)
</code>

Copiez le code ci-dessus dans votre éditeur de texte, nommez le par exemple lyfoo et traitez le avec les 3 commandes suivantes:

<code>glilypond lyfoo > lyfoo1</code>
<code>groff -k lyfoo1 > lyfoo1.ps</code>

Vous ne pourrez pas ouvrir lyfoo1.ps avec votre visionneur de documents.
Ne vous en faites pas, la commande suivante fournit un pdf bien lisible lui.

<code>ps2pdf -dNOSAFER lyfoo1.ps</code>

Pour plus de détails, vous pouvez consulter la page man de glilypond:
 
<code>man glilypond</code>


==== formules chimiques====
Vous pouvez aussi intégrer à votre texte des formules chimiques.
Vous trouverez la documentation à cette adresse\\
http://cm.bell-labs.com/cm/cs/cstr/122.ps.gz [en]


Sur votre machine dans /usr/share/doc/groff/examples/chem, vous trouverez un tas d'exemples de fichiers d'entrée pour chem.

Si vous avez eu recours à  chem, ajoutez l' option **-j** à la commande groff:
<code>groff -me -k -j foo > foo.ps</code>


==== gremlin====

Ce logiciel sert surtout à dessiner des schémas électroniques. La seule documentation disponible à son sujet: man grn, ou alors
[[http://www.eecs.berkeley.edu/Pubs/TechRpts/1987/CSD-87-322.pdf|ici]]

Vous trouverez un exemple de fichier d'entrée et de sortie sous /usr/share/doc/groff/examples

Si vous avez eu recours à grn, ajoutez l' option **-g** à la commande groff
<code>groff -me -k -g foo > foo.ps</code>


=====Astuces groff =====

====Grouper les options====

Les logiciels décrits au chapitre précédent sont des préprocesseurs. Les options de la commande qui s'y rapportent peuvent être regroupées. Vous pouvez simplifier
<code>groff -me -k -p -t foo > foo.ps</code>
en
<code>groff -me -kpt foo > foo.ps</code>
Par contre, pas question d' y mêler en plus l'option principale (ici: -me).


====Identifier un fichier d'entrée: grog====

Si vous êtes en possession d'un fichier d'entrée et que vous ignorez les options permettant de le convertir en fichier de sortie, passez-le par la commande grog:
<code>grog foo</code>
Grog vous indique alors quelles options sont nécessaires à sa conversion.

 
====Conversion automatique: groffer====

La commande groffer convertit votre fichier d'entrée directement en .pdf:
<code>groffer foo</code>
Toutefois il n'active pas automatiquement l'option -k. Donc, pour un texte contenant des accents et des signes particuliers:
<code>groffer -k foo</code>
Groffer ne tient pas compte de certaines séquences d'échappement (par exemple ''\f I'').
Utilisez-le  avec des fichiers d'entrée ne contenant que des balises ordinaires (par exemple ''.ft I''), et en contrôlant avec soin le fichier de sortie. Groffer ne produit que du pdf, inutile d'exiger un autre format de sortie. Le pdf que vous obtenez n'est pas encore enregistré dans votre répertoire personnel.

====Autres formats de sortie===

Par défaut groff transforme un fichier d'entrée en sortie au format .ps.
C'est ce qu'il fera si vous oubliez de spécifier le format de sortie.
<code>groff foo > fo1</code>
fo1 sortira au format .ps, même cela n'est pas spécifié dans l'extension.

<note tip>Si vous donnez au fichier de sortie le même nom que le fichier d'entrée,
<code>groff foo > foo</code>
Groff ne fera rien, pour ne pas détruire votre travail de codage :-D.</note>

Vous pouvez aussi obtenir d'autres formats de sortie: principalement .pdf,  .dvi (le format de sortie de LaTeX) et .html (pour les pages web).
Pour ce faire, il ne suffit pas de changer l'extension du format de sortie, mais il faudra indiquer expressément le format de sortie  à l'aide des options -Tpdf, -Tdvi ou -Thtml.

Ainsi, si vous avec téléchargé meintro_fr.me, vous pouvez aisément le transformer en un document .html:
<code>groff -Thtml -me -k meintro_fr.me > meintro_fr.html</code>

Vous pouvez aussi transfomer ce même fichier d'entrée en .dvi
<code>groff -Tdvi -me -k meintro_fr.me > meintro_fr.dvi</code>
Ensuite, si vous avez LaTeX installé, vous pouvez transfomer ce .dvi en .ps à l'aide de dvips.
<code>dvips meintro_fr.dvi</code>
Et, après ce petit détour, vous retrouvez meintro_fr.ps dans votre répertoire personnel.

<note tip>Autrement dit:\\
 qui connait Groff produira aussi aisément du .dvi ou du .html ;-)</note>

====pdf====

Vous pouvez transformer votre fichier d'entrée directement en pdf.
<code>groff -me -kpt foo > foo.pdf</code>
Il faut simplement savoir que Adobe Reader ne lit pas ce genre de pdf, donc votre pdf ne pourra pas être lu sur un système Windows  8-O. \\
Il y a naturellement une astuce pour régler ce problème: commencez toujours par produire un fichier de sortie au fomat .ps. Vous le transformerez par la suite à l'aide de la commande ps2pdf14. Donc si votre fichier .ps s'appelle foo.ps
<code>ps2pdf14 foo.ps </code>
Et vous récupérez le .pdf dans votre répertoire personnel.



=====Utilisations particulières=====

==== dans le terminal ====
Les textes courts peuvent être tapés directement dans le terminal à l'aide de la commande **echo**.
<code>echo c'est beau la vie | groff > vie.ps</code>

Au lieu d'envoyer le texte sur un fichier .ps (ou autre), nous pouvons aussi en avoir un aperçu à l'aide de l'option -X (gxditview).
<code>echo c'est beau la vie | groff -X</code>

En cliquant gauche sur l'aperçu, nous pouvons diriger le fichier sur l'imprimante (choisir "print" puis "grops | lpr").

Nous pouvons aussi le diriger le texte directement sur l'imprimante:
<code>echo c'est beau la vie | groff -k | lp </code>
lp redirige le fichier sur l'imprimante.


La commande echo ne permet d'écrire qu'une seule ligne. Vous pouvez tester toutes les commandes ci-dessus avec un texte de plusieurs ligne en utilisant la commande **printf**. \\
 **\n** permet de spécifier que vous voulez un changement de ligne à tel endroit. Supprimez les **\n**, et groff écrira les 4 vers bout à bout sur une ligne.

<code>printf ' \n \n \n 
la jument de Michao\n 
et son petit poulain\n 
a passé dans le pré\n 
et mangé tout le foin' | groff -k > michao.ps</code>

Le terminal permet de faire des petits essais sur des textes courts, mais, comme il y est impossible de revenir à la ligne précédente, il ne permet pas de modifier un texte après coup.
Pour formater des textes plus longs nous avons besoin d'un [[éditeur de texte]].


====en console====

Ce que nous venons de faire dans le terminal vous à peut-être mis la puce à l'oreille: avec groff  nous sommes à même de formater des documents __sans interface graphique__  8-) 8-) 8-).

Comment? Ça ne vous tente pas :-O ?\\
Oubliez ce chapitre alors.

Si par contre  l'aventure vous tente, choisissez un des deux éditeurs de texte qui fonctionnent en [[console]]: [[nano]] ou [[vim]].


==nano==
En principe, nano est déjà installé sur Ubuntu.
Un apprentissage rapide est possible en lisant la doc [[nano]], ou en  regardant  la 2e moitié de [[http://www.tutoriels-video.fr/editer-un-fichier-en-mode-administrateur-sur-ubuntu|cette vidéo]].

Si vous êtes prêt(e), vous pouvez imprimer ce sous-chapitre, et rendez-vous en console par Ctrl+Alt+F1.

Après avoir renseigné les informations de login, lancer nano avec la commande
<code>nano</code> 

Se déplacer dans nano à l'aide des flèches.

Vous pouvez entrer par exemple les 4 petites lignes dans l'encadré ci-dessous:\\
(Commencer  par 3-4 lignes vides, pour que le texte soit bien cadré.)

<note tip>Dans un éditeur de texte, \n n'est plus de mise pour changer de ligne.  Si vous voulez rédiger quelques vers, commencez chaque ligne par un signe "espace", ou ajoutez ''.nf'' (=nofill mode) tout au début du texte</note>

<code> 

.nf
l'hiver viendra et quand
l'hiver viendra
la jument de Michao
elle s'en repentira</code> 

Ressortez de nano avec ctrl+x .

Enregistrez le fichier, comme demandé.

Nommez-le, comme demandé, par ex. "hiver".

Vous retrouvez le prompt où vous pouvez lancer la commande

<code>groff -k hiver | lp </code>

L' aperçu gxditview (par l'option -X) ne fonctionne évidemment pas en console. Le seul moyen de voir votre fichier de sortie est donc de l'imprimer.

Retour sur la session graphique par Ctrl+Alt+F7.

==vim==
Vim n'est pas installé par défaut sur Ubuntu.
Pour l'installer et apprendre à l'utiliser,  lisez la doc [[vim]], ou le chapitre 16 de
http://formation-debian.via.ecp.fr/.

Si vous êtes prêt(e). Imprimez ce sous-chapitre et rendez-vous en console par Ctrl+Alt +F1.

Après avoir renseigné les informations de login, lancez vim avec  la commande
<code>vim</code>
Par la touche "Insert" de votre clavier, vous accédez au mode INSERTION (confirmation en bas à gauche de l'écran).
Vous pouvez alors entrer votre texte. Si vous cherchez un exemple; reprenez les 4 lignes proposées pour nano ci-dessus.

Une fois le texte entré, retournez en mode commande par "Échap" (ou "Esc").

Enregistrez votre texte et nommez le avec **:w** nom_de_fichier. Par ex. "hiver".

Quittez vim avec **:q**. Vous retrouvez le prompt où vous pouvez entrer la commande groff:
<code>groff -k hiver | lp </code>

L'aperçu gxditview (par l'option -X) ne fonctionne évidemment pas en console. Le seul moyen de voir votre fichier de sortie est donc de l'imprimer.

Retour sur la session graphique par Ctrl+Alt+F7

<note>Nano et vim peuvent tout aussi bien être lancés dans le terminal. Dans ce cas, vous êtes en mode graphique et gxditview peut vous donner un aperçu de votre texte.</note>


=====Pour aller plus loin=====

La documentation officielle de groff:
[[http://www.gnu.org/software/groff/manual/html_node/index.html|Documentation officielle]] [en]
 
Les utilisateurs de groff se retrouvent et s'entraident sur la [[https://lists.gnu.org/mailman/listinfo/groff/|liste de distribution]].

Sans être abonné à la liste de distribution, on y trouvera de l'aide en fouillant ses [[https://lists.gnu.org/archive/html/groff/|archives]].

Pour apprendre à définir ses propres macros dans groff, lire le chapitre 14 de
[[http://oreilly.com/openbook/utp/|UTP]] [en]


=====Groff  l'ent=====

Comme vous avez pu le voir, groff est un logiciel qui se développe dans le long terme. Il est enraciné dans des logiciels plus anciens (RUNOFF, roff, troff...), mais aussi très ramifié, touffu, avec ses variantes -mom, -me, -ms, -mm,  -man, ses préprocesseurs (tbl, eqn ...) et ses logiciels auxiliaires (grog, groffer...) .

Il est accessible seulement à ceux qui sont prêts à lui consacrer assez de temps.

D'une extrème discrétion, n'apparaissant dans aucun menu déroulant, il se confond avec le paysage, et se contente de très peu de ressources. Néanmoins, c'est un outil très puissant.

Bref, il y en a bien assez pour nous faire penser aux  [[wpfr>Ent|ents]] de Tolkien.\\
On peut donc qualifier groff de logiciel entique  ;-) .


----
//Contributeurs principaux : [[hibou7]], Bertrand Garrigues (exemple d'utilisation de Mom).//