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

View Raw

More Information

⬅ Previous capture (2024-08-18)

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

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]から

芏範的な参照

有益な参照情報