VERSION

Cette documentation décrit l'utilisation de freetable version 2.3.

Si vous utilisez une autre version, certaines différences peuvent apparaitre.

SYNOPSIS

freetable [options] fichier

ou

freetable [options]

Options:

-h, --help Affiche cette aide et stoppe

-V, --version Affiche seulement le numéro de version

-c, --comment Affiche un commentaire avant chaque
                  cellule pour indiquer son emplacement

-b, --no-nbsp N'ajoute pas   dans les cellules
                  vides pour modifier le rendu 3D

-w, --warning Affiche un commentaire avant chaque
                  tableau, indiquant que le tableau est
                  généré automatiquement et ne doit pas
                  être édité

-l, --location Remplace les indicateurs "<row>" (ligne)
                  et "<col>" (colonne) à l'intérieur des
                  tableaux par la position de la cellule
                  courante.

-m, --macro [program]
                  Avec cette option, le contenu des
                  cellules est passé à un pré-processeur,
                  qui est m4 par défaut

AVERTISSEMENT SUR LA SÉCURITÉ

 N'UTILISEZ PAS DE MACRO-PROCESSEUR SUR UN
 FICHIER SOURCE DONT VOUS N'ÊTES PAS SÛR.
 CELA POURRAIT COMPROMETTRE LA SÉCURITÉ DE
 VOTRE SYSTÈME

Plus d'informations dans la documentation de m4, en particulier la commande syscmd.

DESCRIPTION

Ce programme est un logiciel libre qui remplace wwwtable.

HTML est un langage agréable, mais avec un énorme défaut : les tableaux. J'ai passé de nombreuses heures à lire le code source que j'avais tout juste écrit pour essayer de comprendre quelle cellule dans le code source correspond à ce qui est affiché dans le navigateur.

Si cela vous rappelle une expérience similaire, alors lisez cette documentation et votre peine ne sera plus qu'un mauvais souvenir.

Le programme reçoit en entrée du code HTML provenant soit de l'entrée standard (stdin), soit d'un fichier. Il recherche alors les caractères suivants, qui annoncent l'ouverture d'un tableau:

   <wwwtable [options]>

Il analyse le contenu jusqu'à détecter la fin du tableau, affiche le code HTML correspondant puis continue le traitement avec les tableaux suivants.

SYNTAXE

La syntaxe est très simple:

    wwwtable:
    <wwwtable [wwwtable_options]>
    [preambule]
    [cellule]
    [cellule]
    ...
    </wwwtable>

La chaîne optionnelle wwwtable_options est passée telle quelle comme attribut de la balise "<table>". Le préambule n'est pas traité, il peux contenir n'importe quel code HTML, il sera inséré au début du tableau.

Les cellules sont soit des cellules normales (balise "<td>"), soit des cellules d'en-tête (balise "<th>"). Il en était ainsi jusqu'aux versions 1.x, voyez la prochaine section pour une autre méthode d'adressage des colonnes.

    cellule normale:
    (ligne,colonne) options_cellule
    contenu_cellule
    cellule en-tête:
    ((ligne,colonne)) options_cellule  
    contenu_cellule

Le texte contenu dans options_cellule est passé comme attribut de la balise de la cellule. Les mots-clés colspan et rowspan sont interprétés pour générer des tableaux corrects.

Le contenu des cellules (contenu_cellule) est quelconque, il peut même contenir d'autres wwwtables !

Si vous utilisez l'option -m (ou son synonyme --macro), le contenu des cellules sera passé comme entrée standard de la commande m4(1), après avoir remplacé les chaînes de caractères <row> (resp. <col>) par le numéro de ligne (resp. colonne) de la cellule.

Les indices de ligne et colonne sont soit des nombres, soit un adressage relatif, soit une expression régulière qui désigne un ensemble de cellules. À la différence de wwwtable, freetable peut aussi utiliser des expressions régulières dans les cellules d'en-tête. Un autre ajout est la possiblité d'utiliser * à la place de .*.

L'adressage relatif est de la forme :

= ou vide : même indice que la cellule précédente

+ ou +X : incrémente l'indice de X (défaut: 1)

- ou -X : décrémente l'indice de X (défaut: 1)

Lorsqu'une cellule est désignée par plusieurs expressions, à la fois les options et le contenu de chaque cellule sont ajoutés.

