Gemtext

Vad det är

Gemtext är dokumentformatet i protokollet Gemini: vanlig text i
UTF-8 där de första tecknen på varje rad avgör vad raden är, så att
en klient kan rendera en hel sida i ett enda svep uppifrån och ned.
Specifikationen kallar det Geminis hypertextformat, servrar märker
det med medietypen `text/gemini` och filerna slutar enligt
konvention på `.gmi`.

Det finns sex sorters rader. En rad som börjar med `=>` är en länk,
med en adress, absolut eller relativ, och en valfri etikett efter
den. En rad med tre backticks slår på eller av förformaterat läge,
och allt som står mellan två sådana rader visas exakt som det
skrevs, i ett typsnitt med fast bredd. En, två eller tre brädgårdar
gör en rubrik, en asterisk följd av ett mellanslag gör en listpunkt
och en rad som börjar med `>` blir ett citat. Alla andra rader är
vanlig text, och klienten radbryter dem efter bredden på den skärm
de hamnar 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
```

Specifikationen delar in de sex i tre kärntyper som varje klient
måste hantera (text, länkar och växeln för förformaterat läge) och
tre som en minimal klient får visa som vanlig text. Det är hela
formatet. Det saknar fetstil, kursiv, tabeller, bilder i löptexten
och nästling, och det går inte att göra ett ord mitt i en mening
klickbart. En parser håller reda på en enda bit tillstånd: om den
befinner sig i ett förformaterat block eller inte.

Gemtext jämförs oftast med Markdown, som det liknar vid första
anblick. Skillnaden ligger i vad de är till för. En Markdown-fil är
en källfil, skriven för att omvandlas till något annat. En
gemtext-fil är redan det färdiga dokumentet, och läsarens klient är
den enda som renderar det. Sin enda strukturella vana, länken på en
egen rad, har formatet lånat från de äldre menyerna i Gopher.

Varför det spelar roll

Att välja gemtext är att välja vem som styr sidan. Författaren
bestämmer strukturen: vilka rader som är rubriker, vilka som är
länkar och var koden står. Läsarens klient bestämmer resten, från
typsnitt och radlängd till färg, avstånd och om rubrikerna blir en
innehållsförteckning. Specifikationen säger rakt ut att formatet
inte är tänkt att ge författare exakt kontroll över presentationen.
För en del utgivare är det en lättnad, och för andra är frågan
därmed avgjord. Det lönar sig att veta vilket innan man konverterar
en enda sida.

Lättnaden ligger i det som försvinner. En sida i gemtext bär ingen
stilmall, inget skript, inget webbtypsnitt, ingen fråga om samtycke
till kakor och ingen spårningspixel, och det enda som någonsin
behöver uppdateras är orden. Sidorna blir små och går snabbt att
skriva för hand. Länkar hämtar aldrig något på egen hand, eftersom
specifikationen förbjuder en klient att öppna en nätverksanslutning
bara för att visa en länk. En sida kan alltså inte dra in en bild
eller ett typsnitt från tredje part bakom läsarens rygg.

Kostnaden är lika konkret. Gemtext når bara de som kör en
Gemini-klient, och det är en liten publik jämfört med webbens.
Formatet har inga formulär: det enda sätt en kapsel kan be om
inmatning är en statuskod i protokollet, aldrig något i dokumentet.
Och prosan måste fungera utan länkar inne i meningarna. En mening
skriven för HTML, ”se prissidan för detaljer”, behåller sina ord men
tappar sin pekare. Att skriva bra gemtext är därför att skriva
meningar som fortfarande går att förstå när länken står på raden
under.

Därför gäller den realistiska frågan för de flesta organisationer
gemtext utöver en webbplats, inte gemtext i stället för en,
framställt från samma källa av samma bygge. Ställd på det sättet
kostar gemtext lite att lägga till, och det fungerar samtidigt som
ett test av texten. Läses en sida fortfarande tydligt som en kolumn
av textrader och länkrader, så satt strukturen i orden hela tiden.

Så ser det ut i praktiken

Den här webbplatsen publiceras som gemtext vid sidan av sin HTML.
Sidan Engineer i en terminal anger kapselns adress,
`gemini://engineer.company/`, säger att varje sida på webbplatsen
också finns i formatet och nämner klienter som läser det: Amfora,
Lagrange och Bombadillo i en terminal, Castor och Kristall i ett
fönster. Den ger också skälet. En driftsättning skriver en mapp som
varje ytterdörr läser, så kopian i gemtext kan inte glida isär från
HTML-koden, och en sida som läses bra som gemtext är en sida vars
struktur är verklig snarare än pålagd.

