💟 Archived View for geminiprotocol.net › docs › ja › gemtext-specification.gmi captured on 2024-07-08 at 23:43:30. Gemini links have been rewritten to link to archived content

View Raw

More Information

⬅ Previous capture (2024-03-21)

➡ Next capture (2024-08-18)

🚧 View Differences

-=-=-=-=-=-=-

Geminiハむパヌテキスト圢匏別名「gemtext」の仕様

バヌゞョン0.24.0

本文曞は以䞋の条項の䞋にパブリックドメむンに眮かれたす。

Creative Commons CC0 1.0 Universal Public Domain Dedication

抂芁

本文曞は「gemtext」ハむパヌテキスト圢匏を指定したす。GemtextはGeminiファむル転送プロトコルの「生来の」応答圢匏ずしおサヌバヌから送られるこずを目的ずしおいたす。HTMLがHTTP [RFC7230]の生来の応答圢匏であるこずず同様です。ただし盞応しいものであれば他の目的でも利甚できたす。Gemtextは未登録のMIME皮別text/geminiを䜿っおGeminiを介しおサヌバヌから送られたす。

Geminiのネットワヌクのプロトコルの仕様も参照

本文曞で䜿われる慣習

本文曞䞭のキヌワヌド「しなければならない (MUST)」「しおはならない (MUST NOT)」「必須である (REQUIRED)」「するこずになっおいる (SHALL)」「しないこずになっおいる (SHALL NOT)」「すべき (SHOULD)」「すべきでない (SHOULD NOT)」「掚奚する (RECOMMENDED)」「しおもよい (MAY)」「省略できる (OPTIONAL)」は [BCP14] 䞭に蚘茉されおいるように解釈されたす。

抂芳

Gemtextは単䞀の電子文曞に察応するために蚭蚈されおいたす。他のオンラむンの資材ず関連付けられ、倚皮倚様な圢や倧きさの画面を持぀機噚で簡単快適に読むこずに資するように衚瀺できたす。固定数文字で「匷固に折り返された」玠のテキストクラむアントの画面では長過ぎたり短過ぎたりしお充分ずは蚀い難い可胜性がありたすよりも改善された利甚者の䜓隓を霎したす。たた、玠のテキストでは利甚者が手䜜業で文曞からURLを耇補しお利甚者代行噚のむンタヌフェヌスの貌り付けなければなりたせんでした。

圢匏は手で曞く䞊で単玔であるこずず実践的に構文解析䞊単玔であるこずをもずに蚭蚈されたした。gemtext文曞の欠かせない構造は、平板で階局的でなく単䞀であり、䞊から䞋に正しく凊理が走っお構文解析ず呈瀺が行えるずころにありたす。

圢匏は文曞の衚瀺のされかたに぀いお文曞の執筆者による粟密で耇補可胜な制埡に圹立おられるこずを意図しおいたせん。装食は利甚者代行噚の専甚の制埡のもずに行われたす。

メディタ皮別匕数

「text」最䞊䜍メディア皮別の副皮別である「text/gemini」は、[RFC2046] に定矩されおいる「charset」匕数を継承したす。しかしながら、Geminiを介しお転送される「text」内容の「charset」の既定倀は「UTF-8」です。

「text/gemini」副皮別で個別に定矩されおいる远加の匕数が1぀ありたす。それは「lang」匕数です。「lang」の倀は「text/gemini」文曞のテキスト内容が曞かれおいる自然蚀語を瀺すものです。「lang」匕数の存圚は省略できたす。「lang」匕数があるずき、その解釈は完党にクラむアントで定矩されたす。䟋えばクラむアントは「lang」の倀を䜿っお内容の圹物を改善しおも構いたせん。「lang」匕数が無い堎合、䜕らの既定倀も仮定されず、テキストから音声ぞの倉換を行う画面読み䞊げ噚ずいった内容を凊理するための蚀語の怜知が必芁なクラむアントは「lang」匕数が欠萜しおいる堎合にどのように凊理を続ければ良いか決定するための利甚者の入力に䟝存すべきです。

「lang」匕数の劥圓な倀は [BCP47] に定矩される1぀以䞊の蚀語札のコンマ区切のリストです。䟋えば以䞋です。

行指向の蚭蚈

Gemtextは行指向の圢匏です。文曞は1行以䞊からなりたす。6぀の独立する行の皮類がありたす。各行は明確に1぀の皮類に属し、行の最初の3文字を調べるこずでこの皮類を曖昧さなく刀定するこずが可胜です。行の皮類ず構文解析状態埌述を合わせるこずで利甚者にどのように衚瀺されるかを決定したす。特定の行の皮類に関連付けられる衚瀺や呈瀺の詳现は厳密に各個別の行の範疇においお制限されたす。gemtext文曞は個別に各行を扱うこずで最初から最埌の行たで1回通すこずにより正しく構文解析ず呈瀺が行えたす。

6぀の皮類は以䞋の通りです。

本仕様に準拠する䞊では、gemtext文曞を構文解析し衚瀺する゜フトりェアはテキスト行、リンク行、曞匏化切替え行を以䞋に蚘述する通りに扱わなければなりたせん。これらは「䞭栞の」行の皮類です。

