LISEZ-MOI.txt (4860B)
1 aplat(1) 2 ======== 3 4 Convertir le format aplat au format plat. 5 6 Les formats aplat et plat sont équivalents. Le premier a été conçu pour être 7 facile d’utilisation pour un humain et le second, pour bien s’intégrer aux 8 utilitaires de traitement de texte des environnements de type Unix. 9 10 Dépendances d’exécution 11 ----------------------- 12 13 - POSIX 14 - libintl 15 16 Dépendances de compilation 17 -------------------------- 18 19 - compilateur C89 ou plus récent 20 - POSIX 21 - make (supportant les assignations avec « != ») 22 - utilitaires gettext 23 24 Installation 25 ------------ 26 27 aplat(1) a été testé sur : 28 * OpenBSD 7.4 29 * FreeBSD 14.0 30 * Alpine Linux 3.19.0 31 * Debian bookworm 32 33 Télécharger la publication la plus récente, la décompresser, l’extraire : 34 35 $ curl 'https://asteride.xyz/~selve/publications/aplat/aplat.tgz' | 36 gzcat | tar -xvf - 37 $ cd aplat 38 39 Compiler le programme : 40 41 $ make 42 43 Notez que dans certains systèmes, libintl est incluse dans libc. Dans ce cas, il 44 faut retirer « -lintl » de la variable LIBS de la Makefile. 45 46 Installer le programme, avec les pages du manuel et les traductions des messages 47 du programme : 48 49 # make install 50 51 Ils s’installeront sous BIN_DOS, MAN_DOS et I18N_DOS, respectivement. Ces 52 variables ont chacune une valeur prédéfinie dans le Makefile et dépendent de 53 PREFIX ; il peut être utile de les modifier. Puisque les pages du manuel ne sont 54 pour l’instant disponibles qu’en français et que l’installateur les place dans 55 ${MAN_DOS}/fr/, il y a des chances qu’elles soient inaccessibles et qu’il faille 56 modifier la variable d’environnement MANPATH ou le fichier /etc/man.conf. 57 58 Objectif 59 -------- 60 61 Le format XML est très utile pour créer et pour manipuler des documents 62 structurés. Il est cependant pénible à écrire à la main et trop complexe pour 63 les besoins de plusieurs projets. Il s’intègre en outre généralement très mal 64 aux environnements de type Unix. 65 66 Le programme aplat(1) a été conçu pour rendre plus agréable la création de 67 documents structurés hiérarchiquement et pour rendre possible l’utilisation de 68 certains utilitaires de traitement de texte qui fonctionnent bien avec des 69 documents organisés selons le principe des lignes et des champs (grep, sed, awk, 70 cut, etc.). 71 72 Deux formats de document ont donc dû être créés : l’un agréable à écrire et à 73 manipuler manuellement (aplat(5)) ; l’autre agréable à manipuler automatiquement 74 (plat(5)). Il faut concevoir plat(5) comme un format intermédiaire que divers 75 programmes pourront manipuler le long d’un tube et qu’on pourra ensuite 76 convertir vers un ou plusieurs autres formats (XML, HTML, texte, gemtext, epub, 77 etc.). 78 79 Utilisation 80 ----------- 81 82 Voici un extrait d’un document au format aplat(5) qui aurait pu servir à la 83 génération de ce LISEZ-MOI. 84 85 $ cat lisez-moi.aplat 86 (doc 87 (@ (titre "Lisez-moi!") 88 ("nom du programme" aplat) 89 (description "Convertir le format aplat au format plat")) 90 (par "Les formats aplat et plats…") 91 (sous-titre "Dépendances d’exécution") 92 (par "…")) 93 94 $ aplat <lisez-moi.aplat >lisez-moi.plat 95 96 $ cat lisez-moi.plat 97 :doc: ( 98 :doc:@: ( 99 :doc:@:titre: () Lisez-moi! 100 :doc:@:nom du programme: () aplat 101 :doc:@:description: () Convertir le format aplat au format plat 102 :doc:@: ) 103 :doc:par: () Les formats aplat et plats… 104 :doc:sous-titre: () Dépendances d’exécution 105 :doc:par: () … 106 :doc: ) 107 108 On peut alors extraire le titre du document avec la suite de commandes : 109 110 $ <lisez-moi.plat | grep '^:doc:@:titre: ' | cut -f3 | { tr -d '\n' ; echo ; } 111 Lisez-moi! 112 113 Le dernier segment de la séquence {tr -d ’\n’ ; echo ;} est nécessaire parce que 114 le troisième champ peut s’étendre sur plusieurs lignes. Ainsi, dans le format 115 plat, 116 117 :doc:@:titre: () Lisez-moi! 118 et 119 :doc:@:titre: ( Lise 120 :doc:@:titre: ) z-moi! 121 122 sont équivalents. 123 124 Ces deux formats sont décrits dans les pages du manuel aplat(5) et plat(5). 125 La page aplat(1) documente le fonctionnement de l’utilitaire. 126 127 => https://asteride.xyz/~selve/man/aplat.1.txt 128 => https://asteride.xyz/~selve/man/aplat.5.txt 129 => https://asteride.xyz/~selve/man/plat.5.txt 130 131 J’ai écrit une autre petite présentation de cet outil et de ces formats. On peut 132 la retrouver sur ma capsule gemini et sur mon site internet. 133 134 => https://asteride.xyz/~selve/articles/aplat_1_documents_structures_unix.html 135 136 Contribuer 137 ---------- 138 139 Pour tout commentaire, rapport de bogue ou diff, on peut m’envoyer un courriel 140 à selve@asteride.xyz. 141 142 Aussi, les messages de ce programme ont été traduits du français au catalan, à 143 l’espagnol et à l’anglais. La documentation, cependant, n’existe pour l’instant 144 qu’en français. De l’aide est toujours bienvenue. 145 146 Licence 147 ------- 148 149 aplat est disponible sous licence GPLv3. 150 151 Auteur 152 ------ 153 154 aplat a été créé et est maintenu par Loïc Daignault-Pichette <loic@asteride.xyz>.