Ecriture de documents en CWcode
Manuel d'utilisation

Date de publication : 23/09/2004

Date de mise a jour : 24/09/2004

Par Cédric Lemaire
 

Ce manuel précise comment écrire un document en CWcode. Le CWcode s'apparente au BBcode, à ceci près qu'il se destine à la mise en forme de documents, plutôt qu'à l'écriture dans des forums. A l'heure actuelle, seule la production de documents HTML selon le style de Developpez.com est supportée.


1 Pourquoi écrire un document en CWcode ?
2 La syntaxe du CWcode
3 Les balises de structuration du document
3.1 Le titre
3.2 Les informations sur le document
3.3 Le synopsis
3.4 L'introduction
3.5 Les chapîtres
3.6 Les sections
3.7 Les sous-sections
3.8 Les sous-sous-sections
4 Les styles
4.1 Mise en valeur du texte
4.2 Mise en valeur d'un mot-clé
4.3 Les listes
4.4 Les encadrés
4.5 Les tables
5 Les balises spéciales
5.1 Lien vers une URL
5.2 Référence vers un point du document
5.3 Insertion d'une image
5.4 Saut de ligne
6 Insertion de code source
7 Les outils livrés avec le CWcode
7.1 Génération du document en HTML pour Developpez.com
7.2 Reconstitution d'un document CWcode disséminé dans un source


1 Pourquoi écrire un document en CWcode ?

Le CWcode permet d'écrire un document dans un éditeur de texte classique, indépendamment de son aspect visuel. Il s'agit principalement de taper du contenu, avant de se concentrer sur la mise en forme. A partir d'un document écrit en CWcode, on veut pouvoir réaliser facilement une nouvelle déclinaison visuelle du contenu. Le plus facile est de réaliser une déclinaison en HTML.

Pour l'instant, le CWcode est livré avec une conversion en HTML dont le rendu est semblable à celui proposé par Developpez.com. Il est possible d'adapter un convertisseur à la charte graphique de n'importe quel site Web. Les convertisseurs se construisent dans le langage de script CodeWorker, un outil de parsing et un générateur de code, disponible sous licence LGPL à l'adresse http://www.codeworker.org.