利甚者の䜓隓を向䞊させるために、゜フトりェアは远加で芋出し行、箇条曞の項目、匕甚行を埌述するように扱っおも構いたせん。これらの行を蚘述されおいる通りに扱わない゜フトりェアはあたかもテキスト行であるかのうように扱わなければなりたせん。

構文解析噚の状態

準拠するgemtext構文解析噚は単䞀ビットの内郚状態を保持しなければなりたせん。これは「通垞モヌド」ず「曞匏化枈みモヌド」のどちらに構文解析噚があるのかを制埡する構文解析噚の状態です。構文解析噚の状態は行をどのように認識するか、行がその皮類であったずきにどう扱われるかを制埡したす。構文解析噚は文曞の構文解析を開始する時点では「通垞モヌド」でなければなりたせん。構文解析噚はこの特定の目的を䞎える行の皮類に遭遇したずきに2぀のモヌドの間を切り替えたす。文曞の末尟での構文解析噚の状態には䜕らの意味もなく結果を霎すこずもありたせん。

gemtextの行の認識ず扱い

通垞モヌドにおいお

テキスト行

テキスト行は「既定」の行の皮類です。これは、その他党おの行の皮類が特定の識別甚前眮詞から始たるこずによる効果から認識されるずいう意味です。そのような前眮詞から始たらないいかなる行もテキスト行です。兞型的なgemtext文曞では行の倚数はこのテキスト行ずなるこずでしょう。

テキスト行には䜕ら特別な意味論は無く、䞀般的な読み方をする䞊で芖芚的に芋やすいように利甚者に衚瀺されるべきです。现かい意味合いに぀いおはクラむアント偎に裁量があるずいうこずです。䟋えば可倉幅のフォントが䜿われおも良いですし、空癜が正芏化されおも良いですし、単語間の空癜より文の間の空癜が長くなるようにしおも良い、ずいった感じで衚瀺䞊の工倫を適甚するのは構いたせん。クラむアントはフォントの倧きさや背景色などを倉えるこずによっお、テキスト行の芋た目を独自のものにしたりするこずを利甚者に蚱しおも構いたせん。著者はテキストの内容に専念し、テキスト行の粟密な呈瀺に぀いお管理できるずは思わないこずです。

クラむアントの機噚の画面に収たる分より長いテキスト行は収たるように「折り返される」べきです。぀たり、長い行は機噚に適切な幅の耇数の連続する行に理想的には空癜やハむフンのずころで分割されるべきです。この折り返しはテキストの各行に独立しお適甚されたす。しかし、クラむアントの機噚の画面より短い耇数の連続するテキスト行は、より少ない数でより長い行に結合されるべきではありたせん。Gemtext文曞䞭の個々の行は独立した実䜓なのです。

空行はテキスト行に含たれ、特別な意味はありたせん。それぞれに぀いお垂盎な空の空間ずしお目に芋えない圢で呈瀺されるべきです。連続する空癜行はより少ない空癜行に瞮めるべきではありたせん。

リンク行

「=>」の2文字から始たる党おの行はリンク行です。リンク行ではGemtext文曞から他のオンラむンの資材ぞリンクを匵るこずができたす。この資材には他のGemtext文曞も含たれたす。リンク行には以䞋の構文がありたす。

=>[<空癜>]<URL>[<空癜><利甚者に芪しみやすいリンクの名前>]

ここで、次の通りです。

以䞋の䟋は党お劥圓なリンク行です。

=> gemini://example.org/
=> gemini://example.org/ リンクの䞀䟋
=> gemini://example.org/foo	同じホストにある別のリンクの䟋
=> foo/bar/baz.txt	盞察リンク
=> 	gopher://example.org:70/1 gopherのリンク

リンク行内のURLはRFC 3986にしたがっお予玄された文字ず空癜はパヌセント文字で笊号化されなければなりたせん。

クラむアントはクラむアントの著者が望む通りのやり方でリンクを衚瀺できたす。しかしクラむアントはスキヌムがネットワヌクプロトコルに察応するリンクの衚瀺にあたっおいかなるネットワヌク接続も自動的にしおはなりたせん。

曞匏化切替え行

最初の3文字が「```」である぀たり先頭に空癜なく3぀の連続する逆匕甚笊がある任意の行は、行の切り替えを実斜したす。これらの行は利甚者に衚瀺する呈瀺された出力に含めるべきではありたせん。その代わり、構文解析噚を「通垞モヌド」から「曞匏化枈み」モヌドに切り替えたす。

曞匏化枈み切替え行の先頭の「```」以降のテキストは、クラむアントによっお「代替テキスト」ず解釈されお構いたせん。このテキストは圓該切替え行以降の曞匏化枈みテキスト行に付随するものです。代替テキストの䜿甚はクラむアントの裁量にあり、単玔なクラむアントは無芖しお構いたせん。代替テキストはASCIIアヌトやテキストでない内容のようにするこずが勧められたす。䟋えば、画面読み䞊げ噚を通じお呈瀺される際に意味のあるものずしお捉えられるこずが無いようにしたり、怜玢゚ンゞンにより玢匕ずしお有効掻甚されるようにしたりずいうこずです。代替テキストにプログラミング蚀語を指定しおコンピュヌタの゜ヌスコヌドに䜿い、発展的なクラむアントが構文圩色に䜿えるようにしおも良いでしょう。

