BAud : relecture / précisions (10 mars 2023 10:31:02)
Aide à l’édition
================
Pour tous les contenus (dépêche, journal, page wiki, etc.) ou commentaires du site, _LinuxFr.org_ utilise un langage à balisage afin de permettre aux utilisateurs d’ajouter du contenu aisément. Il s’agit de la syntaxe [Markdown](http://fr.wikipedia.org/wiki/Markdown "Définition Wikipédia") qui sert aussi pour la [[[rédaction]]] collaborative de dépêches.
Markdown est une syntaxe ayant pour but d’être _facile_ à lire et écrire, ainsi, un document formaté en Markdown ne donne pas l’impression d’être marqué par des balises. Pour en savoir plus, vous pouvez consulter la [documentation officielle](http://daringfireball.net/projects/markdown/syntax) ou encore s[la traduction en [français du Markdown](http://michelf.com/projets/php-markdown/syntaxe/).
Le site _LinuxFr.org_ modifie quelque peu la syntaxe Markdown et y apporte quelques [extensions](http://www.pell.portland.or.us/~orc/Code/discount/#Language+extensions). Cette page présente les éléments les plus importants de la syntaxe utilisée sur le site _LinuxFr.org_.
Afin de vous essayer à cette syntaxe, vous pouvez utiliser le [bac à sable](Bac-a-sable) : c'est une page _poubelle_ que personne ne regarde.
Caractères
----------
Caractères spéciaux à copier‐coller :
```
æ Æ à À â Â ä Ä
ç Ç
€ é É è È ê Ê ë Ë
î Î ï Ï
œ Œ ô Ô ö Ö
ù Ù û Û ü Ü
ÿ Ÿ
¹ ² ³ ⁴ ⁵ ⁶ ⁷ ⁸ ⁹ ⁰
½ « » ~ # @ … ‰ € – —
```
Pour les caractères scientifiques :
$\alpha$ — $\beta$ — $\Omega$ → utiliser la syntaxe LaTeX `$\Omega$`, [liste plus complète sur Wikipédia](https://fr.wikipedia.org/wiki/Table_des_symboles_litt%C3%A9raux_en_math%C3%A9matiques).
Un exemple de formule :
$U = L \cdot \frac {di}{dt}$
Note : cela a comme effet de bord qu’un paragraphe contenant deux signes `$` ne s’affiche plus correctement. :/ Utilisez l’entité HTML `$` pour faire apparaître le signe $.
Titres
------
Il existe cinq niveaux de titres. Un titre est précédé du symbole `#`, le nombre de fois où ce symbole est répété indique le niveau du titre.
```
# Titre de niveau 1
## Titre de niveau 2
### Titre de niveau 3
#### Titre de niveau 4
##### Titre de niveau 5
```
# Titre de niveau 1
## Titre de niveau 2
### Titre de niveau 3
#### Titre de niveau 4
##### Titre de niveau 5
Afin de clarifier le texte, les titres de niveau 1 et 2 peuvent être écrits sous cette forme :
```
Titre de niveau 1
=================
Titre de niveau 2
-----------------
Fin de la section titre
=======================
```
Le résultat étant le même que précédemment.
Titre de niveau 1
=================
Titre de niveau 2
-----------------
Fin de la section titre
=======================
Sommaire
--------
Lorsque le texte d'un contenu devient suffisamment grand, un sommaire est automatiquement crée à partir des titres par LinuxFr. Actuellement, il faut un texte d'au moins 5 000 caractères ([code source](https://github.com/linuxfrorg/html-pipeline-linuxfr/blob/e570c7b39cad147958f582f5eab17ee7ed6694a0/lib/html/pipeline/linuxfr.rb#L6)).
Pour une dépêche, le sommaire est crée pour chaque partie de la dépêche. Comme il est déconseillé d'avoir une première partie trop longue, en pratique seule la seconde partie aura un sommaire si elle contient elle-même les 5 000 caractères.
Mise en forme du texte
----------------------
Afin de donner du caractère à votre texte, la syntaxe vous permet d’utiliser de l’_italique_ (qui correspond à l’emphase normale), du **gras** (qui correspond à l’emphase forte), et bien plus encore.
Par exemple :
```
_italique_ ou *italique*
__gras__ ou **gras**, ou même au milieu d’un mot comme mon<U+FEFF>**go**<U+FEFF>db
`chasse fixe`
~~barré~~
```
ce qui donne :
> _italique_ ou *italique* : utilisé pour les anglicismes, par exemple, n’ayant pas de [[[traductions classiques]]].
>
> __gras__ ou **gras**, ou même au milieu d’un mot comme mon<U+FEFF>**go**<U+FEFF>db
>
> `chasse fixe` : utilisé pour les instructions en ligne de commande plutôt que d’utiliser la balise de code \`\`\` qui oblige à sauter un paragraphe et passer à la ligne.
>
> ~~barré~~
Note au sujet de la `chasse fixe`: pour un rendu correct, il est parfois nécessaire d'utiliser \`\` au lieu de \` comme délimiteur lorsque certains caractères spéciaux apparaissent dans le texte à mettre en forme, voire même \`\` plus un espace lorsqu'un caractère \` est présent dans l'expression à mettre en forme. Par exemple :
```
Un peu de texte en chasse fixe comme ``$...$`` ou `` `code` `` au milieu de texte normal.
```
ce qui donne :
> Un peu de texte en chasse fixe comme ``$...$`` ou `` `code` `` au milieu de texte normal.
Finalement, si vous voulez vraiment entourer votre texte avec les caractères précédents sans que cela résulte en une mise en forme particulière, vous devez les échapper avec le caractère `\`.
```
Mon texte sans \_mise\_ en \*\*forme\*\*.
```
ce qui donne :
> Mon texte sans \_mise\_ en \*\*forme\*\*.
Code avec coloration syntaxique
-------------------------------
Vous avez aussi la possibilité d’ajouter des blocs de code avec la balise \`\`\` :
* pensez à ajouter une ligne blanche avant la balise \`\`\` ;
* voir <http://pygments.org/languages/> pour la liste des langages gérés.
Exemple Java :
```java
public class Bonjour {
public static int main(String[] args) {
System.out.println("Bonjour !");
}
}
```
Ce qui donne :
```java
public class Bonjour {
public static int main(String[] args) {
System.out.println("Bonjour !");
}
}
```
Exemple Python :
```python
print "Bonjour !"
Bonjour !
```
Résultat :
```python
print "Bonjour !"
Bonjour !
```
Pour mettre en forme les unités _systemd_, utilisez la balise `ini`. Le code suivant :
```ini
[Unit]
Description=Exemple avec la balise ini
[Service]
ExecStart=/usr/bin/troll
[Install]
WantedBy=moules.target
```
donnera ceci :
```ini
[Unit]
Description=Exemple avec la balise ini
[Service]
ExecStart=/usr/bin/troll
[Install]
WantedBy=moules.target
```
À savoir, le langage utilisé doit être spécifié. S’il ne s’agit pas d’un langage en particulier, vous pouvez soit utiliser le formatage `text` ou faire précéder chaque ligne de code de quatre espaces.
```
Ceci est un texte qui n’utilise pas
un langage de programmation en
particulier.
```
équivaut à :
```
[4 espaces] Ceci est un texte qui n’utilise pas
[4 espaces] un langage de programmation en
[4 espaces] particulier.
```
Ceci est un texte qui n’utilise pas
un langage de programmation en
particulier.
Paragraphes
-----------
Un paragraphe est simplement une ou plusieurs lignes consécutives de texte séparées par une ou plusieurs lignes vides.
```
Mox dicta finierat, multitudo omnis ad, quae imperator voluit, promptior laudato consilio consensit in pacem ea ratione maxime percita, quod norat expeditionibus crebris fortunam eius in malis tantum civilibus vigilasse, cum autem bella moverentur externa, accidisse plerumque luctuosa, icto post haec foedere gentium ritu perfectaque sollemnitate imperator Mediolanum ad hiberna discessit.
Exsistit autem hoc loco quaedam quaestio subdifficilis, num quando amici novi, digni amicitia, veteribus sint anteponendi, ut equis vetulis teneros anteponere solemus. Indigna homine dubitatio! Non enim debent esse amicitiarum sicut aliarum rerum satietates; veterrima quaeque, ut ea vina, quae vetustatem ferunt, esse debet suavissima; verumque illud est, quod dicitur, multos modios salis simul edendos esse, ut amicitiae munus expletum sit.
```
> Mox dicta finierat, multitudo omnis ad, quae imperator voluit, promptior laudato consilio consensit in pacem ea ratione maxime percita, quod norat expeditionibus crebris fortunam eius in malis tantum civilibus vigilasse, cum autem bella moverentur externa, accidisse plerumque luctuosa, icto post haec foedere gentium ritu perfectaque sollemnitate imperator Mediolanum ad hiberna discessit.
> Exsistit autem hoc loco quaedam quaestio subdifficilis, num quando amici novi, digni amicitia, veteribus sint anteponendi, ut equis vetulis teneros anteponere solemus. Indigna homine dubitatio! Non enim debent esse amicitiarum sicut aliarum rerum satietates; veterrima quaeque, ut ea vina, quae vetustatem ferunt, esse debet suavissima; verumque illud est, quod dicitur, multos modios salis simul edendos esse, ut amicitiae munus expletum sit.
**Attention**, en contradiction avec la spécification mMarkdown, _LinuxFr.org_ active le « _hard wrapping » : un retour à la ligne au milieu d’un paragraphe n’est pas ignoré et se traduit par un retour à la ligne dans le rendu, même en l’absence de deux espaces en fin de ligne.
```
Eminuit autem inter humilia supergressa iam impotentia fines (pas d’espaces ajoutées)
mediocrium delictorum nefanda Clematii cuiusdam Alexandrini nobilis mors repentina.
```
> Eminuit autem inter humilia supergressa iam impotentia fines (pas d’espaces ajoutées)
mediocrium delictorum nefanda Clematii cuiusdam Alexandrini nobilis mors repentina.
Ce choix perturbe moins les utilisateurs ne connaissant pas Markdown, qui s’attendent à ce qu’un saut de ligne dans le document source se traduise en un saut de ligne forcé au rendu. Si vous utilisez un éditeur externe, il faudra le configurer pour éviter les sauts de ligne de présentation (commande `[unfill-region](http://www.emacswiki.org/emacs/UnfillRegion)` pour Emacs, par exemple).
Attention, ce comportement s’applique seulement aux sauts de ligne au sein d’un paragraphe, pas à plusieurs lignes vides répétées qui sont traduites en une unique ligne inter‐paragraphe.
```
ceci
cela
```
> ceci
>
>
>
> cela
Pour obtenir plusieurs lignes vides (un choix typographique discutable), on peut insérer le caractère d’échappement ` ` sur les lignes interstitielles.
Citations
---------
Les citations sont un ensemble de lignes précédées par le symbole `>`. _Note_ : ne pas oublier de passer une ligne pour ajouter votre commentaire concernant ce qui est cité (sinon c'est intégré dans la citation :/).
```
> Itaque verae amicitiae difficillime reperiuntur in iis qui in honoribus reque publica
> versantur; ubi enim istum invenias qui honorem amici anteponat suo? Quid? Haec ut
> omittam, quam graves, quam difficiles plerisque videntur calamitatum societates!
> Ad quas non est facile inventu qui descendant. Quamquam Ennius recte.
```
> Itaque verae amicitiae difficillime reperiuntur in iis qui in honoribus reque publica
> versantur; ubi enim istum invenias qui honorem amici anteponat suo? Quid? Haec ut
> omittam, quam graves, quam difficiles plerisque videntur calamitatum societates!
> Ad quas non est facile inventu qui descendant. Quamquam Ennius recte.
Les plus paresseux peuvent simplement placer ce symbole sur la première ligne d’un paragraphe. _Note_ : pour distinguer votre commentaire sur ce qui est cité, cela oblige à laisser une ligne blanche (déjà dit avant, c'est un rappel :p).
```
> Itaque verae amicitiae difficillime reperiuntur in iis qui in honoribus reque publica
versantur; ubi enim istum invenias qui honorem amici anteponat suo? Quid? Haec ut
omittam, quam graves, quam difficiles plerisque videntur calamitatum societates!
Ad quas non est facile inventu qui descendant. Quamquam Ennius recte.
```
> Itaque verae amicitiae difficillime reperiuntur in iis qui in honoribus reque publica
versantur; ubi enim istum invenias qui honorem amici anteponat suo? Quid? Haec ut
omittam, quam graves, quam difficiles plerisque videntur calamitatum societates!
Ad quas non est facile inventu qui descendant. Quamquam Ennius recte.
Il est aussi possible d’insérer une citation dans la citation ou encore utiliser des éléments de la syntaxe Markdown :
```
> Sed maximum est in amicitia parem esse inferiori. Saepe enim excellentiae quaedam sunt, qualis erat Scipionis in nostro, ut ita dicam, grege. Numquam se ille Philo, numquam Rupilio, numquam Mummio anteposuit, numquam inferioris ordinis amicis, Q. vero Maximum fratrem, egregium virum omnino, sibi nequaquam parem, quod is anteibat aetate, tamquam superiorem colebat suosque omnes per se posse esse ampliores volebat.
> > Senator exempla publicae ipsas publicae hominum quis fui factorum semper hominum mihi omnium mihi petenda.
```
> Sed maximum est in amicitia parem esse inferiori. Saepe enim excellentiae quaedam sunt, qualis erat Scipionis in nostro, ut ita dicam, grege. Numquam se ille Philo, numquam Rupilio, numquam Mummio anteposuit, numquam inferioris ordinis amicis, Q. vero Maximum fratrem, egregium virum omnino, sibi nequaquam parem, quod is anteibat aetate, tamquam superiorem colebat suosque omnes per se posse esse ampliores volebat.
> > Senator exempla publicae ipsas publicae hominum quis fui factorum semper hominum mihi omnium mihi petenda.
## Hyperliens
Afin d’étoffer vos propos, vous aurez sûrement besoin d’ajouter quelques liens. Nous pouvons différencier trois types de liens : les liens internes qui sont des liens vers le wiki du site, les liens externes qui pointent vers un site InternetWeb et les liens vers un article [Wikipédia](http://fr.wikipedia.org/wiki/Wikipédia "Définition Wikipédia") :
```
* lien vers la page principale du wiki : [[[linuxfr-org]]] ;
* lien nommé vers la [page principale du wiki](//linuxfr.org/wiki/linuxfr-org) ;
* lien externe : <http://linuxfr.org> ;
* lien externe nommé : [LinuxFr.org](http://linuxfr.org), idéalement ce qui est entre crochets indique sémantiquement ce vers quoi le lien va pointer ;
* lien vers une définition Wikipédia : [Wikipédia](http://fr.wikipedia.org/wiki/Wikipédia "Définition Wikipédia") ;
* lien raccourci vers une [[définition]] Wikipédia francophone ;
* lien raccourci vers une [[en:definition]] Wikipedia non francophone en le préfixant du code ISO 639-1 de la langue souhaitée ;
* lien raccourci vers un [[wikt:mot]] du Wiktionnaire.
```
Ce qui donne :
* lien vers la page principale du wiki : [[[linuxfr-org]]] ;
* lien nommé vers la [page principale du wiki](//linuxfr.org/wiki/linuxfr-org) ;
* lien externe : <http://linuxfr.org> ;
* lien externe nommé : [LinuxFr.org](http://linuxfr.org), idéalement ce qui est entre crochets indique sémantiquement ce vers quoi le lien va pointer ;
* lien vers une définition Wikipédia : [Wikipédia](http://fr.wikipedia.org/wiki/Wikipédia "Définition Wikipédia") ;
* lien raccourci vers une [[définition]] Wikipédia francophone ;
* lien raccourci vers une [[en:definition]] Wikipedia non francophone en le préfixant du code ISO 639-1 de la langue souhaitée ;
* lien raccourci vers un [[wikt:mot]] du Wiktionnaire.
Les liens raccourcis vers des Wikipeédia non francophones sont _volontairement_ limités aux versions anglophones [en], germanophones [de], hispanophones [es] et espérantophones [eo], ce qui est lié au fonctionnement de Wikipédia et non de LinuxFr.org.
### Liens par référence
Ce type de lien facilite votre rédaction en utilisant des références pour les liens qui reviennent souvent. Par exemple :
« J’aime \[LinuxFr.org]\[ref_lfr] pour ses trolls magnifiques. \[DLFP]\[ref_lfr] est le meilleur site pour parler de \[LinuxFr.org]\[ref_lfr]. »
\[ref_lfr]: http://linuxfr.org
donnera : « J’aime [LinuxFr.org][ref_lfr] pour ses trolls magnifiques [DLFP][ref_lfr] est le meilleur site pour parler de [LinuxFr][ref_lfr]. »
[ref_lfr]: http://linuxfr.org
Ça n’a rien à voir avec les notes de bas de page (même si c'est la même syntaxe), cela correspond plutôt à des renvois dans une bibliographie (: technique utilisée par _CrEv<_ pour la présentation de sa [veille technologique](http://linuxfr.org/tags/veille_technologique/public)).
## Les listes et énumérations
Il existe trois types de listes, **pensez à mettre une ligne blanche avant pour les utiliser** (s'il faut le répéter, c'est que c'est un [motto](https://fr.wiktionary.org/wiki/motto)) :
### les listes à puces
_pensez à mettre une ligne blanche avant pour les utiliser_
```
* élément 1 (un point‐virgule précédé d’une espace fine insécable (“ ”) termine chaque élément) ;
* élément 2 ;
* je peux même y mettre un texte qui s’étend sur (2 espaces en fin de ligne)
plusieurs lignes :
* et faire des listes imbriquées (une simple virgule sépare les sous‐éléments),
* de cette manière,
* en indentant de deux espaces en début de ligne (le dernier sous‐élément est terminé par un point‐virgule précédé de son inséparable espace fine insécable) ;
* élément final.
```
* élément 1 ;
* élément 2 ;
* je peux même y mettre un texte qui s’étend sur
plusieurs lignes :
* et faire des listes imbriquées,
* de cette manière,
* en indentant de deux espaces en début de ligne ;
* élément final.
### les listes ordonnées
_pensez à mettre une ligne blanche avant pour les utiliser_
```
1. élément 1 ;
1. élément 2 ;
1. élément 3.
```
1. élément 1 ;
1. élément 2 ;
1. élément 3.
### Les listes de définition
_pensez à mettre une ligne blanche avant pour les utiliser_
```
terme 1
(4 espaces) Définition 1.
terme 2
Définition 2.
```
terme 1
Définition 1.
terme 2
Définition 2.
Tableaux
--------
La syntaxe Markdown permet d’insérer des tableaux de façon intuitive :
```
Titre 1 | Titre 2 | Titre 3
------------|-----------|----------
**Ligne 1** | Élément 3 | Élément 5
**Ligne 2** | Élément 4 | Élément 6
```
Titre 1 | Titre 2 | Titre 3
------------|-----------|----------
**Ligne 1** | Élément 3 | Élément 5
**Ligne 2** | Élément 4 | Élément 6
Voir <http://michelf.com/projects/php-markdown/extra/#table> pour aligner les colonnes.
Images
------
Grande nouveauté sur _LinuxFr.org_, on peut maintenant incorporer des images où l’on veut. Alors, profitons-en :
```
```
Il est possible (et même conseillé) de mettre un titre sur l’image :
```
```
Si votre image est trop grande, vous pouvez spécifier la taille à laquelle vous souhaitez l’inclure (mais cela ne fonctionne plus depuis l’ajout du titre /o\\) :
```
 (2 espaces)
Image originale : (2 espaces)
```
Image originale :
L’hébergement de l’image initiale reste à votre charge, elle est en cache sur _img_ : en auto‐hébergé, sur _Pix_ de _Toile‐Libre_ ou _lutim_, selon votre préférence… Notez également que seules les images de [moins de 5MB Mio](https://github.com/linuxfrorg/img-LinuxFr.org/blob/master/img.go#L36) peuvent être incluses dans vos contenus.
**À savoir** : si l’image n’apparaît pas en prévisualisation, elle n’apparaîtra pas plus par magie ou l’effet d’une intervention divine (hors celle de la modération après publication du contenu, s’entend) une fois le contenu publié. Si la source de l’image propose plusieurs adresses à copier, essayez jusqu’à tomber sur la bonne. Si elle provient d’un dépôt git, il est possible que c’est parce que vous avez copié l’adresse sans la mention `?raw=true` ([voir le commentaire signalant celale raw=true](https://linuxfr.org/nodes/125975/comments/1872259)) à la fin.
Ligne de séparation
-------------------
Il est possible de créer une ligne de démarcation en faisant suivre trois ou plus des caractères suivants : `*`, `-` et `_`.
```
***
----
_____
```
***
----
_____
Adresse de courriel, XMPP…
--------------------------
Les adresses de courriel sont automatiquement transformées avec le lien `mailto:` : <example@example.com>.
Pour les adresses XMPP, il faut utiliser la même syntaxe que pour les liens HTTP : `[xmpp:example@example.com](xmpp:example@example.com)` donne [xmpp:example@example.com](<xmpp:example@example.com>)
Notes de bas de page
--------------------
Les notes de bas de page suivent [la syntaxe de PHP Markdown](http://michelf.ca/projects/php-markdown/extra/#footnotes). Par exemple, pour la note de bas de page n^(o) 1, on écrit `[^1]` là où l’on veut placer la référence. Et en fin d’article, on écrit : `[^1]:` note[^1]
**Attention** : le caractère ^ s'obtient généralement avec la touche ^ suivi de la touche espace, si une graphie (avec ou sans espace) ne donne pas le résultat attendu, essayer l’autre. Par ailleurs, il est possible que le copier-coller ne fonctionne pas bien de Writer vers Firefox, dans ce cas, il faudra réécrire les appels de notes.
Attention à ne pas utiliser d’espace insécable dans les notes, sinon le lien de note n’est pas créé.
Note : il y a un [bogue en rédaction empêchant la visualisation](//linuxfr.org/suivi/bug-en-redaction-sur-notes-de-bas-de-page). N’hésitez pourtant pas à les utiliser, cela peut être corrigé en modération.
[^1]: note : on peut ajouter des références dans le texte, directement sous le paragraphe, détaillées en bas, comme ici.
En bref
-------
Quelques éléments qui peuvent s’avérer utiles :
* ` `, espace insécable (le caractère UTF-8 “ ” doit être préféré à cet antique code HTML) ;
* 2\^8 pour mettre un caractère en exposant, suivi d’une espace :
* si vous avez besoin de mettre autre chose qu’une espace‐mot [espace classique, caractère ASCII 32], comme une espace insécable, une ponctuation comme une virgule, il faut entourer l’exposant de parenthèses pour que votre caractère ne soit pas également mis en exposant,
* exemple : 1\^(er) étage ou Paris I\^(er) ;
Donne :
* “ ”, espace insécable ;
* 2^8 pour mettre un caractère en exposant :
* exemple : 1^(er) étage ou Paris I^(er).
Le mot de la fin
================
Cette page ne présente qu’un sous‐ensemble de la syntaxe Markdown mais devrait vous suffire à proposer du contenu sur le site _LinuxFr.org_. Si vous voulez en savoir plus sur la syntaxe Markdown, n’hésiter à jeter un œil sur [le Web concernant Markdown](http://lmgtfy.com/?q=markdown) et pensez au [bac à sable](Bac-a-sable) pour vous entraîner.