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

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.

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.

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.

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

Exemple :

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

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

Options
author	Nom et prénom de l'auteur.
creation	Date de création du document.
keywords	Liste de mot-clés, séparés par une virgule.
profileId	ID du profil de l'auteur chez Developpez.com.
profileName	Abré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.

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]

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

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

Exemples :

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

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

Options
chapter	Nom à 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]

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
section	Nom à utiliser par la balise [reference] pour pointer ici.

Exemples :

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

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
subsection	Nom à utiliser par la balise [reference] pour pointer ici.

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
subsubsection	Nom à utiliser par la balise [reference] pour pointer ici.

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

Balise	Description
[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

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]
keyword	Langage 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()

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 :

Cela donne :

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
frame	Titre 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
rationale	Titre 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

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]
cell	Nombre de cellules à fusionner, celle-ci comprise (vaut 1 par défaut).

Exemple :

Cela donne:

Planning du début de soirée
Faire les courses	18h30
Chauffer le four	19h00
Enfourner le pizza	19h10

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
url	Adresse 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

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!

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"/]

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

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
code	Langage du code source présenté ici. Détermine ainsi le bon algorithme de coloration syntaxique.
command	Commande à exécuter : appel système d'un exécutable.
load	Le code source est à charger à partir d'un fichier.
post	Script 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).
reference	Attribue un identifiant pour pointer ici par la balise [reference]
save	Le code source cité doit être sauvé dans un fichier.
script	Script 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).
title	Affiche 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 code	Note
C	Coloration syntaxique du C.
C++	Coloration syntaxique du C++.
CodeWorker	Coloration 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,
IDL	Coloration syntaxique d'une IDL CORBA.
Java	Coloration syntaxique de Java.
HTML	Coloration syntaxique du HTML.
XML	Coloration 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.

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

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 :

• La ligne de commande qui a généré ce document HTML :
  codeworker -translate CWcode2DevCom.cwp manuelCWcode.txt ManuelCWcode.html
• La ligne de commande qui a généré le tutoriel sur CodeWorker pour Developpez.com :
  codeworker -translate CWcode2DevCom.cwp developpez.com.txt decouverteCW.html

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