Introduction rapide au langage "gemtext"

La manière la plus commune de distribuer du contenu textuel via Gemini n'est pas avec du texte pur comme avec Gopher mais en utilisant un langage de balisage léger nommé "Gemtext" (distribué avec le type MIME officieux text/gemini). Ce document est une introduction rapide à ce langage. Il a quelques ressemblances avec le Markdown, ce qui le rend facile à apprendre si vous connaissez le MD, mais il se différencie sur certains points importants.

Une fois que vous aurez lu ce document, vous voudrez peut-être vous rafraichir la mémoire en vous référant au:

Antisèche Gemtext

Texte

Le texte dans les documents Gemtext doivent être écrits en utilisant des "longues lignes", i.e. vous (ou votre éditeur de text) ne devriez pas insérer de retour chariot tout les X caractères. À la place, laissez le client Gemini qui reçoit le texte le formater pour s'adapter à la taille de l'écran et aux préférences de l'utilisateur. De cette manière le contenu Gemtext est beau et facile à lire quel que soit le type de moniteur: PC fixe, portables, tablettes et smartphones.

Les clients Gemini vont revenir à la ligne quand le texte est plus long que la largeur de l'écran mais ne vont pas concaténer les lignes plus courtes, ce qui arrive en Markdown, HTML ou LaTeX. Ce qui veut dire que les listes à points ou les poèmes sur des lignes courtes sont affichés correctement sans travail supplémentaire du client qui n'a pas besoin d'être plus intélligent pour reconnaître et gérer de genre de contenu.

Pour la plupart des écrits "de tous les jours", cette approche fait que vous utiliserez en général qu'une ligne par paragraphe.

Notez que les lignes vides seront affichées telle quelle par les clients, c-à-d que si vous mettez deux ou trois lignes vides à la suite, le lecteur verra également deux ou trois lignes vides.

Liens

Comme Gopher (et contrairement au Markdown ou au HTML), Gemtext n'autorise le placement de liens vers d'autres documents que sur leur propre ligne. On ne peut pas faire d'une mot en milieu de ligne un lien. Il faut s'y habituer mais cela veut dire que tous les liens sont faciles à trouver, et les clients peuvent les styliser différemment (e.g. rendre évident quel protocole est utilisé, ou le nom de domaine pour aider les utilisateurs à décider s'il veulent suivre le lien) sans interférer avec la lisibilité du texte.

Les liens ressemblent à:

=> https://exemple.com    Un site web cool
=> gopher://exemple.com   Un gopherhole encore plus cool
=> gemini://exemple.com   Une capsule Gemini suprêmement cool
=> sftp://exemple.com

That is:

• Ils commencent par =>,
• suivi de blancs optionnels (espaces ou tabulations, autant que vous voulez),
• puis une URL (utilisant le protocole de votre choix).
• Il peuvent s'arrêter là comme avec l'exemple sftp au dessus!
• Ou ils peuvent être suivi d'au moins un espace ou tabulation,
• puis une étiquette, aussi longue que vous voulez

Dans l'exemple ci-dessus, toutes les URLs et étiquettes sont alignées parce que l'auteur était maniac mais Gemini n'y accorde pas d'importance et ce qui suit est également valable:

=>https://exemple.com Un site web cool
=>gopher://exemple.com      Un gopherhole encore plus cool
=> gemini://exemple.com Une capsule Gemini suprêmement cool
=>   sftp://exemple.com

Titres

Gemtext supporte trois niveau de titres. Les titres sont limités à une seule ligne et commencent par un, deux ou trois symboles # suivis d'un espace obligatoire:

# Titre

## Sous-titre

### Sous-sous-titre

C'est la seule syntaxe autorisé pour les titres. Souligner vos titres avec - ou = comme en Markdown ne servira à rien.

Il est strictement optionnel pour les clients de faire quoi que ce soit de spécial avec les titres. Beaucoup de clients vont les reconnaître et utiliser une police plus large ou une autre couleur ou une forme de stylisation mais d'autres vont les traiter comme n'importe quelle autre ligne de texte et les afficher telles quelles. C'est acceptable car les titres ne sont pas utilisés pour controler l'apparence du contenu. En revanche ils ont une grande importance sémantique sur la structure du contenu. Certains clients vont utiliser les titres pour créer automatiquement une table des matières pour l'utilisateur, qu'ils peuvent utiliser pour naviguer sur les longs documents. Les générateurs de flux Atom ou RSS peuvent utiliser les titres pour détecter les titres de billet de gemlogs.

Listes

Gemtext supporte les listes non ordonées. Chaque item d'une liste est écrit comme une ligne longue, qui commence par un unique * suivi d'un espace obligatoire:

* Mercury
* Gemini
* Apollo

C'est la seule syntaxe autorisée. Utiliser un - au lieu d'un * comme en Markdown ne fera rien. Les listes emboitées ne sont pas supportées.

Il est strictement optionnel pour les clients de faire quoi que ce soit avec les listes, et quelques clients les traitent comme n'importe quelle autre ligne de texte. La seule raison pour laquelle est pour que les clients plus avancées puissent remplacer les * par de plus jolis symboles et quand l'item est plus long que la largeur de l'écran, le texte revient à la ligne joliment aligné avec le symbole. C'est seulement un confort typographique.

Citations

Gemtext supporte les citations. Le contenu cité est écrit dans une seule ligne longue, qui commence par un > :

> Gemtext supporte les citations. Le contenu cité est écrit dans une seule ligne longue, qui commence par un > :

Il est strictement optionnel pour les clients de faire quoi que ce soit avec les citations et certains clients les traitent comme n'importe quelle autre ligne de texte. Comme les listes, elles sont définies seulement pour autoriser l'embellissement typographique des clients avancés.

Texte préformatté

Gemtext est conçu pour être très, très facile à parser et afficher. Les clients Gemini traitent les lignes les unes après les autres indépendamment des lignes précédentes ou suivantes, simplement en vérifiant si les premiers caractères de la ligne sont parmis =>, # , * , etc.

Une ligne commencant par ``` (i.e. trois backticks) dit au client de basculer entre le mode de parsing normal et le "mode préformatté". En mode préformatté, le client n'accorde plus d'importance aux premiers caractères de la ligne, le texte est affiché tel quel. De plus, les clients peuvent utiliser une font à largeur variable pour le texte normal mais ils doivent utiliser une font à largeur fixe en mode préformatté. De fait, une paire de ``` agissent comme les balises <pre> et </pre> en HTML.

Le texte préformatté peut être utilisé pour inclure de l'art ASCII, du code source ou contenu similaire dans un document Gemtext sans que le client l'interprète à tord comme un titre, un point d'une liste, etc. Il peut également être utilisé pour crire des document comme celui-ci qui explique la syntaxe Gemtext avec des exemples - vous pouvez alors voir la syntaxe sans que le client interprète la ligne normalement car il est rendu en mode préformatté.

Tout ce qui vient après les ``` qui activent le mode préformatté (i.e. les trois ou plus premiers) peut être traité comme du "texte alternatif" au contenu préformatté. En général, vous ne devriez pas compter sur le fait qu'il soit visible par l'utilisateur mais, par exemple, un moteur de recherche pourrait l'indexer et un lecteur d'écran pourrait le lire à l'utilisateur pour l'aider à décider s'il veut que le contenu préformatté soit lu (par exemple l'art ASCII ne sera pas lu en général, mais peut-être que le code source oui). Il n'y a pas encore de conventions sur comment le texte alternatif devrait être formatté.