commit 87fa288d6514b18d4940cd8e85715ade6196d07d
parent b448541fa8f4af5c2fe232827589a0c5db1b8756
Auteur: Selve <selve@asteride.xyz>
Date: Thu, 4 Apr 2024 15:35:07 -0400
mise à jour de la documentation
Diffstat:
5 files changed, 86 insertions(+), 66 deletions(-)
diff --git a/LISEZ-MOI.txt b/LISEZ-MOI.txt
@@ -35,7 +35,7 @@ Compiler le programme :
$ make
Notez que dans certains systèmes, libintl est incluse dans libc. Dans ce cas, il
-faut retirer -lintl de la variable LIBS.
+faut retirer -lintl de la variable LIBS de la Makefile.
Installer le programme, avec les pages du manuel et les traductions des messages
du programme :
@@ -44,8 +44,10 @@ du programme :
Ils s’installeront sous BIN_DOS, MAN_DOS et I18N_DOS, respectivement. Ces
variables ont chacune une valeur prédéfinie dans le Makefile et dépendent de
-PREFIX, mais il peut être utile de les modifier. Il peut être nécessaire de
-régler MANPATH ou /etc/man.conf pour accéder aux pages du manuel.
+PREFIX ; il peut être utile de les modifier. Puisque les pages du manuel ne sont
+pour l'instant disponibles qu'en français et que l'installateur les place dans
+${MAN_DOS}/fr/, il y a des chances qu'elles soient inaccessibles et qu'il faille
+modifier la variable d'environnement MANPATH ou le fichier /etc/man.conf.
Objectif
--------
@@ -56,16 +58,17 @@ les besoins de plusieurs projets. Il s’intègre en outre généralement très
aux environnements de type Unix.
Le programme aplat(1) a été conçu pour rendre plus agréable la création de
-documents structurés hiérarchiquement et pour rendre possible l’utilisation des
-utilitaires de traitement de texte qui fonctionnent bien avec des documents
-organisés selons le principe des lignes et des champs (grep, sed, awk, cut,
-etc.).
-
-Deux formats de document ont donc dû être créés : l’un agréable pour les humains
-(aplat) ; l’autre agréable pour les machines (plat). Il faut concevoir le format
-plat comme un format intermédiaire que divers programmes pourront manipuler le
-long d’un tube et qu’on pourra ensuite convertir vers un ou plusieurs autres
-formats (XML, HTML, texte, gemtext, epub, etc.)
+documents structurés hiérarchiquement et pour rendre possible l’utilisation de
+certains utilitaires de traitement de texte qui fonctionnent bien avec des
+documents organisés selons le principe des lignes et des champs (grep, sed, awk,
+cut, etc.).
+
+Deux formats de document ont donc dû être créés : l’un agréable à écrire et à
+manipuler manuellement (aplat(5)) ; l’autre agréable à manipuler automatiquement
+(plat(5)). Il faut concevoir plat(5) comme un format intermédiaire que divers
+programmes pourront manipuler le long d’un tube et qu’on pourra ensuite
+convertir vers un ou plusieurs autres formats (XML, HTML, texte, gemtext, epub,
+etc.)
Utilisation
-----------
@@ -85,30 +88,30 @@ $ cat lisez-moi.aplat
$ aplat <lisez-moi.aplat >lisez-moi.plat
$ cat lisez-moi.plat
-:doc: (
-:doc:@: (
-:doc:@:titre: () Lisez-moi!
-:doc:@:nom du programme: () aplat
-:doc:@:description: () Convertir le format aplat au format plat
-:doc:@: )
-:doc:par: () Les formats aplat et plats…
-:doc:sous-titre: () dépendances
-:doc:par: () …
-:doc: )
+( doc
+( @
+() titre Lisez-moi!
+() nom du programme aplat
+() description Convertir le format aplat au format plat
+)
+() par Les formats aplat et plats…
+() sous-titre Dépendances d’exécution
+() par …
+)
On peut alors extraire le titre du document avec la suite de commandes :
-$ <lisez-moi.plat grep ’^:doc:@:titre: ’ | cut -f3 | { tr -d ’\n’ ; echo ; }
+$ <lisez-moi.plat | accumuler | grep ' :doc:@:titre: ' | cut -f3 | { tr -d '\n' ; echo ; }
Lisez-moi!
Le dernier segment de la séquence {tr -d ’\n’ ; echo ;} est nécessaire parce que
le troisième champ peut s’étendre sur plusieurs lignes. Ainsi, dans le format
plat,
- :doc:@:titre: () Lisez-moi!
+ () titre Lisez-moi!
et
- :doc:@:titre: ( Lise
- :doc:@:titre: ) z-moi!
+ ( titre Lise
+ ) titre z-moi!
sont équivalents.
diff --git a/changements.txt b/changements.txt
@@ -7,7 +7,8 @@ Version 2.0 (???)
* plat(5): Permutation du champ des drapeaux et de celui des étiquettes. Le
champ des drapeaux est maintenant premier et celui des étiquettes second.
* plat(5): Seule l'étiquette du domaine cadet est maintenant affichée dans le
- champ des étiquettes, plutôt que la hiérarchie complète.
+ champ des étiquettes, plutôt que la hiérarchie complète. Chaque étiquette
+ n'est même affichée qu'une seule fois.
* aplat(1): Correction d'un problème où le deux-points d'une étiquette n'était
pas interprété comme il faut lorsque placé entre guillemets ou dans un bloc.
* aplat(1): La nouvelle option -V affiche la version du programme.
diff --git a/man/fr/aplat.1 b/man/fr/aplat.1
@@ -8,6 +8,8 @@
.Nm aplat
<\c
.Ar fichier
+.Nm aplat
+.Fl V
.Sh DESCRIPTION
L’utilitaire
.Nm aplat
@@ -17,6 +19,12 @@ Il convertit le format
.Xr aplat 5
au format
.Xr plat 5 .
+.Pp
+Lorsque
+.Nm aplat
+est exécuté avec l'option
+.Fl V ,
+la version du programme est affichée en sortie standard.
.Sh EXEMPLES
En supposant que le fichier
.Pa exemple.aplat
@@ -32,13 +40,13 @@ La commande suivante affiche le texte suivant\~:
.Pp
.Bd -literal -offset indent
$ aplat <exemple.aplat
-:doc: (
-:doc:@: (
-:doc:@:titre: () Exemple
-:doc:@:date: () 2024-01-21
-:doc:@: )
-:doc:par: () Voici un exemple.
-:doc: )
+( doc
+( @
+() titre Exemple
+() date 2024-01-21
+)
+() par Voici un exemple.
+)
.Ed
.Sh ÉTATS DE SORTIE
L’utilitaire
diff --git a/man/fr/aplat.5 b/man/fr/aplat.5
@@ -7,7 +7,7 @@
.Sh DESCRIPTION
.Nm aplat
est un format de document structuré hiérarchiquement conçu pour être facile à
-manipuler, aussi bien par un humain que par une machine.
+écrire et manipuler, aussi bien par un humain que par une machine.
.Pp
C’est le format qu’\c
.Xr aplat 1
@@ -78,7 +78,7 @@ contient une
.Em étiquette
de plus
que de deux-points.
-Ainsi, dans l’exemple ci-dessus,
+Ainsi, dans les deux exemple ci-dessus,
.Em parent ,
.Em intermédiaire
et
@@ -88,8 +88,8 @@ sont des étiquettes.
Le
.Em contenu
d’un domaine correspond la concaténation de tous les atomes qu’il contient,
-excepté le premier, qui est l’\c
-.Em étiquette .
+excepté le premier, qui contient la ou les
+.Em étiquettes .
.Pp
Finalement, un
.Em atome
@@ -136,8 +136,8 @@ guillemets qu’à l’extérieur.
Les guillemets n’ont pas à se trouver aux extrémités des atomes
mais fonctionnent plutôt comme des commutateurs
réglant le mode d’interprétation.
-Ils fonctionnent en cela comme les guillemets des interpréteurs de commandes
-Unix.
+Ils ressemblent en cela
+aux guillemets des interpréteurs de commandes Unix.
.Pp
La dernière stratégie d’échappement a recourt à un
.Em bloc .
diff --git a/man/fr/plat.5 b/man/fr/plat.5
@@ -9,13 +9,15 @@
est un format de document organisé en lignes et en champs qui permet la
représentation de structures hiérarchiques.
Les utilitaires de traitement de texte conçus pour bien fonctionner dans un
-environnement Unix sont donc tout à fait capables de le manipuler.
+environnement Unix sont donc,
+avec un peu d'aide,
+tout à fait capables de le manipuler.
.Pp
Le format se présente comme une suite de lignes, chacune séparée en trois
champs\~: celui des
-.Em étiquettes ,
-celui des
.Em drapeaux
+celui de l’\c
+.Em étiquette ,
et celui du
.Em contenu .
Les champs sont séparés par des caractères de tabulation
@@ -40,22 +42,6 @@ est le domaine le plus imbriqué à un endroit donné du document.
Tout domaine apparaît au moins une fois en position de domaine cadet,
et ce même s’il est vide.
.Pp
-Une
-.Em étiquette
-nomme un domaine.
-Le champ des étiquettes
-contient l’étiquette du domaine cadet courant
-de même que,
-le cas échéant,
-les étiquettes de tous ses domaines parents.
-Ce champ a la forme d’une liste d’étiquettes
-ordonnée de telle sorte qu’un
-parent se trouve toujours à la gauche de son enfant.
-Chaque étiquette de cette liste est précédée d’un deux-points
-.Pq Sq :\& .
-La dernière étiquette est aussi suivie d’un deux-points.
-Il est impossible d’échapper les deux-points dans ce champ.
-.Pp
Un
.Em drapeau
permet d’identifier les limites d’un domaine.
@@ -66,6 +52,17 @@ la parenthèse fermante
.Pq Sq )\&
indique que la ligne est la dernière à être incluse dans un domaine donné.
.Pp
+Une
+.Em étiquette
+nomme un domaine.
+L'étiquette de chaque domaine n'est affichée qu'une seule fois,
+à l'ouverture du domaine.
+Autrement dit,
+si le champ de l'étiquette n'est pas vide,
+le champ des drapeaux contient au moins
+.Sq \( ,
+et vice-versa.
+.Pp
Les champs
.Em contenu
qui se suivent
@@ -84,17 +81,18 @@ et
respectivement.
Le caractère d’échappement lui-même peut être échappé par
.Sq \e\e .
+Il est interdit d'échapper tout autre caractère.
.Sh EXEMPLES
L’exemple suivant
(où un signe de dollar a été ajouté
pour marquer la fin de la ligne)\~:
.Bd -literal -offset indent
-:doc: ( $
-:doc:par: ( Que veut $
-:doc:par: dire $
-:doc:par:it: () placoter$
-:doc:par: ) ?$
-:doc: ) $
+( doc $
+( par Que veut $
+ dire $
+() it placoter$
+) ?$
+) $
.Ed
.Pp
est tout à fait équivalent au document
@@ -107,5 +105,15 @@ suivant\~:
.Sh VOIR AUSSI
.Xr aplat 1 ,
.Xr aplat 5
+.Sh HISTORIQUE
+.Pp
+Le format
+.Nm
+a changé avec la version 2.0 de l'utilitaire
+.Xr aplat 1 .
+Avant cette publication,
+le champ des drapeaux suivait celui de l'étiquette,
+et ce dernier contenait toute la hiérarchie des étiquettes,
+du domaine racine au domaine cadet.
.Sh AUTEURS
.An Selve <selve@asteride.xyz>
