PageRenderTime 126ms CodeModel.GetById 11ms app.highlight 96ms RepoModel.GetById 2ms app.codeStats 0ms

/doc/French/userguide-fr/userguide-fr.t2t

http://txt2tags.googlecode.com/
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]