Introduction à Texinfo Benjamin Drieu (drieu@bocal.cs.univ-paris8.fr) v0.1 - 25 septembre 1997 Ce document est une introduction à Texinfo, le format de documentation adopté par GNU. Son but est de présenter Texinfo en quelques pages et de permettre de débuter dans ce format, en aucun cas fournir une docu­ mentation exhaustive sur le sujet. Si vous cherchez une documentation plus complète sur Texinfo (mais en langue anglaise) reportez vous au manuel fourni avec toute distribution de Texinfo, au format Texinfo, bien sûr :-). Vous trouverez l'ensemble des fichiers exemples de ce document sur le site web de l'association APRIL (http://www.april.org) à l'url http://www.april.org/Travaux/Doc/Tex­ info/. ______________________________________________________________________ Table of Contents: 1. Qu'est-ce que Texinfo ? 2. A quoi celà ressemble t'il ? 2.1. Petit exemple 2.2. Heu... là j'ai pas tout compris 2.3. Formattons ce document 2.3.1. Sortie papier 2.3.2. Sortie Info 3. Document plus complexe 3.1. Structure en noeuds 3.2. Exemple 3.3. Suite du document 3.4. Suite ... (références) 3.5. Et fin ! (Index et table des matières) 4. Mise en forme du document 4.1. Mise en forme de caractères 4.2. Caractères spéciaux 4.3. Mise en forme de paragraphes 5. Manuel "machine à café" complet 6. Copyright ______________________________________________________________________ 11.. QQuu''eesstt--ccee qquuee TTeexxiinnffoo ?? Vous avez une documentation à faire mais vous aimeriez qu'elle soit consultable sous forme hypertextuelle et en même temps qu'elle soit imprimable ? Vous n'aimez pas le _W_Y_S_I_W_Y_G ni le _l_o_o_k_-_a_n_d_-_f_e_e_l ? Vous trouvez les manuels de GNU sublimes ? Alors sans aucun doute, Texinfo est fait pour vous ! C'est un formateur de texte, massivement utilisé par GNU (tous les manuels GNU ou presque sont au format Texinfo), qui permet une sortie consultable par exemple sous Emacs à l'aide du mode _I_n_f_o ou imprimable avec l'aide de _T_e_X. 22.. AA qquuooii cceellàà rreesssseemmbbllee tt''iill ?? 22..11.. PPeettiitt eexxeemmppllee Voici un exemple minimal de fichier Texinfo. Il sera étoffé tout au long de ce document, et figurera en version complète à sa fin. L'exemple est traditionnel: c'est le manuel d'une machine à café. ______________________________________________________________________ \input texinfo @c -*-texinfo-*- @c %**start of header @setfilename cafe.info @settitle Manuel Machine @`a caf@'e @c %**end of header @titlepage @title Machine @`a caf@'e @subtitle v1.2 - 25 septembre 1997 @author Benjamin Drieu @end titlepage Ce manuel va vous expliquer comment utiliser la machine @`a caf@'e. @bye ______________________________________________________________________ 22..22.. HHeeuu...... llàà jj''aaii ppaass ttoouutt ccoommpprriiss Le principe d'un document Texinfo est qu'il est composé d'un en-tête, suivi du corps du document. Une ligne peut comporter une commande Texinfo qui commence toujours par '@', et peut comporter des arguments. Décortiquons ligne-à-ligne l'exemple ci-dessus: · charge les macros Texinfo lors du formatage par _T_e_X. Celà se fait par le chargement du fichier texinfo.tex au moment du formatage. Si vous voulez personnaliser la mise en page de vos documents Texinfo formatés (par exemple franciser les titres), vous pouvez éditer ce fichier qui est au format _T_e_X. · ligne de commentaire: tout ce qui est compris en '@c' et le caractère de fin de ligne ne sera pas formaté. Les commentaires destinés à Emacs. · spécifie le nom de fichier en sortie lors du formatage par _T_e_X (voir plus loin). · spécifie le titre du document · tout ce qui suit initialise la page de titre: on entre dans la section titlepage. · spécifie le titre de la page qui sera imprimé en page de couverture dans le cas d'un formatage par _T_e_X. · spécifie un sous-titre qui sera imprimé sur la page de couverture après le titre. Plusieurs sous-titres peuvent être spécifiés. · spécifie l'auteur du document. Plusieurs auteurs peuvent être spécifiés. · permet de sortir de la section titlepage pour revenir dans le corps du document. Les choses sérieuses peuvent commencer. · spécifie au formateur de textes de s'arrèter lorsqu'il rencontrera cette ligne. Remarquons l'insertion de commandes telles que '@`a' au milieu du texte. Ces commandes ont pour but d'insérer un caractère accentué à l'endroit ou elles se trouvent. 22..33.. FFoorrmmaattttoonnss ccee ddooccuummeenntt 22..33..11.. SSoorrttiiee ppaappiieerr Effectuer une sortie papier est relativement simple. Elle est faite par le biais de la commande texi2dvi puis de la commande dvips. L'appel de la commande texi2dvi est tout simplement : texi2dvi _f_i_c_h_i_e_r.texi Si tout s'est bien passé, un fichier _f_i_c_h_i_e_r.dvi a été créé dans le répertoire courant. Il s'agit d'un fichier au format dvi (_D_e_V_i_c_e _I_n_d_e_p_e_n_d_a_n_t), qui est une étape intermédiaire vers l'impression du document. L'étape suivante consiste à convertire ce fichier en PostScript, ce qui s'effectue par la commande : dvips _f_i_c_h_i_e_r.dvi -o_f_i_c_h_i_e_r.ps. Un fichier PostScript devrait être généré à partir du fichier l'appel de dvips sans les arguments -o_f_i_c_h_i_e_r.ps envoie directement le résultat à l'imprimante). Il existe de plus un programme visionneur de fichiers dvi : xdvi. 22..33..22.. SSoorrttiiee IInnffoo Le plus simple est d'ouvrir le fichier texinfo dans un buffer d'Emacs (voir http://www.april.org/Travaux/Doc/Html/emacs.html), puis d'effectuer un M-x texinfo-format-buffer. Ceci génèrera un nouveau buffer qui est la sortie _i_n_f_o de ce fichier. 33.. DDooccuummeenntt pplluuss ccoommpplleexxee 33..11.. SSttrruuccttuurree eenn nnooeeuuddss Un document Texinfo est généralement structuré comme un arbre: chacune des sections du document est un noeud qui possède un père et des fils. De plus, chaque noeud pointe vers le noeud suivant ainsi que le noeud précédent. Celà permet une navigation linéaire mais aussi par exemple en profondeur dans un chapitre. Un noeud est créé grâce à la commande '@node'. 33..22.. EExxeemmppllee ______________________________________________________________________ @c Noeud, Suivant, Précédent, Père @node Sommaire, , , (dir) @menu *Description:: Qu'est-ce qu'une machine à café ? *Utilisation:: Comment l'utiliser *Index:: Index du document @end menu ______________________________________________________________________ La première ligne est un commentaire destiné à rappeler quels sont les arguments passés à la commande '@node'. Le noeud Sommaire n'a pas de noeud suivant ou précédent. Ils sont donc laissés en blanc. Le père du noeud sommaire est (dir), c'est à dire la page Texinfo du système. Le document sera donc incorporé à l'arborescence _i_n_f_o du système. La commande '@menu' englobe une liste des noeuds "fils" du noeud Sommaire. Ici: Description, Utilisation, et Index. 33..33.. SSuuiittee dduu ddooccuummeenntt ______________________________________________________________________ @c Noeud, Suivant, Précédent, Père @node Description, Utilisation, Sommaire, Sommaire @chapter Ce qu'est une machine @`a caf@'e @cindex machine @`a caf@'e @cindex description @cindex caf@'e Une machine @`a caf@'e est un instrument complexe essentiel dans la vie d'un programmeur. Elle lui fournit de quoi survivre lors des heures de programmation, de la chaleur et de l'amiti@'e, et constitue l'@'epicentre de la vie sociale de tout d@'epartment informatique. ______________________________________________________________________ · _p_r_é_c_é_d_e_n_t, _p_è_r_e' cette commande spécifie le noeud courant et ses liens. · cette commande crée un nouveau chapitre. Elle n'a un effet que dans la version du manuel formatée avec _T_e_X. Les commandes '@section _n_o_m _d_e _s_e_c_t_i_o_n' et '@subsection _n_o_m _d_e _s_e_c_t_i_o_n' ont un effet approchant: elles créent une nouvelle section ou sous-section. · cette commande ajoute une entrée dans l'index conceptuel avec un lien vers le noeud courant. D'autres index peuvent être utilisés en changeant de commande: · @vindex: index des variables · @findex: index des fonctions · @kindex: index des clefs · @pindex: index des programmes · @dindex: index des types de données 33..44.. SSuuiittee ...... ((rrééfféérreenncceess)) ______________________________________________________________________ @c Noeud, Suivant, Précédent, Père @node Utilisation, Index, Description, Sommaire @chapter L'utilisation de la machine @`a caf@'e @cindex utilisation de la machine @`a caf@'e @cindex obtention d'un caf@'e L'utilisation d'une machine @`a caf@'e est relativement simple. L'obtention d'un caf@'e se fait par l'introduction d'une pi@`ece de monnaie suivie de la pression de la touche "cafe". @xref{Description} pour plus d'informations sur une machine @`a caf@'e. ______________________________________________________________________ L'insertion d'une référence se fait par le biais de trois commandes: · cette commande génère une référence au noeud spécifié en argument. Dans la version Info, un lien hypertexte sur le texte passé en argument emmènera au noeud spécifié. Dans la version formatée par _T_e_X, une phrase de la forme "See section _s_e_c_t_i_o_n, page _p_a_g_e" sera générée. Si vous préférez une version française, vous devriez éditer le fichier texinfo.tex fournit avec la distribution de Texinfo. Vous pouvez éventuellement modifier le texte inséré dans le fichier _i_n_f_o ou formaté par _T_e_X en passant des arguments suplémentaires à la commande '@xref'. La syntaxe est alors: '@xref{ _n_o_e_u_d, _d_e_s_c_r_i_p_t_i_o_n _p_o_u_r _I_n_f_o, _d_e_s_c_r_i_p_t_i_o_n _p_o_u_r _T_e_X}'. La _d_e_s_c_r_i_p_t_i_o_n _p_o_u_r _I_n_f_o apparaîtra dans le fichier _i_n_f_o généré, et _d_e_s_c_r_i_p_t_i_o_n _p_o_u_r _T_e_X dans le fichier formaté par _T_e_X. Il est possible de laisser n'importe lequel de ces deux arguments vide. Vous pouvez de plus faire référence à un autre manuel _I_n_f_o en ajoutant un quatrième argument qui sera le nom de ce manuel. · le comportement de cette commande est le même que celui de la précédente, hormis que la phrase générée commence par une mot en minuscules (see), et finit par un point dans la version _i_n_f_o). · info, _n_o_m _d_u _f_i_c_h_i_e_r}' cette commande fait spécifiquement référence à un fichier _I_n_f_o, y compris dans la version formatée par _T_e_X. Dans le format formaté par _T_e_X, cette référence sera de la forme "See Info file '_n_o_m _d_u _f_i_c_h_i_e_r 'node 33..55.. EEtt ffiinn !! ((IInnddeexx eett ttaabbllee ddeess mmaattiièèrreess)) ______________________________________________________________________ @c Noeud, Suivant, Précédent, Père @node Index, , Utilisation, Sommaire @unnumbered Index conceptuel @printindex cp @shortcontents @contents @bye ______________________________________________________________________ · cette commande agit comme la commande @'chapter: elle génère une entrée dans la table des matières et crée une page de chapitre pour l'index. · cette commande imprime l'index spécifié par un code de deux lettres. Ces deux lettres peuvent être: · cp: index conceptuel · vr: index des variables · fn: index des fonctions · ky: index des clefs · pg: index des programmes · tp: index des types de données · cette commande génère une brève table des matières, qui ne contient que les chapitres et les appendices. Seuls les gros manuels peuvent avoir besoin de cette commande. · cette commande génère une table des matières complète à partir des commandes '@chapter', '@section', et · cette commande dit poliment _a_u _r_e_v_o_i_r à Texinfo. Son but est de spécifier à _T_e_X ou _I_n_f_o que le document est terminé. 44.. MMiissee eenn ffoorrmmee dduu ddooccuummeenntt 44..11.. MMiissee eenn ffoorrmmee ddee ccaarraaccttèèrreess Texinfo permet de mettre en forme des caractères du document. Il y parvient au moyen de commandes dont l'argument est le texte à mettre en forme, tout comme _T_e_X. Parmis ces commandes, les plus courantes sont: · le texte passé en argument sera formaté comme étant un code source. La police de ce texte sera une police de type _c_o_u_r_i_e_r dans le cas d'un formatage par _T_e_X, et entourée par des guillemets dans le cas d'un fichier _I_n_f_o. · le texte passé en argument sera formaté comme étant un exemple, typiquement en italiques. · le texte passé en argument est le nom d'un fichier. · le texte passé en argument est une séquence de touches tapée au clavier. · le texte passé en argument est un caractère de contrôle ASCII. Par exemple, '@ctrl{C}' produit '^C'. · le texte passé en argument est est un terme technique. · le texte passé en argument est mis en italique dans le manuel formaté par _T_e_X. · le texte passé en argument est mis en gras dans le manuel formaté par _T_e_X. · le texte passé en argument est mis en police _c_o_u_r_i_e_r dans le manuel formaté par _T_e_X. 44..22.. CCaarraaccttèèrreess ssppéécciiaauuxx Certains caractères tels qu'@ ont une signification pour Texinfo, ou ne peuvent pas être entrés au clavier. Il existe des séquences spéciales pour les produire: · · · · un rond est produit '@bullet{}' · · · · · · · 44..33.. MMiissee eenn ffoorrmmee ddee ppaarraaggrraapphheess Texinfo permet de mettre en page des paragraphes afin de forcer les sauts de ligne ou au contraire empecher du texte de passer à la page. · avec _T_e_X, mais pas dans le manuel _I_n_f_o. · avec _T_e_X ainsi que dans le fichier _I_n_f_o. · saut de ligne dans le texte passé en argument. Cette commande n'a aucun effet dans le cas d'un manuel _I_n_f_o. · manuel formatée avec _T_e_X. · 55.. MMaannuueell ""mmaacchhiinnee àà ccaafféé"" ccoommpplleett Vous trouverez le manuel "machine à café" complet au format Texinfo, html, et PostScript sur le site web d'APRIL à l'url http://www.april.org/Doc/Texinfo/. ______________________________________________________________________ \input texinfo @c On commence l'en-tête @setfilename cafe.info @settitle Manuel Machine @`a caf@'e @c Fin de l'en-tête @titlepage @title Machine @`a caf@'e @subtitle v1.2 - 25 septembre 1997 @author Benjamin Drieu @end titlepage @c Noeud, Suivant, Précédent, Père @node Sommaire, , , (dir) @menu *Description:: Qu'est-ce qu'une machine à café ? *Utilisation:: Comment l'utiliser *Index:: Index du document @end menu @c Noeud, Suivant, Précédent, Père @node Description, Utilisation, Sommaire, Sommaire @chapter Ce qu'est une machine @`a caf@'e @cindex machine @`a caf@'e @cindex description @cindex caf@'e Une machine @`a caf@'e est un instrument complexe essentiel dans la vie d'un programmeur. Elle lui fournit de quoi survivre lors des heures de programmation, de la chaleur et de l'amiti@'e, et constitue l'@'epicentre de la vie sociale de tout d@'epartment informatique. @c Noeud, Suivant, Précédent, Père @node Utilisation, Index, Description, Sommaire @chapter L'utilisation de la machine @`a caf@'e @cindex utilisation de la machine @`a caf@'e @cindex obtention d'un caf@'e L'utilisation d'une machine @`a caf@'e est relativement simple. L'obtention d'un caf@'e se fait par l'introduction d'une pi@`ece de monnaie suivie de la pression de la touche "cafe". @xref{Description} pour plus d'informations sur une machine @`a caf@'e. @c Noeud, Suivant, Précédent, Père @node Index, , Utilisation, Sommaire @unnumbered Index conceptuel @printindex cp @shortcontents @contents @bye ______________________________________________________________________ 66.. CCooppyyrriigghhtt Ce document est placé sous copyright © 1997 de Benjamin Drieu, association APRIL. Ce document peut être reproduit et distribué dans son intégralité ou partiellement, par quelque moyen physique que ce soit. Il reste malgré tout sujet aux conditions suivantes : · La mention du copyright doit être conservée, et la présente section préservée dans son intégralité sur toute copie intégrale ou partielle. · Si vous distribuez ce travail en partie, vous devez mentionner comment obtenir une version intégrale de ce document et être en mesure de la fournir.