Regles reconnues par le convertisseur

la PREMIERE ligne du ducument ASCII devient le titre du document HTML.

Consequences :

• cette premiere ligne est encadree par le tag html <H1>...</H1>,
• quand le document est charge, ce titre devient le titre de la fenetre qui contient le navigateur (en general),
• ce titre est associe au nom du fichier dans le fichier list_of_links, et txt2html mettra par defaut ce titre comme texte du lien hypertexte pour toutes les directives ( cf: nom_fichier).

Pour faire simple, il suffit de commencer une ligne par une parenthese fermante pour qu'elle soit reconnue comme un titre.

A) titre en chef (il n'y a pas que les chiffres dans la vie)
A.1) sous titre
A.1.1) desole, je ne gere pas encore les sous-sous-titre !

Toute ligne separee par au moins DEUX RETURN de la ligne precedente devient un paragraphe, ce qui genere le tag HTML <p>.

Comme HTML utilise des caracteres speciaux pour faire sa mise en page, txt2html convertit d'abord les caracteres suivants :

• & devient &amp,
• " devient &quot,
• < devient &lt,
• > devient &gt.

Il manque... les accents !

Ca se complique : quel jeu de caracteres utilisez vous sur votre machine preferee ?

Si votre machine travaille en ISO-8859, vous pouvez taper des caracteres accentues, il y a des fortes chances pour qu'ils apparaissent tels-quels (sans conversion). Sinon, pour faire propre, il faut respecter les directives HTML sur les caracteres speciaux :

• é doit etre represente par &#233
• è doit etre represente par &#232
• ê doit etre represente par &#234
• etc...

Pour identifier un document, inserez la directive ( origin) dans votre fichier ASCII. L'URL du fichier sera insere dans le document HTML final, ainsi que la date du fichier.

Si vous communiquez des versions imprimees de vos documents, cette reference permettra au lecteur curieux d'aller a la peche, si il pense que la date qui figure sur sa version papier est suffisamment ancienne pour que le document ait ete modifie depuis. A condition qu'il n'hesite pas a jouer du reload selon la configuration du cache de son navigateur...

Ci-dessous, voici la signature de ce document : source :
  http://192.9.210.24/tws/txt2html/txt2html_4.html
  1999-Aug-25   21:48

Pour inserer un bas de page standard, utilisez la directive ( footer).

NOTE : a ce jour, cette directive est TRES rudimentaire, car elle ne sait inclure qu'un seul modele global de pied de page. Il y a longtemps que je me dis que je vais modifier txt2html pour inserer le fichier .footer si il existe, ou alors autoriser la directive (footer: nom_fichier). Wait and see...

Inutile de la chercher, c'est un projet... qui nececite une passe supplementaire dans txt2html. Je cherche quelquechose d'astucieux.

Idee : la directive (contents) est remplacee par des liens sur tous les titres et sous-titres. Il suffit de faire des liens relatifs #numero, en inserant le contenu du titre comme texte du lien.

YAKA... c'est pour bientot.

C'est aussi un projet, et ja ne sais pas sous quelle forme la placer dans le document pour que ca ne soit pas trop laid.

Idee : la directive (navbar) est remplacee par trois icones Previous-Up-Next, qui permettre d'avancer rapidement en relatif dans le document.

A priori, ces icones doivent etre a proximite de chaque ligne de titre, mais je ne trouve pas ca tres beau. Partout, c'est utile mais c'est laid. au debute et/ou a la fin d'un document, ca passe mieux mais c'est moins pratique.

A voir...

BOUM !

Comme vous le savez sans doute, un GROS document est penible :

• a charger,
• pour naviguer,
• a lire !

Imaginez : vous ecrivez un document XXX.txt, contenant 7 chapitres. Vous inserez la directive (split), et txt2html va faire automatiquement :

• creation du repertoire XXX,
• creation du fichier XXX/XXX.html, qui contient le titre et les liens vers tous les titres et sous-titres,
• creation des documents XXX/XXX_1.html, ..., XXX/XXX_7.html, et insertion des liens de navigation relative (dans le genre : prev-up-next).

Si l'aspect general du document (ex: couleur des caracteres) ne peut pas etre modifie (pour l'instant), l'aspect du texte dans le document HTML n'est pas uniforme. Heureusement pour le lecteur...

Comme ces outils ont ete concus pour faire de la doc technique, la mise en valeur des informations importantes est revenue... aux termes techniques, pardi. Pour mettre en valeur les mots qui servent a faire de l'esprit, il reste les caracteres italiques, qui ne vont pas si mal.

