É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:
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"
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 une 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 #
Pour mettre en forme votre texte, les caractères suivants sont écrits au début d'une ligne:
# --- => *> !!! ``` %%%
- # : En-tête (titre). 1 à 6 "#" peuvent être écrits pour distinguer les niveaux d'en-tête.
- --- : Règle horizontale.
- => : un lien
- * : nouvel élément d'une liste.
- > : Citation.
- !!! : Message important (avertissement).
- ``` : commencer / arrêter un bloc de code.
- %%% : commencer / arrêter un bloc verbatim.
Deux blocs doivent être séparés par une ligne vide pour la lisibilité.
Deux lignes vides consécutives forcent un retour à la ligne.
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.
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.
Liens #
=> https://foo.bar => https://another.link lien avec description => https://this.is/a-picture.jpg alt texte La description du lien suivant est très longue, Il est donc écrit avant: => http://one-last.link
Un lien doit être facile à copier / coller, il est donc écrit sur une seule ligne.
Un lien doit être identifié facilement, on le note après "=>".
Un lien doit être décrit.
La description est écrite après le lien sur la même ligne, sur un paragraphe avant le lien pour les longues descriptions.
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 "*".
Pour écrire un "*" dans un long élément après un saut de ligne, ajoutez un espace au début de la ligne.
Citations #
> Ceci est une citation. -- auteur > C'est une très longue citation Sur plusieurs lignes - un autre auteur
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 [])
{
return 0;
}
```
Une ligne commençant par "```" ouvre ou ferme un bloc de code.
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
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//", etles lecteurs d'écran pour déficients visuels peinent aussi.
Si vous souhaitez mettre une partie en valeur:
- Utilisez des majuscules.
- Écrivez le texte important sur sa propre ligne.
- Utilisez un bloc "!!!".
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.