Générateurs de documentations en REBOL

Introduction

Les générateurs de documentation sont des dialectes spécialisés qui exploitent la fonction “parse” de rebol. Parse est un des atouts fondamentaux de REBOL. Dans cet article nous allons voir une des applications concrètes de parse dans le domaine de la réalisation de documentation.

Le but de ces générateurs est d’offrir la réalisation de documentation sous différents formats dont les plus connus sont HTML, PDF, à l’aide de formats spécifiques comprenant des balises simples qui facilite la saisie des documentation ainsi que leur hierarchisation. Il est à noter qu’entre autre contenu que l’on peut insérer dans les les documentations basées sur le format MakeDoc Like il y a la possibilitée d’insérer le résultat de code REBOL/view (une état de prérendering est nécessaire…). Ce qui est fort util dans le cadre de docuementation d’aide ç l’utilisation de logiciel basés sur REBOL/View. L’avantage est de ne pas faire de capture écran en laissant le soin au moteur MakeDoc Like le soin de réaliser l’illusatration à partir du code source d’illustration.

Les modalités d’utilisation sont aisées. A l’aide d’un éditeur de texte standard, on réalise un fichier ASCII dont l’extension est .txt et qui contient les balises adaptées au générateur de type MakeDoc que l’on souhaite utiliser.

Nous détaillerons dans cet article les differents formats pour les différents générateurs.

Le grand nombre de générateur de type MakeDoc se justifie par des envies de mise en forme différente ainsi que l’apport de certaines particularité de mise en forme de la documentation au format résultant (PDF, HTML).

Historique

