Frozen Fish 1: Amiga/FrozenFish-Apr94.iso/bbs/alib/d5xx/d583/aroff.lha/ARoff/Sources/aroff.doc.src

Text File | 1992-01-04 | 20KB | 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).