# Écrire du texte pour toute une vie
Garder les bonnes idée du gemtext et markdown et autre pour avoir une
meilleure syntaxe.
Voir aussi:
=> https://sr.ht/~prx/amore/ amore: a more readable plaintext markup
## À propos du texte brut et balisages
### Plaintext (texte brut)
Le texte brut, ou plaintext, sera lisible pour toujours, contrairement
à d'autres formats de fichier.
C'est aussi TRÈS léger.
Par exemple, un fichier contenant seulement "Coucou" au format txt pèse
7B tandis qu'il pèse 4,9KB au format docx.
Le texte brut peut avoir la forme qu'on souhaite vraiment.
Par ailleurs, c'est très bien supporté par les lecteurs d'écran.
Voir aussi "Writing for the internet across a human lifetime"
=> https://web.archive.org/web/20211025182333/https://len.falken.ink/misc/writing-for-the-internet-across-a-human-lifetime.txt
### Markup (balisage)
Certains outils de balisage sont pratiques pour rendre votre texte brut
à d'autres formats, comme HTML. On peut ajouter des hyperliens, des
titres ou même des images.
Un bon markup devrait être:
* Facile à retenir.
* Facile à lire.
* Facile à modifier (pensez git).
* Facilement convertible en un autre balisage.
Le Markdown est l'un des langages de balisage les plus connus:
=> https://www.markdownguide.org/
Il est assez facile à lire, à se souvenir et à modifier.
Cependant, il souffre de pénibles défauts:
* Les liens sont illisibles.
* Les liens pour les images sont différents des autres.
* Il existe différentes implémentations, ce qui le rend parfois incohérent.
* Les listes non ordonnées ne peuvent pas commencer par un numéro (sauf
avec de la magie).
Gemtext est un autre markup avec de très bonnes idées:
=> https://geminiprotocol.net/docs/gemtext-specification.gmi
Il est très facile à retenir et peu complexe.
Il est également très facile de le convertir en un autre format.
Cependant, cela produit parfois de très longues lignes difficiles à lire et à éditer.
## Une meilleure syntaxe de texte brut
Si la ligne écrite n'est pas un simple paragraphe, indiquez au moins
l'un des caractères suivants en début de ligne :
```
# - * > ! ` %
```
* # : En-tête (titre). 1 à 6 "#" peuvent être écrits
pour distinguer les niveaux d'en-tête.
* * : nouvel élément d'une liste.
* > : Citation.
* ! : un message important (avertissement).
* - : Règle horizontale.
* ` : commencer / arrêter un bloc de code.
* % : commencer / arrêter un bloc verbatim.
Un bloc se termine par une ligne vide. Cela favorise la lisibilité, et
permet d'écrire de longs segments sur plusieurs lines (même les titres).
Cela est vrai sauf pour les blocs de code "`" et verbatim "%".
Deux lignes vides consécutives forcent un retour à la ligne.
Quand un bloc est déjà ouvert, on peut continuer à commencer les lignes
suivantes du même bloc par le caractère spécial correspondant, mais ce
n'est pas obligé.
Les liens sont seuls sur leur ligne. Les lignes (non-vides) suivantes
sont la description du lien.
Toute autre ligne fait partie d'un paragraphe.
Cela fait moins de 10 choses à retenir.
Si l'un des caractères précédents doit être écrit au début d'une ligne
sans formatage, ils doivent être écrits après un espace.
! Remarquez que c'est compatible avec le Markdown.
### En-têtes
```
# En-tête 1
## En-tête 2
### En-tête 3
```
Une ligne d'en-tête commence avec un à six "#".
Les niveaux 4, 5, 6 doivent être évités: 3 niveaux sont suffisants pour
garder une structure de document raisonnable.
Les espaces après les derniers "#" sont facultatifs.
### Règles horizontales
```
-
```
Une ligne commençant par "-" est transformée en une règle horizontale.
"---" fonctionne aussi.
### Liens
Contrairement au gemtext, pas besoin d'indiquer "=>" en début de ligne :
les liens sont souvent très longs ce qui, avec la description en plus,
crée des lignes inutilement grandes et rend difficile la copie d'un
lien.
Exemples :
```
[h|Lien avec description
https://another.link|URL:https://another.link|server|port]
[h|Description de l'image suivante
```
https://this.is/a-picture.jpg|URL:https://this.is/a-picture.jpg|server|port]
On remarque qu'un lien direct vers un fichier adjacent, par exexemple "image.jpg"
n'est pas possible. Il faudra explicitement indiquer son chemin
relatif, c'est à dire "./image.jpg". C'est aussi bien pour éviter les
confusions.
Une image, un fichier audio ou une vidéo peuvent être intégrés avec
leur URL.
L'outils de conversion éventuel détectera l'extension pour les placer
dans une balise appropriée.
Terminer l'URL avec un "?" ou un "#" permet d'insérer un lien vers le
media plutôt qu'une balise spéciale.
### Listes
```
* Objet 1
* Objet 2
* Objet 3
* Objet 4 un peu trop long
il est divisé sur deux lignes
* Objet 5 divisé
sur 3 lignes mais on ajoute quelques
espaces pour faire plus joli.
```
Les éléments des listes sont identifiés avec des lignes commençant par
"*".
### Citations
```
> Ceci est une citation. -- auteur
> C'est une très longue citation
Sur plusieurs lignes
- un autre auteur
> Encore une citation
> sur plusieurs lignes
>
> mais plus lisible.
```
Une ligne commençant par un ">" ouvre un nouveau bloc de citation.
### AVERTISSEMENT / IMPORTANT
```
! C'est un message très important
```
Une ligne commençant par "!" doit être affichée comme un message
important.
### Blocs de code
```
`
/* Ceci est un bloc de code */
#include <stdio.h>
int
main (int argc, char * argv [])
{
Happy helping ☃ here: You tried to output a spurious TAB character. This will break gopher. Please review your scripts. Have a nice day!
}
`
```
Une ligne commençant par "`" ouvre ou ferme un bloc de code.
On peut bien sûr utiliser "```".
### Verbatim
```
%%%
C'est du code qui ne sera sera pas modifié
<details>
<summary> Cliquez pour afficher plus </summary>
Surprise!
</details>
%%%
```
Démarrer une ligne avec "%%%" ouvre/ferme un bloc verbatim.
## FAQ
### Mais il me manque <insérer fonctionnalité ici>
Cela veut peut-être dire qu'il faut revoir comment présenter et
organiser son texte.
Souvent, le résultat est plus clair ensuite.
Sinon, il existe d'autres markups peut-être plus adaptés?
### Des tableaux?
Non
Si vous avez vraiiiiment besoin d'un tableau, utilisez des tableaux
ASCII dans des blocs de code.
=> https://plaintexttools.github.io/plain-text-table/
=> https://www.tablesgenerator.com/text_tables
=> https://asciiflow.com/#/
### Comment ajouter des listes imbriquées?
Vous ne pouvez pas.
Les listes imbriquées ne sont pas pratiques à lire et peuvent rendre le
texte confus.
### Comment écrire des listes numérotées?
Ajoutez simplement des nombres:
```
* 1. Premier élément
* 2. Deuxième élément
* 3. Troisième élément
```
### Comment insérer des lignes vides?
Ajoutez simplement un espace au début d'une ligne pour forcer une
rupture de ligne.
En fait, cela insérera un paragraphe vide.
Sinon, 2 lignes vides consécutives forcent un retour à la ligne.
### Comment ajouter du texte gras, italique et souligné?
Vous ne pouvez pas.
C'est pénible de lire des "__souligné__", ou "**gras**" ou même
"//italique//", et les lecteurs d'écran pour déficients visuels peinent
aussi.
Par ailleurs, on a souvent tendance à penser (en tant qu'auteur) qu'à
partir du moment où un mot a été écrit en gras, le lecteur l'aura
forcément repéré, alors qu'il est souvent perdu au milieu d'un
paragraphe.
Si vous souhaitez mettre une partie en valeur:
* Utilisez des majuscules.
* Écrivez le texte important sur sa propre ligne.
* Utilisez un bloc "!".
Si, comme Alain Damasio, vous utilisez la typographie pour rendre votre
texte mélodieux, alors vous avez toujours accès à l'italique et au gras
avec l'UTF-8.
### Comment insérer du texte en indice?
Utilisez le symbole UTF-8: H₂o
### Comment insérer une note de bas de page
Évitez si possible.
Les notes de bas de page sont pénibles : le lecteur est obligé de
descendre tout en bas de la page pour la lire puis de remonter ensuite.
Cependant, une phrase bien écrite ou même des parenthèses
sont beaucoup plus faciles à lire.
### Quelle extension de fichier dois-je utiliser?
Vous pouvez utiliser l'extension de fichier ".pot", comme "prx's
opinionated text".
Ou peut-être ".bts" comme "better text syntax".
Je plaisante, peu importe.
Pour ma part, j'utilise ".txt", car c'est du texte brut après tout.