Le système de document Bocal

Le système de document Bocal

Copyright (C) 2007 Edouard Thiel <Edouard.Thiel@lif.univ-mrs.fr>

01 dec 2008


Le langage Boc est un langage à balises, qui permet de générer du Html et du Latex avec le compilateur bocal.
Ce document présente la syntaxe et les possibilités du langage.

\thispagestyle{empty} \rule{\linewidth}{1mm} \\[10mm] \centerline{\Huge\sc Le système de document Bocal } \\[8mm] \rule{\linewidth}{1mm} \vfill \begin{center} {\Huge\bf Tutorial }\\[20mm] {\Large Edouard Thiel } \end{center} \vfill \hfill {\large 1er décembre 2008 } \newpage
Retour à la page d'accueil

Structure d'un document Compilation Le langage Boc est un langage à balises dédié à la rédaction de documentation de logiciels. Le compilateur s'appelle bocal, et il est capable de générer du Html et du Latex. Le source et l'exécutable du compilateur sont situés dans le répertoire src.

Le compilateur est écrit en lex, et fonctionne en plusieurs passes : il y a toujours une passe initiale, où bocal mémorise la structure logique du document (titres), les labels des titres, les macros, etc. Puis il y a une passe pour générer le Html, et/ou une passe pour générer le Latex.

La syntaxe pour appeler bocal est : bocal [--index] [--macro] [--html ] [--latex ] L'option --index affiche dans la console la table des matières et les labels des titres ; l'option --macro affiche le contenu des macros en mémoire.

Document principal Le document principal commence par \ et finit par \.

Le corps du document est composé de texte, entrecoupé de sections qui lui donnent sa structure logique.

Le texte est une suite de caractères et de balises Boc délimités par \< et \>.

Sections Il y a quatre niveaux logiques de section, numérotés de 1 à 4 ; ils correspondent en Latex à chapter, section, subsection et subsubsection.

On commence un chapitre par \Titre du chapitre\, une section par \Titre de la section\, etc.

La numérotation des sections est automatique, et chaque section produit automatiquement une entrée dans la table des matières.

Fichiers inclus On peut inclure des fichiers Boc par la commande : \. Le découpage du document en fichiers Boc n'a rien à voir avec la structure logique du document, qui est établie à partir des sections.

Table des matières Pour faire apparaître la table des matières complète, on fait \ ; pour avoir l'index des chapitres on fait \.

Les chaînes "toc-long" et "toc-short" sont utilisés pour les références (voir ).

Fichier résultat unique ou multiple Après compilation, le résultat en Latex est toujours un fichier unique.

En Html on a la possibilité de demander un fichier unique ou un fichier par chapitre. Par défaut le compilateur bocal est en mode fichier unique ; pour passer en mode fichiers multiples il suffit d'insérer quelque part la balise \.

Le texte Paragraphes Comme en html, on termine une ligne par un \ et un paragraphe par \.

Attributs Les balises suivantes permettent de mettre le texte en \gras\, en \italique\ ou en \code\.

Indice ou exposant On met le texte en indice ou en exposant en tapant indice ou exposant.

Texte centré On centre le texte en tapant

texte centré
, ce qui donne :

texte centré

Espace On génère un espace insécable avec \.

Césure On rajoute une possibilité de césure dans un mot avec la balise \<-\>. Cette commande est sans effet en Html ; elle consiste à rajouter un \\- en Latex.

Si un paragraphe déborde et qu'on n'a pas la possibilité de rajouter des césures, on peut mettre la balise \ au début du paragraphe. Cette commande est sans effet en Html ; elle consiste à rajouter un \\sloppy en Latex.

Lettres accentuées Les lettres accentuées sont automatiquement traduites : àâä éèêë îï ôö ùûü ÀÂÄ ÉÈÊË ÎÏ ÔÖ ÙÛÜ

Caractères spéciaux Les seuls caractères spéciaux du langage Boc sont \< , \> et \\ . Pour les produire il faut taper \\\< , \\\> ou \\\\ .

Symboles Les autres caractères sont automatiquement traduits, par exemple : $ & % # _ { } ~ .

Commentaires On peut mettre du texte en commentaire en le plaçant entre \ et \>. Par exemple, \. Les commentaires n'apparaissent pas en Html ni en Latex.

Les environnements Verbatim Pour insérer du texte non interprété contenant par exemple des balises Boc, on encadre le texte entre \ et \. Le résultat sera traduit en verbatim Html ou Latex.

Par exemple, \du texte \italique\\
produit : du texte italique.

Code Html On peut insérer du code Html, qui ne figurera que dans le fichier Html produit ; il suffit de l'encadrer entre \ et \.

Par exemple, \du texte \italique\\
produit : du texte italique.

Code Latex On peut insérer du code Latex, qui ne figurera que dans le fichier Latex produit ; il suffit de l'encadrer entre \ et \.

Par exemple, \du texte {\\em italique}\
produit : du texte {\em italique}.

Le test if L'environnement if permet d'insérer du texte qui n'apparaît que dans un type de fichier précis, voire n'apparaît pas du tout : le texte encadré entre \ et \ n'apparaît pas (c'est une façon de commenter du texte) ; entre \ et \ le texte n'apparaît qu'en mode Html ; entre \ et \ le texte n'apparaît qu'en mode Latex.

Attention, pour le moment on ne peut pas emboiter plusieurs if.

Listes On peut créer deux types de listes : les listes numérotées et les listes non numérotées. Une liste numérotée est délimitée par les balises \ et \. Une liste non numérotée est délimitée par les balises \ et \. Chaque entrée d'une liste commence par \. Par exemple la liste ordonnée :

  1. Oranges ;
  2. pêches.
est obtenue avec le code
  1. Oranges ;
  2. pêches.
tandis que la liste non ordonnée :
  • Pommes ;
  • poires.
est obtenue avec le code
  • Pommes ;
  • poires.
Code préformaté On peut faire apparaître un bout de code préformatté, qui apparaît en police code avec un espacement fixe, et un fond coloré ; il suffit d'encadrer le paragraphe entre \ et \. Par exemple :

\
void Exemple1 (int i, char *s)
{
printf ("i = %d , s = %s\\n", i, s);
}
\

affiche : void Exemple1 (int i, char *s) { printf ("i = %d , s = %s\n", i, s); } Ceci correspond au style par défaut \. Les autres styles sont :

\ void Exemple1 (int i, char *s) { printf ("i = %d , s = %s\n", i, s); } \ void Exemple1 (int i, char *s) { printf ("i = %d , s = %s\n", i, s); } \ void Exemple1 (int i, char *s) { printf ("i = %d , s = %s\n", i, s); } Listing Pour faire apparaître un listing avec un habillage coloré, il suffit de mettre \.

Par exemple, voici ce que donne \ :

On peut aussi donner le numéro de ligne de départ, ou encore le numéro de ligne de départ et de fin, avec \ ou \. Labels, références et liens Labels On peut donner un label à une section, comme en Latex, puis y faire référence dans le document. Pour donner un label à une section on fait \Titre du chapitre\, ou \Titre de la section\, etc. Le label doit être une chaîne sans blancs. Si un label n'est pas donné, bocal donne un label par défaut pour que les mécanismes internes fonctionnent.

Pour voir tous les labels d'un document on appelle bocal avec l'option --index.

Références Pour insérer dans le texte le numéro correspondant au label d'une section, il suffit de faire \. De même on peut insérer le titre d'une section avec « \ » (les guillemets sont purement esthétiques).

Liens Comme en Html, on insère un lien sur du texte par : \texte souligné\. En Latex, le texte apparaît sans aucune autre indication.

On peut aussi rajouter une ancre (invisible) : \texte ancré\.

Liens muets Une écriture équivalente de \Texte\ est \ : le résultat est identique si "mon-url" n'est pas vide. Dans le cas inverse, le texte apparaît mais non souligné. Cette fonctionnalité est exploitée pour afficher « Précédent » ou « Suivant » avec ou sans lien si on est en début/fin de document ou non.

Liens sur labels On peut mettre un lien sur un numéro de section généré par une référence, ou sur un titre, ou sur les deux :
\ produit le numéro,
\ produit le titre,
\ produit le numéro + titre,
\ produit un lien avec un autre texte.

Les variables Principe Les variables de Boc ont la forme $identificateur ; on les place dans des balises, et elles sont substituées par leur valeur au moment de la compilation du document Boc.

Variables prédéfinies Les variables prédéfinies sont $thecur, $thenext, $theprev, $thecurt1, $thenextt1, $theprevt1, $thecurt2, $thenextt2, $theprevt2. Chacune de ces variable est remplacée par le label d'une partie ; respectivement de la partie courante, suivante ou précédente, du chapitre courant, suivant ou précédent, de la section courante, suivante ou précédente.
On n'a pas la possibilité pour le moment de définir d'autres variables.

Utilisation On se sert des variables de la famille $thecur avec les commandes de la famille \ et \ :

\ donne ,
« \ » donne « » ;
\ donne ,
« \ » donne « »,
« \ » donne « » ;
\ donne .

La commande echo a été introduite pour afficher dans le texte la valeur des arguments de la balise, à des fins de débogage. Par exemple \ donne .

Liens muets Les variables de la famille $thecur sont substituées par la chaîne vide si on est en extrémité de document (il n'y a pas de précédent ou de suivant par exemple). Comme indiqué dans la section , les commandes de la famille \ produisent du texte non souligné si le label est vide, ce qui est le but recherché.

Les macros Principe Les macros de Boc sont des blocs de code Boc mémorisé en mémoire et accessibles par une clé.

Pour mémoriser une macro, on fait \Corps de la macro\ et pour replacer le corps de la macro dans le texte on fait \.

Compilation Le compilateur bocal mémorise toutes les macros lors de la passe initiale. Si on mémorise une macro avec une clé déjà utilisée, la nouvelle macro remplace l'ancienne. Pour afficher dans la console la liste des macros à l'issue de la première passe, appeler bocal avec l'option --macro.

Lors de la deuxième passe, les macros sont replacées littéralement dans le texte, si bien qu'on peut très bien mettre un \ dans un bloc \ ... \. Attention toutefois à ne pas provoquer d'imbrication en boucle, actuellement aucun test n'est fait dans bocal pour le détecter.

Macros prédéfinies Un certain nombre de macros sont prédéfinies ; il suffit de les redéfinir pour surcharger leur contenu :

Exemples Pour générer dans ce document la barre « Index Table Précédent Suivant » au début de chaque chapitre on a redéfini la macro "begin-t1-html" :

Le source Boc de ce document est situé dans le répertoire
doc/bocal-tut.boc. Il peut être intéressant à consulter, en particulier pour l'écriture de la première page, qui n'est pas pour le moment écrite sous forme de macros.