Il y a quelques temps, j’ai écrit un article au sujet des syntaxes wiki-like de Creole et Markdown. Au fil des commentaires, j’ai expliqué que j’avais développé ma propre syntaxe, principalement inspirée par Creole.
J’ai récemment développé un outil de gestion de projets, interne à mon entreprise. Je l’ai nommé Skriv, du nom de mon projet-arlésienne. Je ne désespère d’ailleurs pas d’en faire une version open-source que je pourrais publier ; ça en vaudrait la peine, je suis très fier du résultat − mais j’aurais l’occasion de vous en reparler sur ce blog.
Bref, au sein de ce projet, j’ai fait évoluer ma syntaxe wiki. L’interpréteur est développé sur la base de la bibliothèque WikiRenderer, créée par Laurent Jouanneau. Je vais bientôt publier cet interpréteur, mais pour le moment je vais surtout présenter les éléments de la syntaxe.
À terme, je pense mettre en place un site dédié, avec une explication détaillée de chaque éléments de la syntaxe (et des raisons qui ont conduit à chaque choix), et un système d’extension permettant d’ajouter des nouvelles fonctionnalités.
Base
Styles de base
| Skriv | Résultat | Origine |
|---|---|---|
**gras** |
gras | txt2tags, Creole |
''italique'' |
italique | MediaWiki |
--barré-- |
txt2tags | |
__souligné__ |
souligné | txt2tags, Creole |
##monospace## |
monospace | Creole, AsciiDoc |
texte ^^exposant^^ |
texte exposant | Creole |
texte ,,indice,, |
texte indice | Creole |
Titres
| Skriv | HTML généré | Origine |
|---|---|---|
=Titre 1 ==Titre 2 ===Titre 3 ====Titre 4 =====Titre 5 ======Titre 6 |
<h1>Titre 1</h1> <h2>Titre 2</h2> <h3>Titre 3</h3> <h4>Titre 4</h4> <h5>Titre 5</h5> <h6>Titre 6</h6> |
Creole |
=Titre 1= ==Titre 2== ===Titre 3=== ====Titre 4==== =====Titre 5===== ======Titre 6====== |
<h1>Titre 1</h1> <h2>Titre 2</h2> <h3>Titre 3</h3> <h4>Titre 4</h4> <h5>Titre 5</h5> <h6>Titre 6</h6> |
txt2tags, MediaWiki, Creole |
Blocs de texte
Paragraphes
| Skriv | Résultat | Origine |
|---|---|---|
Une ou plusieurs lignes de texte forment un paragraphe. Les paragraphes sont séparés par une ligne vide. Au sein d'un paragraphe, les retours- chariots sont préservés. |
Une ou plusieurs lignes de texte forment un paragraphe. Les paragraphes sont séparés par une ligne vide.
Au sein d’un |
Markdown Extra |
Texte préformaté
| Skriv | Résultat | Origine |
|---|---|---|
il suffit d'au moins un espace **au début** de ''chaque ligne'' |
il suffit d'au moins un espace au début de chaque ligne |
MediaWiki |
[[[ les triples crochets fonctionnent aussi, mais la **syntaxe wiki** n'est pas ''interprétée'' ]]] |
les triples crochets fonctionnent aussi, mais la **syntaxe wiki** n'est pas ''interprétée'' |
Skriv |
Blocs de texte stylisés
Paragraphes avec classes CSS
| Skriv | Résultat | Origine |
|---|---|---|
{{{justify italic
Cette syntaxe permet de
spécifier une ou plusieurs
classes CSS.
Le style s'applique à tous
les paragraphes concernés.
}}}
|
Cette syntaxe permet de spécifier une ou plusieurs classes CSS. Le style s’applique à tous les paragraphes concernés. |
Skriv |
{{{italic
Il est possible d'imbriquer les
blocs stylisés.
{{{bold
Ce qui peut être très pratique.
{{{blue
Mais un peu difficile à lire.
}}}
}}}
{{{ {{{ underline
Pour faciliter la lecture, il est
possible d'ajouter des accolades
ouvrantes et fermantes.
}}} }}}
C'est quand même mieux.
}}}
|
Il est possible d’imbriquer les blocs stylisés. Ce qui peut être très pratique. Mais un peu difficile à lire. Pour faciliter la lecture, il est possible d’ajouter des accolades ouvrantes et fermantes. C’est quand même mieux. |
Skriv |
Code source
| Skriv | Résultat | Origine |
|---|---|---|
[[[php $a = 12; ]]] |
$a = 12; |
Skriv |
Éléments avancés
Listes
| Skriv | Résultat | Origine |
|---|---|---|
* liste à points * élément 2 ** sous-élément |
|
Creole / MediaWiki |
# liste numérotée # élément 2 ## sous-élément |
|
Creole / MediaWiki |
Liens
| Skriv | Résultat | Origine |
|---|---|---|
http://skriv.org |
http://skriv.org | Skriv |
ftp://tres.longue.url.com/vraiment/tres/longue |
ftp://tres.longue.url.com/vraiment/tres/… | Skriv |
amaury@amaury.net |
amaury@amaury.net | Skriv |
[[http://skriv.org]] |
http://skriv.org | Creole |
[[http://tres.longue.url.com/vraiment/tres/longue]] |
http://tres.longue.url.com/vraiment/tres… | inspiré de Creole |
[[Skriv|http://skriv.org]] |
Skriv | inspiré de Creole et de Markdown |
**''[[Skriv|http://skriv.org]]''** |
Skriv | Creole |
[[Un ''lien'' **génial**|http://skriv.org]] |
Un lien génial | Skriv |
Images
| Skriv | Résultat | Origine |
|---|---|---|
{{http://www.comprendrechoisir.com/img/logoPJ.png}}
|
 |
inspiré de Creole |
{{PagesJaunes|http://www.comprendrechoisir.com/img/logoPJ.png}}
|
|
inspiré de Creole |
Tableaux
| Skriv | Résultat | Origine | ||||||
|---|---|---|---|---|---|---|---|---|
!! titre 1 !! titre 2 || cell 1 || cell 2 || cell 3 || cell 4 |
|
Skriv |
Séparations horizontales
| Skriv | HTML généré | Origine |
|---|---|---|
---- (au moins 4 tirets ; que des tirets sur la ligne) |
<hr /> |
Creole |
Citations
| Skriv | Résultat | Origine |
|---|---|---|
> texte citation qui respecte les paragraphes > > comme d'habitude |
|
Markdown |
Notes de bas de page
| Skriv | Résultat | Origine |
|---|---|---|
texte ((note de bas de page)) |
texte 1
1. note de bas de page |
Skriv |
texte ((titre|note de bas de page)) |
texte titre
titre. note de bas de page |
Skriv |
texte ((lien vers [[Skriv|http://skriv.org]])) |
texte 3 | Skriv |
Abréviations
| Skriv | Résultat | Origine |
|---|---|---|
??OABP|Open AddressBook Protocol?? |
OABP | WikiRenderer |
Smileys
| :-) | ☺ |
| :-( | ☹ |
| :-D | 😃 |
| :-p | 😋 |
| :-| | 😐 |
| ;-) | 😉 |
| :-o | 😲 |
| :-x | 😶 |
| :'-( | 😥 |
| :-@ | 😠 |
| :-* | 😘 |
| :sun: | ☀ |
| :cloud: | ☁ |
| :umbrella: | ☂ |
| :star: | ★ |
| :phone: | ☎ |
| :check: | ✔ |
| :mult: | ✖ |
| :plus: | ✚ |
| :skull: | ☠ |
| :radioactive: | ☢ |
| :biohazard: | ☣ |
| :peace: | ☮ |
| :yinyang: | ☯ |
| :moon: | ☽ |
| :square: | ■ |
| :circle: | ● |
| :triangle: | ▲ |
| :arrow: | ➔ |
| :arrowhead: | ▶ |
| :bullet: | ◉ |
| :love: | ♥ |
| :heart: | |
| :spade: | ♠ |
| :diamond: | ♦ |
| :club: | ♣ |
| :note: | ♩ |
| :recycle: | ♻ |
| :_1_: | ➊ |
| :_2_: | ➋ |
| :_3_: | ➌ |
| :_4_: | ➍ |
| :_5_: | ➎ |
| :_6_: | ➏ |
| :_7_: | ➐ |
| :_8_: | ➑ |
| :_9_: | ➒ |
| :_10_: | ➓ |
| :_11_: | ⓫ |
| :_12_: | ⓬ |
| :_13_: | ⓭ |
| :_14_: | ⓮ |
| :_15_: | ⓯ |
| :_16_: | ⓰ |
| :_17_: | ⓱ |
| :_18_: | ⓲ |
| :_19_: | ⓳ |
| :_20_: | ⓴ |
| :dice1: | ⚀ |
| :dice2: | ⚁ |
| :dice3: | ⚂ |
| :dice4: | ⚃ |
| :dice5: | ⚄ |
| :dice6: | ⚅ |
| :flag: | ⚑ |
| :scale: | ⚖ |
| :atom: | ⚛ |
| :warning: | ⚠ |
| /!\ | |
| :clock: | ⌚ |
| :command: | ⌘ |
| :hourglass: | ⌛ |
| :enter: | ⎆ |
| :infinity: | ∞ |
| :_1/2_: | ½ |
| :_1/3_: | ⅓ |
| :_2/3_: | ⅔ |
| :_1/4_: | ¼ |
| :_3/4_: | ¾ |
| :_1/5_: | ⅕ |
| :_2/5_: | ⅖ |
| :_3/5_: | ⅗ |
| :_4/5_: | ⅘ |
| :_A_: | Ⓐ |
| :_B_: | Ⓑ |
| :_C_: | Ⓒ |
| :_D_: | Ⓓ |
| :_E_: | Ⓔ |
| :_F_: | Ⓕ |
| :_G_: | Ⓖ |
| :_H_: | Ⓗ |
| :_I_: | Ⓘ |
| :_J_: | Ⓙ |
| :_K_: | Ⓚ |
| :_L_: | Ⓛ |
| :_M_: | Ⓜ |
| :_N_: | Ⓝ |
| :_O_: | Ⓞ |
| :_P_: | Ⓟ |
| :_Q_: | Ⓠ |
| :_R_: | Ⓡ |
| :_S_: | Ⓢ |
| :_T_: | Ⓣ |
| :_U_: | Ⓤ |
| :_V_: | Ⓥ |
| :_W_: | Ⓦ |
| :_X_: | Ⓧ |
| :_Y_: | Ⓨ |
| :_Z_: | Ⓩ |
Je suis très intéressé par SkrivML.
En quoi est-il codé et quand penses-tu le mettre disponible ?
Renaud, je te vois venir à des kilomètres :).
Serai-je si prévisible ?
Comme c’est basé sur WikiRenderer, c’est codé en PHP. Je vais essayer de le publier très rapidement.
Si vous avez un projet en cours, je veux bien en entendre parler 😉 (par MP s’il le faut)
Je m’occupe de la doc d’atoum et les solutions actuelles de génération de doc ne répondent pas à mes besoins: trop basiques ou trop complexes.
La doc est actuellement en markdown, après avoir regardé un peu les autres markup langages, je me suis dit que rst était le plus adapté, mais il est finalement assez complexe pour les non initiés.
Ton SkrivML me convient parfaitement. Est-ce que ton générateur ne fait que la convertion en HTML ou est-ce qu’il a d’autres fonctionnalités, comme par exemple la génération d’une TOC ?
@Renaud : Ah, c’est pour la doc Atoum ! Intéressant ! 🙂
Pour le moment, le projet est tout récent. Je me suis focalisé sur l’interprétation Skriv vers HTML ; mais je suis ouvert à toutes les bonnes idées.
Bon point pour la génération de tables des matières, qu’on peut même imaginer de deux manières différentes : soit une directive permet de l’ajouter au début du texte, soit on peut récupérer le TOC séparément du reste du texte (comme c’est déjà le cas pour les notes de bas de page). L’un n’empêche pas l’autre, d’ailleurs.
Si d’autres fonctionnalités te passent pas la tête, n’hésite pas 😉
Comment sont gérés les liens ?
Là, concrètement, j’ai 6 pages (pour le moment) de documentation. J’ai besoin de faire des liens au sein même d’une page mais également entre les pages.
C’est facilement faisable ?
J’ai cru comprendre que si je faisais un retour à la ligne au milieu d’une phrase, ce retour à la ligne serait également répercuté dans le code HTML généré.
Or, j’ai volontairement coupé les lignes à max 100 caractères pour que cela reste lisible sur github, par exemple… Il faudra peut-être que je revienne sur ce point…
Tu parles d’un système d’extension. Existe-t-il déjà ?
Dans la documentation, j’ai souvent besoin d’écrire une note, un warning, bref quelque chose qui ressorte un peu du reste de la doc.
Est-ce que d’après toi, il serait facile d’ajouter (au hasard) {{{ note // blablabla }}} ?
Pour les liens entre les pages, il n’y a pas de soucis si tu connais les URLs à l’avance. Par exemple, tu peux faire un lien du genre [[/fr/chapitre-3.html#executable]]. Ou bien tu peux faire un lien qui ne commence pas par la racine, comme [[chapitre3.html]].
Je dois encore travailler sur le générateur d’identifiants pour les titres (afin que l’ancre “#executable” fonctionne).
Concernant les liens, j’ai des choses à faire. Parce que pour le moment le code effectue des traitements spécifiques à mon outil de gestion de projets, ce qui conduit à altérer certains liens (ceux qui ne commencent pas par « http[s]:// » ni par un slash sont considérés comme pointant sur une pièce-jointe ; ceux qui commencent par un dièse suivi de plusieurs chiffres sont considérés comme pointant vers un autre élément de l’outil). Il faut que je rende ces comportements débrayables et modifiables.
Pour les retours-chariots en milieu de paragraphe, j’ai choisi ce qui me semble correspondre le plus souvent à ce que souhaite l’utilisateur. D’autres personnes sont arrivées à la même conclusion (cf. GitHub Flavored Markdown et ce post de Jeff Atwood).
Le système d’extension n’existe pas encore. Mais j’y travaille 😉
Pour écrire des paragraphes stylisés, tu peux effectivement utiliser les triples accolades. Ce que tu places à droite des trois accolades ouvrantes sera utilisé comme classe CSS. Tant que tu crées les classes équivalentes dans tes styles CSS, tu peux faire ce que tu veux. (Par contre, tu auras remarqué que ce n’est pas une syntaxe inline, contrairement à ce que tu as écrit dans ton exemple.)
Tu peux déjà trouver une version pré-alpha sur mon compte GitHub : https://github.com/Amaury/SkrivMarkup
Et un standard de plus pour dans les ténèbres les lier…
http://xkcd.com/927/
Ce serait pas mieux de développer un programme de configuration tout simplement ? j’veux dire que tous ces langages de mark-up utilisent les mêmes « concepts » genre Gras, Italique, Titre etc donc on pourrait faire un programme qui configurerai suivant les choix de l’utilisateur les marqueurs à utiliser.
j’vais donner un exemple parce que je sens que je vais m’embrouiller sinon.
Je crée un programme qui va sauver les fichiers contenant les textes + les marqueurs que moi (le programmeur du soft) j’ai choisit, par exemple [[texte]] pour le gras
Quand un utilisateur ouvre un fichiers avec mon programme le programme va remplacer à l’affichage tous les marqueurs que moi j’ai choisit ( ex : [[ ) par ceux que l’utilisateur a définit ( ex : ** ) et vice versa à la sauvegarde.
Et hop, plus jamais besoin de créer un enième standard
Win/Fail ?
Je vois plusieurs problème au fait de mettre un bout de l’url en dur. Ça implique de mettre le format de sortie dans les sources alors que ça pourrait être tout autre chose que du HTML comme du PDF par exemple. Et puis, je pourrais très bien changer le nom des fichiers en sorties (chapitre3.html, chap3.html, chapitres/3.html, etc…)
Pour les retours chariots, ok, je changerai 🙂
Ok pour les triples accolades (oui, oui, j’ai écrit un exemple à la va vite, mais j’avais bien compris que ce n’était pas en ligne 🙂
Je vais regarder ton code sur github 🙂
@Rincevent : J’adore cette image de XKCD (je l’avais d’ailleurs déjà utilisée). C’est effectivement une vraie préoccupation. Créer un énième langage wiki-like a peu d’intérêt si ce n’est que pour finasser sur des détails.
Mais là, je pense avoir mis le doigt sur un équilibre que je n’arrive pas à trouver ailleurs, grâce notamment aux paragraphe stylisés, aux caractères spéciaux (smileys and co), à l’aspect systématique de la syntaxe (doubles caractères pour le marquage inline, triples caractères pour le marquage multilignes), au futur système d’extensions, … sans oublier le parseur lui-même, que j’essaye de rendre le plus souple possible (mais là j’avoue que je connais moins bien les autres parseurs que les autres syntaxes).
L’un dans l’autre, au final, ça reste fidèle à la logique du logiciel libre : Je ne suis pas satisfait par ce qui existe, je suis libre de développer mon propre projet ; tant qu’à faire, je le mets à disposition des autres, si ça peut leur servir c’est bien.
@Renaud : OK, je comprends le soucis pour les URLs en dur. Je suis en train d’ajouter un système de callback qui te permettra de réécrire les URLs comme tu veux. Ainsi, si quelqu’un écrit [[atoum-chap-3]], tu pourras générer une URL chapitre3.html. Et si un jour tu veux changer ton arborescence, tu n’auras plus qu’à modifier la fonction de réécriture des URLs.
Qu’en penses-tu ?
Bonne idée, j’ai hâte de voir tout ca 🙂
Très intéressant ! Vraiment, c’est intuitif comme syntaxe. J’attends de voir ce que ça va donner par la suite ^^
Est-ce que le système de callback permettra de personnaliser n’importe quel marqueur ?
Là par exemple, je souhaiterai personnaliser {{{info / {{{warning en ajoutant le html nécessaire pour utiliser fontawesome. Il faudrait donc que je puisse facilement ajouter un <i class= »icon-mon-icon »></i> entre le <div> et le <p> du texte.
Tu penses que c’est faisable ?
@Tatsu : Merci 🙂
@Renaud : A priori non. Le but reste de garder une certaine simplicité. Si on autorise la personalisation de tous les tags, on n’a pas fini. Et d’ailleurs, je ne pense pas qu’aucun autre système wiki ne permette ce genre de chose (pour commencer, je ne connais pas d’équivalent à mes blocs stylisés).
Mais on peut imaginer plusieurs solutions à ton problème :
– Solution idéale : Pouvoir tout faire par CSS. Ce qui n’est malheureusement pas possible si tu veux utiliser FontAwesome.
– Solution bidouille : Utiliser une callback de traitement post-parsing, qui convertirait tous les
<div class='warning'>en<div class='warning'><i class='icon-xzy'></i>.– Solution à moyen terme : Utiliser le futur système d’extensions, et créer ton propre marquage. Un truc du genre (attention, je réfléchis à voix haute, ne pas prendre cet exemple pour argent comptant) :
<<<mon_style_custom|warningTon texte...
>>>
Ah oui, j’aime bien la 3ème solution… mais effectivement, je vais utiliser la 2ème pour commencer 🙂
Merci beaucoup 🙂
Dommage que tu n’autorises pas la création d’issue sur tes repos, les commentaires sur ce billet ne sont sans doute pas la meilleure place pour faire des demandes 🙂
Bref, comment récupérer la TOC ?
Pour les issues, l’option était bien cochée pour SkrivMarkup. Je viens de l’ajouter sur WikiRenderer.
Pour la TOC il va falloir patienter un peu. J’ai à peine commencé à coder cette partie hier matin ! 🙂
Ah oui, zut, je regardais sur mon fork github, lol
Est-ce que la partie colorisation syntaxique fonctionne déjà ?
Non, il faut que je regarde l’intégration de la bibliothèque GeSHi.
À moins de passer par Google Code Prettify.
Bonjour,
je rejoins un peu le commentaire de Rincevent, c’est un peu dommage d’avoir créé un nouveau langage, inspiré des autres, alors qu’il existe déjà de très bonnes choses.
Au moins tu es parti sur de bonnes bases : effectivement markdown c’est pas la joie, et moi aussi je me pose la question de savoir pourquoi c’est devenu tellement hype.
Creole me semble plus structuré, et c’est dommage que ce projet semble mort depuis quelques années. Txt2tags, qui est antérieur à creole et markdown, propose d’ailleurs beaucoup d’éléments qui ont été « redécouverts » dans Creole (et étonnamment Creole n’y fait pas référence alors que 80 % de la syntaxe est similaire).
Skriv est effectivement cohérent, et ton travail de présentation est vraiment très bien fait.
Je ne peux m’empêcher de penser que c’est un peu dommage d’avoir un peu réinventé la roue alors que par exemple txt2tags permet grâce à son système de préprocesseur de réimplémenter assez facilement n’importe quelle syntaxe modifiée (si tu préfères les » au lieu des // pour les italiques, en txt2tags tu fais ça simplement avec un preproc). De plus on avait déjà réalisé un convertisseur txt2tags en php (qui permet également d’utilisateur le préprocesseur en regex, dans un fichier externe ou en entête de ficher) : http://txt2tags.org/txt2tags.form.php
Au final un certain nombre de gens vont utiliser skriv, d’autres vont utiliser txt2tags, et ça divisera un peu les forces au lieu de les fédérer dans un projet plus fort.
Au passage, je vois que ton blog est réalisé avec wordpress. Est-ce que tu composes tes messages en syntaxe Skriv ? Si ça t’intéresse on a réalisé un plugin txt2tags pour wordpress, ça devrait pouvoir s’adapter assez facilement pour Skriv : http://wiki.txt2tags.org/demos/wordpress/
@farvardin : Oui, je me suis évidemment posé longuement la question avant de créer ma propre syntaxe.
Mais ma démarche tient en deux points :
1. Je pense avoir apporté des innovations intéressantes (comme les paragraphes stylisés) qu’on ne trouve pas dans les autres syntaxes wiki-like. Sur le reste, j’ai pas mal détaillé les raisons qui ont poussé à choisir telle ou telle syntaxe (sur le site http://markup.skriv.org), ce qui explique en quoi je pense que cette syntaxe est intéressante.
2. C’est ça la magie des logiciels libres. Chacun fait ce qui lui semble le plus utile, le partage avec les autres, qui ont le choix de l’utiliser ou non.
Sinon, pour mon blog, j’utilise l’éditeur WYSIWYG la plupart du temps, et l’édition HTML de temps en temps. Usage différent, outils différents.