Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 608b.lha / ARoff / Sources.LZH / Sources / aroff.doc.src < prev next >

Wrap

Text File | 1992-01-06 | 19.5 KB | 609 lines

.ll 76 .lt 76 .pl 66 .nh \" numéro de paragraphe (registre) .nr PN 0 1 \"------------- début de paragraphe .de PR .nf .ne 5 .fs u1 \\n+(PN. \\$1 .fs n .fi .. \"------- description d'une requête .de RQ .ne 3 .ti -4 \\$1 \\$2 .br Syntaxe\\ \\ \\ \\ \\ :\\ \\$1 \\$3 .br Description\\ :\\ \\ .. .de SP .br .ti -16 .. \" entête de page .de HD .ls 2 .tl "ARoff"Manuel de référence"Page \\n(pn" .ls 1 .. \"-------- début de note importante .de NI .ne 4 .ce NOTE IMPORTANTE : .in 8 .ll -8 .. \"---------- fin de note importante .de FN .in .ll .. .wh 1 HD \"--------------------------- TEXTE .PR Avertissement .ti +8 Ce manuel décrit la version 1.12 de l'utilitaire ARoff. Ce programme est placé dans le domaine public, avec autorisation de le copier librement et de le diffuser par n'importe quels moyens, à condition que le produit soit diffusé dans son intégralité, et sans aucune modification. ARoff est (c)1991 par Denis GOUNELLE, toute utilisation commerciale ou vente de ce programme sans autorisation écrite est STRICTEMENT INTERDITE. .ti +8 Malgré de nombreux tests, je ne peux garantir qu'ARoff ne contient aucune erreur. VOUS UTILISEZ CE PROGRAMME A VOS RISQUES ET PERILS. Je ne pourrai en aucun cas être tenu responsable de tout dommage, direct ou indirect, résultant de l'utilisation d'ARoff. .PR Introduction .ti +8 ARoff est un programme de formatage de texte puissant et complet, avec registres, macros, etc... : il prend en entrée un fichier comprenant à la fois le texte et les commandes de formatage, et produit en sortie le texte mis en page comme vous l'avez demandé. .ti +8 ARoff peut être considéré comme une sorte de portage de l'utilitaire "nroff", que l'on trouve habituellement sous système UNIX. Les deux programmes sont cependant assez différents, et il y a sûrement beaucoup de choses que ARoff ne sait pas faire. .ti +8 La syntaxe d'appel de ARoff est la suivante : .ce aroff [-wpile] [-l] <nom de fichier> <nom de fichier> est le nom du fichier que vous voulez traiter. Si vous indiquez "-" comme nom, l'entrée standard sera utilisée. .NI La version actuelle de ARoff ne peut fonctionner correctement si elle est utilisée en sortie de pipe (e.g. "cat toto | aroff -"). .FN .br .ti +8 L'option -w vous permet d'augmenter la taille de la pile de travail allouée par ARoff. Par défaut cette taille est de 256 emplacements de 8 octets chacun, mais il peut arriver que cela ne suffise pas : vous obtiendrez alors un message "Error 2 in file pile.c at line 58". Pour faire passer la taille de la pile à 300 emplacements (par exemple), appelez ARoff par "aroff -w300 <nom de fichier>". .ti +8 Si vous indiquez l'option -l, le fichier d'entrée sera chargé entièrement en mémoire avant d'être traité. Sur Amiga, ceci peut rendre le traitement deux à trois fois plus rapide dans certains cas, mais est à déconseiller si vous avez peu de mémoire libre. .ti +8 Si vous appelez ARoff sans arguments (ou avec des arguments incorrects) vous obtiendrez un message indiquant la version du programme et la syntaxe à respecter pour les arguments. .PR Principe\ de\ fonctionnement .ti +8 Comme "nroff", ARoff assemble automatiquement les lignes de texte pour obtenir une ligne suffisamment longue. Cela veut dire que votre texte est vu comme une suite de mots que ARoff se contente de recopier, jusqu'à ce que la taille d'une ligne de sortie soit atteinte, ou que vous provoquiez la fin de l'assemblage (soit par une requête, soit par une ligne vide). Les requêtes suivantes provoquent automatiquement une fin de l'assemblage : .nf .in 16 bp\tnouvelle page br\tnouvelle ligne ce\tcentre la(les) ligne(s) suivante(s) fi\tactivation du mode "assemblage" nf\tdésactivation du mode "assemblage" sp\tsaut de ligne in\tindentation ti\tindentation temporaire .in .fi .ti +8 Une fois cette ligne assemblée, ARoff effectue un ajustement, suivant le mode que vous avez indiqué : centrage, justification, cadrage à droite ou à gauche. Le résultat constitue une ligne de sortie. .ti +8 Les commandes de formatage (ou requêtes) doivent être indiquées sur une ligne à part, commençant par un point. Le nom de la requête suit immédiatement, et fait exactement deux caractères. Viennent ensuite les arguments éventuels de la requête. Pour utiliser une des requêtes ci-dessus sans provoquer de fin d'assemblage, utilisez le caractère "quote simple" à la place du point (e.g. : "'ti -3" au lieu de ".ti -3"). .PR Liste\ des\ requêtes\ courantes .ti +8 Dans tout ce qui suit, N désigne un entier positif, et ±N désigne soit un entier positif (spécification d'une valeur précise), soit le signe plus suivi d'un entier positif (spécification d'une incrémentation), soit enfin le signe moins suivi d'un entier positif (spécification d'une décrémentation). .in 8 .RQ ab ABort message affiche le message indiqué, vide le tampon de sortie et termine. .RQ ad ADjust [mode] change le mode d'ajustement des lignes. Si vous n'indiquez pas d'argument, la valeur précédente est reprise. Les valeurs de mode sont : .nf \tl\tcadrage à gauche \tr\tcadrage à droite \tc\tcentrage \tb\tjustification .fi .RQ bp Begin\ Page [N] provoque un saut de page. La page suivante aura le numéro N si un argument est indiqué. .RQ br BReak provoque un saut de ligne. L'assemblage de la ligne courante est interrompu, et cette ligne est imprimée sans ajustement. .RQ ce CEnter [N] centre la ligne suivante, ou les N lignes suivantes si un argument est indiqué. .RQ ex EXit vide le tampon de sortie et termine. .RQ fi FIll active l'assemblage des lignes. .RQ fs Font\ Style style modifie le style des caractères. La chaine "style" est une combinaison quelconque des spécifications suivantes : .nf \tb0\tfin de caractères gras \tb1\tdébut de caractères gras \ti0\tfin de caractères italiques \ti1\tdébut de caractères italiques \tu0\tfin de caractères soulignés \tu1\tdébut de caractères soulignés \tn\tretour aux caractères normaux .fi .RQ in INdent [±N] change la marge gauche. Sans argument, la valeur précédente est reprise. .RQ ll Line\ Length [±N] change la longueur des lignes de sortie (indentation comprise). Sans argument, la valeur précédente est reprise. .RQ ls Line\ Spacing [±N] change l'espacement des lignes de sortie. Sans argument, la valeur précédente est reprise. .RQ lt Title\ Length [±N] change la longueur du titre (voir requête "tl"). Sans argument, la valeur précédente est reprise. .RQ na No\ Adjusting désactive l'ajustement des lignes en sortie. .RQ ne NEed [N] provoque un saut de page s'il reste moins de N lignes (1 si aucun argument n'est indiqué) avant la fin de la page ou la prochaine trappe. .RQ nf No\ Filling désactive l'assemblage des lignes. .RQ nm line\ NuMbering [±num\ int\ spc\ idt] active la numérotation des lignes. La numérotation commence au numero "num", et se fera toutes les "int" lignes (1 par défaut). Il y aura "spc" espaces (1 par défaut) entre les numéros et le texte, et "idt" espaces (0 par défaut) entre la marge et les numéros. Sans arguments, la numérotation est désactivée. Un argument non numérique est considéré comme manquant. Un argument manquant n'est pas modifié. .RQ nn No\ line\ Numbering [N] ne numérote pas les N lignes suivantes, ou la ligne suivante si aucun argument n'est indiqué. .RQ pl Page\ Length [±N] change le nombre de lignes par page. Sans argument, la valeur par défaut est reprise. .RQ pn Page\ Number ±N change le numéro de la prochaine page. .RQ po Page\ Offset [±N] change la marge gauche pour tout le document (différent de l'indentation). Sans argument, la valeur précedente est reprise. .RQ so SOurce fichier insère le contenu du fichier indiqué. .RQ sp SPace [N] insère N (1 par défaut) lignes blanches. .RQ ta TAbulation N positionne les arrêts de tabulations aux colonnes 1, N+1, 2N+1, etc... .RQ tc Tab\ Character [c] indique le caractère à utiliser lors de l'extension des tabulations. Sans argument, la valeur par défaut est reprise. .RQ ti Temporary\ Indent N indente la ligne suivante de la valeur indiquée. .RQ tl TitLe 'a'b'c' imprime un texte en trois parties : "a" est cadré à gauche, "b" est centré, et "c" est cadré à droite. N'importe quel caractère peut être utilisé pour séparer les trois parties, et une ou deux parties peuvent être vides. .RQ tm Terminal\ Message message affiche le message indiqué. .RQ tr TRanslate abcd... indique une conversion en sortie : a est changé en b, c est changé en d, etc... Si un nombre impair de caractères est indiqué, le dernier sera changé en un espace. .RQ ts Title\ Style str indique le style de caractères du titre. "str" est n'importe quelle combinaison de : .nf \tb\tpassage en gras \ti\tpassage en italiques \tu\tpassage en souligné .fi .in .PR Le\ format\ des\ lignes .ti +8 ARoff reconnait les constructions suivantes : .fi .in 24 .SP \\t\t\ttabulation .SP \\<espace>\tespace fixe .SP \\<newline>\tretour à la ligne à ignorer .SP \\"\t\tle reste de la ligne est un commentaire .SP \\!\t\tle reste de la ligne est à lire sans aucune interprétation, et à envoyer sur la sortie sans ajustement (ne peut être utilisé qu'en début de ligne) .SP \\n\t\tinsérer la valeur d'un registre .SP \\*\t\tinsérer la valeur d'une chaine .in Il vous est très vivement conseillé de ne pas mettre de tabulations dans votre texte : utilisez plutôt la séquence "\\t". .ti +8 Les registres permettent de stocker des valeurs numériques entières. On manipule les registres à l'aide des requêtes suivantes : .in 8 .RQ nr New\ Register nom\ val\ [inc] crée le registre "nom" et lui donne la valeur initiale "val". Si l'argument "inc" est indiqué, il est mémorisé comme valeur de l'incrément du registre. Le nom peut faire un ou deux caractères. Les arguments "val" et "inc" sont des entiers positifs. .RQ rr Remove\ Register nom détruit le registre "nom". .in L'utilisation des registres se fait de la manière suivante : .nf .in 8 \\nx\tinsère la valeur du registre x \\n+x\tincrémente puis insère la valeur du registre x \\n-x\tdécrémente puis insère la valeur du registre x \\n(xx\tinsère la valeur du registre xx \\n+(xx\tincrémente puis insère la valeur du registre xx \\n-(xx\tdécrémente puis insère la valeur du registre xx .ti -8 Les registres suivants sont pré-définis par ARoff : dw\tjour de la semaine (1 à 7) dy\tjour du mois (1 à 31) mo\tmois (1 à 12) yr\tannée (deux chiffres) hr\theure (0 à 23) mn\tminutes (0 à 59) sc\tsecondes (0 à 59) pn\tnuméro de la page courante (en sortie) il\tnuméro de la ligne courante (en sortie) ol\tnuméro de la ligne courante (en entrée) .fi .in Notez que les registres donnant la date et l'heure sont initialisés une fois pour toutes lors de l'initialisation de ARoff, et ne sont pas mis à jour par la suite. .ti +8 Les chaines permettent de stocker des chaines de caractères d'au plus 255 caractères. On manipule les chaines à l'aide des requêtes suivantes\ : .in 8 .RQ ds Define\ String nom\ chaine crée une chaine de nom indiqué, et lui affecte la valeur "chaine". Pour conserver les espaces en début de chaine, il suffit de mettre un guillemet avant le premier espace. Le nom peut faire un ou deux caractères. Si la chaine "nom" existe déjà, ARoff se contente de changer sa valeur. .RQ as Append\ String nom\ chaine ajoute la chaine indiquée à la chaine "nom". Cette chaine est créée si elle n'existe pas. Pour conserver les espaces en début de chaine, il suffit de mettre un guillemet avant le premier espace. .RQ rs Remove\ String nom détruit la chaine indiquée. .in Les chaines s'utilisent de la manière suivante : .in 8 \\*x\tinsère la valeur de la chaine x .br \\*(xx\tinsère la valeur de la chaine xx .in La chaine "fn" est définie automatiquement par ARoff, et contient le nom du fichier en cours de traitement. .PR Les\ macros .ti +8 Les macros permettent de stocker et de rappeler facilement une serie de requêtes et/ou un grand morceau de texte. On manipule les macros à l'aide des requêtes suivantes : .in 8 .RQ de DEfine\ macro nom commence la définition de la macro "nom". Si cette macro existe déjà, son contenu est effacé. Les lignes suivantes sont mémorisées en tant que définition, jusqu'à ce qu'une ligne commence par ".." (deux points). .RQ am Append\ to\ Macro nom ajoute les lignes suivantes (jusqu'à ce qu'une ligne commence par "..") à la définition de la macro "nom". Si cette macro n'existe pas, elle est créée. .RQ rm Remove\ Macro nom détruit la macro indiquée. .RQ pm Print\ Macro [macro] affiche la définition de la macro indiquée, ou de toutes les macros si aucun argument n'est spécifié. .in L'appel d'une macro se fait exactement de la même manière qu'une requête\ : un point en début de ligne, suivi du nom de la macro. On peut passer au plus neuf arguments à une macro. Ils sont accessibles dans la définition par \\$1, \\$2, ... \\$9. Le nombre d'arguments peut être connu en consultant le registre ".$". Le séparateur d'arguments est l'espace. Si vous voulez passer un argument comprenant un espace, ajoutez un "\\" devant cet espace. Si vous voulez passer un argument comprenant un espace fixe, ajoutez trois "\\" devant cet espace. .NI Lors de la lecture de la définition d'une macro, le texte est interprété de la même façon que d'habitude. Pensez donc à doubler les "\\" devant les appels de registres, de chaines ou d'arguments, si vous voulez différer leur interprétation à l'exécution de la macro. .FN Contrairement à "nroff", il est d'interdit d'inclure une requête ".de" ou ".am" dans une définition de macro. L'appel d'une macro par une autre est possible. .PR Les\ trappes .ti +8 Les trappes permettent de déclencher l'exécution d'une macro à une certaine position verticale dans la page. C'est avec ce mécanisme que l'on peut ajouter une en-tête ou un pied-de-page. On manipule les trappes à l'aide des requêtes suivantes : .in 8 .RQ wh WHen ligne\ nom place une trappe à la ligne indiqué. La macro exécutée sera la macro "nom". S'il y avait déjà une trappe à cette position, ARoff se contente de changer le nom de la macro à exécuter. Si "ligne" est négatif, il s'agit d'une position relative à la fin de la page. Si "ligne" est nul, la trappe est déclenchée en fin de page. .RQ rt Remove\ Trap ligne enlève la trappe placée à la ligne indiquée. .NI Dans la version actuelle de ARoff, la trappe de fin de page n'est jamais déclenchée sur la dernière page de texte. .FN .in 0 Lorsque ARoff est sur le point d'écrire une ligne, il regarde si une trappe est placée sur cette ligne. Si oui, il appelle la macro indiquée avant de tenter à nouveau d'écrire la ligne. Ce fonctionnement permet le déclenchement en cascade de trappes placées sur des lignes consécutives. .PR Les\ conditions .ti +8 ARoff permet de rendre conditionnelle l'exécution d'une requête ou d'une macro, ou bien encore l'insertion d'une portion de texte. On manipule les conditions à l'aide des requêtes suivantes : .in 8 .RQ if If cond\ reste Ignore le reste de la ligne si la condition n'est pas verifiée. .RQ el Else reste Ignore le reste de la ligne si la condition testée par le "if" précédent était verifiée. La requête "el" doit suivre IMMEDIATEMENT la requête "if". .in Le format des conditions est le suivant : .nf \to\t\tla page courante est de numéro impaire \te\t\tla page courante est de numéro pair \tn\t\tle formateur est "nroff" (toujours vrai) \tt\t\tle formateur est "troff" (toujours faux) \t'ch1'ch2'\tla chaine 'ch1' est identique à la chaine 'ch2' \tN<M\t\tl'entier N est inférieur à l'entier M \tN>M\t\tl'entier N est supérieur à l'entier M \tN=M\t\tl'entier N est égal à l'entier M .fi On peut inverser une condition, en la faisant précéder par un point d'exclamation "!". Les arguments des tests peuvent bien entendu être des registres ou des chaines. Voici quelques exemples : .nf .in 8 \!.if o .tl 'Entete de page impaire''\n(pn' \!.el .tl 'Entete de page paire''\n(pn' \!.if '\*(fn'macros' le fichier macros \!.el un autre fichier \!.\" Saut de page si la ligne d'entrée est > 56 \!.if \n(il>56 .bp .in .fi .PR Divers .ti +8 Les registres et les chaines sont insérés dans le texte au fur et à mesure de sa lecture. On peut utiliser un registre ou une chaine comme argument d'une requête. Un registre inconnu a une valeur égale à zéro, une chaine inconnue est remplacée par une chaine vide. Une requête inconnue entrainera la recherche d'une macro. L'appel d'une macro non définie sera ignoré. .ti +8 A la différence de "nroff", les registres, chaines et macros sont conservés dans des listes différentes. Cela veut dire que vous pouvez donner le même nom à un registre, à une chaine et à une macro : il n'y aura aucune confusion. Par contre, comme la liste des requêtes est parcourue avant la liste des macros, si une macro et une requête ont le même nom, c'est la requête qui sera exécutée. .nf Voici la liste des codes d'erreurs indiqués par ARoff : .in 16 0\terreur interne 1\tpile vide 2\tpile pleine 3\terreur de syntaxe 4\tdébordement de table ou de tampon 5\touverture de fichier impossible 6\targuments incorrects 7\terreur d'écriture 8\tplus de mémoire libre 9\trequête "el" non précédée par une requête "if" 10\timpossible de se déplacer dans le fichier 11\terreur de lecture dans le fichier à traiter 12\tle fichier à traiter est vide .in Voici les valeurs par défaut des paramètres de mise en page : .in 16 ajustement\t\tad\tb indentation\t\tin\t0 longueur des lignes\tll\t80 espacement des lignes\tls\t1 longueur des titres\tlt\t80 longueur des pages\tpl\t66 numero de page\t\tpn\t1 marge gauche\t\tpo\t0 tabulation\t\tta\t8 caractere tabulation\ttc\tespace .in .fi .ti +8 Vous pouvez me faire part de vos remarques ou critiques sur ce programme, en écrivant à l'adresse suivante : .ne 4 .ce 4 M. GOUNELLE Denis Boite 71 6, rue des cailloux 92110 CLICHY - FRANCE .ti +8 ARoff a été développé presque entièrement sous système UNIX, puis recompilé sur Amiga avec l'Aztec C 3.6a. Les fichiers sources sont fournis (il n'y a pas beaucoup de commentaires, désolé !), avec les "makefile" pour Unix et pour Aztec. Ce programme devrait pouvoir être compilé sans trop de problèmes par n'importe quel compilateur C. Les parties spécifiques au compilateur Aztec C sont placées entre "#ifdef". .PR Historique .in 8 .ti -8 v1.00\t06-Sep-91, 22144 octets .br Première version diffusée. .ti -8 v1.01\t20-Oct-91, 22524 octets .br Ajout de la requête "fs". .br Ajout de la chaine "$VER:" pour la commande Version (OS 2.0). .ti -8 v1.02\t11-Nov-91, 22736 octets. .br Ajout de la requête "ts". .br Correction d'une erreur dans la numérotation des pages (commençait à 2 au lieu de 1). .ti -8 v1.03\t13-Nov-91, 22896 octets .br Plusieurs optimisations (6% plus rapide d'après "prof", consomme moins de mémoire). .ti -8 v1.10\t14-Nov-91, 24020 octets .br La pile interne est maintenant allouée correctement : depuis le début on allouait (TaillePile * 2) octets au lieu de (TaillePile * 8), d'où des plantages avec de gros fichiers sources. .br Ajout des requêtes "if" et "el". .br La fonction Pop() ne dépilait jamais le dernier élément (s'arrêtait quand SP valait 1, au lieu d'aller jusqu'à 0). .br La fonction myalloc() alloue toujours un nombre pair d'octets (pour éviter des problèmes d'alignement), et vérifie qu'on essaye pas d'allouer 0 octets. .br La fonction LigneSuiv() n'allouait pas assez de place pour stocker la ligne en cours en cas de trappe (il manquait un octet pour l'octet nul à la fin). .br Lorsqu'on utilise la requête "so", n'oublie plus de revenir au fichier précédent en fin de fichier. .br N'oublie plus l'indentation quand une ligne commence par \\!. .ti -8 v1.11\t27-Nov-91, 24028 octets .br La fonction SetMacArgs() n'allouait pas assez de place pour les arguments des macros (il manquait un octet pour l'octet nul à la fin). .br [Erreur détectée et corrigée grâce à l'aide de Michel SCHINZ] .ti -8 v1.12\t29-Nov-91, 24828 octets .br Ajout de l'option -l (charge le fichier en mémoire) qui permet de rendre le traitement deux à trois fois plus rapide dans certains cas (166% à 280% constatés sur mon A500).