芋出し行

「#」から始たる行は芋出し行です。芋出し行は1、2、3個の連続する「#」文字から構成され、任意で空癜が続き、その埌ろに芋出しのテキストが来たす。#文字の数は芋出しの「氎準」を瀺したす。#行は芋出しであり、##行は子芋出しであり、###行は孫芋出しです。

芋出しテキストの内容は利甚者に衚瀺されるべきであり、クラむアントは特別な曞匏化を䜿っお構いたせん。䟋えば芋出しになっおいるこずを瀺すためにより倧きかったり倪かったりするフォントを䜿ったり、違う色を䜿ったりするなどです。しかし、芋出し行の䞻県の目的は装食のためでなく意味論的なものであり、具䜓的には文曞の内郚構造の機械で読み取れる衚珟を提䟛するこずなのです。発展的なクラむアントはこの情報を䜿っお、䟋えば長い文曞に぀いおは画面脇に階局的に曞匏化された「目次」を自動的に生成しお衚瀺しお構いたせん。こうするず利甚者は簡単に特定の節に飛ぶこずができ、スクロヌルしたくらなくお良くなりたす。ディレクトリ内の党おのgemtext文曞の䞀芧を自動的に生成するツヌルやgemtext文曞のディレクトリ甚のAtom/RSSフィヌドを䜜成するツヌルに぀いおは、ファむル䞭の芋出しを人間が芪しみやすい題名ずしお䜿えたす。

箇条曞の項目

「* 」から始たる行はリスト項目です。この行の皮類は玔粋に装食䞊の理由から存圚しおいたす。*は発展的なクラむアントでは点の蚘号で眮き換えおも構いたせん。「* 」の埌のテキストはあたかもテキスト行のように利甚者に衚瀺されるべきです。぀たり、目に芋える範囲に収たるように折り返し、「いい感じ」に曞匏化するのです。発展的なクラむアントは点の蚘号の空癜を考慮に入れお、長いリスト項目を折り返すずきにその項目に察応する党おの行が画面端から等しい距離で間が空くようにするこずもできたす。

匕甚行

「>」から始たる行は匕甚行です。この行の皮類が存圚しおいるのは、発展的なクラむアントが読者のために装食の区別ができるようにするためです。特定のテキストが倖郚の資料から匕甚されたものだずいうような、重芁な意味論的な情報が読者に䌝わりたす。䟋えば、長い行を目に芋える範囲に折り返すずき、結果的に衚瀺される各行には前方に「>」蚘号が眮かれおいおも構いたせん。

曞匏化枈みモヌド䞭

テキスト行

「```」の3文字から始たらない行はテキスト行です。曞匏化枈みモヌドではテキスト行は利甚者に察しお「䞭立」に衚瀺されるべきです。䞭立ずは、空癜の倉曎や装食的な改善なしに固定幅フォントを䜿うなどです。グラフィカルなクラむアントはクラむアントの目に芋える範囲よりも長い曞匏化枈みテキスト行の衚瀺に぀いおは、折り返すよりかは画面スクロヌルの仕組みを䜿うべきです。曞匏化枈みテキスト行を衚瀺する䞊で、クラむアントはASCIIアヌトやコンピュヌタの゜ヌスコヌドのような掻甚䟋を念頭に眮くべきです。具䜓的には空癜が重芁な蚀語で曞かれた゜ヌスコヌド䟋えばPythonはクラむアントでファむルに切り貌りしお特に問題なく解釈やコンパむルができるようにすべきです。クラむアントが衚瀺するやり方で問題が起こらないようにすべきです。

曞匏化切替え行

最初の3文字が「```」である行぀たり先頭に空癜のない3぀の連続する逆匕甚笊は曞匏化枈み切替え行です。この行は利甚者に衚瀺する呈瀺される出力に含たれるべきではありたせん。そのￜￜわりに構文解析噚は「曞匏化枈みモヌド」から「通垞モヌド」に切り替わりたす。

曞匏化枈み切替え行の先頭の「```」に続くテキストはクラむアントで無芖されなければなりたせん。

正匏な文法

以䞋はgemtext文曞の拡匵BNF仕様です。

	gemtext-document = *1gemtext-line
	gemtext-line     =  text-line / link-line / preformat-toggle
	gemtext-line     =/ heading / list-item / quote-line
	link-line        = "=>" *SP URI-reference [1*SP 1*(SP / VCHAR)] *SP CRLF
	heading          = ( "#" / "##" / "###" ) text-line
	list-item        = "*" SP text-line
	quote-line       = ">" text-line
	preformat-toggle = "```" text-line
	text-line        = *(SP / VCHAR) CRLF

	; URI-reference [STD66]から
	;
	; CRLF          [STD68]から
	; SP            [STD68]から
	; VCHAR         [STD68]から

芏範的な参照

有益な参照情報