Быстрое введение в язык разметки "gemtext"

Общепринятый способ передавать текстовое содержимое через Gemini - не простым текстом, как в Gopher, а с помощью лёгкого языка разметки под названием "Gemtext" (который раздаётся с неофициальным MIME-типом text/gemini). Данный документ служит быстрым введением в этот язык разметки. Gemtext имеет поверхностное сходство с Markdown, что делает его изучение простым, если вы уже знаете MD, но они также имеют и ряд отличий.

После того, как вы прочитаете этот документ, вы можете время от времени освежить свою память, обращаясь к шпаргалке.

Шпаргалка по Gemtext

Текст

Текст в документах Gemtext пишется с помощью "длинных строк", то есть вы (или ваш редактор) не должны вставлять символы переноса строки каждые 80 символов или около того. Вместо этого, оставьте задачу переноса строк клиенту Gemini на принимающей стороне, чтобы он подогнал содержимое под ширину экрана и предпочтения пользователя. Таким образом, контент Gemtext выглядит красиво и удобочитаемо на мониторах компьютеров, экранах ноутбуков, планшетов и смартфонов.

Учтите, что хотя клиенты Gemini переносят строки текста, которые не помещаются в экран пользователя, они не объединяют короткие строки вместе, как происходит в Markdown, HTML или LaTeX. Это значит, что, к примеру, списки или стихи с намеренно короткими строками будут отображаться правильно без необходимости для автора делать дополнительную работу или для клиента быть умнее, чтобы распознавать и обрабатывать такой вид содержимого корректно.

Для большинства "повседневного" письма такой подход будет означать, что вам нужно писать каждый параграф отдельной строкой.

Учтите, что пустые строки выводятся точь-в-точь, то есть если вы вставляете две или три пустых строки между параграфами, читатель увидит две или три пустых строки.

Ссылки

Как Gopher (и в отличие от Markdown и HTML), Gemtext позволяет размещать ссылки на другие документы только на отдельной строке. Вы не сможете сделать ссылкой одно слово посреди предложения. К этому надо привыкнуть, но зато ссылки крайне легко найти, а клиенты могут по-разному их стилизовать (например, дать ясно понять, какой протокол они используют, или отображать доменное имя, чтобы помочь пользователям решить, хотят ли они переходить по ним или нет), не испортив при этом удобочитаемость вашего текста.

Строки ссылок выглядят так:

=> https://example.com    Крутой вебсайт
=> gopher://example.com   Ещё более крутой gopher-сайт
=> gemini://example.com   Невероятно крутая капсула Gemini
=> sftp://example.com

А именно:

• Они начинаются с двух символов =>,
• после которых идут один либо несколько пробелов или табуляций,
• после которых идёт URL (имеющий любой протокол).
• Они могут заканчиваться прямо здесь, если вы так хотите, как с примером sftp выше!
• Или после может быть хотя бы один пробел или табуляция,
• А потом понятная человеку подпись, которая может быть любой длины

В примере выше все URL и подписи к ним выровнены, потому что автор был педантичным. Но Gemini всё равно, и так тоже можно:

=>https://example.com Крутой вебсайт
=>gopher://example.com      Ещё более крутой gopher-сайт
=> gemini://example.com Невероятно крутая капсула Gemini
=>   sftp://example.com

Заголовки

Gemtext поддерживает три уровня заголовков. Заголовки ограничены одной строкой и начинаются с одного, двух или трёх символов #, после которых обязательно следует один пробел:

# Заголовок

## Подзаголовок

### Подподзаголовок

Это единственный поддерживаемый синтаксис заголовков. Подчёркивания заголовков символами - и = в стиле Markdown не имеют никакого эффекта.

