gemtext

Hva det er

Gemtext er dokumentformatet til protokollen Gemini: ren UTF-8-tekst
der de første tegnene på hver linje avgjør hva linjen er, slik at en
klient kan rendre en hel side i én gjennomgang fra topp til bunn.
Spesifikasjonen kaller det Gemini-hypertekstformatet, på engelsk
«Gemini hypertext format». Servere merker det med medietypen
`text/gemini`, og filene slutter etter fast skikk på `.gmi`.

Formatet har seks slags linjer. En linje som begynner med `=>`, er
en lenke, laget av en adresse, absolutt eller relativ, og en valgfri
etikett etter den. En linje med tre backticks slår forhåndsformatert
modus av eller på, og alt som står mellom to slike linjer, vises
nøyaktig som det er skrevet, i en font med fast tegnbredde. Ett, to
eller tre `#`-tegn gir en overskrift, en stjerne fulgt av et
mellomrom gir et listepunkt, og et `>`-tegn gir et sitat. Alle andre
linjer er vanlig tekst, og klienten bryter dem til bredden på den
skjermen de havner på.

```text
i# Field notes		engineer.company	70

A text line is a paragraph, however long it runs. The client wraps it.

i=> /archive/ Older notes		engineer.company	70
i=> gemini://example.org/ A capsule elsewhere		engineer.company	70

i* A list item		engineer.company	70
> A quoted line
```

Spesifikasjonen deler de seks i tre kjernetyper som alle klienter må
håndtere (tekst, lenker og bryteren for forhåndsformatering), og tre
som en minimal klient har lov til å vise som ren tekst. Mer er det
ikke. Fet skrift, kursiv, tabeller, innebygde bilder, nesting og
klikkbare ord midt i en setning står alle utenfor formatet. En
parser holder styr på én eneste bit med tilstand: om den befinner
seg inne i en forhåndsformatert blokk.

Gemtext sammenlignes oftest med Markdown, som det ligner ved første
øyekast. Forskjellen ligger i hva de to er til for. En Markdown-fil
er kildetekst, skrevet for å bli konvertert til noe annet. En
gemtext-fil er allerede det ferdige dokumentet, og leserens klient
er den eneste som rendrer den. Den ene strukturelle vanen sin,
lenken på en egen linje, har formatet lånt fra de eldre menyene i
Gopher.

Hvorfor det er viktig

Å velge gemtext er å velge hvem som styrer siden. Forfatteren
bestemmer strukturen: hvilke linjer som er overskrifter, hvilke som
er lenker, og hvor koden står. Leserens klient bestemmer alt annet,
fra skrifttype og linjelengde til farge, luft og om overskriftene
blir til en innholdsfortegnelse. Spesifikasjonen sier rett ut at
formatet ikke er ment å gi forfattere presis kontroll over
presentasjonen. For noen utgivere er det en lettelse, for andre
setter det punktum for hele samtalen, og det lønner seg å vite
hvilken gruppe dere hører til før dere konverterer en eneste side.

Lettelsen ligger i det som forsvinner. En gemtext-side består av ord
og lenker og ingenting annet: stilark, skript, webfonter, varsler om
informasjonskapsler og sporingspiksler har ingen plass i den, og det
eneste som noen gang må oppdateres, er ordene. Sidene er små og
raske å skrive for hånd. Lenker henter aldri noe av seg selv, fordi
spesifikasjonen forbyr en klient å åpne en nettverksforbindelse bare
for å vise en lenke. En side kan dermed aldri trekke inn et bilde
eller en font fra en tredjepart bak ryggen på leseren.

Kostnaden er like konkret. Gemtext når bare folk som bruker en
Gemini-klient, og det er et lite publikum ved siden av webens.
Inndata ber en kapsel om gjennom en statuskode i protokollen, aldri
gjennom noe i selve dokumentet, for skjemafelt har formatet ikke. Og
prosaen må klare seg uten innebygde lenker. En setning skrevet for
HTML, «se prissiden for detaljer», beholder ordene og mister
pekeren, så å skrive god gemtext betyr å skrive setninger som
fortsatt gir mening når lenken står på linjen under.

Derfor er det realistiske spørsmålet for de fleste virksomheter
gemtext i tillegg til et nettsted, ikke gemtext i stedet for et,
produsert fra den samme kilden av det samme bygget. Stilt slik
koster gemtext lite å legge til, og formatet fungerer samtidig som
en prøve på skrivingen. Hvis en side fortsatt leses klart som en
kolonne av tekstlinjer og lenkelinjer, lå strukturen i ordene hele
tiden.

Slik ser det ut i praksis