Les générateurs de texte très connus sont LaTeX, GhostScript, Tex, AFT (http://www.maplefish.com/todd/aft.html), plus connus dans le monde Linux/UNIX car Miscrosoft Word a complètement occulté le passage de ces outils au monde Windows. Tout comme les générateurs de textes en REBOL basé sur le modèl MakeDoc, ces différents outils offres un système de balisages ASCII employant des mots clefs. Les générateur transformes ces fichiers sources au format ASCII en divers format.

A l’origine de ce courant de création autour des script REBOL de génération de documentation nous trouvons le script MakeDoc.r de Carl Sassenrath. A l’origine Carl Sassenrath souhaitait au moyen du script MakeDoc.r illustrer l’emploi de la fonction “parse” de REBOL, ainsi que fournir un support documentaire simple et efficace afin de produire rapidement des articles. Ce script a été mis en ligne le 25 Mai 2001.

Ce script a créé de par la simplicité des balises proposées et de par la simplicité de programmation un réel engouement dans la communauté des programmeurs REBOL.

Il est primordial de comprendre l’intérêt de la fonction parse pour bien appréhender tout l’intérêt des générateurs de texte en REBOL. Il n’est pas dans mes intentions de vous détailler ici l’utilisation de la fonction parse; mais simplement vous exposer le mode de fonctionnement de cette fonction. La fonction parse qui constitue la clef de voûte des scripts de génération de documentation emploie des règles qui permettent de reconnaitre des mots clef organisés en règle. Pour chaque mot clef trouvé une fonction peut être appelée pour réaliser un traitement spécifique.

MakeDoc 1.0

Présentation

Comme je vous l’ai expliqué dans l’historique MakeDoc version 1.0 (md1) est le script fondateur du courant des générateurs de documentation.

Ce premier jet contient un nombre de balises réduit par rapport aux générateurs de documentation qui sont apparus par la suite.

Comme tous les générateurs de documentation réalisés en REBOL l’idée phare est de proposer un système de balises simples puis de transformer ces balises simples en formatage plus élaboré.

Liste des balises du format MD1

Les balises ci-dessous sont en général placées en début de ligne.

Balise MD1	Description de la balise
*	Titre du document +
=== ou -1-	Chapitre de niveau 1 +
--- ou -2-	Chapitre de niveau 2 +
+++ ou -3-	Chapitre de niveau 3 +
… ou -4-	Chapitre de niveau 4 +
###	Balise de fin de document
:	Définition de mot +
*	Boulets +
#	Enumération +
;	Commentaire +
=image	Insertion d’une image
=url	Insertion d’un lien html
=view	Insertion d’une fenêtre view
=include	Insertion d’un document externe
=file	Sous document à générer
=toc	Index des chapitres du document
=options	Options du document ++
\in et /in	Paragraphe indenté
\note et /note	Notes(encart contenant du texte)
espace ou tabulation	Code +++

+ : Balises suivies de texte sur la même ligne.

++: Options possibles no-indent modern

+++: Encart contenant le texte tel qu’il est écrit

Un exemple de document généré

Télécharger MD1

( Note du rédacteur:

présentation de MD1
table avec les balises du format MD1 et leur signification
liens vers une page HTML qui montre la documentation générée

)

MakeDoc v2

Présentation

Le format MakeDoc v2 (MD2) est le petit frêre du format MakeDoc v1. L’auteur Carl Sassenrath a intégré dans MD2 plus de balises que dans son premier essai. Actuellement ce format est employé très largement par Rebol Technologies pour le Blog de Carl mais aussi pour certaines documentations. A terme il constituera sûrement le format employé pour le serveur de documentations partagées de Rebol Technologies.

Liste des balises du format MD2

Balises MD2	Description de la balise
=== ou -1-	Section de niveau 1 +
--- ou -2-	Section de niveau 2 +
+++ ou -3-	Section de niveau 3 +
… ou -4-	Section de niveau 4 +
###	Fin du travail de traduction ++
*	Boulet de niveau 1 +
** ou *>	Boulet de niveau 2 +
* ou *>>	Boulet de niveau 3 +
#	Enumération de niveau 1 +
#>	Enumération de niveau 2 +
#>>	Enumération de niveau 3 +
\in ou /in	Début ou fin d’une section indentée
\note ou /note	Début ou fin d’une section de note
\table ou /table	Début ou fin d’une table
=row	Insère une nouvelle ligne dans une table +++
=column	Insère une nouvelle colonne dans une table +++
\group ou /group	Début ou fin d’un groupe
\center ou /center	Début ou fin d’un paragraphe centré
\column ou /column	Début ou fin d’un texte mis en colonnes
;	un commentaire ou un paragraphe caché +
==	Emission d’un texte
=image	Insertion d’une image +
=options	Options de l’interprète +
=template	Fichier de pré formatage (template)
un caractère de tabulation	Section de texte mise en forme de code +

+ : balise suivie de texte ASCII sur la même ligne la balise perd son effet en fin de ligne.

++: Fin de l’interprétation ce qui suit n’est pas interprété par le traducteur de format MD2 vers HTML.

+++: Balise qui insère un bloc de plusieurs lignes, jusqu’à rencontre de la balise de fin de la section dont il est question.

Exemple de document généré

Télécharger MD2

MakeDoc Pro

Présentation

MakeDoc Pro est réalisé par Robert MÜNCH. Ce format s’appuit dans l’ensemble sur les balises du format MakeDoc tout en améliorant le rendu offert. MakeDoc Pro est un format idéal pour la rédaction d’articles et de documentations techniques.

Liste des balises MakeDoc Pro

Balise	Description de la balise
1ère Ligne du document	Titre du document
=== ou -1-	Chapitre de niveau 1 +
--- ou -2-	Chapitre de niveau 2 +
+++ ou -3-	Chapitre de niveau 3 +
… ou -4-	Chapitre de niveau 4 +
###	Balise de fin de document
:mot - définition	Définition de mot +
*	Boulets +
	Boulets de niveau 2 +
*	Boulets de niveau 3 +
#	Enumération +
;	Commentaire +
=image	Insertion d’une image
=url	Insertion d’un lien html
=view	Insertion d’une fenêtre view
=include	Insertion d’un document externe
=file	Sous document à générer
=toc	Index des chapitres du document
/table \table	Début et Fin d’une table (possible entête)
\| et \|\|	Séparateurs de colonne et de lignes
=options	Options du document ++
\in et /in	Paragraphe indenté
\note et /note	Notes(encart contenant du texte)
espace ou tabulation	Encare de l’auteur quand c’est en début de document
espace ou tabulation	Code +++
=langue	Spécifie une langue alternative
=fonts	Spécifie un fichier avec la configuration des polices de cractères
texte	Texte en gras
_texte_	Texte souligné
-texte-	Texte barré
~texte~	Texte en italique

+ : Balises suivies de texte sur la même ligne.

++: Options possibles no-indent modern no-toc

+++: Encart contenant le texte tel qu’il est écrit

Example de fichiés générés

fichier de texte:

http://shadwolf.free.fr/makedocpro.txt

fichier html généré:

http://shadwolf.free.fr/makedocpro.html

Le site HTML de MakeDoc Pro

http://www.robertmuench.de/projects/mdp/

NicomDoc

Présentation

NicomDoc est réalisé par John NICLASEN. NicomDoc est le format qui offre le plus de possibilité pour la mise en forme de texte. Il est inspiré des travaux de Carl SASSENRATH concernant les dialectes de génération de texte avec REBOL. La mise en forme HTML avec NicomDoc est moins sophistiquée que MakeDoc Pro. Le rendu HTML conserve le style de MakeDoc tout en étendant les balises des caractères et en simplifiant les balises du format MakeDoc v2.

Liste des balises NicomDoc

Balises	Description
-1-	Section 1
-2-	Section 2
-3-	Section 3
-4-	Section 4
\	Evite le carctère suivant
[reset]	Remet à zéro l’etat du texte
[b] [/b]	Texte en gras
[i] [/i]	Texte en italique
[s] [/s]	Texte baré
[u] [/u]	Texte souligné
[c tuple! ou wor! ][/c]	texte en couleur
[font integer! ou string!] [/font]	Polices de caractères un integer! donne la taille des caractères, un string! donne le nom de la police
[url (lien)] [/url]	Fait un lien
bold	Le texte entre * serra en gras
~italic~	Le texte entre ~ serra en italique
-strike-	Le texte entre - serra en baré
_underline_	Le texte entre _ serra sous ligné
;	Met un texte en commentaire
–	Met une ligne horizontale
=note (titre) [ contenu ]	Fait une note
=table []	Fait une table qui contient des lignes et des cellules
= row	Crée une ligne dans la table
=cell (rowspan <integer!>) (colspan <integer!>)	Crée une céllule d’un table
#	Liste énumérée niveau 1
#>	Liste énumérée niveau 2
#»	Liste énumérée niveau 3
*	Bullets niveau 1
*ou >**	Bullets niveau 2
* ou *»	Bullets niveau 3
:<define> -<definition>	Une définition
=image (left ou center ou right) <file!>	Insert dans le document une image
=reset	Remet à zéro le niveau du paragraphe
=center	Aligne le texte au centre
=left	Aligne le texte à gauche
=right	Aligne le texte à droite
=inleft (number!)	Indente à gauche
=/indent	Fin de l’indentation
=magic	Authorise l’utilisation des caractères magic gras, -barré-, etc
=/magic	fin de l’utilisation des caractères magic.
=escape	Authorise l’utilisation des caractères d’échappement.
=/escape	Fin de l’authorisation de l’utilisation des caractères d’échappement.
=toc (title)	Table des matières avec titre
###	Fin du document. Authorize les notes et commentaires à la suite
=styledef <style> []	Défnie un style
-<style>-	Un style en cours d’utilisation
=infirst number!	Indente la première ligne
=inright number!	Indente a droite
=tab number! ou []	Tabultation
=margin []	Marge
=mbottom	Marge basse
=mleft	Marge gauche
=mright	Marge droite
=mtop	Marge haute
=options	Options, parmis toc, nums, indent, no-indent, no-toc, no-nums, no-template, no-title
=template	Un template
=index	Indexe
=header []	Entête du document
=footer []	Bas de page
[field <name>]	Pour l’insertion d’un e-mail
[footnote]	Note de bas de page

Exemple de document généré

* Version Texte :

http://home.tiscali.dk/john.niclasen/nicomdoc/example.txt

* Version HTML :

http://home.tiscali.dk/john.niclasen/nicomdoc/example.html

Télécharger NicomDoc

Vous pouvez télécharger NicomDoc depuis le lien ci-dessous:

http://home.tiscali.dk/john.niclasen/nicomdoc/nicomdoc.r

Le site complet sur NicomDoc:

http://home.tiscali.dk/john.niclasen/nicomdoc/

wikiDoc

Liste des balises wikiDoc 2005-06-22

Command	Description
-1- or =1= or ======	section 1
-2- or =2= or =====	section 2
-3- or =3= or ====	section 3
-4- or =4= or ===	section 4
-5- or =5= or ==	section 5
\\	newline
bold	bold
//italic//	italic
~~strike~~	~~strike~~
''monospace''	`monospace`
__underline__	underline
%% nowiki %%	nowiki block
;; or ;[space]	line comment
:: or :[space] <definition> - <definition>	definition
(( ))	footnote
----	horizontal line (4 or more “-”)
--	short line (2 or 3 “-”)
[2 space]*	bullets level 1
[4 space]*	bullets level 2
[6 space]*	bullets level 3
[8 space]*	bullets level 4
[2 space]-	enum level 1
[4 space]-	enum level 2
[6 space]-	enum level 3
[8 space]-	enum level 4
8-) LOL ;-) :-) :-\| :-D :-P :-O :-X ;-) :-/ :-? :i: :?: :!: LOL	smileys
[[ link[\|comment] ]]	external or local link with optional comment; [[http://www.wp.pl\|Wirtualna Polska]]
{{ [space] image[\|comment] [space] }}	insert image with optional comment and placement (left, right aligned or centered); {{http://www.wp.pl/i/const/v3/logo.gif\|Logo}}
http://www.wp.pl	inline link (http:// https:// mailto: ftp:// gg://)
<login@domain.com>	inline email address (with anti-spam protection)
\note [header] /note	note block
\html /html	html block (by default all html tags are removed)
\center /center	center block
\left /left	left-align block
\right /right	right-align block
\nowiki /nowiki	output text block as-is
\code /code	preformated block
\comment /comment	comment block
\table /table	table block
=options	global options (nums \| no-nums \| no-title \| toc \| no-toc)
=template name	css and html template to use (see templates dir)
=include file-name	include file as wiki text
=file file-name	insert file as block of code
=charset encoding	charset encoding for html page generated by wikidoc
=line	horizontal line (like “----”)
=toc	table of contents
=title name	set page title (in means of <head><title> tag)
=author	unused but reserved
=license	"GFDL" \| "GPL" \| "BSD" \| "OPL" \| "PLCC" \| "UNKNOWN"
=category	unused but reserved
=status	unused but reserved
###	end of document

Shortcuts:

Shortcut	Description
_FIXME_	<b>TO NIE JEST FINALNA WERSJA DOKUMENTU I MOZE PODLEGAC ZMIANOM!</b>
_DELETEME_	<b>DOKUMENT NIE JEST AKTUALNY I ZOSTANIE USUNIETY!</b>
_EMPTY_	<b>DOKUMENT JEST PUSTY! JESLI CHCESZ - UZUPELNIJ GO!</b>
_DATETIME_	insert actual date and time

Template variables:

Variable	Description
$title	page title
$date	current date and time (standard internet date string)
$charset	page encoding (see =charset)
$css-file	css filename with path
$css	css file content
$toc	table of content
$content	document content
$footnote	footnotes
$license	license name (see =license)

Exemple de document généré

* Version Texte :

http://rowery.olsztyn.pl/narg/rebol/wikiDoc/example.txt

* Version HTML :

http://rowery.olsztyn.pl/narg/rebol/wikiDoc/example.html

MakeDoc Anywhere

Présentation

Parfaite transition entre les générateurs de documentation et les outils d’aide à l’utilisation des générateurs de documentation au format MakeDoc, MakeDoc Anywhere est à la fois un outil web pour réaliser de la documentation de qualité sans installation d’outils préalable mais aussi un format spécifique issu du courant MakeDoc.

L’auteur Christopher ROSS-GILL a souhaité d’une part étendre le format makedoc mais aussi proposer une interface web d’aide à la génération de documentation. Le format de sortie sont XHTML, DocBook ou AmigaGuide.

Liste des balises du format MakeDoc Anywhere

Balises MDA	Description de la balise
Première ligne de texte	Titre du document
===	Section de niveau 1 +
---	Section de niveau 2 +
=toc	Indexe des sections du document
*	Boulet de niveau 1 +
#	Enumération de niveau 1 +
###	Fin du document
[b] texte [/b]	texte en gras
[i] texte [/i]	texte en italique
:mot - description	Définition d’un mot
\in et /in	Section de texte indenté
\note et /note	Section de note
=image	Affiche une image dans le document
=view	Affichage d’une fenêtre VID dans le document
[url http://url_de_la_page/] texte [/url]	Lien hypertexte vers une page distante
espaces ou tabulation en début de ligne	Pargraphe de texte encadré + ++

+: Balise suivie de texte et collée à gauche (sans espaces ou tabulations)

++: Utile pour faire des notes ou mettre en forme un code source indenté dans le document

Accès à l'interface de saisie WEB

http://www.ross-gill.com/make-doc/

exemple de documentation générée

* Version Texte :

http://www.ross-gill.com/make-doc/guide/make-spec.txt

* Version HTML :

http://www.ross-gill.com/make-doc/guide/

Editeurs pour le format MakeDoc

MD2-IDE

Présentation

MD-IDE est un éditeur de documentation qui offre une interface de visualisation rapide VID. La génération de la documentation aux formats HTML et PDF est aussi possible.

Capture d'écran

Voici a quoi ressemble MD-IDE.

Télécharger

Vous pourrez télécharger MD-IDE ici:

http://www.dobeash.com/files/md2-ide.zip

MDP-GUI

Présentation

MDP-GUI est un éditeur de documentation au format Makedoc Pro. Il permet d’optimiser la saisie des documentations grâce à un jeu très élaboré de boutons d’interface pour la saisie des balises.

Il est aussi possible d’ajouter les balises voulues de part et d’autre d’un texte sélectionné. Il aussi possible de configurer les marqueurs de fin de ligne.

MDP-GUI intègre une interface de prévisualisation intégrée. Il permet aussi de générer la documentation au format HTML.

Captures écran

Voici a quoi ressemble MDP-GUI.

Télécharger

Version beta 1.4.1:

http://shadwolf.free.fr/mdp-gui-1-4-1.zip

MDP-GUI est aussi disponnible sur rebol.org sous forme de package!!

L’avantage c’est que les package sur le site rebol.org serront mis à jour plus souvent que le lien sur mon site perso.. 1) Dans une console rebolview tapper

 do http://www.rebol.org/library/public/repack.r

2) Dans l’application repack * Cliquez sur le bouton resfresh * dans la liste de gauche choisissez MDP-GUI-package * Vérifier que tous les fichiers du package sont cochés * Choisissez le répertoire Cible où serront stoquer les fichiers télécharger * Cliquez sur le bouton “Download” en bas de la liste des fichiers du package

Une réadaptation de l’Interface graphique en employant RebGUI serra effectuée quand ce dernier.

MD Viewer

Présentation

MDViewer est un navigateur de fichier MD2. Comparable au navigateur HTML il offre une visualisation formatée au standard MD2. A la différence de MD-IDE et de MDP-GUI ce logiciel ne dispose pas d’un mode éditon. MDViewer est pourvu d’un moteur de rendu extrêmement optimisé et rapide. Du point de vue du format de nombreuses nouveautés sont apparues et améliorent les possibilités du format MD2.

Captures écran

Voici à quoi ressemble MDViewer. Nous pouvons admirer les fonctionnalité de navigation de documentation qui en font un logiciel aussi util et hergonomique que les navigateurs WEB.

Télécharger

Vous pouvez télécharger MDViewer ici :

http://www.dobeash.com/files/mdViewer.zip

MDP-Browser

Présentation

MDP-Browser est le second logiciel orienté creation /affichage de documentation au format MDP réalisé par Alphé Salas-Schumann (aka ShadWolf). MDP-Browser est une toute nouvelle expérience!! Puisqu’il est l’interface utilisateur permettant de transformer un server X-internet de Rebol Technologies (IOS) en véritable wiki MDP. MDP-Browser fonctionne aussi bien avec rebol/link qu’avec REBOL/View, dans ce cas le téléchargement du script make-doc-pro.r est même automatique!!!

Capture écran

Le projet est encore au stade de développement mais voici déjà a quoi resemble se fils naturel de MD Viewer et MDP-GUI. MDP-Browser alie à la fois le moteur de rendu de MDP-GUI très largement amélioré et les fonctionnalité de navigation de documentation de MD-Viewer !!!