💾 Archived View for it.gemini-site.omarpolo.com › docs › it › gemtext.gmi captured on 2021-12-05 at 23:47:19. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2021-11-30)
-=-=-=-=-=-=-
Il metodo più comune per elaborare contenuti testuali via Gemini, a differenza di Gopher, non è plaintext bensì un linguaggio markup chiamato "Gemtext" (presentato attraverso la tipologia MIME non ufficiale text/gemini). Questo documento è una breve introduzione a questo linguaggio. In alcuni aspetti è simile al Markdown, e sarà facile da apprendere se si conosce MD, ma per certi aspetti presenta delle sostanziali differenze.
Una volta letto questo documento, sarà possibile rinfrescarsi la memoria facendo riferimento al:
Il testo in documenti Gemtext va formattato in "stringhe lunghe", ovvero paragrafi ininterrotti da caratteri newline (ritorno a capo). Al contrario, si lascia che sia Gemini a riformattare queste stringhe in base alla grandezza dello schermo ed altre preferenze dell'utente. In questo modo i contenuti Gemtext si presentano in modo gradevole su monitor, schermi di laptop, tablet e smartphone.
È importante fare nota che i client Gemini spezzano linee di testo che sono più larghe dell'interfaccia utente, ma a differenza di Markdown, HTML o LaTeX, lasciano stringhe più corte intatte senza unirle. Ciò significa che liste, poemi o altre sequenze di stringhe brevi saranno visualizzate correttamente senza che l'autore debba lavorare sui contenuti ulteriormente per specificarne la corretta formattazione.
Nella maggior parte dei casi, ciò significa che basterà usare una sola stringa per paragrafo.
È da notare che ogni ritorno accapo è interpretato dal client così com'è, per cui due o tre linee vuote saranno rappresentate tal quali.
Allo stesso modo di Gopher (e a differenza di Markdown e HTML), Gemtext permette di inserire link a altri documenti soltanto all'inizio di una nuova stringa. Non è possibile inserire un link nel mezzo di una frase. Bisogna abituarsi a questo aspetto, ma il vantaggio è che i link sono estremamente facili da ritrovare, e i client possono elaborarne lo stile (specificando se visualizzarne il protocollo o il dominio così che l'utente possa decidere se seguirli o meno), senza interferire con la leggibilità del documento in sé.
Le stringhe contenenti link sono così:
=> https://example.com Un sito interessante => gopher://example.com Un gopherhole ancora più interessante => gemini://example.com Una meravigliosa capsula Gemini! => sftp://example.com
Quindi:
Nell'esempio di sopra, tutte gli URL e descrizioni sono bene allineati (l'autore è stato pignolo!) Ma a Gemini non interessa, così anche l'esempio seguente va bene:
=>https://example.com Un sito interessante =>gopher://example.com Un gopherhole ancora più interssante => gemini://example.com Una meravigliosa capsula Gemini! => sftp://example.com
Gemtext supporta tre livelli di intestazione. Le intestazioni sono limitate ad una singola stringa ed iniziano per uno, due o tre simboli #, seguiti da uno spazio:
# Intestazione ## Secondo livello di intestazione ### Terzo livello di intestazione
Soltanto questa sintassi è supportata. L'uso di caratteri come - o = non avrà risultati.
I client non necessariamente formattano le testate in modo particolare. Molti client riconoscono la sintassi ed usano un carattere più grande, di colore diverso o altre formattazioni, mentre altri client li visualizzeranno allo stesso modo di normali stringhe di testo. Ciò è normale, perché le testate non hanno lo scopo di controllare l'aspetto estetico del contenuto. Invece, forniscono importanti indicazioni semantiche sulla struttura dei contenuti. Alcuni client usano le testate per generare un indice dei contenuti per l'utente, cosa molto utile per documenti più lunghi. Un software può generare feed Atom o RSS usando le intestazioni per estrarre i titoli dei post in un gemlog.
Gemtext supporta liste non ordinate. Ogni oggetto in una lista va scritto su una stringa a sé stante, che inizia con il carattere * seguito da uno spazio:
Questa è l'unica sintassi supportata da Gemini. Usare sintassi Markdown come - invece di * non avrà risultati. Sotto-liste, subordinate a oggetti di una lista non sono supportate.
Come per le testate, i client non necessariamente formattano gli oggetti di una lista, e alcuni client li visualizzeranno esattamente come normali oggetti testuali. Lo scopo del definire una lista è permettere a client più complessi di rimpiazzare il simbolo * con un bullet più gradevole, e creare margini allineati quando gli oggetti di una lista che si estendono oltre la dimensione dell'interfaccia vengono riformattati su più linee.
Gemtext supporta citazioni. Il testo di una citazione è scritto su un'unica stringa, che inizia con un singolo carattere >:
> Gemtext supporta citazioni. Il testo di una citazione è scritto su un'unica stringa, che inizia con un singolo carattere >
Come per gli altri oggetti di cui sopra, i client più ambiziosi saranno in grado di formattare il testo nello stile desiderato, ma ciò non è neccessario o previsto dal protocollo.
Gemtext è stato progettato con la massima attenzione perché sia facile da elaborare e visualizzare. I client Gemini elaborano una singola stringa alla volta, ed elaborano ognuna di esse indipendentemente in base ai primi caratteri, quali =>, # , * , eccetera.
Una linea che inizia con ``` (tre 'backtick') dice al client di passare dalla sua normale modalità di elaborazione ad una modalità "preformattata". In questa modalità, il client non verifica se una stringa rappresenti un link, un'intestazione, o altro. Semplicemente, visualizzerà i contenuti allo stesso modo in cui sono scritti. Inoltre, mentre i client Gemini hanno la possibilità di usare un carattere a dimensione variabile per i normali contenuti, nel caso di testo peformattato dovranno usare un carattere monospazio. Quindi un paio di stringhe ``` si comportano come la tag <pre> ... </pre> in HTML.
Il testo preformattato può essere utilizzato per arte ASCII, linee di codice, e altri contenuti in un documento Gemtext che il client non potrà erroneamente interpretare come intestazioni, liste, etc. Può anche essere usato per scrivere documenti come questo, che mostra esempi di sintassi in Gemtext - questi esempi non vengono interpretati dal client ma visualizzati così come scritti perché elaborati in modalità preformattata.
Tutto ciò che segue i caratteri ``` in una stringa che *attiva* la modalità preformattata (ovvero la prima, terza, quinta, etc. di queste stringhe in un documento) potrà essere elaborata come "testo alternativo" per i contenuti preformattati. In generale, sarà meglio aspettarsi che l'utente non veda questi contenuti ma, per esempio, un programma di lettura o motori di ricerca potranno decidere se leggere il testo (arte ASCII, per esempio, dovrebbe essere ignorata, mentre potrebbe essere desiderabile leggere delle linee di codice). Non è al momento definita alcuna convenzione per la sintessi di questo testo alternativo.