Gemtextの書き方

Gemini Protocol specification
仕様書。5.4 Core line typesから
A quick introduction to "gemtext" markup
簡単なマークアップの概要
Gemtext cheatsheet
さらに簡単なチートシート(すぐに書きたい人向け)

はじめに

もはや説明不要なほどですが、ここでは私の個人的な理解(非公式な見解)をまとめてゐます。

対象仕様:Speculative specification v0.16.1, January 30th 2022

以上から、作成する文書の目的、性質を考へた上でHTMLかGemtextか(あるいはそれ以外のフォーマット)を選択します。

基本的にGemtextはほぼプレーンテキストで、Geminiは軽量なハイパーテキストの配信を志向してゐます。

空白文字・改行

行内テキストの空白文字(半角・全角問はず)、改行は忠実に描画されます。100字(行)でも1000字(行)でも。

なぜ文書を空白文字、記号、絵文字、アスキーアートで飾るべきではないか

なぜ整形済みテキスト行以外の行にアスキーアートを書くべきではないか

整形済みテキスト行とは異なり、他の行は代替テキストを設定できません

とくに視覚情報が望めない環境では、読者はどこからどこまでがアスキーアート(無意味な記号の羅列)なのか、見当がつけられません。書くならば整形済みテキスト行にし、代替テキストを設定します。

行種

Gemtextは6つの行種で構成され、クライアントは行頭の3字で行種を判別します。

見出し、リスト、引用は高度な行種であり、簡素なクライアントはこの3種をテキスト行と同等に(つまりそのまま)描画します。

テキスト行

行頭3字がリンク、整形済みテキスト、見出し、リスト、引用のマークでない行です。つまり、テキスト行にはマークがありません。

実態としてはプレーンテキストです。

空行

どの程度の空行が読みやすいか、は人によります。だから、いたづらに改行すべきではありません。空行が長ければ長いほど、読者は読書を長引かされます。

インライン(行内)の強調

マークはないため、著者の表現に依存します。慣習的には、括弧かっこや引用符で囲ふことになるでせう。

インライン(行内)のコード

マークはないため、著者の表現に依存します。

罫線

プレーンテキストでは、ハイフン(-)やダッシュ(—)の羅列で罫線、つまり段落の区切りを表現することは珍しくありません。しかし、Gemtext文書がスクリーンリーダーを対象にしてゐることを考へると、この表現は望ましくありません。スクリーンリーダーが記号の羅列を無視するかどうかは分かりませんし、読書の邪魔になってしまふことはいなめないからです。このやうな特定の環境(視覚)に依存した表現は、特定の読者の読書を困難にしてしまひます。

行頭空け(文章作法)

日本語には行頭を1字空ける慣習があります(所謂いはゆる文章作法)。文書と外観の分離に照らすなら、不要と言へます。

リンク行

行頭が=>で始まる行は、リンク行です。

HTMLとは異なり、Gemtextのリンクはブロックレベル(行)です。a要素に当ります。マークによる関係性の明示(rel属性に当る)はできません。

