bocal. 2. Le texte
if4. Labels, références et liens
6. Les macros
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 <filein.boc> [--index] [--macro]
[--html <fileout.html>] [--latex <fileout.tex>]
--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. <bocal> et finit par
</bocal>. 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 >.
On commence un chapitre par <t1>Titre du chapitre</t1>, une
section par <t2>Titre de la section</t2>, etc.
La numérotation des sections est automatique, et chaque section produit automatiquement une entrée dans la table des matières.
<include "fichier.boc">.
Le découpage du document en fichiers Boc n'a rien à voir avec la structure
logique du document, qui est établie à partir des sections.<tabmat long "toc-long" "Table des matières"> ;
pour avoir l'index des chapitres on fait
<tabmat short "toc-short" "Index rapide">.
Les chaînes "toc-long" et "toc-short" sont utilisés
pour les références (voir 6.4.).
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 <split-html>.
<br>
et un paragraphe par <p>.<b>gras</b>,
en <i>italique</i>
ou en <c>code</c>.<sub>indice</sub> ou
<sup>exposant</sup>.<center>texte centré</center>,
ce qui donne :
<nbsp>.<->. 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 <sloppy> au début du paragraphe.
Cette commande est sans effet en Html ; elle consiste
à rajouter un \sloppy en Latex.
\< ,
\> ou
\\ .<! et >. Par exemple, <!ceci est un commentaire>.
Les commentaires n'apparaissent pas en Html ni en Latex. <verb> et </verb>.
Le résultat sera traduit en verbatim Html ou Latex.
Par exemple, <verb>du texte <i>italique</i></verb>
produit : du texte <i>italique</i>.
<lang html>
et </lang>.
Par exemple, <lang html>du texte <em>italique</em></lang>
produit : du texte italique.
<lang latex>
et </lang>.
Par exemple, <lang latex>du texte {\em italique}</lang>
produit : .
ifif 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 <if> et </if> n'apparaît pas
(c'est une façon de commenter du texte) ;
entre <if html> et </if> le texte n'apparaît qu'en
mode Html ;
entre <if latex> et </if> le texte n'apparaît qu'en
mode Latex.
Attention, pour le moment on ne peut pas emboiter plusieurs if.
<ol> et </ol>.
Une liste non numérotée est délimitée par les balises
<ul> et </ul>.
Chaque entrée d'une liste commence par <li>.
Par exemple la liste ordonnée :
<ol>
<li> Oranges ;
<li> pêches.
</ol>
<ul>
<li> Pommes ;
<li> poires.
</ul>
<codepre> et </codepre>. Par exemple :
<codepre>
void Exemple1 (int i, char *s)
{
printf ("i = %d , s = %s\n", i, s);
}
</codepre>
affiche :
void Exemple1 (int i, char *s)
{
printf ("i = %d , s = %s\n", i, s);
}
<codepre "codedef">. Les autres
styles sont :
<codepre "codeusage">
void Exemple1 (int i, char *s)
{
printf ("i = %d , s = %s\n", i, s);
}
<codepre "codeterm">
void Exemple1 (int i, char *s)
{
printf ("i = %d , s = %s\n", i, s);
}
<codepre "codealert">
void Exemple1 (int i, char *s)
{
printf ("i = %d , s = %s\n", i, s);
}
<filec "chemin/fichier.c">.
Par exemple, voici ce que donne
<filec "hello.c"> :
#include <stdio.h>
#include <stdlib.h>
int main (int argc, char *argv[])
{
printf ("Hello World!\n");
exit (0);
}
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 <filec "chemin/fichier.c" "depart"> ou
<filec "chemin/fichier.c" "depart" "fin">.
<t1 "label-du-chapitre">Titre du chapitre</t1>,
ou <t2 "label-de-section">Titre de la section</t2>, 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.
<refn "label-de-section">. De même on peut
insérer le titre d'une section avec « <reft "label-de-section"> »
(les guillemets sont purement esthétiques). <a href="mon-url">texte souligné</a>.
En Latex, le texte apparaît sans aucune autre indication.
On peut aussi rajouter une ancre (invisible) :
<a name="mon-ancre">texte ancré</a>.
<a href="mon-url">Texte</a>
est <a-url-str "mon-url" "Texte"> : 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.<a-refn "label-section"> produit le numéro,<a-reft "label-section"> produit le titre,<a-refnt "label-section"> produit le numéro + titre, <a-ref-str "label-section" "autre texte"> produit un lien avec
un autre texte. $identificateur ; on les
place dans des balises, et elles sont substituées par leur valeur au moment
de la compilation du document Boc. $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. $thecur avec les commandes
de la famille <ref> et <a-ref> :
<refn $thecur> donne 5.3.,
« <reft $thecur> » donne « Utilisation » ;
<a-refn $theprev> donne 5.2.,
« <a-reft $theprev> » donne « Variables prédéfinies »,
« <a-refnt $theprev> » donne « 5.2. Variables prédéfinies » ;
<a-ref-str $thenext "section suivante">
donne section suivante .
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
<echo $thecur $thenext> donne sec-var-util sec-var-lienmu .
$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 4.4., les
commandes de la famille <a-ref>
produisent du texte non souligné si le label est vide, ce qui
est le but recherché.
Pour mémoriser une macro, on fait
<macro "cle-de-macro">Corps de la macro</macro>
et pour replacer le corps de la macro dans le texte on fait
<expand "cle-de-macro">.
--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 <expand "cle2"> dans
un bloc <macro "cle1"> ... </macro>. Attention toutefois à ne
pas provoquer d'imbrication en boucle, actuellement aucun test n'est fait
dans bocal pour le détecter.
"title" le titre du document.
"body-html" définition des couleurs de fond et de liens en Html.
"begin-doc-html" le début du document Html ; utilise les macros
"title" et "body-html".
"end-doc-html" la fin du document Html.
"begin-split-html" le début de chaque sous-fichier en Html ;
utilise les macros "title" et "body-html".
"end-split-html" la fin de chaque sous-fichier en Html.
"begin-t1-html" inséré juste avant un titre de chapitre en Html.
"end-t1-html" inséré juste avant la fin d'un chapitre en Html.
"begin-t2-html" inséré juste avant un titre de section en Html.
"begin-doc-latex" le début du document Latex.
"end-doc-latex" la fin du document Latex.
"begin-t1-latex" inséré juste après un titre de chapitre en Latex.
"begin-t1-html" :
<macro "begin-t1-html">
<center>
<a-url-str "#toc-short" "Index"><nbsp>
<a-url-str "#toc-long" "Table"><nbsp>
<a-ref-str $theprevt1 "Précédent"><nbsp>
<a-ref-str $thenextt1 "Suivant">
</center><lang html><hr></lang>
</macro>
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.