).
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 :
- Oranges ;
- pêches.
est obtenue avec le code
- Oranges ;
- pêches.
tandis que la liste non ordonnée :
est obtenue avec le code
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 :
- "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.
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.