Для клиентов придавать какое-либо специальное значение заголовкам строго опционально. Многие клиенты будут распознавать их и использовать крупный шрифт, или другой цвет, или ещё какой-нибудь особый стиль, но некоторые не будут и просто воспримут и выведут их как обычные строки текста. Это нормально, потому что заголовки предназначены не для того, чтобы контролировать внешний вид содержимого, а чтобы предоставлять важную семантическую информацию о структуре содержимого. Некоторые клиенты будут использовать заголовки, чтобы автоматически генерировать оглавление, которое может пригодиться пользователю для навигации по большим документам. Программы для генерации лент Atom и RSS могут использовать заголовки, чтобы автоматически определять наименования постов гемлога.

Списки

Gemtext поддерживает маркированные списки. Каждый элемент в списке пишется как одна длинная линия, которая начинается с одного символа *, за которым обязательно следует один пробел:

* Меркурий
* Джемини
* Аполлон

Это единственный поддерживаемый синтаксис списков. Использование - вместо * в стиле Markdown не имеет никакого эффекта. Вложенные списки не поддерживаются.

Для клиентов делать что-либо особое с элементами списков строго опционально, и некоторые клиенты будут воспринимать их как любую другую строку текста. Единственная причина, по которой они определены, заключается в том, что более функциональные клиенты могут заменить символ * на более красивый маркер, а когда элементы списка слишком длинные, чтобы уместиться в ширину экрана, и разбиваются на несколько строк, вторая и последующие строки могут смещаться от края на то же расстояние, что занимает символ маркера. Это просто типографическая утончённость.

Цитаты

Gemtext поддерживает цитаты. Цитированное содержимое пишется одной длинной строкой, которая начинается с одного символа >:

> Gemtext поддерживает цитаты.  Цитированное содержимое пишется одной длинной строкой, которая начинается с одного символа >

Для клиентов делать что-либо особое с цитатами строго опционально, и некоторые клиенты будут воспринимать их как любую другую строку текста. Как и в случае со списками, они определены исключительно для того, чтобы позволить более претенциозным клиентам отрисовывать более красивую типографию.

Преформатированный текст

Gemtext тщательно спроектирован быть очень-очень простым для парсинга и рендеринга. Клиенты Gemini обрабатывают Gemtext по одной строке за раз, выводя каждую строку независимо от любых строк до и после неё, просто смотря на первые несколько символов строки, чтобы найти там что-то вроде =>, # , * , и т.д.

Строка, начинающаяся с ``` (то есть с трёх обратных апострофов), говорит клиенту переключиться между его обычным режимом парсинга и "преформатированным режимом". В режиме преформатированного текста клиенты не проверяют, является ли строка ссылкой, или заголовком, или чем-либо ещё. Она просто выводится как есть. Также, в то время как клиенты могут использовать разные шрифты для всего другого обычного текста, в преформатированном режиме клиенты должны использовать моноширинный шрифт. Таким образом, пара строк ``` служит для того же, что и теги <pre> и </pre> в HTML.

Преформатированный текст можно использовать, чтобы включать в документ Gemtext ASCII-арт, исходный код или подобное содержимое, а клиенты не будут по ошибке воспринимать строки как заголовки, элементы списка и так далее. Также его можно использовать, чтобы писать документы как этот, где объясняется синтаксис Gemtext с примерами - вы можете видеть примеры синтаксиса выше, потому что ваш клиент не интерпретирует их как он делает в норме, ведь они отрисованы в режиме преформатированного текста.

Всё, что идёт после символов ``` на строке, которая *включает* режим преформатированного текста (то есть первая, третья, пятая и т.д. такая строка в документе), может быть распознано как "альтернативный текст" для преформатированного содержимого. В общем случае, вы не должны рассчитывать на то, что его увидит пользователь, но, к примеру, поисковые движки могут его индексировать, а программы для чтения с экрана могут озвучить это пользователям, чтобы помочь им решить, нужно ли читать преформатированный текст вслух (чего, например, с ASCII-артом происходить не должно, а с исходным кодом должно). Пока нет общепринятого соглашения насчёт того, как должен быть отформатирован альтернативный текст.