Hur det byggdes står i redogörelsen för hur webbplatsen speglades
till Gemini och Gopher. Gemtext är ett utdataformat i samma bygge,
inte en separat verktygskedja. Webbplatsgeneratorn fick egna
medietyper och utdataformat, och varje sida, sektion och
taxonomiterm fick ett Gemini-dokument vid sidan av sin HTML och sin
Markdown-tvilling: 777 stycken i det dokumenterade
implementeringsskedet, serverade av en liten daemon på samma
värddator. De nya formaten är markerade som icke-alternativa
representationer. En separat jämförelse av byggen mätte noll ändrade
HTML-byte när formaten lades till; den mätte inte senare
redaktionella eller visuella ändringar.

Mallarna bakom den kopian visar vad en konvertering till gemtext
innebär. Varje länk inne i en mening lyfts ut: orden stannar där
meningen behöver dem, och adressen flyttar ned under texten som en
egen `=>`-rad. Markeringar för fetstil tas bort, punkter med
bindestreck blir asterisker, och ett kodblock mellan tre backticks
passerar orört, eftersom Markdown och gemtext ramar in sådana block
med samma tre tecken.

Var det går fel

Halva rader som aldrig fogas ihop

Prosan kommer fram i klienten som en ojämn kolumn av korta rader,
brutna mitt i en sats. Källan var hårt radbruten vid 80 kolumner,
som Markdown-filer ofta är, och specifikationen förbjuder en klient
att foga ihop korta textrader som följer på varandra till längre.
Skriv varje stycke som en enda lång rad, eller låt konverteraren
foga ihop mjuka radbrytningar innan den skriver filen.

Länkar som lämnar kapseln

Den första länken en läsare följer öppnar en webbläsare.
Konverteraren skrev varje länk som en absolut `https://`-adress, och
en Gemini-klient lämnar över sådana adresser till ett annat program.
Skriv navigeringen som sökvägar från roten, t.ex. `/about/`, som
tolkas relativt till kapselns adress, och behåll en avsiktlig länk
per sida till sidans webbversion.

Kod som faller ihop till en enda rad

Ett kodexempel visas som en enda lång rad som sitter fast i sin
inledande rad med backticks. Konverteraren behandlade blocket som
prosa och fogade ihop dess rader med allt annat. Dela upp dokumentet
vid kodblockens gränser före alla andra steg, släpp igenom varje
förformaterat block precis som det skrevs och låt växelraden bära
högst en kort alternativtext, t.ex. språkets namn.

Markdown som blir till bokstavliga tecken

Punkter med bindestreck, dubbla asterisker, understrukna rubriker,
nästlade listor och länkar inom hakparenteser dyker upp i klienten
exakt som de skrevs. Gemtext känner bara igen en asterisk och ett
mellanslag som listpunkt och brädgårdar som rubrik, och formatet har
ingen markering alls inne i löptexten. Konvertera de
konstruktionerna på vägen ut, eller skriv kapseln direkt i gemtext.

Meningar som pekar på ingenting

Ett stycke säger ”klicka här” eller ”som länkas ovan”, och läsaren
har ingen aning om vart det leder. Länken lyftes ut ur meningen, och
orden som blev kvar sa aldrig vart den gick. Skriv länketiketter som
namnger sitt mål, så att både meningen och `=>`-raden går att förstå
var för sig.

Läs mer

  * A quick introduction to gemtext markup — projektets egen korta
genomgång av varje radtyp, med anteckningar för den som kan
Markdown.

  * Gemini hypertext format specification — den normativa texten:
radtyper, parserns tillstånd, regler för radbrytning, parametern
`lang` och en formell grammatik.

  * Gemini network protocol specification — hur en kapsel serverar
gemtext: förfrågningar, statuskoder och de regler för TLS som en
klient följer.

  * Project Gemini FAQ — resonemanget bakom designen, bl.a. varför
länkar står på egna rader.

hDen här sidan på webben	URL:https://engineer.company/sv/glossary/gemtext/	engineer.company	70