La souplesse d'adaptation du rendu visuel n'est pas le seul critère qui peut pousser à utiliser le CWcode. Ce dernier se prête bien à l'écriture de documentations informatique ou de tutoriels, incluant des échantillons de code notamment. Il offre la possibilité d'exécuter les codes sources qu'il contient, et d'inclure les résultats de ces exécutions. Vous garantissez ainsi à la fois que le code source a une syntaxe correcte et fonctionne, mais en plus que le résultat coïncide bien avec ce que le code est sensé faire (voir le chapitre consacré à l'insertion de code source).

Ce document a été entièrement réalisé en CWcode. Vous lisez ici une représentation visuelle possible. On pourrait en inventer une infinité, dans des formats autres que HTML.

2 La syntaxe du CWcode

Le terme CWcode est un clin d'oeil au BBcode, ce langage de mise en forme du texte, très répandu sur les forums des sites Web. Son principe est le même : on utilise des balises pour appliquer des caractéristiques au texte : nouveau chapître, passage en italique, présentation de code source.

Une balise terminale marque la fin du champ d'application de la balise initiale dans le texte. Une balise initiale est un mot-clé placé entre crochets. Une balise terminale ressemble à une balise initiale, si ce n'est que le mot-clé est précédé du symbole /. Parfois, des options sont spécifiées à l'intérieur d'une balise terminale. Elles se présentent sous la forme d'un ensemble de propriétés séparées par des virgules. Une propriété est un nom suivi d'une valeur, les deux séparés par une virgule. Une valeur peut être placée entre guillemets.

Exemples de balises :

  • Cette phrase a [i]quatre mots en italique[/i], pas un de plus.
  • [code,save="test.cpp"]vitesse = 45;[/code]
  • [chapter=force_coriolis]La force de Coriolis[/chapter]

Une ligne vide est comptée comme un saut de paragraphe. En revanche, plusieurs lignes vides consécutives sont comptées pour un seul saut de paragraphe. Un saut de ligne n'a pas d'effet, à moins qu'il ne soit placé derrière un point, point d'interrogation, point d'exclamation ou deux-points.

3 Les balises de structuration du document

Les documents possèdent un titre, et se conforment à une structure hiérarchique : synopsis, chapîtres, sections et sous-sections. Ils disposent éventuellement d'informations générales sur l'auteur et sur l'historique des mises à jour.

3.1 Le titre

Le titre du document se place dans la balise [title].

Exemple :

  • [titre]La programmation générative : perspectives[/titre]

3.2 Les informations sur le document

Les informations sur le document sont placées dans la balise [docinfo].

Options
authorNom et prénom de l'auteur.
creationDate de création du document.
keywordsListe de mot-clés, séparés par une virgule.
profileIdID du profil de l'auteur chez Developpez.com.
profileNameAbréviation du nom de l'auteur chez Developpez.com.

Les mot-clés sont injectés directement dans les méta-informations de l'entête du fichier HTML cible.

3.3 Le synopsis

Le synopsis est annoncé par la balise [synopsis]. Dans la structure du document, elle se place avant l'écriture des chapîtres. Le synopsis est injecté directement dans le champ 'description' des méta-informations de l'entête du fichier HTML cible.

Exemple :

  • [synopsis]Cet article traite du ramassage des feuilles à l'approche de la mousson.[/synopsis]

3.4 L'introduction

La balise [introduction] sert à annoncer l'introduction, mais aussi la préface ou l'avant-propos.

Options
introductionNom à utiliser par la balise [reference] pour pointer ici.

Exemples :

  • [introduction]introduction[/introduction]
  • [introduction=avant_propos]Avant-propos[/introduction]

3.5 Les chapîtres

Les chapîtres sont annoncés par la balise [chapter].

Options
chapterNom à utiliser par la balise [reference] pour pointer ici.

Exemples :

  • le chapitre courant : [chapter]Les balises de structuration du document[/chapter]
  • [chapter=fondements_reseaux_neurones]Les fondements des réseaux de neurones[/chapter]

3.6 Les sections

Les sections sont annoncés par la balise [section]. Dans la structure du document, elles ne peuvent se placer que directement sous un chapître.

Options
sectionNom à utiliser par la balise [reference] pour pointer ici.

Exemples :

  • la section courante : [section]Les sections[/section]
  • [section=histoire]Un peu d'histoire[/section]

3.7 Les sous-sections

Les sous-sections sont annoncés par la balise [subsection]. Dans la structure du document, elles ne peuvent se placer que directement sous une section.

Options
subsectionNom à utiliser par la balise [reference] pour pointer ici.

3.8 Les sous-sous-sections

Les sous-sous-sections sont annoncés par la balise [subsubsection]. Dans la structure du document, elles ne peuvent se placer que directement sous une sous-section.

Options
subsubsectionNom à utiliser par la balise [reference] pour pointer ici.

4 Les styles

4.1 Mise en valeur du texte

Les balises existent pour le passage du texte en gras, italique et emphatique.

BaliseDescription
[i]Basculement du texte en mode italique.
[b]Basculement du texte en gras.
[a]Basculement du texte en mode emphatique.

Exemple :

  • [i]Jeux Olympiques[/i] en [b]Grèce[/b] pour [a]2004[/a]

Cela donne :

Jeux Olympiques en Grèce pour 2004

4.2 Mise en valeur d'un mot-clé

Un mot-clé peut être mis en valeur par la balise [keyword]. L'option keyword peut éventuellement préciser le langage d'appartenance du mot-clé.

Options de la balise [keyword]
keywordLangage d'appartenance du mot-clé. Pour l'instant, seul CodeWorker est reconnu, et cela établit un lien vers l'explication du mot-clé dans le manuel de référence.

Exemple :

  • Déclaration d'une classe en C++ ou en Java : [keyword]class[/keyword]
  • Exécuter un modèle de génération de code avec CodeWorker : la fonction [keyword=CodeWorker]generate()[/keyword]

Cela donne :

Déclaration d'une classe en C++ ou en Java : class
Exécuter un modèle de génération de code avec CodeWorker : la fonction generate()

4.3 Les listes

Une liste est annoncée par la balise [list]. Chaque entrée dans la liste est annoncée par le symbole [*], qui ne possède pas de balise terminale.

Exemple :

[list]
[*] faire les courses,
[*] chauffer le four,
[*] cuire la pizza,
[/list]

Cela donne :

  • faire les courses,
  • chauffer le four,
  • cuire la pizza,

4.4 Les encadrés

Une portion de texte que l'on désire mettre en valeur dans un encadré, est annoncée par la balise [frame]. Le texte figure alors dans un cadre.

Options
frameTitre porté par la partie encadrée.

Exemples :

  • [frame]Ceci est un exemple d'encadré simple[/frame]
    Ceci est un exemple d'encadré simple
  • [frame="Le titre de l'encadré"]Ceci est un exemple d'encadré portant un titre[/frame]
    Le titre de l'encadré
    Ceci est un exemple d'encadré portant un titre

Il existe une nature particulière d'encadrés, annoncée par la balise [rationale], et qui est chargée de mettre en valeur une explication ou des motivations.

Options
rationaleTitre porté par cette explication.

Exemple :

[rationale]Ceci est un exemple d'explication mise en valeur[/rationale]
 
Ceci est un exemple d'explication mise en valeur
 

4.5 Les tables

Une table est annoncée par la balise [table]. Elle se compose d'un entête, éventuellement suivi de une ou plusieurs lignes. Une ligne est composée de cellules, et une cellule peut fusionner ses voisines.

La ligne d'entête est annoncée par la balise [header]. Elle est composée de une ou plusieurs cellules.

Une ligne de la table est annoncée par la balise [row]. Elle est composée de une ou plusieurs cellules.

Une cellule est annoncée par la balise [cell]. Une cellule encadre son contenu textuel. Elle peut éventuellement fusionner avec ses voisines à sa droite, pour former une cellule plus grande.

Options de la balise [cell]
cellNombre de cellules à fusionner, celle-ci comprise (vaut 1 par défaut).

Exemple :

[table]
[header][cell=2]Planning du début de soirée[/cell][/header]
[row][cell]Faire les courses[/cell][cell]18h30[/cell][/row]
[row][cell]Chauffer le four[/cell][cell]19h00[/cell][/row]
[row][cell]Enfourner la pizza[/cell][cell]19h10[/cell][/row]
[/table]

Cela donne:

Planning du début de soirée
Faire les courses18h30
Chauffer le four19h00
Enfourner le pizza19h10

5 Les balises spéciales

5.1 Lien vers une URL

La balise [url] sert à établir un lien vers une page Web, n'importe quelle URL. Le nom du lien est placé entre les balises initiales et terminales. Si le nom ne coïncide pas avec l'adresse du lien, celle-ci doit être assignée à l'option url.

Options
urlAdresse de l'URL sur laquelle pointer.

Exemples :

  • [url=http://www.developpez.com]Developpez.com[/url]
  • [url]http://www.codeworker.org[/url]

Cela donne :

Developpez.com
http://www.codeworker.org

5.2 Référence vers un point du document

La balise [reference] sert à pointer quelque part dans le document. Le nom que l'on veut donner à la référence est placé entre les balises initiales et terminales. L'identifiant de l'objet référé est assigné à l'option reference, champ obligatoirement renseigné.

Options
reference (obligatoire)Identifiant de l'objet pointé. L'identifiant est passé dans la propriété reference de l'objet pointé (voir la balise [chapter] par exemple).

Exemple :

  • Référence vers la balise [reference=table]<table>[/reference]... juste comme ça!

Cela donne :

Référence vers la balise <table>... juste comme ça!

5.3 Insertion d'une image

La balise [image/] sert à inclure un fichier image (bmp, gif, png). Elle n'a pas de balise terminale.

Options
image (obligatoire)Chemin complet du fichier image.
tooltip (facultatif)Brève description de l'image.
height (facultatif)Hauteur de l'image, éventuellement en pourcentage par rapport à la taille d'origine.
width (facultatif)Largeur de l'image, éventuellement en pourcentage par rapport à la taille d'origine.

Exemples :

  • La terre vue du ciel : [image=planete_terre.png/]
  • [image=noel_famille.png,tooltip="Photo prise à Noël dernier, aux iles Seychelles"/]

5.4 Saut de ligne

La balise [line/] impose de revenir à la ligne. Elle n'a pas de balise terminale, ni d'options particulières.

Exemple :

  • Reproduction des vers de terre[line/]Révélation sans précédent

Cela donne :

Reproduction des vers de terre
Révélation sans précédent

6 Insertion de code source

L'insertion de code source dans un document mérite qu'on lui consacre un chapître à part entière. Ce chapître sera amené à s'étoffer, au fur et à mesure que de nouveaux langages seront reconnus pour la coloration syntaxique, ou que des extensions intéressantes seront apportées sur les options.

Une portion de code source est annoncée par la balise [code]. Quelques options intéressantes sont proposées.

Options
codeLangage du code source présenté ici. Détermine ainsi le bon algorithme de coloration syntaxique.
commandCommande à exécuter : appel système d'un exécutable.
loadLe code source est à charger à partir d'un fichier.
postScript CodeWorker qui s'applique sur le code source après sa colorisation, mais avant son injection dans le fichier en cours de construction. Le code source est passé en tant que this au script (voir signification des contextes this dans la documentation de CodeWorker).
referenceAttribue un identifiant pour pointer ici par la balise [reference]
saveLe code source cité doit être sauvé dans un fichier.
scriptScript CodeWorker qui s'applique sur le code source avant sa colorisation. Typiquement, c'est très utile pour raccourcir un code source à l'affichage. Le code source est passé en tant que this au script (voir signification des contextes this dans la documentation de CodeWorker).
titleAffiche un titre en tête du code source.

Exemples :

  • [code]vitesse = 45;[/code]
  • [code,title="Vitesse maxi du yacht, en noeuds!"]vitesse = 45;[/code]

  • [code=CodeWorker.cws,save="$TMP/ManuelCWcode/exemple.cws",command="codeworker $TMP/ManuelCWcode/exemple.cws -nologo"]
    local maClasse;
    insert maClasse.name = "Ciboulette";
    insert maClasse.parent = "HerbeAromatique";
    generate({#ifndef _@this.name@_h_
    #define _@this.name@_h_

    class @this.name@ : public @this.parent@ {
    };

    #endif
    @
    }, maClasse, getEnv("TMP") + "/ManuelCWcode/" + maClass.name + ".h");
    [/code]
  • [code=C++,load="$TMP/ManuelCWcode/Ciboulette.h"][/code]

Nous obtenons respectivement les rendus suivants :

  • aucune option spécifiée :
    vitesse = 45;
  • attribution d'un titre :
    Vitesse maxi du yacht, en noeuds!
    vitesse = 45;
  • coloration syntaxique, sauvegarde du code source dans un fichier puis exécution d'une commande :
    $TMP/ManuelCWcode/exemple.cws
    codeworker $TMP/ManuelCWcode/exemple.cws -nologo
    local maClasse;
    insert maClasse.name = "Ciboulette";
    insert maClasse.parent = "HerbeAromatique";
    generate({#ifndef _@this.name@_h_
    #define _@
    this.name@_h_

    class @
    this.name@ : public @this.parent@ {
    };

    #endif
    @

    }, maClasse, getEnv("TMP") + "/ManuelCWcode/" + maClasse.name + ".h");

  • chargement d'un fichier source, produit à l'exécution du code source précédent :
    $TMP/ManuelCWcode/Ciboulette.h
    #ifndef _Ciboulette_h_
    #define _Ciboulette_h_

    class Ciboulette : public HerbeAromatique {
    };

    #endif

Note : les retour-chariots, les espaces et les tabulations sont conservés dans le rendu.

Lorsque plusieurs options sont requises, elles s'exécuteront en respectant l'ordre dans lequel vous les aurez placées, à l'exception du chargement du code source (option load), toujours opéré en premier).

Pour la coloration syntaxique, voici les différents langages reconnus à l'heure actuelle :

Option codeNote
CColoration syntaxique du C.
C++Coloration syntaxique du C++.
CodeWorkerColoration syntaxique et lien des mot-clés et symboles vers le manuel HTML en ligne.
Il existe plusieurs formes dérivées de ce code :
  • CodeWorker.cws : lecture d'un script standard,
  • CodeWorker.cwp : lecture d'un script de parsing BNF ou d'un script de transformation,
  • CodeWorker.cwt : lecture d'un modèle de génération de code,
IDLColoration syntaxique d'une IDL CORBA.
JavaColoration syntaxique de Java.
HTMLColoration syntaxique du HTML.
XMLColoration syntaxique du XML.

Vous ne pouvez pas incruster de CWcode à l'intérieur d'un code source qui dispose d'une coloration syntaxique : le code source doit se conformer rigoureusement à la syntaxe du langage spécifié. En revanche, un code source dont le langage n'a pas été précisé, peut contenir des balises de style ou spéciales : mise en gras, listes à puce, images... Une condition tout de même : ce code formaté doit être placé entre les balises initiales et terminales, et non pas provenir d'un fichier chargé par l'option load.

7 Les outils livrés avec le CWcode

Les outils sont des scripts CodeWorker, à lancer en ligne de commande.

7.1 Génération du document en HTML pour Developpez.com

Une fois le document rédigé en CWcode, il suffit de taper une ligne de commande pour générer le document au format HTML, en conformité avec la charte graphique de Developpez.com :

codeworker -translate CWcode2DevCom.cwp <votre-document-CWcode.txt> <votre-document.html>

Exemples :

7.2 Reconstitution d'un document CWcode disséminé dans un source

Vous pouvez écrire une partie des commentaires de votre code source en CWcode. Ceux qui n'éclairent que sur les aspects fortement techniques, sur des points très locaux de l'implémentation, ne sont généralement pas de ceux qui méritent de figurer dans un document. En revanche, ceux destinés à une présentation générale du code source ou à son exploitation peuvent sembler dignes d'être rassemblés dans un document.

Ce document pourrait bien sûr faire l'objet d'une rédaction à part. Dans ce cas, il est fort à parier que son contenu divergerait rapidement des fonctionnalités offertes par ce code, au gré des évolutions, maintenances et corrections que ce dernier subira. En revanche, si la description d'une caractéristique se fait au niveau de son implémentation dans le code source, le développeur l'aura sous les yeux lorsqu'il interviendra sur le code source, et sera plus enclin à la mettre à jour.

Fusionner la documentation et le code source dans même fichier, malgré l'avantage majeur cité plus haut, présente un inconvénient : comment extraire la documentation du fichier, séparer le bon grain de l'ivraie ? Cet inconvénient est levé grâce au script CodeWorker DocExtractor.cwp, qui se charge de récupérer tous les commentaires en CWcode et de le mettre bout à bout pour former un document CWcode complet. Il s'applique ainsi :

codeworker -translate DocExtractor.cwp <votre-code-source> <votre-document-CWcode.txt>

Point d'importance : comment exprimer qu'un commentaire figure un fragment de CWcode ? Il doit simplement commencer par /**[description] et s'achever par [/description]**/. Cette spécification sera étendue plus tard pour accepter des types de commentaires variés, et pas seulement ceux issus du C.

Exemple :

  • Le CWcode de ce document HTML est issu du script CWcode2DevCom.cwp, qui porte ainsi l'écriture de tout ce manuel :
    codeworker -translate DocExtractor.cwp CWcode2DevCom.cwp manuelCWcode.txt
    Il ne reste plus qu'à générer la page HTML correspondante, comme nous avons pu le voir dans la section précédente :
    codeworker -translate CWcode2DevCom.cwp manuelCWcode.txt manuelCWcode.html


© 2004 Cédric Lemaire - Tous droits réservés : Cédric Lemaire. Toute reproduction, utilisation ou diffusion de ce document par quelque moyen que ce soit autre que pour un usage personnel doit faire l'objet d'une autorisation écrite préalable de la part de : Cédric Lemaire , le propriétaire des droits intellectuels.