Pour montrer au lecteur que le mot qui se trouve dans la doc est un terme informatique reel (et pas une francisation d'un terme informatique), il faut l'encadrer avec des quotes (simples). Ce qui genere le tag HTML <b>..</b> (bold).

Pour les Perlistes acharnes, voila la regle de reconnaissance de mots encadres par des quotes pouvant contenir une apostrophe mais pas une ponctuation. Si vous avez une idee pour la simplifier...

s/^'([\S\.\/][^\']*[\S\/]*)'([\<\n\.!, ])/ '<b>$1<\/b>'$2/g;
s/\s'([\S\.\/][^\']*[\S\/]*)'([\<\n\.!, ])/ '<b>$1<\/b>'$2/g;
s/\s'([\w ]+\'[\w ]+)'/ '<b>$1<\/b>'/g;

Pour insister sur ce qui est important, je vous conseille de METTRE EN MAJUSCULES pour dissuader le lecteur de ne pas faire autre chose que ce que vous venez de lui expliquer...

Pour mettre en valeur le petit quelque chose qui se cache dans votre phrase, rien de tel que des italiques. Ce qui genere un tag HTML <i>..</i> (italic).

C'est tellement simple, que tout exemple est inutile.

Intuitivement, quand on redige un document dans lequel on cherche a enumerer des informations, il y a de fortes chances :

• pour que la phrase qui decrit le contenu de la liste se termine par un :,
• que tous les elements de cette liste soient presentes a la ligne,
• que chaque ligne commence par un grigri qui veut dire que c'est un nouvel element dans la liste.

ceci est une liste :
 - premier ligne
    - deuxieme ligne (peu importe le nombre d'espaces en debut de ligne)
	- un TAB en debut de ligne...

L'utilitaire txt2html genere des listes ENUMEREES (tag <ul>..</ul>) en s'appuyant sur plusieurs regles :

• une ligne se termine par : puis RETURN,
• la ligne suivante commence par un - (peu importe le nombre d'espaces ou de tabulations),
• toutes les lignes suivantes qui commencent par un - seront incorporees dans la liste, peu importe le nombre de RETURN entre les lignes.

• un titre est equivalent a une ligne terminee par un : !...
• vous en avez la demonstration dans le chapitre ci-dessous.
• cette regle est utilisee entre autres par l'utilitaire create_automatic_index.pl, qui genere les fichiers index.html dont les liens contiennent les titres des documents .html et les header des sous-repertoires si ils existent.

Ici encore, on se refere a l'intuition pour deviner ce qui doit etre fait...

Si on cherche a enumerer des informations en les numerotant pour les classer, il y a de fortes chances :

1. pour que la phrase qui decrit le contenu de la liste se termine par un :,
2. que tous les elements de cette liste soient presentes a la ligne,
3. que chaque ligne commence par un grigri numerote, qui veut dire que c'est un nouvel element dans la liste.

ceci est une liste :
 1 - premiere ligne
2- deuxieme ligne (peu importe le nombre d'espaces en debut de ligne)
	3- un TAB en debut de ligne (c'est aussi de l'espace pour Perl)

L'utilitaire txt2html genere des listes ORDONNEES (tag <ol>..</ol>) en s'appuyant sur plusieurs regles :

• une ligne se termine par : puis RETURN,
• la ligne suivante commence par un NOMBRE puis - (peu importe le nombre d'espaces ou de tabulations)(peu importe la valeur du nombre),
• toutes les lignes suivantes qui commencent par un - seront incorporees dans la liste, peu importe le nombre de RETURN entre les lignes.

NOTE 1 : A ce stade du developpement, l'option sous-liste n'a pas non plus ete retenue.

• sachant que le navigateur HTML se charge de faire la mise en page tout seul,
• sachant que toute tentative de mise en page a base de tabulation ou d'espace se retrouvera reduite a un seul espace,
• sachant que toute ligne terminee par un RETURN sera agglomeree a la ligne suivante dasn le meme paragraphe,

Comme cette fois ci, il n'y avait aucune justification fumeuse du type c'est comme ca que vous l'auriez fait, il fallait bien inventer une regle :

• tout texte compris entre les lignes <<< et >>> doit etre affichee telle-quelle.

En langage HTML, c'est une horizontal rule.

txt2html detecte les lignes qui contiennent beaucoup de caracteres susceptibles de servir de separateur dans du texte : -, _, = ou #.

La ligne du fichier ASCII qui contient beaucoup de ces caracteres a la suite est entierement remplacee par un tag <hr>, SAUF dans une zone <pre>...</pre>, cela va de soi.

Voici un exemple protege, suivi de sa transformation en <hr> par txt2html :

 -------------------------------------------- ce texte sera efface

Quand txt2html analyse le fichier ASCII, il essaye au juge de reproduire ce qu'il voit.

Si votre fichier ASCII contient un grand nombre de caracteres RETURN entre deux paragraphes, c'est sans doute car vous vouliez mettre en evidence une separation.

Par defaut, la separation des paragraphes a une taille constante, car c'est le navigateur HTML qui se charge de la mise en page des tags <p>

Si vous voulez inserer des RETURN dans un editeur HTML, vous utilisez le tag <br>. txt2html aussi, et il utilise la loi suivante : nb_BR = int((nb_RETURN - 2) / 2).

Deux caracteres RETURN, c'est la facon classique de marquer les paragraphes.

Trois caracteres RETURN : pas de difference.

Quatre caracteres RETURN : un <br> insere entre les paragraphes.

A l'origine de tout ce bricabrac, il y avait le besoin de faire la documentation _technique_ d'une plate-forme heterogene, pour Mr tout-le-mode, et sur tout ou presque (du partitionnement d'un disque systeme a la facon d'ecrire une macro Excel).

Comme l'ecriture d'un MEGA-MANUEL-D'UTILISATION aurait rendu chevre le plus patient des managers, qu'aucun utilisateur n'aurait consulte le document, et qu'il aurait ete impossible d'en sortir une version papier a jour, il ne restait plus que la documentation vivante.

Meme si vous defendez FrontPage ou Word 97 ou AolPress (plutot chouette, ce freeware !), vous avez besoin DE TEMPS pour faire votre doc. Il est impossible de l'ecrire sur un coin de table et de la deposer dans l'arborescence Intranet pour esperer qu'elle sera automatiquement incorporee au tas. Si vous avez la chance d'avoir un moteur de recherche sur votre site, au mieux elle sera accessible apres la mise a jour de l'index, mais elle ne sera pas hypertexte.

Comme les editeurs hypertexte ne permettent pas de rediger rapidement de la doc (entre le temps de chargement de l'editeur et le temps passe a mettre en forme et a brancher les liens...), il y avait la solution alternative : laisser a la machine le soin de faire le gros du travail.

L'ambition de txt2html est de retrouver A LA PLACE du redacteur de la doc l'emplacement du document auquel il fait reference a priori. Si plusieurs documents portent exactement le meme nom dans l'arborescence, txt2html retient celui qui offre le maximum de vraissemblance, en raisonnant utilisant sur les chemins d'acces.

La directive universelle (et assez intuitive) de lien hypertexte est cf:. Elle peut etre consommee a plusieurs sauces, mais c'est toujours le meme principe de base.

Comme vous allez rediger vous aussi votre doc sur un coin de table, vous aurez le droit a l'erreur. Si txt2html NE TROUVE PAS le lien demande, il insere dans le document .html un lien de type mailto: pour l'administrateur du site, que l'utilisateur est invite a utiliser pour signaler qu'il y a un couac. Que vous mettrez a jour en 30 secondes, bien sur...

Si vous avez une regle de nommage pseudo-normalisee pour tous vos documents, vous devez pouvoir y faire reference de tete, car le nom du fichier doit correspondre avec son contenu.

Usage: ( cf: nom_fichier), sans l'extension .html ou .htm (sans espace entre la parenthese et cf).

Il suffit de faire reference a l'ancrage que vous avez declare. Le lien ci-dessus a ete genere en substituant la directive ( cf: #quatrieme dimension).

Si vous avez une memoire d'elephant, et si vous vous souvenez avoir declare un point d'ancrage dans un autre fichier, vous pouvez y faire pointer un lien en precisant le nom du point d'ancrage a la suite du nom du fichier. Si l'ancrage n'existe pas, le navigateur vous laissera au debut du fichier, et ce n'est deja pas si mal...

Usage : ( cf : #ancrage) ou ( cf : nom_fichier#ancrage) (sans espace entre la parenthese et cf).

Comme vous n'etes pas oblige de prendre pour argent comptant ce que txt2html va substituer a votre directive de lien, il suffit de surcharger avec du texte.

Usage : '( cf : nom_fichier, surcharge)', '( cf : #ancrage, surcharge)' ou '( cf : nom_fichier#ancrage, surcharge)' (sans espace entre la parenthese et le cf).

Quoi de plus naturel que des copies d'ecrans pour illustrer votre propos !

Comme les navigateurs reconnaissent par defaut les types GIF et JPEG, moi aussi !

L'automate construit la liste de toutes les images disponibles en retenant les extensions correspondantes .gif, .pjg ou .jpeg. Si vous avez des images dans d'autres formats :

Creez un micro-document qui fait reference a la grosse image avec la directive inc:. Le chargement de ce micro-document provoquera le chargement de la grosse image.

Dans votre document, faites reference au micro-document, et debrouillez-vous pour inclure la version miniature de la grosse image a proximite du lien. Ceci est un exemple de micro-document, dont le titre incite a cliquer tout de suite :

Surchargez le lien avec la directive inc: nom_image, et pointez sur une mini-image. Elle sera rapide a charger. Et si c'est la version miniature d'une grosse image, ca fait vraiment pro.

Pour ce type de fichier, il faut preciser le nom complet avec l'extension. txt2html se charge de trouver le chemin qui offre le maximum de vraissemblance.

Usage : file: nom_fichier ou 'file: nom_fichier, surcharge en clair'.

Vous pouvez pointer sur n'importe quoi, sauf sur un fichier .html, car il est dans la liste utilisee par cf:.

Si vous pointez sur une image, il faut preciser son extension complete (a la difference de la directive inc:).