Si vous n'utilisez que des expressions régulières, il faut indiquer au programme la position de la dernière cellule.

    <wwwtable>
    (*,1)
    cellules de la colonne 1
    (1,*)
    cellules de la ligne 1
    (4,4)
    </wwwtable>

AUTRE SYNTAXE D'ADRESSAGE

Il n'est pas très pratique de spécifier les numéros de cellules avec des expressions régulières. Freetable 2.0 a introduit deux nouvelles méthodes d'adressage, qui peuvent être utilisées sur les cellules normales et les cellules d'en-tête.

Une compatibilité totale avec les versions antérieures est assurée. Pour cette raison, il n'était pas question de modifier la syntaxe actuelle. Malheureusement, vous ne pouvez pas spécifier les lignes en utilisant une syntaxe d'adressage, et les colonnes avec une autre syntaxe. Pour remédier à ce problème, les deux méthodes sont très souples, si bien que vous ne devriez jamais avoir à les mélanger, et elles vous permettent d'utiliser =, +, -, +X, -X et la chaîne vide de la même façon qu'avec freetable 1.x.

De plus, ces nouvelles méthodes déterminent automatiquement la dernière cellule, contrairement à l'adressage par des expressions régulières.

BORNES EXPLICITES

    (bornes_ligne;bornes_colonne) options_cellule
    contenu_cellule

La syntaxe pour bornes_ligne et bornes_colonne est de la forme: 1-2,4-7,9,12. Les doublons sont éliminés. Pour les besoins de l'adressage relatif, le dernier nombre est utilisée. Ainsi, quand vous écrivez

    (1-100,32;1)
    foo
    (+,)
    bar

la cellule (33,1) contiendra « foo bar » et toutes les autres seulement « foo ».

CODE PERL QUELCONQUE

    ({code pour les lignes},{code pour les colonnes}) options_cellule
    contenu_cellule

Vous pouvez utiliser n'importe quel code Perl qui tient sur une seule ligne du moment qu'il est repéré oar notre expression régulière (pas très futée) et renvoie une liste. Il n'est malheureusement pas possible de détecter n'importe quel code de Perl grâce à une expression régulière, mais du moment qu'il ne contient pas les séquences },{ et }), cela devrait marcher. Exemple :
    <wwwtable>
    ({grep {$_%3 == 1} 1..100},{1..2,4})
    foo
    </wwwtable>

va créer un tableau de 100 lignes par 4 colonnes avec « foo » dans les premières, deuxième et quatrième colonnes de chaque ligne dont le numéro vaut 1 modulo 3.

Si vous voulez mélanger cet adressage avec le précédent, il suffit de remplacer - par .. dans la définition des bornes, et l'entourer par des accolades { et }.

Si vous voulez mélanger cet adressage avec une expression régulière, vous pouvez remplacer cette dernière par {grep {/expression/} min..max}. Il est malheureusement obligatoire de spécifier explicitement la dimension du tableau.

INCOMPATIBILITÉS AVEC WWWTABLE

Les utilisateurs de wwwtable qui décident de passer à freetable devraient lire cette section. La majorité des incompatibilités proviennent du traitement des expressions régulières. Il faut aussi noter que wwwtable ne permettait ni le remplacement automatiques des numéros de lignes et de colonnes, ni l'utilisation d'un pré-processeur.

L'option -w a le comportement opposé. Nous n'écrivons aucun commentaire par défaut, et -w ou --warning est utilisée pour les ajouter.

Les cellules d'en-tête peuvent être définies avec des expressions régulières, par exemple

    ((1,*))

ce qui était impossible avec wwwtable.

Les indices des axes sont 100% orthogonaux, ce qui signifie qu'avec le code suivant

    (*,1) width=30
    (*,2) width=35
    (*,3) width=40
    (=,=)
    Foo

Foo va apparaitre en 3e colonne, et si vous vouliez qu'il soit en 1e position, il faut écrire

    (*,1) width=30
    (*,2) width=35
    (*,3) width=40
    (=,1)
    Foo

ou

    (*,) width=30
    (*,+) width=35
    (*,+) width=40
    (=,1)
    Foo

Avec freetable 2.0, deux méthodes complètement nouvelles d'adressage des cellules ont été introduites. Elles sont totalement incompatibles avec wwwtable.

AUTEUR

Tomasz Wegrzanowski <[email protected]>

Traduction française de la documentation: Denis Barbier <[email protected]>