URLに制限はなく、そのまま記述できます。(gemini://でもhttp://でも)

=>[<半角空白>]<URL>[<半角空白><リンクテキスト>]

半角空白は連続しても構ひません(描画されない)。[]内は省略可能です。つまり、最小の構成は以下になります。

=>gemini://gemini.circumlunar.space/

URLと半角空白の後に続く文字は、リンクテキストとして扱はれます。

=>gemini://gemini.circumlunar.space/ Gemini公式サイト

リンクテキスト

リンクテキストは、読者がリンク先を予測できる表現にします。リンク先がどのやうなサイトか分からなくて、アクセスをためらったことはありませんか? 読者の不安を払拭ふっしょくし、時間を無駄にしないためにも、著者は適切なリンクテキストを心掛けるべきです。

リンクの説明を同じ行に書くことができないため、説明・コメントをリンクテキストに書く著者もゐますが、主観的な表現は控へます。事実に焦点を当てるやうにします。


望ましくない例:

=>gemini://gemini.circumlunar.space/ Gemini公式サイト(最高!

Geminiの公式サイトが最高かどうかは、読んだ人によります。何がどう最高かは、リンク行ではなくテキスト行で書きます。


単にリンク先の補足をしたいなら、具体的に、しかし簡潔に書きます。

=>gemini://gemini.circumlunar.space/ Gemini公式サイト(仕様書とFAQ、リンク集など

リンクの構成

Gemtextのリンクは行のため、文書の構成を少し考へる必要があります。

Project Geminiは、例へば文書内にリンク集(参考文献)を作って、重要なリンクをまとめて載せるやう提案してゐます。


Project Gemini FAQ2.10 Why doesn't text/gemini have support for in-line links?より:

It's true that you need to shift your thinking a bit to get used to the one link per line writing style, but it gets easier over time. There are benefits to the style as well. It encourages including only the most important or relevant links, organising links into related lists, and giving each link a maximally descriptive label without having to worry about whether or not that label fits naturally into the flow of your main text.

クロスプロトコル(プロトコルの横断)

ハイパーリンクのURIには、プロトコルの制限はありません。著者は、Gemini以外のプロトコルへのリンクについて、遠慮をする必要はありません。文書は適切に補完(リンク)されるべきです。


クロスプロトコルのリダイレクト(異なるプロトコルの横断)について、仕様ではとくに定められてゐません。ですが、Project Geminiはクライアントの設計者に対して、ユーザーに注意を促すやう強く推奨してゐます。

Best practices for Gemini implementationsCross-protocol redirectsより:

Cross-protocol redirects (i.e. redirects from Gemini to something else, like Gopher) are possible within Gemini, but are very heavily discouraged. However, misconfigured or malicious servers will always be able to serve such redirects, so well-written clients should be ready to detect them and respond accordingly.

It is strongly recommended that even clients which generally follow redirects automatically alert the user and ask for explicit confirmation when served a redirect to a non-TLS-secured protocol like HTTP or Gopher, assuming the client implements support for these protocols. This avoids unintentional plaintext transfers.

整形済みテキスト行

行頭が```で始まる行は、整形済みテキスト行のトグル(スイッチ)として認識され、その行は描画されません。次の```で始まる行でトグルは無効になり、整形済みテキストは終了します。つまり、```行と```行で挟まれたテキストが、整形済みテキストです。

HTMLで言へば、pre要素です。等幅フォントで描画され、行種を示すマーク(=>など)もそのまま描画されます。

```
<!DOCTYPE html>
<title>最小限のHTML</title>
```

代替テキスト

トグルを有効にする行頭```に続く文字は、代替テキストとしてクライアントが利用可能です。

スクリーンリーダーがテキストの内容を把握したり、シンタックスハイライトのコード種の判別に利用したりできます。

仕様によれば、著者に設定する義務はなく、クライアントも利用する義務はありません。しかし、テキストが文章として読めない場合、著者は代替テキストを設定すべきです。とくに視覚情報が望めない環境では、読者は整形済みテキストがプログラムなどのコードなのか、アスキーアートのやうな芸術性の高い表現なのか、判断が難しくなります。

```CSSのサンプル
pre.art
{display: none !important}
```

アスキーアート

アスキーアートの害については、Gemtext雜感に書きました。

著者は、アスキーアートを避けるべきです。


要約すると:

見出し行

行頭が#で始まる行は、見出し行です。#の後に1字以上の半角空白があっても構ひませんが、簡素なクライアントはそのまま描画するため、1字に留めるべきです。レベル順に#が加はります。

HTMLとは異なり、Gemtextの見出しレベルは3までです。h1h3要素に当ります。

# Gemtextの書き方
## 行種
### テキスト行

見出しの重要性

見出しは、Gemtextで唯一クライアントの抽出が見込める(文書構造が明示できる)行です。読者が文書の流れを追ふ目印でもあります。

特定の部位へのアクセスが容易になるため、読者の利用が想定される情報、注意を引きたい段落には見出しをつけるべきです。

順不同リスト行

行頭が* アスタリスクと半角空白)で始まる行は、順不同リスト行です。* の後に1字以上の半角空白があっても構ひませんが、簡素なクライアントはそのまま描画するため、不要と言へます。

HTMLとは異なり、リストを入れ子にしたり、リンクや引用を含めたりはできません。つまり、行頭のマーク以外はテキスト行と同じです。ulli要素に当ります。

また、リスト項目の順番に意味を与へる(序列)マークはありません。

* りんご
* バナナ
* みかん

序列リスト

マークはないため、著者の表現に依存します。スクリーンリーダーを考慮すると、文章として読める表現が適してゐます。

1. フライパンに油を敷く
2. 卵を落とす
3. 蓋をする
一、野菜を切る
二、鍋で肉を炒める
三、切った野菜を鍋に入れる

引用行

行頭が>で始まる行は、引用行です。>の後に1字以上の半角空白があっても構ひませんが、簡素なクライアントはそのまま描画するため、1字に留めるべきです。

HTMLとは異なり、テキスト以外の行を含めることはできません(マークはそのまま描画される)。また、マークによる引用元の明示(cite属性に当る)はできません。blockquote要素に当ります。

引用行の中の引用については、仕様上とくに定義されてゐません。>>のやうに、>を加へても良いでせう。

夏目漱石著『吾輩ハ猫デアル』より
> 吾輩は猫である。名前はまだ無い。

インライン(行内)の引用

マークはないため、著者の表現に依存します。慣習的には、引用符や鉤括弧かぎかっこで囲ふことになるでせう。

文脈で引用であること、引用の範囲引用元を明確にします。

その他

HTMLと同じやうに、トップページに戻るリンクや、ライセンスの記述などは手動で追加する必要があります。

検証ツール

マークの検証ツールはありません。行頭3字を検索するだけなので、標準出力やテキストエディタから簡易的に検証ができます。

grep --color=always -nE '^(-|~|=[^>]|@|`[^`]|``$|`{4,}|3|\*[^ ])'

マークアップ例

実際に、私のWebコンテンツをGemtext化してみます。HTMLのマークアップに慣れてゐると、簡単にページが作れることに驚きます。

小説の目次

HTML:小說(2020年)

Gemtext:

=> / 君のちんぽに戀してる
# 小說(2020年作)
* 成人對象 — 二十歲以上の讀者を對象とする
* 性描寫 — 性に關はる話題・性行爲の描寫等を含む

=> 16.gmi 野崎の娘
會社の上司は、嘗ての母の戀人、私の父かも知れなかつた。
* 性行爲の描寫
* 初版:2020年5月10日

=> 15.gmi 思ひ出
今彼と元彼。誰かとする事に、誰かを思ひ出す。
* 性行爲の描寫
* 初版:2020年4月7日

=> 14.gmi 微妙な氣持の事
さういふ意味ではない「好き」、私が抱へるのは、好奇心。
* 性行爲の描寫
* 初版:2020年3月29日

=> 13.gmi 白い窻
窓枠に嵌まつた、奇異な女にする嫉妬。
* 性に關はる話題
* 初版:2020年3月8日

## 案內
=> /2021/ 新:2021年作
=> /2019/ 舊:2019年作

## 發行情報
公開:2020年3月8日
=> http://sinumade.net/about#author 著:絲
=> http://creativecommons.org/publicdomain/zero/1.0/deed.ja 適用:CC0[著作權抛棄]

小説本文

HTML:北風に太陽はあるか

Gemtext:

=> /2021/ 小說(2021年作)
# 北風に太陽はあるか
公開:2021年11月21日 第1版
=> http://sinumade.net/about#author 著:絲
=> http://creativecommons.org/publicdomain/zero/1.0/deed.ja 適用:CC0[著作權抛棄]
=> 17-atogaki.gmi 附錄:『北風に太陽はあるか』後書

## 註

* 成人對象 — 二十歲以上の讀者を對象とする
* 小說(フィクション) — 實在の事柄とは關はり無し、描寫中の行爲を獎めるもので無し

## 本文

 バーの扉を押す前に、サブロは濕つぽい外氣を取込んだ。
「あのよおー、せめて【はだかになる】つてのはどうかな?」
 クインはぱつと自分の中折れ帽に手を乘せると、それをサブロの頭部に乘つけた。
「ふざけるなよッ。畜生ッ。おれは生れてこの方そんな眞似はした事無かつたんだ。幾らなんでも、な!」
 怒りの表明に、クインはそつと帽子を自分の頭に戾した。
「行くぞッ」
 サブロは腹積りを決めて、……

参考リンク

内容はHTML向けですが、Gemtextにも応用できるはずです。

ハンディがあっても利用できるページづくり
アクセシビリティについて。異なる環境にゐる、多くの人々がコンテンツを利用できるやうに。
オンライン・ハイパーテキストのためのスタイルガイド
Gemtextにも署名、進捗状況などは必要でせう。URIの構成と保持も重要です。
文書指向ウェブデザインにおけるハイパーテキスト設計指針
リンクテキストを考える
リンクタイトルは行き先が予想できるものに
リンクテキストの書き方、その重要性を考へるのに参考になります。Gemtextのリンクはなので、それほど迷ふこともないと思ひますが。
よいウェブページを書こうとする人のためのヒント
もちろん、公開活動には責任が伴ひます。Gemtext文書の読者は少ないかもしれませんが、公共のリソースであることに変りはありません。
WWWで情報発信しよう
発信のアイディアは何でも良いのです。
ウェブ制作, キスとキズつて似てるよね
リンク集。公開文書を制作する上で、参考になったリソースです。

更新履歴

  1. 2022年5月14日:
  2. 2022年5月8日:
  3. 2022年5月7日: