/doc/French/userguide-fr/userguide-fr.t2t
Unknown | 2108 lines | 1563 code | 545 blank | 0 comment | 0 complexity | 7df9a50643c4870801dd2b348d46127f MD5 | raw file
1Txt2tags User Guide - French Translation 2Aurélio Marinho Jargas v2.2 (Dez 2004) 3Translated by Claude Hiebel (Mar 2005) 4 5%!target: html 6%!encoding: UTF-8 7 8%%% htmldoc does TOC 9%!options(html): --no-toc --no-css-sugar -o userguide-pdf.html 10 11%%% Images are in the same dir 12%!preproc: IMGPATH . 13%%% Remove separator lines and strong lines 14%!preproc(html): '^ *[-=]{10,} *$' '' 15%%% Little clean up for less large tables 16%!postproc: /pessoal/sourceforge.net '' 17%%% All images with border 18%!postproc: '(<IMG [^>]*BORDER)="0"' '\1="1"' 19%%% removing first header, htmldoc ignores all until next <H1> (cool!) 20%!postproc(html): '<H1>Txt2tags User Guide .*</H1>' '' 21 22% normalizing common text 23%!preproc: CONFAREA Zone CONFIGURATION 24%!preproc: HEADAREA Zone ENTETE 25%!preproc: BODYAREA Zone CORPS 26%!preproc: MARKPROP **Propriétés :** 27%!preproc: MARKCONT **Contenu :** 28%!preproc: MARKDESC **Description :** 29%!preproc: MARKSYN **Syntaxe :** 30%!preproc: MARKDET **Détails :** 31%!preproc: NOMARKS Les marques ne sont pas interprétées 32%!preproc: NOMACRO Les macros ne sont pas interprétées 33 34%!preproc: URLMARKUP http://txt2tags.org/fr/marques.html 35 36% 15/Mar/2005: translated to french by Claude Hiebel 37% 22/Jun/2006: translation revised by Nicolas Dumoulin 38 39======================================================================== 40 41= Première partie - Introduction =[intro] 42 43== Les premières questions que vous vous posez ==[1st-questions] 44 45Ce chapitre est un aperçu de txt2tags, qui présente son utilisation et ses 46caractéristiques. 47 48------------------------------------------------------------------------ 49 50=== Qu'est-ce que c'est ? === 51 52Txt2tags est un outil de mise au format de texte et de conversion. 53 54Txt2tags convertit un fichier texte brut avec des petites marques en de 55multiples formats cibles : 56 57- Document HTML 58- Document XHTML 59- Document SGML 60- Document DocBook 61- Document LaTeX 62- Document Lout 63- Page de man UNIX 64- Présentation MagicPoint 65- Document Creole 1.0 66- Page Wikipedia (MediaWiki) 67- Page Google Wiki 68- Page PmWiki 69- Page DokuWiki 70- Page MoinMoin 71- Document PageMaker 6.0 72- Document AsciiDoc 73- Texte ASCII Art 74- Texte brut (sans marques) 75 76 77------------------------------------------------------------------------ 78 79=== Pourquoi dois-je l'utiliser ? === 80 81Vous allez trouver txt2tags très pratique si : 82- vous avez besoin de publier des documents sous divers formats, 83- maintenir des documents à jour sous divers formats, 84- écrire des documents techniques ou des manuels, 85- vous ne savez pas comment écrire un document dans un format 86 particulier, 87- vous n'avez pas un éditeur spécifique pour un certain format, 88- vous voulez utiliser un éditeur simple pour faire les mises à jour. 89 90 91Et la motivation principale est : 92- gagner du temps : écrire le **contenu** et ne pas vous soucier de la 93**mise en forme**. 94 95------------------------------------------------------------------------ 96 97=== Pourquoi est-ce un bon choix par rapport à d'autres outils ? === 98 99Txt2tags est en très forte croissance, suivant des 100concepts de base. 101En voici les points forts : 102 103| //Fichiers source lisibles// | les marques Txt2tags sont très simples, presque naturelles. 104| //Document de sortie lisible// | Comme le fichier source, le fichier résultat est lisible, avec des indentations et des lignes courtes. 105| //Des marques compatibles// | les marques txt2tags sont suffisamment spécifiques pour aller dans n'importe quel document et ne peuvent pas être confondues avec le contenu. 106| //Des règles simples// | Comme les marques, les règles qui s'appliquent sont liées les unes aux autres. Il n'y a pas de "cas spéciaux" ni "d'exception". 107| //Structures simples// | Toute la mise en forme supportée est **simple** sans autre option ni modificateur compliqué. Juste une marque sans aucune option. 108| //facile à apprendre// | Avec des marques simples et un source lisible, l'apprentissage de txt2tags est ``user friendly``. 109| //De jolis exemples// | Les **fichiers d'exemple** inclus dans le package donnent des exemples réels simples ou "sur"-compliqués écrits avec txt2tags. 110| //Des outils précieux// | Les **fichiers de syntaxe** inclus dans le logiciel (pour les éditeurs vim, emacs, nano et kate) vous aidant à écrire des documents sans erreur de syntaxe. 111| //trois interfaces utilisateur// | Il y a **l'interface graphique Tk**, très facile à utiliser, une **interface Web** qui peut être utilisée à distance et une **interface en ligne de commande** pour les connaisseurs des langages de script. 112| //langage script// | Avec le mode ligne de commande comportant toutes les options, un utilisateur expérimenté peut **automatiser** les tâches et faire de la **post-édition** sur les fichiers convertis. 113| //Chargez et lancez / Multi-platforme// | Txt2tags est un simple **script Python**. Il n'y a pas besoin de compilateur ni de charger des modules supplémentaires. Ainsi il tourne sans problème sur *NIX, Linux, Windows et Macintosh. 114| //Mises à jour fréquentes// | Le programme possède une liste de diffusion très active avec des utilisateurs qui proposent des corrections et des améliorations. L'auteur lui-même est un utilisateur intensif à la maison et au travail, donc le développement n'est pas prêt de s'arrêter. 115 116 117------------------------------------------------------------------------ 118 119=== Ai-je à payer? === 120 121 || Absolument PAS ! | 122 123C'est un logiciel libre, GPL, open source et du domaine public. 124//<mettez-votre-mot-favori-ici>//. 125 126Vous pouvez le copier, l'utiliser, le modifier, le vendre et faire des 127mises à jour comme s'il vous appartenait. La politique de copyright du 128logiciel n'est pas un des soucis principaux de l'auteur. 129 130------------------------------------------------------------------------ 131 132 133== Structures de mise au format supportées==[structures] 134 135Voici la liste de toutes les structures supportées par txt2tags. 136 137- entête (titre du document, nom de l'auteur, date) 138- titre de section (numéroté ou non) 139- paragraphes 140- modificateurs de fontes 141 - gras 142 - italique 143 - souligné 144- fonte non proportionnelle (verbatim) 145 - dans un paragraphe en fonte non proportionnelle 146 - ligne en fonte non proportionnelle 147 - zone en fonte non proportionnelle 148- citations 149- liens 150 - URL/liens Internet, 151 - liens e-mail, 152 - liens locaux, 153 - liens nommés. 154- listes 155 - liste pointée 156 - liste numérotée 157 - liste de définition 158- lignes de séparation horizontales 159- image avec un joli alignement 160- table (avec ou sans bordures, alignement dans la cellule) 161- marques spéciales pour du texte brut (sans traitement) 162- macro spéciale pour la date courante (avec une mise en forme souple) 163- commentaires (pour des notes, TODO, FIXME) 164 165 166------------------------------------------------------------------------ 167 168== Cibles supportées ==[targets] 169 170: **HTML** 171 Tout le monde sait ce qu'est l'HTML. (Internet) 172 173 Txt2tags génère des documents HTML propres, qui sont jolis et dont le 174source est lisible. Il N'UTILISE PAS javascript, des fenêtres ou autre 175technique futile, qui ne sont pas nécessaires pour des documents simples 176ou techniques. Mais un fichier CSS peut être utilisé si demandé. Txt2tags 177génère du code "//HTML 4.0 Transitional//". 178 179Depuis la version 2.0, le code HTML généré est approuvé 100% par 180le [w3c validator http://validator.w3.org/]. 181 182: **XHTML** 183C'est la nouvelle génération de HTML, avec des règles plus strictes aussi 184près des marques que vous ouvrez. Cela rend le code plus facile à 185traiter et à comprendre. Pour les cas généraux, considérez que c'est 186du HTML. Txt2tags génère du code "//XHTML 1.0 Transitional//". 187 188Depuis la version 2.0, le code XHTML généré est approuvé 100% par 189le [w3c validator http://validator.w3.org/]. 190 191: **SGML** 192C'est un format courant de document qui a de puissants 193 [outils de conversion http://www.sgmltools.org]. 194A partir d'un fichier sgml vous pouvez générer des documents html, pdf, 195ps, info, latex, lyx, rtf. Les outils sgml2* font aussi une table des 196matières automatique et sépart les sections en pages distinctes (sgml2html). 197 198Txt2tags génère des fichiers SGML dans le système de fichiers linuxdoc 199prêt à être convertis avec les outils sgml2* sans fichier catalogue 200supplémentaire et sans besoin ennuyeux du SGML 201 202: **LATEX** 203Le format académique préféré, bien plus puissant que vous pouvez 204le rêver. Des livres complets, des formules compliquées et tout texte 205complexe peuvent être écrits en LaTeX. Mais si vous voulez écrire les 206marques à la main, préparez vous à vous arracher les cheveux ... 207 208Txt2tags génère des fichiers LaTeX prêts à l'usage, faisant 209tout le travail complexe de mise en forme avec ses exceptions. 210L'utilisateur n'a à s'occuper que du texte. 211 212: **LOUT** 213Très semblable à LaTeX en puissance, mais avec une syntaxe plus facile, 214utilisant des "@" à la place des "\" et évitant l'utilisation des 215accolades dans les cas classiques. Son approche tout-est-objet rend 216le marquage plus sain. 217 218Txt2tags génère des fichiers Lout prêts à l'usage, qui peuvent être 219convertis en PS ou PDF en utilisant la commande "lout". 220 221: **MAN** 222Les page de manuel UNIX résistent au temps. Les formats de documents 223passent et elles sont toujours là, inamovibles. 224 225Il y a d'autres outils pour générer des pages de man, mais txt2tags a un 226avantage : une source de multiples cibles. Ainsi la même page de man peut 227être convertie en page HTML, présentation Magic Point, etc. 228 229: **MGP** 230 [Magic Point http://www.mew.org/mgp] est un outil de présentation très 231pratique (genre : Microsoft PowerPoint), qui utilise un langage de 232marques pour définir tous les écrans. Vous pouvez faire des 233présentations complexes avec vi/emacs/notepad. 234 235Txt2tags génère des fichiers .mgp prêts à l'usage, définissant toutes 236les entêtes pour les fontes et pour les définitions de la présentation, 237ainsi que le support des accents en encodage ISO-8859 avec le support des accents. 238 239 **POINT FORT 1 :** txt2tags crée les fichiers .mgp en utilisant les 240fontes XFree86 Type1. Ainsi vous n'avez pas à joindre les fichiers 241de fontes TrueType à votre présentation. 242 243 **POINT FORT 2 :** les définitions de couleurs des fontes sont 244propres, même sur un système avec une palette de couleurs réduite 245(même lancé avec la commande ``startx -- -bpp 8``) la présentation sera 246correcte. 247 248 Les mots clés sont : convertir et utiliser. Aucun autre besoin ou 249arrangement nécessaire. 250 251: **MOIN** 252 Vous ne savez pas ce qu'est [MoinMoin http://moin.sourceforge.net] ? 253 C'est [WikiWiki http://www.c2.com/cgi/wiki]! 254 255 La syntaxe du Moin est un tantinet ennuyeuse quand vous devez mettre 256``{{{'''''des apostrophes et des accolades'''''}}}``, txt2tags vient 257avec ses marques simples et sa solution unifiée : un source des cibles 258multiples. 259 260: **PM6** 261J'espère que vous ne le savez pas, mais Adobe PageMaker 6.0 a son 262propre langage de balises. Les styles, les couleurs de table, les 263modificateurs de caractères et la majorité des possibilités à la souris 264sont également disponibles dans son langage de marques. Vous avez juste 265besoin d'accéder au menu "Import tagged text". Juste pour information, 266c'est un langage de marques <comme HTML>. 267 268Txt2tags génère toutes les marques et définit déjà une entête 269complète et fonctionnelle, réglant la mise au format et les styles de 270paragraphe. C'est le morceau le plus difficile. 271 272**ATTENTION:** Pas de coupure de ligne. Un paragraphe doit être sur une 273seule ligne. 274 275 Note de l'auteur : 276 //Mon livre entier en portugais [regular expression's book http://guia-er.sf.net]// 277 //a été écrit avec VI, convertit en PageMaker avec txt2tags et envoyé 278 //sous presse.// 279 280: **TXT** 281TXT est le texte. Le seul vrai type de mise au format. 282Quoique les marques de txt2tags soient intuitives et discrètes, vous 283pouvez les enlever en convertissant le fichier en texte pur. 284 285Les titres sont soulignés. Et le texte est laissé comme dans le fichier 286source. 287 288 289------------------------------------------------------------------------ 290 291== Statuts des structures supportées par cible ==[struct-support] 292 293 || Structure | html | xhtml | sgml | tex | lout | man | mgp | moin | pm6 | txt | 294 | entêtes | O | O | O | O | O | O | O | N | N | O | 295 | entête de section | O | O | O | O | O | O | O | O | O | O | 296 | paragraphes | O | O | O | O | O | O | O | O | O | O | 297 | gras | O | O | O | O | O | O | O | O | O | - | 298 | italique | O | O | O | O | O | O | O | O | O | - | 299 | souligné | O | O | - | O | O | - | O | O | O | - | 300 | fonte non proportionnelle | O | O | O | O | O | - | O | O | O | - | 301 | ligne verbatim | O | O | O | O | O | O | O | O | O | - | 302 | zone verbatim | O | O | O | O | O | O | O | O | O | - | 303 | zone de citation | O | O | O | O | O | O | O | O | O | O | 304 | liens internet | O | O | O | - | - | - | - | O | - | - | 305 | liens e-mail | O | O | O | - | - | - | - | O | - | - | 306 | liens locaux | O | O | O | N | N | - | - | O | - | - | 307 | liens nommés | O | O | O | - | - | - | - | O | - | - | 308 | liste pointée | O | O | O | O | O | O | O | O | O | O | 309 | liste numérotée | O | O | O | O | O | O | O | O | O | O | 310 | liste de definition | O | O | O | O | O | O | N | N | N | O | 311 | ligne horizontale | O | O | - | O | O | - | O | O | N | O | 312 | image | O | O | O | O | O | - | O | O | N | - | 313 | table | O | O | O | O | N | O | N | O | N | N | 314 || Extras | html | xhtml | sgml | tex | lout | man | mgp | moin | pm6 | txt | 315 | alignement d'image | O | O | N | N | O | - | O | N | N | - | 316 | alignement cellule table | O | O | O | O | N | O | N | O | N | N | 317 318 || | Légende 319 | **O** | //supporté// 320 | **N** | //non supporté (peut-être dans une révision future)// 321 | **-** | //non supporté (ne peut pas l'être dans cette cible)// 322% | **?** | //non supporté (pas sûr que cela puisse être fait)// 323 324------------------------------------------------------------------------ 325 326== Les trois interfaces utilisateur : GUI, internet et ligne de commande==[interfaces] 327 328Comme les utilisateurs ont des besoins différents et des environnements 329divers, txt2tags est très souple dans son utilisation. 330 331Il y a trois interfaces utilisateur pour le programme, chacune avec ses 332particularités et fonctionnalités. 333 334- **GUI**: écrite en Tk, apporte le fenêtrage et le clic de souris à txt2tags 335- **Web**: écrite en PHP, permet de lancer txt2tags sur un butineur, ne 336 nécessitant aucune installation côté client. 337- **ligne de commande**: écrite en Python, c'est le coeur du programme. 338 Toutes les options sont disponibles en option. 339 340 341------------------------------------------------------------------------ 342 343=== Interface graphique Tk ===[gui] 344 345Depuis la version 1.0, il y a une jolie interface graphique, qui 346fonctionne sur Linux, Windows, Mac et autres. 347 348Le programme détecte automatiquement si votre système peut afficher 349l'interface, et est lancé sans argument. On peut 350forcer l'interface graphique avec l'option ``--gui``. S'il manque une 351ressource, le programme le dira. 352 353 **Note:** Le module Tkinter est nécessaire. Comme il est 354 disponible dans la distribution standard de Python, vous devez 355 certainement l'avoir. 356 357L'interface est simple et intuitive. 358 359 [IMGPATH/gui.png] 360 361+ Vous localisez le fichier .t2t sur le disque et les options sont 362chargées. 363 364+ Si aucune cible n'est définie, vous devez en choisir une 365 366+ Ensuite vous pouvez choisir quelques options, mais aucune n'est 367nécessaire 368 369+ A la fin vous appuyez sur le bouton "convertir" 370 371Un option pratique est "//visualisation à l'écran//". Vous pouvez voir le 372code généré dans une autre fenêtre , aucun fichier n'est sauvegardé. 373Quand le code est correct, vous enlevez l'option et la conversion 374s'effectuera normalement. 375 376Les couleurs par défaut peuvent être changées dans le fichier 377``~/.txt2tagsrc``, en utilisant les réglages ``%!guicolors``. Par 378exemple : 379``` 380% choisir mes couleurs pour l'interface graphique (bg1, fg1, bg2, fg2) 381%!guicolors: blue white brown yellow 382``` 383 384------------------------------------------------------------------------ 385 386=== Interface Web === 387 388L'interface Web est disponible à l'adresse 389http://txt2tags.org/online.php. Vous pouvez tester et utiliser le 390programme avant de le charger. 391 392 [IMGPATH/web.png] 393 394On peut aussi installer cette interface sur le réseau local. Cela évite 395d'avoir à l'installer sur toutes les machines. 396 397------------------------------------------------------------------------ 398 399=== Interface ligne de commande===[cmdline] 400 401Pour les utilisateurs en ligne de commande l'option ``--help`` doit suffire. 402 403``` 404Utilisation : txt2tags [OPTIONS] [entrée.t2t ...] 405 406 -t, --target indiquez le type de document de sortie supporté : 407 html, xhtml, sgml, tex, lout, man, mgp, moin, pm6, txt 408 -i, --infile=ENTREE choisissez le fichier d'entrée ('-' pour STDIN) 409 -o, --outfile=SORTIE choississez le fichier de sortie ('-' pour STDOUT) 410 -n, --enum-title numéroter les titres en : 1, 1.1, 1.1.1, etc 411 -H, --no-headers supprimer les entêtes, les titres et les pieds de page 412 --headers montrer les entêtes, les titres et les pieds de page (par défaut) 413 --encoding=ENC choisir l'encodage de sortie (utf-8, iso8859-1, etc) 414 --style=FILE utiliser FILE comme feuille de style (comme HTML CSS) 415 --css-sugar insère des étiquettes CSS pour des sorties HTML et XHTML 416 --css-sugar insèrer le contenu du fichier CSS pour des sorties HTML et XHTML 417 --mask-email cacher l'email des robots spammeurs x@y.z devient x (a) y z 418 --toc ajouter la table des matières à la sortie 419 --toc-only imprime la table des matières et sort 420 --toc-level=N limiter la profondeur de la table des matières à N 421 --rc lire le fichier de configuration ~/.txt2tagsrc (option par défaut) 422 --gui appeler l'interface graphique Tk 423 -q, --quiet mode silencieux, plus de sortie (sauf les erreurs) 424 -v, --verbose imprimer des messages d'information pendant la conversion 425 -h, --help imprimer cette aide et sortir 426 -V, --version imprimer la version et sortir 427 --dump-config imprimer toute la configuration trouvée et sortir 428 429Désactive les options (OFF) 430 --no-outfile, --no-infile, --no-style, --no-encoding, --no-headers 431 --no-toc, --no-toc-only, --no-mask-email, --no-enum-title, --no-rc 432 --no-css-sugar, --no-css-inside, --no-quiet 433 434Exemple : 435 txt2tags -t html --toc myfile.t2t 436 437Par défaut, la sortie convertie est sauvée dans 'entrée.<type>' 438Utilisez --outfile pour imposer un fichier de sortie 439Si le fichier d'entrée est '-', la lecture est à partir de STDIN 440Si le fichier de sortie est '-', la sortie est sur STDOUT 441``` 442 443==== Exemples ==== 444 445Si vous avez créé un fichier marqué ``file.t2t``, voici quelques 446exemples : 447 448| **Convertir en HTML** | ``$ txt2tags -t html file.t2t`` 449| **Le même avec redirection** | ``$ txt2tags -t html -o - file.t2t > file.html`` | | . 450| **Avec une table des matières** | ``$ txt2tags -t html --toc file.t2t`` 451| **Et aussi avec les titres numérotés** | ``$ txt2tags -t html --toc --enum-title file.t2t`` | | 452| **vue rapide de la table des matières** | ``$ txt2tags --toc-only file.t2t`` 453| **la même numérotée** | ``$ txt2tags --toc-only --enum-title file.t2t`` | | . 454| **coder une ligne à partir de STDIN** | ``$ echo -e "\n**bold**" | txt2tags -t html --no-headers -`` 455| **Tester l'option masquer les emails** | ``$ echo -e "\njohn.wayne@farwest.com" | txt2tags -t txt --mask-email --no-headers -`` 456| **Édition post-conversion** | ``$ txt2tags -t html -o- file.t2t | sed "s/<BODY .*/<BODY BGCOLOR=green>/" > file.html`` 457 458: //Note// 459 Depuis la version 1.6 vous pouvez faire du traitement avant et après 460conversion avec les filtres ``%!preproc`` et ``%!postproc``. 461 462 463======================================================================== 464 465 466 467= Deuxième partie - OK je le veux, que faire maintenant ?=[install] 468 469Téléchargez le programme et lancez le sur votre machine. 470 471== Charger et installer Python ==[download-python] 472 473Avant tout, vous devez charger et installer l'interpréteur 474Python sur votre système. Si vous l'avez déjà, sautez ce 475paragraphe. 476 477Python est un bon programme, il fonctionne sur Windows, 478Linux, UNIX, Macintosh et autres et peut être téléchargé à 479partir du [site web Python http://www.python.org]. Les 480instructions d'installation sont disponibles sur le site 481web. Txt2tags marche mieux avec une version de Python 1.5 ou 482supérieure. 483 484Si vous n'êtes pas sûr d'avoir Python, ouvrez une console 485(tty, xterm ou MSDOS) et tapez ``python``. Si ce n'est pas 486installé, votre système vous le dira. 487 488 489== Charger txt2tags ==[download-txt2tags] 490 491Le site officiel de la distribution txt2tags est 492http://txt2tags.org/src. 493 494Tous les fichiers sont des archives compressées (fichiers .tgz), qui peuvent être 495décompressés par la plupart des utilitaires (Winzip inclus). 496 497Prenez la **dernière** version (la plus récente ou le numéro de version le 498plus élevé). Les versions précédentes restent pour des raisons 499historiques. 500 501== Installer txt2tags ==[install-txt2tags] 502 503Comme tous les scripts Python, txt2tags ne nécessite aucune 504installation. 505 506Le seul fichier nécessaire pour le programme est le script txt2tags. Les 507autres fichiers de l'archive compressée sont de la documentation, des outils et des 508fichiers d'exemple. 509 510Le moyen le plus sur de lancer txt2tags est de l'appeler par Python. 511``` prompt$ python txt2tags 512 513Si vous voulez installer txt2tags sur le système comme programme, copiez 514(ou faites un lien) sur le fichier script txt2tags dans un répertoire 515référencé par la variable PATH et assurez vous que le système peut le 516lancer. 517 518: **UNIX/Linux** 519Rendez le script exécutable (``chmod +x txt2tags``) et copiez le dans un 520répertoire référencé par la variable PATH (``cp txt2tags /usr/local/bin``). 521 522: **Windows** 523Renommez le fichier script en ajoutant l'extension .py 524(``ren txt2tags txt2tags.py``) et copiez le dans un répertoire de la 525variable PATH (``copy txt2tags.py C:\WINNT``). 526 527 528Après cela, vous pouvez créer un icône pour votre bureau, si vous voulez 529utiliser l'interface graphique. 530 531=== Paquets spéciaux pour les utilisateurs Windows === 532 533Il y a aussi deux distributions .EXE pour txt2tags, chacune installe le 534programme sur les machines Window avec quelques clics : 535 536- Le script txt2tags pour ceux qui ont l'interpréteur Python déjà 537 installé 538- La version complète, qui n'a pas besoin de l'interpréteur Python (il 539 y a une version légère de Python incluse). 540 541 542Visitez le site //Txt2tags-Win// pour charger les paquets : 543http://txt2tags-win.sf.net 544 545== Installer les colorateurs syntaxiques pour les éditeurs ==[editor-syntax] 546 547Txt2tags est livré avec des fichiers de colorateurs syntaxiques utilisables 548avec les éditeurs suivants : 549 550- Vim (www.vim.org) 551- Emacs (www.emacs.org) 552- Nano (www.nano-editor.org) 553- Kate (http://kate.kde.org) 554 555 556Ces fichiers de coloration syntaxique connaissent toutes les règles et les 557marques de txt2tags, aidant l'utilisateur à écrire des documents sans 558faute de syntaxe. Visualisant les marques en couleur, vous voyez en 559direct si vous écrivez correctement. 560 561 | [IMGPATH/vim.png] | 562 | Exemple de fichier ouvert avec l'éditeur Vim 563 564Chaque éditeur a une procédure d'installation spécifique, lire 565l'entête du ficher de syntaxe et la documentation de l'éditeur. 566 567======================================================================== 568 569 570 571= Troisième partie - Écrire et convertir son premier document =[your-1st-doc] 572 573== Tester les outils == 574 575Pour faire votre première conversion, vous avez besoin de trois choses : 576txt2tags, un éditeur de texte et un butineur. 577 578+ Vérifiez que txt2tags fonctionne sur votre machine. 579 580 - **Interface en ligne de commande :** Appelez "txt2tags" sur une ligne 581 de commande et le programme va vous donner le message "Missing 582input file" ou similaire. Si cela ne marche pas essayez "python /chemin/vers/txt2tags" 583ou "/chemin/vers/python /chemin/vers/txt2tags" si Python n'est pas dans 584votre PATH. 585 586 - **Interface Gui :** Cliquez sur l'icône du programme pour lancer 587 l'interface graphique. 588 589+ Ouvrez un éditeur de texte que vous connaissez bien. cela peut être 590**n'importe lequel**, de vi jusqu'à MS Word ou Open Office. Créez un 591nouveau document marqué qui sera votre premier document txt2tags. 592 593+ Lancez votre butineur préféré pour voir les résultats de la conversion 594dans une page HTML. 595 596 597------------------------------------------------------------------------ 598 599== Écrire l'entête du document == 600 601+ Allez dans l'éditeur de texte et tapez sur la **première** ligne du 602 document //Mon premier doument// 603+ Sur la deuxième ligne faire un sous titre avec le texte //test txt2tags// 604+ Puis sur la troisième ligne mettre une information de date //Lundi 2029// 605 606 607Si tout c'est bien passé vous avez un document avec le contenu suivant : 608 609``` 610Mon premier document 611test txt2tags 612Lundi 32 Janvier 2029 613``` 614 615Ceci n'est qu'une partie du document, mais vous pouvez le convertir et 616tester le résultat. 617 618Maintenant sauvegardez le résultat avec le nom ``test.txt``. Notez 619dans quel dossier vous sauvez le fichier, vous en aurez besoin 620plus tard. 621 622 623------------------------------------------------------------------------ 624 625== La première conversion - l'interface graphique == 626 627Si vous utilisez l'interface en ligne de commande passez au paragraphe 628suivant. 629 630Si vous utilisez l'interface graphique procédez comme suit: 631 632 [IMGPATH/firstdoc.png] 633 634+ Appuyez sur le bouton "choisir" et choisir le fichier ``test.txt`` 635que vous venez de sauver (souvenez vous du dossier !) 636+ De retour à la première image, choisir "page HTML" pour "Choisissez le type du document de sortie" 637+ Appuyez sur le bouton "convertir" 638 639 640 [IMGPATH/firstdoc-done.png] 641 642Une boite de dialogue apparaît, qui vous informe que le fichier a été 643converti avec succès. Notez que le fichier HTML généré a été sauvé dans 644le même dossier que le fichier texte avec l'extension "html". 645 646------------------------------------------------------------------------ 647 648== La première conversion - interface ligne de commande == 649 650Si vous utilisez l'interface graphique allez au paragraphe précédent. 651 652Si vous êtes dans l'interface ligne de commande allez dans le dossier où 653a été sauvé votre fichier et tapez la commande : 654 655``` txt2tags --target html test.txt 656 657Notez qu'il y a des espaces entres les parties de la commande mais pas 658dans la chaîne "--target", c'est une option. Cette option est suivie de 659la chaîne "html", qui dit au programme dans quel format votre fichier 660texte doit être converti. Le dernier argument est le nom du fichier. 661 662Si la conversion se réalise, le résultat est sauvé dans le fichier 663``test.html`` et le programme affichera le message 664"//txt2tags écrit test.html//" Sinon il vous indiquera l'erreur que 665vous avez faite en tapant la ligne de commande. Vérifiez 666attentivement. 667 668Voici un exemple de ce que vous verrez à l'écran : 669``` 670prompt$ txt2tags --target html test.txt 671txt2tags écrit test.html 672prompt$ 673``` 674 675------------------------------------------------------------------------ 676 677== Tester le résultat == 678 679Ouvrez le fichier ``test.html`` avec le butineur pour vérifier que tout 680est bon. 681 682 [IMGPATH/firstdoc-html.png] 683 684On y arrive ! Vous avez juste tapé trois lignes simples de texte et 685txt2tags a fait tout le travail pour configurer l'entête de la page HTML. 686L'alignement du texte, les tailles, les espacements et l'apparence. 687Voyez que le titre principal est également dans l'onglet du butineur. 688 689 || Vous écrivez du texte, txt2tags fait le reste :) | 690 691Astuce : Vous pouvez également utiliser des CSS sur les pages HTML 692générées par txt2tags, ainsi l'apparence de la page est configurable à 693100%. 694 695------------------------------------------------------------------------ 696 697== Écrire le corps du document == 698 699Retournons à l'éditeur de texte, l'étape suivante est d'écrire le corps 700du document. Vous pouvez écrire du texte brut comme vous le faites pour 701les emails. Vous voyez que txt2tags reconnaît les paragraphes et les 702listes d'items automatiquement, vous n'avez pas besoin de les "marquer". 703 704Sauvez à nouveau, convertissez et testez le résultat. C'est le cycle de 705développement avec txt2tags. Vous ne vous intéressez qu'au contenu du 706document, terminant les documents plus rapidement qu'avec les autres 707éditeurs. Pas de cliquage de souris, pas de menus, de fenêtre ni de 708distraction. 709 710Regardez le contenu du fichier suivant ``test.txt``, qui n'est que du 711texte brut et comparez le avec la page HTML générée : 712 713``` 714Mon premier document 715test txt2tags 716Lundi 32 Janvier 2029 717 718Essayons donc ce truc qui s'appelle txt2tags. 719Ce que je met c'est juste pour noircir l'écran. 720C'est pas un temps à aller dehors chercher : 721- des mouches 722- des souris 723- des canards 724- des éléphants 725- des baleines 726``` 727 728 [IMGPATH/firstdoc-fullhtml.png] 729 730 731Vous pouvez écrire une page complète sans aucune connaissance de HTML. 732Vous n'avez pas besoin d'insérer des marques. En plus le même fichier 733texte peut être converti dans tous les autres formats cibles supportés par 734txt2tags. 735 736A côté du texte brut, txt2tags a quelques marques très simples, que vous 737utilisez quand vous avez besoin d'autres mises au format ou structures 738comme le gras, l'italique, les titres, les images, les tables et autres. 739Un exemple rapide : 740``**commencez en gras**`` et ``== les signes == pour le titre ==``. 741Vous pouvez apprendre les marques grâce au fichier 742[Txt2tags Markup Demo http://txt2tags.org/markup.html]. 743 744======================================================================= 745 746 747 748= Quatrième partie - maîtriser les concepts de txt2tags =[concepts] 749 750== Les zones d'un document .t2t ==[areas] 751 752Les fichiers marques txt2tags sont divisés en 3 zones. Chacune a ses 753propres règles et usage. Ce sont : 754 755: //ENTETE// 756 La zone pour le titre du document, l'auteur, la version et la date 757(ceci est optionnel) 758: //CONFIGURATION// 759 La zone pour la configuration générale du document et le comportement 760de la conversion(ceci est optionnel). 761: //CORPS// 762 La place du contenu du document (obligatoire) 763 764 765Comme vu au dessus, les deux premières zones sont optionnelles, seul le 766//CORPS// est obligatoire. 767 768Les zones sont délimitées par des règles spéciales, qui seront vues en 769détail dans le chapitre suivant. La représentation graphique des zones du document 770est la suivante : 771 772``` 773 _____________ 774 | | 775 | ENTETE | 1. En premier, l'entête 776 | | 777 |CONFIGURATION| 2. Puis la configuration 778 | | 779 | CORPS | 3. Enfin le corps du document, 780 | | 781 | ... | jusqu'à la fin. 782 | ... | 783 |_____________| 784 785``` 786 787En bref, les zones sont définies de la façon suivante : 788 789 | **Entête** | Les 3 premières lignes du fichier ou la première ligne vide 790 | **Configuration** | Commence après l'entête (4e ou 2e ligne) et termine lorsque le corps commence 791 | **Corps** | La première ligne de texte valide (pas un commentaire ou une configuration après l'//ENTETE// 792 793 794=== Exemple complet=== 795 796``` 797Mon joli titre de document 798Mr. John Doe 799Dernière mise à jour: %%mtime(%c) 800 801%! Target : html 802%! Style : fancy.css 803%! Encoding: iso-8859-1 804%! Options : --toc --enum-title 805 806Salut ! Ceci est mon premier essai de document. 807Son contenu se termine ici. 808``` 809 810------------------------------------------------------------------------ 811 812== ENTETE ==[headers-area] 813 814Localisation: 815- position fixe : **les 3 premières lignes** du fichier. C'est tout. 816- position fixe : **la première ligne** du fichier si elle est blanche. 817 Cela signifie une entête vide. 818 819 820L'ENTETE est la seule zone qui a une position fixe, et est orientée 821ligne. Elle est localisée dans les trois premières lignes du fichier 822source. 823 824Ces lignes sont libres, aucune information statique de type est 825demandée, mais le contenu suivant est recommandé : 826 827 - //ligne 1//: titre du document 828 - //ligne 2//: nom de l'auteur et/ou email 829 - //ligne 3//: date du document et/ou version 830 (un lieu privilégié pour ``%%date``) 831 832 833Gardez en mémoire que les trois premières lignes du document source 834seront les trois premières lignes du document cible, séparées et 835contrastées par rapport au corps du document (grandes lettres en gras). 836Si la pagination est autorisée, l'entête sera seule et centrée sur la 837première page. 838 839 840==== Plus (ou pas) de lignes d'entête ==== 841 842Quelquefois l'utilisateur désire spécifier moins de trois lignes pour 843l'entête, ne donnant que le titre et/ou la date. 844 845Il n'y a qu'à laisser la deuxième et/ou la troisième ligne vide et cela 846ne sera pas inclus dans le document final. Mais gardez en mémoire que 847même vides, ces lignes font partie de l'entête et que le corps du 848document **doit** commencer après cette troisième ligne. 849 850Le titre est le seul élément demandé de l'entête, mais si vous le 851laissez vide, vous dites que votre document n'aura **pas d'entête**. le 852corps du document commencera juste après à la deuxième ligne. 853 854Ne pas mettre d'entête est souvent utile si vous voulez spécifier votre 855propre entête personnalisée après conversion. L'option de ligne de 856commande ``--no-headers`` est nécessaire pour cette opération. 857 858==== En deux mots ==== 859 860 || En résumé : "les entêtes sont des __positions__ pas des contenus." | 861 862Placez un texte sur la première ligne et il apparaîtra sur la première ligne 863du fichier résultat. Idem pour les deuxième et troisième lignes de 864l'entête. 865 866------------------------------------------------------------------------ 867 868== CONFIGURATION ==[config-area] 869 870Localisation: 871- Commence juste après l'ENTETE 872 - Commence à la **quatrième ligne** du fichier si des **entêtes** sont spécifiées. 873 - Commence à la **deuxième ligne** du fichier si **aucune entête** n'est spécifiée. 874- Se termine lorsque le CORPS commence. 875 - Se termine par une ligne vide, une ligne qui n'est pas un réglage, ou une ligne 876 de commentaire 877 878 879La zone de CONFIGURATION est optionnelle. Un utilisateur moyen peut écrire un 880tas de fichiers txt2tags sans savoir que cela existe, mais les 881utilisateurs expérimentés apprécieront la puissance et le contrôle que 882cela procure. 883 884La zone de CONFIGURATION est utilisée pour ranger les réglages du document, 885vous n'aurez pas à taper les options dans la ligne de commande au 886moment de la conversion. Par exemple vous pouvez définir le format de la 887cible et l'encodage. 888 889Lire la section [réglages #settings-overview] pour plus 890d'informations. 891 892---------------------------------------------------------------- 893 894== CORPS ==[body-area] 895 896Localisation: 897- Commence à la première ligne valide de texte du fichier. 898 - Les entêtes, les réglages et les commentaires ne sont **pas** 899 des lignes de texte valides. 900- Se termine à la fin du fichier (EOF). 901 902 903Le CORPS est tout ce qui n'est pas ENTETE ou CONFIGURATION. 904 905Le CORPS est constitué du contenu du document et de toutes les 906structures et mises en forme que txt2tags peut reconnaître. Dans le 907corps vous pouvez inclure des commentaires pour les //TODO// et les 908//notes personnelles//. 909 910Vous pouvez utiliser l'option en ligne de commande ``--no-headers`` pour 911convertir le corps du document, en supprimant les entêtes. C'est 912pratique pour fabriquer vos entêtes dans un fichier séparé, que vous 913concaténez ensuite. 914 915---------------------------------------------------------------- 916 917== Réglages ==[settings-overview] 918 919Les réglages sont des lignes de commande placées dans la CONFIGURATION 920et qui modifient la conversion. Leur syntaxe est : 921 922 || %! clé : valeur | 923 924Liste des clés valides : 925 926 || clé | Description | 927 | Target | définit la cible par défaut dans laquelle le document sera converti 928 | Options | Définit les options par défaut qui seront utilisées à la conversion. Le format est le même que dans la ligne de commande. 929 | Style | Définit le style du document. Utilisé pour définir un fichier CSS pour HTML/XHTML et pour charger un package LaTeX. 930 | Encoding | Choisit le jeu de caractères. Utilisé si le document contient des caractères accentués ou des caractères non ASCII 931 | PreProc | Filtre d'entrée. Définit les règles "trouve et remplace" qui seront appliquées au document source. 932 | PostProc | filtre de sortie. Définit les règles "trouve et remplace" qui seront appliquées au document de sortie. 933 934Exemple: 935 936``` 937%! Target : html 938%! Options : --toc --toc-level 3 939%! Style : fancy.css 940%! Encoding: iso-8859-1 941%! PreProc : "AMJ" "Aurelio Marinho Jargas" 942%! PostProc: '<BODY.*?>' '<BODY bgcolor="yellow">' 943``` 944 945----------------------------------------------------------------------- 946 947== Option en ligne de commande ==[options] 948 949Le moyen le plus rapide de changer le comportement par défaut est 950d'utiliser les options de la ligne de commande. Cela n'est disponible 951que sur l'interface en ligne de commande pas sur l'interface GUI ou 952Web. 953 954Comme les autres programmes système, le programme accepte un jeu 955d'options prédéfinies. Une option est un tiret suivi par une lettre ou 956deux tirets suivis d'un ou plusieurs mots comme ``-t`` ou ``--target``. A 957propos de l'option "target", c'est la seule obligatoire, toutes les 958autres sont optionnelles. 959 960Les options généralement utilisées sont ``--outfile`` pour définir un 961fichier de sortie particulier, ``--toc`` pour activer la génération 962automatique de la table des matières et ``--encoding`` pour choisir le 963jeu de caractères. La plupart des options peuvent être désactivées en la 964précédant de "no-" devant, par exemple :``-no-encoding`` et 965``--no-toc``. 966 967Vous pouvez enregistrer les options désirées dans le fichier source dans 968la CONFIGURATION, en utilisant le réglage ``%!option``. Par ce 969moyen, vous n'avez plus à les retaper dans la ligne de commande. 970Exemple: ``%!options: --toc -o mydoc.html``. L'exception est la 971spécification de la cible qui a sa propre syntaxe : ``%!target: html``. 972 973Utilisez l'option ``--help`` pour avoir la liste complète des options 974disponibles dans txt2tags. 975 976----------------------------------------------------------------------- 977 978== Fichier de configuration utilisateur (fichier RC) ==[rc] 979 980Le fichier de configuration utilisateur (appelé aussi fichier RC) est le 981lieu de stockage des réglages qui vont être gérés pour **tous** 982les fichiers convertis. Si vous insérez les mêmes réglages pour tous 983les fichiers .t2t que vous écrivez, déplacez les dans le fichier RC, ils 984seront utilisés globalement pour les fichiers existants et à venir. 985 986L'emplacement par défaut de ce fichier dépend de votre système. Il peut 987aussi être spécifié par l'utilisateur, en utilisant une variable 988d'environnement. 989 990 || | localisation du fichier RC | 991 | Windows : | ``%HOMEPATH%\_t2trc`` 992 | Linux et autres : | ``$HOME/.txt2tagsrc`` 993 | défini par l'utilisateur : | variable d'environnement ``T2TCONFIG`` 994 995 996Le format des réglages est exactement le même que celui utilisé dans 997la zone CONFIGURATION des fichiers .t2t. Il y a un exemple de fichier RC 998dans l'archive compressée à l'emplacement ``doc/txt2tagsrc``. Exemple: 999 1000``` 1001% ma config 1002 1003%%% utiliser un fichier CSS pour le HTML 1004%!options(html): --css-sugar 1005 1006%%% changer la profondeur de la table des matières à 4 pour toutes les cibles 1007%!options: --toc-level 4 1008 1009%%% encodage par défaut pour tous les documents 1010%!options: --encoding iso-8859-1 1011``` 1012 1013Toute ligne non vide, un commentaire ou une ligne de configuration valide 1014va générer une erreur à l'exécution de txt2tags. Donc soyez attentif 1015quand vous éditez ce fichier. 1016 1017Txt2tags applique automatiquement le fichier RC à tout fichier qu'il 1018convertit. Si vous voulez désactiver ce comportement pour un fichier 1019spécifique, utilisez l'option ``--no-rc`` en option dans la ligne de 1020commande. 1021 1022== Ordre de chargement des configuration et précédence ==[config-loading] 1023 1024Il y a trois moyens pour préciser à txt2tags les options et les 1025réglages à utiliser. Ceci est l'ordre dans lequel ils sont lus et 1026appliqués : 1027 1028+ Le fichier de configuration utilisateur (RC) 1029+ La zone CONFIGURATION dans le document source 1030+ Les options de la ligne de commande 1031 1032 1033En premier txt2tags lit le contenu du fichier RC s'il existe et applique 1034contenu sur le fichier source. Puis il scrute la zone CONFIGURATION du 1035fichier source courant si elle existe et l'applique en surchargeant les 1036règles du fichier RC en cas de conflit. En dernier, il applique les 1037options de la ligne de commande qui ont toujours priorité. 1038 1039Ainsi, si l'encodage est défini dans les trois sources, ce sera l'option 1040de la ligne de commande qui sera utilisée. 1041 1042----------------------------------------------------------------------- 1043 1044== commande %!include ==[include] 1045 1046La commande ``include`` est utilisée pour inclure un fichier externe 1047dans le corps du document source courant. Ce n'est pas une 1048configuration mais une commande qui est valide dans le CORPS du document. 1049 1050La commande ``include`` est pratique pour découper un gros document en 1051d'autres plus petits (comme les chapitres d'un livre) ou pour inclure le 1052contenu complet d'un fichier externe dans le document source. Exemple : 1053 1054``` 1055Mon premier livre 1056Dr. John Doe 10571ere Édition 1058 1059%!include: intro.t2t 1060%!include: chapter1.t2t 1061%!include: chapter2.t2t 1062... 1063%!include: chapter9.t2t 1064%!include: ending.t2t 1065``` 1066 1067Indiquez juste le nom du fichier après la chaîne ``%!include``. Les 1068spécification optionnelles de la cible sont supportées. La commande suivante est valide : 1069 1070``` %!include(html): file.t2t 1071 1072Notez que la commande include insère le CORPS dans le fichier source du 1073document. Les zones ENTETE et CONFIGURATION sont ignorées. Cela permet 1074de convertir le fichier inclus séparément ou avec le document principal. 1075 1076Il y a 3 variantes de la commande include : 1077- inclusion Verbatim 1078- inclusion tel-quel (brut) 1079- inclusion marquée 1080 1081 1082Le type **verbatim** inclut le fichier texte en préservant le format et 1083les espaces du fichier original comme s'il était marqué par VERB(```). 1084Pour cela encadrer le nom de fichier avec des apostrophes inverses : 1085 1086``` %!include: ``/etc/fstab`` 1087 1088Le type **tel-quel** inclut un fichier texte tel quel, ne cherchant pas les 1089marques txt2tags et **ne les interprétant pas**, comme s'il était marqué par 1090RAW ("""). Pour cela encadrer le nom de fichier par des apostrophes 1091doubles comme : 1092 1093``` %!include: ""nice_text.txt"" 1094 1095Le type **marqué** est envoyé directement dans le fichier résultat, sans 1096aucun traitement effectué par txt2tags. Par ce moyen vous pouvez inclure 1097des parties marquées ou du code avec des marques de sortie plus complexes 1098non supportées par txt2tags : 1099 1100``` %!include(html): ''footer.html'' 1101 1102Notez que le fichier est encadré par des apostrophes, et comme le texte 1103est inclus déjà marqué vous devez spécifier la cible pour 1104éviter les erreurs. 1105 1106----------------------------------------------------------------------- 1107 1108== commande %!includeconf ==[includeconf] 1109 1110La commande ``includeconf`` est utilisée pour inclure la configuration 1111d'un fichier externe dans le fichier courant. Cette commande n'est 1112valide que dans la zone CONFIGURATION. 1113 1114C'est pratique pour avoir la même configuration pour de multiples 1115fichiers, vous pouvez en centraliser la gestion. Dans le fichier où vous 1116voulez inclure cette configuration globale, mettez un appel 1117``includeconf``. Par exemple : 1118 1119``` 1120Mon premier Document 1121John Doe 1122Juillet 2004 1123 1124%!includeconf: config.t2t 1125 1126Hi, ceci est mon premier document 1127``` 1128 1129Le format dans le fichier inclus est le même que dans le 1130[fichier RC #rc]. 1131 1132======================================================================= 1133 1134 1135 1136= Cinquième partie - maîtriser les marques =[marks] 1137 1138Synthèse de toutes les marques txt2tags : 1139 || Basic | ``...............`` | modificateurs | ``...............`` | 1140 | //Entête// | 3 premières lignes | //gras// | ""**mots**"" 1141 | //Titre// | = mots = | //Italique// | ""//mots//"" 1142 | //2cwtitre numéroté// | + mots + | //souligné// | ""__mots"" 1143 | //Paragraphe// | mots | //fonte non proportionnelle// | ""``mots``"" 1144 || blocs de texte | ``...............`` | autre | ``...............`` | 1145 | //Quote// | <TAB>mots | //ligne de séparation// | ------------... 1146 | //Liste// | - mots | //ligne épaisse// | ============... 1147 | //liste numérotée// | + mots | //liens// | ""[label url]"" 1148 | //liste de définition// | : mots | //Image// | ""[filename.jpg]"" 1149 | //ligne Verbatim// | ``` mots | //Commentaire// | % commentaire 1150 | //zone Verbatim// | ""```\n lignes \n```"" | //texte brut// | """"mots"""" 1151 | //ligne tel-quel(raw)// | """"""" mots | //Table// | ""| cell1 | cell2 | cell3..."" 1152 | //zone tel-quel (Raw)// | """""""\n lignes \n""""""" | //Ancre// | = titre =[ancre] 1153 1154Règles générales : 1155 1156- **Entêtes** Ce sont les 3 premières lignes du document, les marques ne sont pas interprétées. 1157- **Titres** ce sont des caractères "=" ou "+" équilibrés autour du 1158 texte du titre. Plus il y a de caractères, plus le niveau du titre est 1159important. 1160- les **modificateurs** n'acceptent pas d'espace entre les marques et leur 1161 contenu. 1162- les marques de **commentaire** "%" doivent être au début de la ligne 1163 (première colonne). 1164- les fichiers **Image** doivent se terminer par GIF, JPG, PNG ou 1165 similaire. 1166- Les seules marques **multiligne** sont les marques des zones Verbatim 1167 et tel-quel (brut). 1168- **Aucune marque n'est interprétée** dans les zones Verbatim et 1169 tel-quel (brut). 1170- Les **lignes séparatrices** doivent avoir au moins 20 caractères. 1171- La profondeur des citations et les listes est définie par 1172 **l'indentation**. 1173- Les **titres de table** sont définis par deux "||" au début de la 1174 ligne. 1175 1176------------------------------------------------------------------------ 1177%- MARKPROP Multiline, FreeSpaces, Align, Nesting 1178%- MARKCONT Macros, Beautifiers, Quote, Lists, Table, Verbatim, Raw, Bars, Links, Image, Comment 1179%----------------------------------------------------------------------- 1180 1181== Entête ==[mark-headers] 1182 1183- MARKDESC Identifie l'entête du document 1184- MARKPROP Multiline, FreeSpaces, !Align, !Nesting 1185- MARKCONT Macros 1186- MARKSYN 1187 - Les 3 premières lignes du fichier source. 1188 - Pour ne pas spécifier d'entête laisser la première ligne vide 1189 Pratique pour les entêtes particulières et les spécialistes 1190 "oneliners" en ligne de commande 1191 - Laisser les deuxième et troisième lignes vides pour éliminer les 1192 autres parties de l'entête. 1193- MARKDET 1194 - NOMARKS 1195 - les 3 lignes doivent être les trois premières du document final, 1196 elles vont être mises en valeur par rapport au corps du document 1197 et isolées sur la première page (si la pagination est autorisée). 1198 - Le contenu des entêtes est quelconque, sans aucune obligation de 1199 format, mais le contenu recommandé pour la plupart des documents est : 1200 - Ligne 1: Titre du document 1201 - Ligne 2: Nom de l'auteur et/ou email 1202 - Ligne 3: Date du document et/ou version (le bon endroit pour ""%%mtime"") 1203 1204 1205------------------------------------------------------------------------ 1206 1207== Titre, titre numéroté ==[mark-title] 1208 1209- MARKDESC Identifie un titre de section (numéroté ou non) 1210- MARKPROP !Multiline, FreeSpaces, !Align, !Nesting 1211- MARKCONT Raw 1212- MARKSYN 1213 - Pour des titres numérotés changez "=" par "+" sur les règles 1214 suivantes 1215 - des signes équilibrés autour ``=comme ceci=`` 1216 - Plus il y a de signes, plus le niveau est élevé : ``=titre=``, 1217 ``==soustitre==``, 1218 ``===soussoustitre===``, ... 1219 - Il y a a un maximum de 5 niveaux ``===== comme ceci =====`` 1220 - Des signes non équilibrés ne font pas un titre , ``=comme ceci===`` 1221 - Des espaces libres dans les marques ne sont pas 1222 autorisés ``= comme ceci =`` 1223 - Les titres peuvent avoir des ancres ``=comme ceci=[ancre]``. Pour 1224 créer une ancre créez un ``[lien local#ancre]`` 1225- MARKDET 1226 - NOMARKS 1227 - NOMACRO 1228 1229 1230------------------------------------------------------------------------ 1231 1232== Paragraphe ==[mark-paragraph] 1233 1234- MARKDESC Identifie un paragraphe de texte 1235- MARKPROP Multiline, FreeSpaces, !Align, !Nesting 1236- MARKCONT Macros, Beautifiers, Raw, Links, Image, Comment 1237- MARKSYN 1238 - Les paragraphes sont des groupes de lignes délimités par des lignes 1239 vides 1240 - D'autres blocs comme les listes, les citations, les tables et les 1241 zones verbatim terminent aussi un paragraphe. 1242 1243 1244------------------------------------------------------------------------ 1245 1246== Commentaire ==[mark-comment] 1247 1248- MARKDESC Utilisé pour insérer du texte qui n'apparaîtra pas dans le 1249 document cible 1250- MARKPROP !Multiline, !<FreeSpaces, !Align, !Nesting 1251- MARKCONT - 1252- MARKSYN 1253 - Un ligne avec le caractère "%" en première colonne ``% comme ceci`` 1254 - PAS d'espace devant 1255- MARKDET 1256 - Comme les commentaires, ils ne sont pas montrés dans le texte 1257 converti 1258 - Ce n'est pas un bloc : chaque ligne de commentaire doit commencer 1259 par "%" 1260 - Pratiques pour les TODO, rappels FIXME et les notes de l'éditeur 1261 1262 1263------------------------------------------------------------------------ 1264 1265== Gras, italique et souligné ==[mark-beautifiers] 1266 1267- MARKDESC Utilisé pour insérer du texte gras/italique/souligné dans un 1268 paragraphe, une table, une liste ou une citation 1269- MARKPROP !Multiline, !FreeSpaces, !Align, Nesting 1270- MARKCONT Macros, Beautifiers, Raw, Links, Image 1271- MARKSYN 1272 - Deux étoiles autour pour le gras ``**comme ceci**`` 1273 - Deux barres autour pour l'italique ``//comme ceci//`` 1274 - Deux signes soulignés pour le souligné ``__comme ceci__`` 1275 - Les marques doivent collées au contenu (pas d'espace) ``** ceci ** est invalide`` 1276- MARKDET 1277 - Tous les modificateurs de texte doivent être sur une seule ligne du 1278 fichier source, il ne doit pas y avoir de coupure de ligne 1279 - Les macros dont autorisées à l'intérieur : ``**%%date**`` 1280 - Vous pouvez mixer les modificateurs à l'intérieur ``""**__comme__ //ceci//**""`` 1281 1282 1283------------------------------------------------------------------------ 1284 1285== fonte non proportionnelle ==[mark-monospaced] 1286 1287- MARKDESC Utilisé pour mettre un texte en fonte non proportionnelle 1288 dans un paragraphe, un table, une liste ou une citation. 1289- MARKPROP !Multiline, !FreeSpaces, !Align, !Nesting 1290- MARKCONT - 1291- MARKSYN 1292 - Deux apostrophes inverses ````comme ceci```` 1293 - Les marques doivent être collées au contenu (pas d'espace) 1294 ```` ceci `` est invalide`` 1295- MARKDET 1296 - NOMARKS 1297 - NOMACRO 1298 - Tout le texte en fonte non proportionnelle doit être sur une seule ligne, pas de 1299 coupure de ligne dans le contenu 1300 - Dans quelques cibles les espaces internes sont maintenus, dans 1301 d'autres les espaces multiples sont remplacés par un seul. 1302 - Vous pouvez créer un texte gras en fonte non proportionnelle en l'insérant dans 1303 les marques de gras : 1304 ``""**``gras non proportionnel``**""``. La même chose pour les autres modificateurs 1305 comme ``""//``italique``//""`` et ``""__``souligné``__""``. 1306 1307 1308--------------------------------------------------------------------- 1309 1310== ligne et zone Verbatim ==[mark-verbatim] 1311 1312- MARKDESC Utilisé pour insérer du code programme ou autre texte 1313 pré-formatté, préservant les espaces et les sauts de ligne et en 1314utilisant une fonte non proportionnelle 1315- MARKPROP Multiline, !FreeSpaces, !Align, !Nesting 1316- MARKCONT - 1317- MARKSYN **ligne Verbatim :** 1318 - Une ligne commençant avec exactement 3 apostrophes inverses suivis d'un espace, 1319 et suivi du texte ``""```"" comme ceci`` 1320 - Les apostrophes inverses doivent être en première colonne, sans 1321 espace devant 1322- MARKSYN **Zone Verbatim :** 1323 - Une ligne commençant avec exactement 3 apostrophes inverses 1324 ``````` suivie par les lignes de texte, suivis d'une autre ligne 1325 avec exactement 3 apostrophes inverses ``````` 1326 - **AUCUN** espace n'est autorisé avant et après les marques 1327- MARKDET 1328 - NOMARKS 1329 - NOMACRO 1330 - Si on atteint la fin du fichier (EOF), la zone verbatim est 1331 terminée 1332 1333 1334--------------------------------------------------------------------- 1335 1336== Ligne de séparation, ligne épaisse ==[mark-separator] 1337 1338- MARKDESC identifie une ligne de séparation ou une ligne épaisse 1339- MARKPROP !Multiline, FreeSpaces, !Align, !Nesting 1340- MARKCONT - 1341- MARKSYN 1342 - La ligne de séparation peut être composée de tirets "-" ou 1343 de caractères soulignés "_" 1344 - La ligne épaisse est composée par des signes égal "=" 1345 - Il faut au moins 20 tirets/soulignés/égal 1346 - Des espaces optionnels peuvent être mis en début ou en fin de ligne 1347 - Tout autre caractère sur la ligne invalide la marque 1348- MARKDET 1349 - Si la cible n'admet pas de ligne de séparation, une ligne de 1350 commentaire la remplace 1351 - La ligne épaisse peut avoir une traduction différente sur certaines 1352 cibles : 1353 - Une ligne de séparation plus épaisse 1354 - Une pause dans les formats de présentation comme Magic Point 1355 - Une coupure de page pour les cibles avec pagination comme LaTeX 1356 1357 1358--------------------------------------------------------------------- 1359 1360== Liens, liens nommés ==[mark-link] 1361 1362- MARKDESC identifie une lien distant (internet) ou local 1363- MARKPROP !Multiline, !FreeSpaces, !Align, !Nesting 1364- MARKCONT Macros, Raw, Image 1365- MARKSYN 1366 - Toute adresse internet valide URL, ftp, news ou adresse email est 1367 détectée et une adresse est convertie automatiquement 1368 - Le protocole (http, https, ftp) est optionnel ``www.comme-ceci.com`` 1369 - Un nom peut être utilisé pour un lien : ``[cliquer ici www.url.com]`` 1370 - Une image peut pointer sur un lien : ``[[image.jpg] www.url.com]`` 1371 - Les macros sont autorisées dans les adresses de lien : ``[voir source %%infile]`` 1372 - Les macros sont autorisées dans le nom du lien : ``[mirror of %%outfile www.url.com]`` 1373% - Beautifiers are allowed on the link name: ``[**click** here www.url.com]`` 1374 - Le lien doit être spécifié sur une seule ligne, sans 1375 coupure de ligne 1376- MARKDET 1377 - Si la cible n'a pas de support de liens elle sera soulignée 1378 1379 1380--------------------------------------------------------------------- 1381 1382== Quote ==[mark-quote] 1383 1384- MARKDESC identifie une ligne citation indentée 1385- MARKPROP Multiline, !FreeSpaces, !Align, Nesting 1386- MARKCONT Macros, Beautifiers, Quote, Raw, Bars, Links, Image, Comment 1387- MARKSYN 1388 - Une ligne qui commence par une tabulation (TAB) 1389 - Plus il y a de tabulation plus la profondeur est grande 1390 - Les citations ne sont pas autorisées dans les listes et les tables 1391- MARKDET 1392 - Si la fin du fichier est atteinte (EOF), la citation ouverte est 1393 terminée 1394 - Certaines cibles ne supportent pas différents niveaux de citation, alors les 1395 "sous-citations" sont transformées au niveau supérieur 1396 - Il n'y a pas de limitation pour la profondeur. Mais certaines cibles 1397 peuvent avoir des restrictions, les sous-citations sont mises au 1398niveau supérieur 1399 1400 1401 -------------------------------------------------------------------- 1402 1403== Listes, listes numérotées, listes de définition ==[mark-lists] 1404 1405- MARKDESC identifie le début d'une liste d'items 1406- MARKPROP Multiline, !FreeSpaces, !Align, Nesting 1407- MARKCONT Macros, Beautifiers, Lists, Table, Verbatim, Raw, Bars, Links, Image, Comment 1408- MARKSYN 1409 - Une ligne commence par un tiret/plus/deux points suivi d'un seul 1410 espace 1411 - le premier caractère de la liste ne peut PAS être un espace (sauf 1412 dans les listes de définition) 1413 - Des espaces (pas des TAB) en début de ligne définissent la 1414 profondeur de l'indentation 1415 - Les sous-listes se terminent par une sous-liste de moindre 1416 profondeur ou avec un item vide 1417 - Toutes les listes ouvertes sont fermées par deux lignes blanches 1418 consécutives 1419- MARKDET 1420 - Si la fin de fichier est atteinte (EOF), toutes les listes ouvertes 1421 sont terminées 1422 - Les listes peuvent être mixées, comme une liste de définition dans 1423 une liste numérotée 1424 - Quelques cibles n'admettent pas les imbrications de listes, les items des 1425 sous-listes sont transformées dans le niveau supérieur 1426 - Il n'y a pas de limite pour la profondeur des listes. Mais certaines 1427 cibles ont des restrictions, les sous-listes de niveau inférieur sont 1428alors remontées 1429 1430 1431--------------------------------------------------------------------- 1432 1433== Image ==[mark-image] 1434 1435- MARKDESC Identifie une image 1436- MARKPROP !Multiline, !FreeSpaces, Align, !Nesting 1437- MARKCONT Macros 1438- MARKSYN 1439 - Un nom de fichier image encadré entre deux crochets, ``[comme_ceci.jpg]`` 1440 - Le fichier doit se terminer par une extension comme PNG, JPG, GIF, 1441 ... (la casse est indifférente) 1442 - les symboles ne sont pas autorisés dans le nom de fichier 1443 ``[comme_ceci!~1.jpg]`` 1444 - Les macros sont autorisées dans le nom de fichier ``[report-%%date(%Y-%m-%d).png]`` 1445 - PAS d'espace dans le nom de fichier ``[comme ceci.jpg]`` 1446 - PAS d'espace entre le crochet et le nom de fichier ``[ comme-ceci.jpg ]`` 1447- MARKDET 1448 - Si la cible n'a pas de support d'image, le nom de fichier est entre 1449 (parenthèses) 1450 - La position des marques indique l'alignement de l'image : 1451 - ``[GAUCHE.jpg]`` blablablabla 1452 - blablablabla ``[CENTRE.jpg]`` blablablabla 1453 - blablablabla ``[DROITE.jpg]`` 1454 1455 1456--------------------------------------------------------------------- 1457 1458== Tableau ==[mark-table] 1459 1460- MARKDESC Délimite une ligne d'un tableau avec n'importe quel nombre de 1461 colonnes 1462- MARKPROP Multiline, FreeSpaces, Align, !Nesting 1463- MARKCONT Macros, Beautifiers, Raw, Links, Image, Comment 1464- MARKSYN 1465 - Une barre verticale "|" identifie la ligne d'un tableau 1466 - Deux lignes verticales au début de la ligne "||" identifient la ligne de titre d'un 1467 tableau 1468 - les espaces avant le première barre verticale personnalisent le 1469 centrage de ta table 1470 - Les champs sont séparés par la chaîne " | " (espace barre-verticale espace) 1471 - Une barre verticale "|" à la fin de la première ligne du tableau rend les 1472 bordures visibles 1473 - La barre verticale "|" à la fin des autres colonnes de la table est ignoré 1474 - Les espaces dans chaque cellule spécifient leur alignement 1475 - Exemple: ``| ligne | de tableau | à | cinq | colonnes |`` 1476- MARKDET 1477 - Chaque ligne du tableau doit être sur une seule ligne du fichier 1478 source, sans saut de ligne 1479 - Les cibles avec alignement par colonne (comme sgml et LaTeX), 1480 utilisent l'alignement de la première ligne comme référence 1481 - Toute ligne "non table" la termine, sauf les lignes de commentaire 1482 - Le nombre de cellules est flexible, chaque ligne peut avoir un 1483 nombre différent de cellules 1484 - il n'y a pas de moyen de spécifier la largeur d'une colonne ou d'une 1485 rangée 1486 - Si la cible n'admet pas les tableaux, les lignes de la table sont 1487 considérés comme une zone Verbatim 1488 1489 1490--------------------------------------------------------------------- 1491 1492== caractères, lignes et zones tel-quel (brut) ==[mark-raw] 1493 1494- MARKDESC Utilisée pour "protéger" du texte du fichier source, pour que 1495 les marques et les macros ne soient pas traitées. 1496- MARKPROP !Multiline, !FreeSpaces, !Align, !Nesting 1497- MARKCONT - 1498- MARKSYN **caractères tel-quel :** 1499 - trois apostrophes doubles autour ``""""comme ceci""""`` 1500 - Les marques sont collées au contenu (pas d'espace entre les marques 1501 et le contenu) 1502- MARKSYN **ligne tel-quel :** 1503 - Une ligne commençant par trois apostrophes doubles ``""" comme ceci`` 1504 - La marque doit être au début de la ligne en première colonne 1505 - Utiliser un espace après les doubles apostrophes pour les séparer 1506 du texte. 1507- MARKSYN **zone tel-quel :** 1508 - Une ligne avec exactement 3 doubles apostrophes suivis de la ligne de 1509 texte, suivi d'exactement 3 doubles apostrophe 1510 - PAS d'espace avant et après les marques 1511- MARKDET 1512 - NOMARKS 1513 - NOMACRO 1514 - Si la fin du fichier (EOF) est atteinte la zone tel-quel (brut) est fermée. 1515 1516 1517======================================================================= 1518 1519 1520 1521= Sixième partie - maîtriser les macros =[macros] 1522 1523Les macros sont des mots clés spécifiques qui sont développées au moment 1524de la conversion. Elles sont utilisées pour insérer des informations 1525dynamiques comme la date ou des informations sur les documents source et 1526converti. 1527 1528Une macro est constituée par les caractères ``%%`` suivis par son nom 1529comme dans ``%%date``. Quelques macros acceptent une chaîne de formatage 1530entre parenthèses juste après le nom de la macro comme 1531``%%date(%Y-%m-%d)``. Cette chaîne de formatage inclut du texte classique 1532avec des directives identifiées par le signe % suivi d'un caractère 1533d'identification. Si aucune chaîne de formatage n'est fournie, le format 1534par défaut est utilisé. 1535 1536 || Nom de la macro | Produit ... | Format par défaut | 1537 | ""%%date"" | la date courante | %Y%m%d 1538 | ""%%mtime"" | la date de modification du fichier source | %Y%m%d 1539 | ""%%infile"" | le chemin du fichier source | %f 1540 | ""%%outfile"" | le chemin du fichier de sortie | %f 1541 | ""%%toc"" | la table des matières du document(TOC) | - 1542 1543Règles générales : 1544 1545- le nom de la macro est insensible à la casse : ``%%date``, ``%%DaTe`` et ``%%DATE`` sont identiques 1546- le macros sont valides dans la zone ENTETE et la zone CORPS sauf 1547 ``%%toc`` valide seulement dans la zone CORPS 1548- Une macro démarre la zone CORPS si elle est trouvée dans la zone 1549 CONFIGURATION 1550- Une macro peut être n'importe où dans la ligne (sauf la macro 1551 ``%%toc`` qui doit être seule sur une ligne) 1552- Une macro peut être utilisée dans les liens et les marques d'image 1553 (sauf ``%%toc``) 1554- Les macros ne sont pas traitées dans les titres, le verbatim et 1555 le texte brut 1556 1557 1558Exemple complet ( les zones en gras montrent les macros développées) : 1559 1560 Ceci est le manuel utilisateur de txt2tags, converti en 1561 **%%outfile(%e)** par txt2tags à partir du fichier source **%%infile**. 1562 La conversion a été faite le **%%date(%Y-%m-%d %X)**, mais la dernière 1563 modification dans le document source a été faite le **%%mtime(%Y-%m-%d %X)**. 1564 Les fichiers source et résultats sont dans le répertoire 1565 **%%infile(%D)**. 1566 1567----------------------------------------------------------------------- 1568 1569== %%date ==[macro-date] 1570 1571La macro ``%%date`` produit la date et l'heure courante. C'est très 1572pratique pour les entêtes et les pieds de document, pour indiquer quand 1573le document a été généré. Pour développer la dernière date de 1574modification voir la [macro ""%%mtime"" #macro-mtime]. 1575 1576Cette macro accepte un certain nombre de directives de formatage. La liste 1577complète peut être consultée sur le 1578[site Python http://www.python.org/doc/current/lib/module-time.html]. 1579 1580Voici les plus couramment utilisées : 1581 1582 || Directive | Description | 1583 | %a | jour de la semaine en abrégé d'après la locale 1584 | %A | jour de la semaine d'après la locale 1585 | %b | nom du mois en abrégé d'après la locale 1586 | %B | nom du mois d'après la locale 1587 | %c | jour et heure d'après la locale 1588 | %d | jour du mois en chiffre [01,31] 1589 | %H | heure (24-heures) en chiffre [00,23] 1590 | %I | heure (12-heures) en chiffre [01,12] 1591 | %m | mois en chiffre [01,12]. 1592 | %M | Minute en chiffre [00,59]. 1593 | %p | équivalent d'après la locale de AM/PM 1594 | %S | iseconde en chiffre [00,61]. (1) 1595 | %x | représentation de la date d'après la locale 1596 | %X | représentation de l'heure d'après la locale 1597 | %y | année sans les siècles en chiffre [00,99]. 1598 | %Y | année complète avec les siècles en chiffre 1599 | %% | caractère "%" 1600 1601Exemples: 1602 1603 || Macro | --> | Résultats pour la date %%date(%Y, %b %d at %H:%M) | 1604 | ""%%date(Converti le: %c)"" | --> | %%date(Converti le : %c) 1605 | ""%%date(%Y-%m-%d)"" | --> | %%date(%Y-%m-%d) 1606 | ""%%date(%I:%M %p)"" | --> | %%date(%I:%M %p) 1607 | ""%%date(Aujourd'hui est le %A, du mois %B.)"" | --> | %%date(Aujourd'hui est le %A, du mois %B.) 1608 1609----------------------------------------------------------------------- 1610 1611== %%mtime ==[macro-mtime] 1612 1613La macro ``%%mtime`` produit la date de dernière modification 1614du fichier source. C'est utile pour noter quand le fichier a été changé 1615la dernière fois. Cette macro est la "soeur" de la [macro ""%%date"" #macro-date], 1616et accepte les mêmes chaînes de formatage. 1617 1618Comme exemple : ce guide utilisateur a été édité la dernière fois le 1619**%%mtime(%c)**. Cette date est développée à partir de ``%%mtime(%c)``. 1620 1621----------------------------------------------------------------------- 1622 1623== %%infile ==[macro-infile] 1624 1625 La macro ``%%infile`` produit le chemin du fichier source dans le 1626système. C'est utile pour dire "//voir le source de ce fichier//" sur 1627les liens des pages HTML. Donner cette information est une attitude 1628aimable avec les débutants, pour qu'ils puissent utiliser votre source 1629comme exemple pour leurs propres pages. 1630 1631Cette macro accepte les chaînes de formatage suivantes : 1632 1633 || %<caractère> | Description | Sortie pour ce manuel utilisateur | 1634 | %f | nom du fichier | %%infile(%f) 1635 | %F | nom du fichier (sans extension) | %%infile(%F) 1636 | %e | extension du fichier | %%infile(%e) 1637 | %p | chemin absolu du fichier | %%infile(%p) 1638 | %d | chemin du fichier (répertoire seulement) | %%infile(%d) 1639 | %D | chemin du fichier (répertoire parent seulement) | %%infile(%D) 1640 | %% | caractère "%" seul | %%infile(%%) 1641 1642Exemples: 1643 1644 || Source | --> | Développement | 1645 | Ce guide est dans le répertoire ""%%infile(%D)"". | --> | Ce guide est dans le répertoire %%infile(%D). | 1646 | j'utilise l'extension ""%%infile(%e)"" | --> | j'utilise l'extension %%infile(%e) | 1647 | ""[voir le source %%infile]"" | --> | [voir le source %%infile] 1648 | Convertit en XHTML, cela donne ""%%infile(%F)"".xhtml | --> | Convertit en XHTML, cela donne %%infile(%F).xhtml 1649 1650Note: La macro et développée en "-" si la source vient de STDIN 1651 1652----------------------------------------------------------------------- 1653 1654== %%outfile ==[macro-outfile] 1655 1656La macro ``%%outfile`` produit le nom du fichier converti dans 1657le système. C'est pratique dans les zones CORPS et ENTETE. Cette macro 1658est une "soeur" de la [macro ""%%infile"" #macro-infile] et accepte les 1659mêmes chaînes de formatage. 1660 1661Exemples: 1662 1663 || Source | --> | Développement | 1664 | vous lisez le fichier ""%%outfile"" | --> | vous lisez le fichier %%outfile 1665 | txt2tags -t ""%%outfile(%e)"" -i ""%%infile"" -o ""%%outfile"" | --> | txt2tags -t %%outfile(%e) -i %%infile -o %%outfile 1666 1667Note: La macro et développée en "-" si la sortie est STDOUT 1668 1669----------------------------------------------------------------------- 1670 1671== %%toc ==[macro-toc] 1672 1673La macro ``%%toc`` produit la table des matières du document. 1674C'est pratique pour indiquer où vous voulez l'insérer. Vous pouvez 1675l'utiliser plusieurs fois et la placer à la fin du document. Ce guide 1676utilise ""%%toc"" pour positionner la table des matières. 1677 1678Différente des autres macros, cette macro n'accepte pas de chaîne de 1679format et a ses propres règles : 1680 1681- n'est valide que dans le CORPS du document 1682- doit être seule sur la ligne (des espaces avant et après sont 1683 autorisés) 1684- doit être utilisée avec l'option en ligne de commande --toc sinon elle 1685 sera ignorée 1686- le positionnement et le format par défaut sont désactivés quand la 1687 macro %%toc est trouvée 1688 1689 1690======================================================================= 1691 1692 1693 1694= Septième partie - maîtriser les réglages =[settings] 1695 1696Ces réglages sont des réglages spéciaux placés dans la zone 1697CONFIGURATION du document source qui modifient le comportement de la 1698conversion. Ces réglages sont tous optionnels. Les utilisateurs moyens 1699peuvent les ignorer. Mais ils créent une dépendance, si vous commencez à 1700les utiliser, vous ne pourrez plus vous en passer. 1701 1702Le lignes de réglage sont des //lignes de commentaire spéciales// 1703précédées d'une marque ("!") qui les rendent différents des commentaires 1704classiques. La syntaxe est aussi simple que le réglage des variables, 1705composés d'une clé et d'une valeur séparés par deux points (":"). 1706 1707 || %! clé : valeur | 1708 1709Détail de la syntaxe : 1710 1711- le point d'exclamation doit être collé avec le caractère commentaire 1712 sans espace ("%!") 1713- les espaces entre la clé et le séparateur (":") sont optionnels 1714- le mot clé et la valeur sont insensibles à la casse (pas de 1715 distinction majuscule-minuscule) 1716 1717Règles: 1718 1719- Ces réglages ne sont valides que dans la zone CONFIGURATION et sont 1720 pris comme des commentaires dans la zone CORPS du document 1721 1722- Si la même clé apparaît plusieurs fois dans la zone CONFIGURATION, la 1723 dernière occurrence sera celle utilisée. Exception : ``options, preproc et postproc`` sont cumulatifs. 1724 1725- Une ligne de réglage avec une clé non valide est considérée comme du 1726 commentaire 1727 1728- ces réglages ont priorité sur le fichier RC mais pas sur les options 1729 en ligne de commande 1730 1731 1732----------------------------------------------------------------------- 1733 1734== %!Target ==[setting-target] 1735 1736En utilisant le réglage ``target`` un format cible par défaut est défini 1737pour le document 1738 1739``` %!target: html 1740 1741Ainsi il suffit de lancer la conversion par : 1742 1743``` $ txt2tags file.t2t 1744 1745Et la conversion sera faite dans la cible spécifiée 1746 1747Le réglage ``target`` ne supporte pas de spécification d'option de 1748cible. La déclaration ``%!target(tex): html`` n'a pas de sens ... 1749 1750----------------------------------------------------------------------- 1751 1752== %!Options ==[setting-options] 1753 1754Écrire une longue ligne de commande avec plein d'options n'est pas 1755agréable et source d'erreur. Les réglages ``options`` permettent à 1756l'utilisateur de sauver les options de conversion dans le document 1757source. Cela garantit que le document source sera toujours converti de 1758façon identique avec les mêmes options. 1759 1760Il suffit d'écrire les options sans erreur de syntaxe comme vous le 1761feriez dans la ligne de commande sans mettre l'appel du programme 1762txt2tags, la spécification de cible et le nom du fichier source. 1763 1764Par exemple si vous tapez cette ligne de commande pour convertir votre 1765document : 1766 1767``` $ txt2tags -t html --toc --toc-level 2 --enum-title file.t2t 1768 1769Vous vous simplifiez la vie en tapant dans la zone CONFIGURATION les 1770options suivantes dans le document source : 1771 1772``` 1773%!target: html 1774%!options(html): --toc --toc-level 2 --enum-title 1775``` 1776 1777Et en ligne de commande vous tapez "``txt2tags file.t2t``", et vous 1778pouvez lancer directement la conversion à partir de votre éditeur favori 1779par exemple pour vi : 1780 1781``` :!txt2tags % 1782 1783----------------------------------------------------------------------- 1784 1785== %!Encoding ==[setting-encoding] 1786 1787Ce réglage est nécessaire aux non anglophones, qui utilisent 1788des caractères accentués ou d'autres détails spécifiques à la locale. Ainsi 1789l'encodage de la cible peut être personnalisé. 1790 1791Les valeurs valides pour le réglage de l'encodage sont les mêmes que 1792pour les document HTML comme //iso-8859-1// et //koi8-r//. Si vous 1793n'êtes pas sur consultez 1794[cette adresse http://www.iana.org/assignments/character-sets]. 1795 1796La cible LaTeX utilise des noms d'alias pour l'encodage. Ce n'est pas 1797un problème pour l'utilisateur car txt2tags traduit les noms de façon 1798interne. Quelques exemples : 1799 1800 || txt2tags/HTML | > | LaTeX | 1801 | windows-1250 | >>> | cp1250 | 1802 | windows-1252 | >>> | cp1252 | 1803 | ibm850 | >>> | cp850 | 1804 | ibm852 | >>> | cp852 | 1805 | iso-8859-1 | >>> | latin1 | 1806 | iso-8859-2 | >>> | latin2 | 1807 | koi8-r | >>> | koi8-r | 1808 1809 1810Si la valeur est inconnue elle est transmise telle quelle autorisant 1811à l'utilisateur des encodages spécifiques. 1812 1813----------------------------------------------------------------------- 1814 1815== %!PreProc ==[setting-preproc] 1816 1817Le réglage PreProc est un filtre d'entrée utilisé sur le document 1818source. C'est une ressource "trouve et remplace" appliquée après que la 1819ligne a été lue du document source et avant d'êtres traitée par 1820txt2tags. 1821 1822C'est utile pour définir des abréviations pour du texte tapé de façon 1823répétitive comme : 1824 1825``` 1826%!preproc JJS "John J. Smith" 1827%!preproc RELEASE_DATE "2003-05-01" 1828%!preproc BULLET "[images/tiny/bullet_blue.png]" 1829``` 1830 1831Ainsi l'utilisateur peut écrire une ligne comme : 1832 1833``` Bonjour, je suis JJB. Aujourd'hui nous sommes le RELEASE_DATE. 1834 1835Et txt2tags va "voir" la ligne suivante : 1836 1837``` Bonjour, je suis John J. Smith. Aujourd'hui nous sommes le 2003-05-01. 1838 1839Ce filtre agit entre l'auteur du document et la conversion txt2tags. 1840C'est une première conversion avant la "vraie" conversion. Il se 1841comporte comme un filtre Sed/Perl externe appelé de cette façon : 1842 1843``` $ cat file.t2t | preproc-script.sh | txt2tags - 1844 1845Le traitement de txt2tags commencera après que les substitutions PreProc 1846aient été appliquées. 1847 1848----------------------------------------------------------------------- 1849 1850== %!PostProc ==[setting-postproc] 1851 1852Le réglage PostProc est un filtre de sortie appliqué sur le document 1853converti. C'est une ressource "trouve et remplace" appliquée après le 1854traitement de txt2tags. 1855 1856Il est utile pour faire quelques finitions sur le document de 1857sortie, changer des marques ou ajouter un texte particulier. Des 1858exemples : 1859 1860``` 1861%!postproc(html): '<BODY.*?>' '<BODY BGCOLOR="green">' 1862%!postproc(tex) : "\\newpage" "" 1863``` 1864 1865Ces filtres changent la couleur de fond des pages HTML et enlèvent les 1866sauts de page en LaTeX. 1867 1868Les règles PostProc sont comme un filtre Sed/Perl externe appelé de 1869cette façon : 1870 1871``` $ txt2tags -t html -o- file.t2t | postproc-script.sh > file.html 1872 1873Avant que cette fonctionnalité ne soit intégrée, il était courant d'avoir 1874des petits scripts pour ajuster le résultat de txt2tags. 1875Ces scripts étaient en fait des commandes ``sed``, pour faire des 1876remplacements. 1877Maintenant ces chaînes de remplacement peuvent être sauvées avec le 1878document source, et le plus est l'utilisation possible des expressions 1879régulières pour trouver les motifs. 1880 1881----------------------------------------------------------------------- 1882 1883== %!Style ==[setting-style] 1884 1885- Utile pour les cibles HTML et XHTML, il définit un fichier CSS pour le 1886 document résultat. 1887 1888- utile pour la cible LaTeX pour charger des modules par 1889 ``\usepackage``. 1890 1891- le même résultat est obtenu par l'option en ligne de commande ``--style``. 1892 1893- l'option --style est plus forte que le réglage %!style. Si les deux 1894 sont utilisés l'option --style sera appliquée. 1895 1896 1897----------------------------------------------------------------------- 1898 1899== Définir un réglage pour une cible spécifique ==[setting-specific] 1900 1901Tous les réglages (sauf %!target) peuvent être liés avec une cible 1902spécifique en utilisant la syntaxe : ``%!clé(target): valeur``. De cette 1903façon vous pouvez définir plusieurs configurations pour différentes 1904cibles. 1905 1906Cela est particulièrement utile pour les filtres pre/postproc, mais est 1907applicable à tous les réglages. Par exemple définir des styles 1908différents pour HTML et LaTeX : 1909 1910``` 1911%!style(html): fancy.css 1912%!style(tex) : amssymb 1913``` 1914 1915Cela est également utile pour ajuster les options sur le document converti : 1916 1917``` 1918%!target: sgml 1919%!options(sgml): --toc 1920%!options(html): --style foo.css 1921%!options(txt ): --toc-only --toc-level 2 1922``` 1923 1924Dans cet exemple, la cible par défaut est sgml et générera une table des 1925matières. Si on lance la commande : ``txt2tags -t html file.t2t`` seules 1926les options html seront utilisées, ainsi le fichier converti utilisera 1927la feuille de style "foo.css" et n'aura pas de table des matières. 1928 1929----------------------------------------------------------------------- 1930 1931== Détails sur les filtres PreProc et PostProc ==[filters-details] 1932 1933- Les filtres sont des fonctions "trouve et remplace" (pensez Sed) 1934- les filtres ne sont pas "utilise le dernier trouvé", ils sont 1935 cumulatifs. Vous pouvez définir sans limite autant de filtres que vous 1936avez besoin. Ils seront appliqués dans l'ordre dans lequel ils sont 1937définis. 1938- différents des autres réglages, les filtres spécifiques pour une cible 1939 et ceux génériques sont appliqués. s'appliquant sur toutes les cibles. 1940Dans l'exemple suivant les deux filtres sont utilisés sur une cible HTML. 1941``` 1942%!postproc : this that 1943%!postproc(html): that other 1944``` 1945 1946- Les filtres doivent avoir deux arguments 1947 1948- les séquences spéciales comme ``\n`` (saut de ligne) et ``\t`` 1949 (tabulation) sont interprétés 1950 1951- pour supprimer du texte utilisez une chaîne vide 1952``` %!postproc: "chaîne non désirée" "" 1953 1954- pour éviter les problèmes, spécifiez toujours la cible quand vous 1955 utilisez PostProc pour changer les marques : ``%!PostProc(target): <ceci> <cela>`` 1956 1957- PreProc est appliqué avant que la ligne ait été lue et PostProc est 1958 appliqué après que la conversion a été faite. Attention à l'UUOC (Useless Use Of Cat : utilisation inutile de cat) : 1959 1960``` $ cat file.t2t | preproc.sh | txt2tags | postproc.sh 1961 1962- la première partie du filtre (la chaîne "cherche") n'est pas lue comme 1963 une chaîne mais comme une expression régulière. Si vous ne savez pas 1964ce que c'est, ne vous en souciez pas, vous pouvez ne jamais en avoir 1965besoin. Mais gardez en mémoire que vous devez "échapper" des caractères 1966pour l'utiliser. Échapper veut dire faire précéder la caractère par "\". 1967En voici la liste : 1968``` \* \+ \. \^ \$ \? \( \) \{ \[ \| \\ 1969 1970- les expressions régulières Python sont disponibles. Elles sont 1971 identiques aux Perl Regexes (PCRE). Exemple: Changer les marques en 1972gras "<B>" et"</B>" en "STRONG" en HTML : 1973``` %!postproc(html): '(</?)B>' '\1STRONG>' 1974 1975- les arguments des filtres peuvent être passés de 3 façons : 1976 + une simple chaîne comme FOO (sans espace) 1977 + une chaîne avec des apostrophes doubles comme "FOO" 1978 + une chaîne avec des apostrophes comme 'FOO' 1979 1980- Si votre motif a des apostrophes doubles, protégez le avec des 1981 apostrophes simples et vice-versa. Quelques exemples valides : 1982 1983``` 1984%!postproc: PATT REPLACEMENT 1985%!postproc: "PATT" "REPLACEMENT" 1986%!postproc: 'PATT' 'REPLACEMENT' 1987%!postproc: PATT "REPLACEMENT" 1988%!postproc: "PATT" 'REPLACEMENT' 1989``` 1990 1991 1992======================================================================= 1993 1994 1995 1996= Huitième partie - magie noire =[black-magic] 1997 1998Ce chapitre n'est pas recommandé aux débutants. Il montre comment faire 1999des choses étranges avec les filtres txt2tags, en utilisant des 2000expressions régulières et des motifs complexes. 2001 2002 **ATTENTION** : les manipulations suivantes ne sont pas 2003 encouragées et peuvent casser des choses. Un partie du texte de 2004 sortie peut être perdu lors de la conversion, n'apparaissant pas dans le 2005 document de sortie. N'utilisez ces trucs que si vous en avez réellement 2006 besoin et que savez ce que vous faites. 2007 2008 || Les filtres sont une fonctionnalité puissante mais dangereuse | 2009 2010 || De mauvais filtres génèrent des résultats inattendus. | 2011 2012SVP ne l'oubliez pas. 2013 2014----------------------------------------------------------------------- 2015 2016== Insérer plusieurs lignes avec %!PostProc (comme des règles CSS) ==[postproc-multiline] 2017 2018Dans les filtres, le motif de remplacement peut inclure plusieurs lignes 2019en utilisant la chaîne de coupure de ligne ``\n``. 2020 2021Elles peuvent être utiles pour inclure de courtes règles CSS dans une 2022cible HTML, supprimant le besoin d'un fichier supplémentaire. 2023 2024``` 2025%!postproc: <HEAD> '<HEAD>\n<STYLE TYPE="text/css">\n</STYLE>' 2026%!postproc: (</STYLE>) 'body { margin:3em ;} \n\1' 2027%!postproc: (</STYLE>) 'a { text-decoration:none ;} \n\1' 2028%!postproc: (</STYLE>) 'pre,code { background-color:#ffffcc ;} \n\1' 2029%!postproc: (</STYLE>) 'th { background-color:yellow ;} \n\1' 2030``` 2031 2032Tous ces filtres sont liés au premier, en remplaçant une chaîne qui a été 2033insérée. Ainsi un simple "<HEAD>" se change en : 2034 2035``` 2036<HEAD> 2037<STYLE TYPE="text/css"> 2038body { margin:3em ;} 2039a { text-decoration:none ;} 2040pre,code { background-color:#ffffcc ;} 2041th { background-color:yellow ;} 2042</STYLE> 2043``` 2044 2045----------------------------------------------------------------------- 2046 2047== créer un contenu spécifique à la cible avec %!PostProc ==[target-specific-contents] 2048 2049Quelquefois vous devez inclure du texte dans une seule cible, mais pas 2050dans les autres. Ce comportement peut être obtenu en utilisant des astuces 2051de PreProc. 2052 2053L'idée est d'inclure un texte spécial en commentaire dans le document 2054source, mais de le marquer de telle façon qu'un filtre spécifique à une 2055cible le décommente. 2056 2057Par exemple si un paragraphe doit être ajouté uniquement dans la cible 2058HTML comme cela : 2059 2060``` 2061%html% Cette page HTML est générée par [txt2tags http://txt2tags.org]. 2062%html% voir le fichier texte source [ici source.t2t]. 2063``` 2064 2065Comme ces lignes commencent par ``%`` ce sont des lignes de commentaire 2066et seront ignorées. En ajoutant ce filtre : 2067 2068``` %preproc(html): '^%html% ' '' 2069 2070La chaîne "%html% est supprimée et ces lignes deviennent visibles, n'étant plus 2071des commentaires. Comme une cible est spécifiée ce filtre ne sera actif 2072que pour générer du html. 2073 2074----------------------------------------------------------------------- 2075 2076== Changer les marques de txt2tags avec %!PreProc ==[creating-marks] 2077 2078Si l'utilisateur est un spécialiste en expressions régulières, il peut 2079personnaliser la syntaxe du document source en changeant les marques par défaut en 2080quelque chose de plus "confortable". 2081 2082Par exemple une tabulation en début de ligne est la marque de la 2083citation. Si cela ne plaît pas à l'utilisateur, ou que son éditeur a un comportement bizarre avec 2084les tabulations, il peut définir une nouvelle marque pour les citations. 2085Par exemple ">>>". Il ajoute ce simple filtre : 2086 2087``` %!PreProc: '>>> ' '\t' 2088 2089Et dans le document source, la citation sera indiquée par : 2090 2091``` 2092>>> Ceci est une citation. 2093>>> L'utilisateur a défini cette marque. 2094>>> Mais elles seront converties en tabulations par PreProc. 2095``` 2096 2097Avant que la conversion ne commence, les marques ">>>" seront converties 2098en tabulations et txt2tags reconnaîtra le format de citation 2099 2100 **ATTENTION** : des règles PreProc peuvent changer toute la 2101 syntaxe des marques, générant éventuellement des conflits entre les 2102 marques. Soyez très attentif quand vous faites cela. 2103 2104======================================================================= 2105 2106The End. 2107 2108[../../img/t2tpowered.png]