aplat(1)
========

Convertir le format aplat au format plat.

Les formats aplat et plat sont équivalents. Le premier a été conçu pour être
facile d’utilisation pour un humain et le second, pour bien s’intégrer aux
utilitaires de traitement de texte des environnements de type Unix.

Dépendances d’exécution
-----------------------

- POSIX
- libintl

Dépendances de compilation
--------------------------

- compilateur C89
- POSIX
- make (supportant les assignations avec « != »)
- utilitaires gettext

Installation
------------

aplat(1) a été testé sur :
* OpenBSD 7.4
* FreeBSD 14.0
* Alpine Linux 3.19.0
* Debian bookworm

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.

Installer le programme, avec les pages du manuel et les traductions des messages
du programme :

# make install

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.

Objectif
--------

Le format XML est très utile pour créer et pour manipuler des documents
structurés. Il est cependant pénible à écrire à la main et trop complexe pour
les besoins de plusieurs projets. Il s’intègre en outre généralement très mal
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.)

Utilisation
-----------

Voici un extrait d’un document au format aplat(5) qui aurait pu servir à la
génération de ce LISEZ-MOI.

$ cat lisez-moi.aplat
(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 "…"))

$ 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:	)

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!

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!
et
	:doc:@:titre:	(	Lise
	:doc:@:titre:	)	z-moi!

sont équivalents.

Ces deux formats sont décrits dans les pages du manuel aplat(5) et plat(5).
La page aplat(1) documente le fonctionnement de l’utilitaire.

=> https://asteride.xyz/~selve/man/aplat.1.txt
=> https://asteride.xyz/~selve/man/aplat.5.txt
=> https://asteride.xyz/~selve/man/plat.5.txt

J’ai écrit une autre petite présentation de cet outil et de ces formats. On peut
la retrouver sur ma capsule gemini et sur mon site internet.

=> https://asteride.xyz/~selve/articles/aplat_1_documents_structures_unix.html

Contribuer
----------

Pour tout commentaire, rapport de bogue ou diff, on peut m’envoyer un courriel
à selve@asteride.xyz.

Aussi, les messages de ce programme ont été traduits du français au catalan, à
l’espagnol et à l’anglais. La documentation, cependant, n’existe pour l’instant
qu’en français. De l’aide est toujours bienvenue.

Licence
-------

aplat est disponible sous licence GPLv3.

Auteur
------

aplat a été créé et est maintenu par Selve <selve@asteride.xyz>.