Dette nettstedet publiseres som gemtext ved siden av HTML-en. Siden
Engineer i en terminal oppgir kapselens adresse,
`gemini://engineer.company/`, sier at hver side på nettstedet også
finnes i formatet, og nevner klienter som leser det: Amfora,
Lagrange og Bombadillo i en terminal, Castor og Kristall i et vindu.
Den gir også begrunnelsen. Én produksjonssetting skriver én mappe
som alle inngangsdørene leser, så gemtext-kopien holder seg i takt
med HTML-en, og en side som leses godt som gemtext, er en side der
strukturen er ekte og ikke malt på.

Hvordan det ble bygd, er beskrevet i gjennomgangen av speilingen av
nettstedet til Gemini og Gopher. Gemtext er et utdataformat fra det
samme bygget, ikke en separat verktøykjede. Nettstedsgeneratoren
fikk egendefinerte medietyper og utdataformater, og hver side,
seksjon og taksonomiterm fikk et Gemini-dokument ved siden av
HTML-en og Markdown-tvillingen sin: 777 dokumenter på det
dokumenterte implementeringstidspunktet, servert av en liten daemon
på samme vert. De nye formatene er merket som ikke-alternative
representasjoner. En separat sammenligning av bygg målte null
endrede HTML-byte da disse formatene ble lagt til; den målte ikke
senere redaksjonelle eller visuelle endringer.

Malene bak den kopien viser hva en konvertering til gemtext
innebærer. Hver innebygd lenke løftes ut av setningen sin: ordene
blir stående der setningen trenger dem, og adressen flyttes ned
under teksten som en egen `=>`-linje. Markeringene for fet skrift
fjernes, punkter med bindestrek blir til stjerner, og en kodeblokk
mellom tre backticks går gjennom urørt, fordi kodegjerdet i Markdown
og bryteren for forhåndsformatering i gemtext er de samme tre
tegnene.

Hvor det går galt

Halve linjer som blir stående hver for seg

Prosaen kommer fram i klienten som en ujevn kolonne av korte linjer,
brutt midt i setningsleddene. Kilden var hardt brutt ved 80
kolonner, slik Markdown-filer ofte er, og spesifikasjonen forbyr en
klient å slå sammen påfølgende korte tekstlinjer til lengre linjer.
Skriv hvert avsnitt som én lang linje, eller la
konverteringsverktøyet slå sammen myke linjeskift før det skriver
filen.

Lenker som fører ut av kapselen

Den første lenken en leser følger, åpner en nettleser.
Konverteringsverktøyet skrev hver lenke som en absolutt
`https://`-adresse, og en Gemini-klient sender slike adresser videre
til et annet program. Skriv navigasjonen som rotrelative stier som
`/about/`, som tolkes relativt til kapselens adresse, og behold én
bevisst lenke per side til webversjonen.

Kode som klapper sammen til én linje

Et kodeeksempel vises som én lang linje klistret til åpningsgjerdet.
Konverteringsverktøyet behandlet blokken som prosa og slo sammen
linjene med alt det andre. Del dokumentet opp ved gjerdene før noe
annet steg, send hver forhåndsformatert blokk gjennom slik den er
skrevet, og la bryterlinjen bære høyst en kort alternativtekst, for
eksempel navnet på språket.

Markdown som blir til bokstavelige tegn

Punkter med bindestrek, doble stjerner, understrekede overskrifter,
nestede lister og lenker i hakeparenteser dukker opp i klienten
nøyaktig slik de ble skrevet. Gemtext kjenner bare igjen en stjerne
og et mellomrom som listepunkt og `#`-tegn som overskrift, og
formatet har ingen oppmerking inne i linjene. Konverter disse
konstruksjonene på vei ut, eller skriv kapselen direkte i gemtext.

Setninger som peker ut i løse luften

Et avsnitt sier «klikk her» eller «som lenket ovenfor», og leseren
blir stående uten å vite hvor det skal gå videre. Lenken ble løftet
ut av setningen, og ordene som ble igjen, sa aldri hvor de førte.
Skriv lenketekster som navngir målet sitt, slik at både setningen og
`=>`-linjen gir mening hver for seg.

Les mer

  * A quick introduction to gemtext markup — prosjektets egen korte
gjennomgang av alle linjetypene, med merknader for den som kan
Markdown.

  * Gemini hypertext format specification — den normative teksten:
linjetyper, parsertilstand, regler for linjebryting, parameteren
`lang` og en formell grammatikk.

  * Gemini network protocol specification — hvordan en kapsel
serverer gemtext: forespørsler, statuskoder og TLS-reglene en klient
følger.

  * Project Gemini FAQ — begrunnelsen bak designet, blant annet
hvorfor lenker står på egne linjer.

hDenne siden på nettet	URL:https://engineer.company/nb/glossary/gemtext/	engineer.company	70
