Формат разметки Comtext

Формат Comtext предназначен для разметки электронных книг.

Описание формата

Предложения сюда писать или в какое-то другое место (типа, страница обсуждения в wikijs)?

Пока удобнее всего будет писать сюда. На wiki уже утвержденный вариант или готовый концепт.

  1. В разделе «Вложенные списки» опечатка в примере: написано «Усастник» вместо «Участник».

  2. В раздел «Цитаты», нмв, нужно добавить, что считать цитатой, а что не является цитатой. Например: если абзац начинается с кавычек, в середине есть речь автора, а потом идет продолжение цитаты, то выделять весь абзац цитатой или нет? Я предлагаю, считать это одной цитатой, если речь автора находится внутри цитируемого отрывка, а не соединяет два разных цитируемых отрывка. Но бывают случаи и посложнее. Вот их, думаю, стоит обсудить.

  3. В разделе «Виды сносок» написано

Если тип сноски не указан явно, то она считается редакторской.

Это не опечатка? Просто, в бумажных изданиях все наоборот: то, что не указано как редакторская сноска является авторской

  1. В разделе « Горизонтальная линия» стоит упомянуть о том, что другие символы так же рендерятся как горизонтальные линии. Например, звездочки, если их не экранировать, становятся горизонтальной линией
    Код:
***

Результат:


  1. В подразделе «Способы встраивания» раздела «Формулы» написано:

Для встраивания формул используется LaTeX.

Почему именно LaTeX? Почему не MathJax?

6.1. В подразделе «Пробелы» раздела «Формулы» написано:

Для добавления пробелов между словами в формулах используйте Для добавления пробелов между словами в формулах используйте \medspace :

В MathJax используется просто слэш \. Есть, конечно, и другие способы вставить пробелы. Но этот самый простой.

6.2. В том же подразделе в примере:

$$
\frac{стоимость \medspace продукта \medspace А}{стоимость \medspace продукта \medspace Б} = \frac{стоимость \medspace 4 \medspace часов \medspace труда}{стоимость \medspace 2 \medspace часов \medspace труда}
$$

Я предлагаю слова в формулах, оборачивать в теги \text{}. Тогда и пробелы не потребуются и кириллица будет рендериться более-менее.

  1. В подразделе «Фигурные скобки» раздела «Что нельзя использовать» написано:

В тексте книги нельзя использовать фигурные скобки

Допустим. Но как тогда быть с тем же «Капиталом» Маркса, где фигурные скобки означают вставку Энгельса?

  1. В подразделе «Выделения» раздела «Рекомендации» написано:

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

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

  1. В подраздел «Пробелы» того же раздела (или в раздел «Что нельзя использовать») предлагаю добавить текст примерно следующего содержания:

Не допускается заканчивать абзац на пробел или несколько пробелов


Пока что такие предложения

Я в английском не силен.
сколько букв в этом слове должно быть?

Это была опечатка, спасибо за сообщение.

Правильно version.

Спасибо, исправил опечатку.

Здесь действительно сложный вопрос. В целом сейчас цитаты очень примитивные, например, никак нельзя указать источник. А это было бы очень полезно, чтобы через ссылки на источник связывать книги. Тут действительно стоит обсуждать детальнее.

Так выбрали из-за того что при вычитке Черншыевского, редакторские сноски попадались чаще. В целом выбранный способ указания авторства нужно пересмотреть, например, тут не учтено что книги могут быть на разных языках.

Здесь дело в том что сайт собирается готовыми средствами (VuePress) почти без модификаций. Всё работает только потому что формат на 90% совпадает с Markdown. Но, я думаю, имеет смысл ограничить, там где это возможно варианты разметки. В дальнейшем, когда будут средства работы с Comtext, они уже будут поддерживать только эти выбранные варианты.

MathJax это не язык разметки, а движок для рендера формул. Разметка которую он может использовать может быть разной, в том читсле LaTeX

MathJax is an open-source JavaScript display engine for LaTeX, MathML, and AsciiMath notation that works in all modern browsers. (What is MathJax? — MathJax 3.2 documentation)

На сайте используется аналог MathJax — KaTeX.

В целом, по формулам, я думаю допустимы и другие варианты, например, AsciiMath. Может быть имеет смысл обозначить стандартную разметку. А если применяется другая, то возможности её в явном виде указать, например

$$[asciimath] formula $$

Это техническое ограничение текущей реализации. Другие варианты не работали. Возможно, из-за багов в каком-то из движков (VuePress, KaTeX). Это всё нужно будет убрать когда появится парсер Comtext.

Перепроверю это предложение. Скорее всего, нужно заменить на обязательное экранирование фигурных скобок. А так, конечно, все символы должны быть допустимы в тексте на выходе.

Это не знал. Можно пересмотреть этот пункт. Вопрос сводится вот к такому. Полужирный и курсив обозначенные в формате, сейчас не совсем правильно. Полужирный шрифт и курсив относятся к тому как текст выглядит (виды акцента Emphasis (typography) - Wikipedia). В разметке же нужно только обозначить что это текст важен, а то как он будет отображаться уже зависит от средства отображения. Если это текст на печат или вывод на экран то он может быть выведен полужиным, а знаки препинания могут не измениться, это уже легко реализуется средством отображения. А если книга будет выводится через синтезатор речи, то там акцент может быть выражен как-то подругому. При таком подходе полужирный и курсив вообще логично заменить, например, на акцент и сильный акцент.

Добавлю это. На основе всех замечаний сделаю новую редакцию и скину на обсуждение.

Ещё про один момент по поводу разметки. При оформлении сложных книг становится видно что книгу нельзя представить в виде плоского списка абзацев, как изначально предполагалось. Абзацы книги, или даже более правильно их назвать блоками, формируют дерево.

Например.

Абзац1[^1]
[^1]: примечание1 абзац1 [^2]
     примечание1 абзац2
[^2]: Примечание2
     примечание2 абзац2

В этом тексте один абзац и два примечания из двух абзацев. Причем примечание2 относится к первому абзаце примечения1.

Получается такая структура

|- Абзац1
   |
   |- Примечание1, абзац1 
       |
       |- Примечание2, абзац1
       |   |
       |   |- Примечение2, абзац2
       |
       |- Примечание1, абзац2 

Такие же структуры формируются при обработке цитат, цитат с примечаниями, вложенных цитат.

Вероятно, нужно эти моменты в явном виде указать в описании формата.

Я такое нашёл при вычитке “очерков о гоголевском периоде литературы”. Здесь такая ситуация возникает потому, что в авторское примечание вставлены примечания редакции. Есть ли ситуации, где сам автор делал бы такую структуру - примечание в примечании?

1 лайк

Возник вопрос. В некоторых книгах ссылки оформлены не совсем привычным способом: вместо сноски внизу страницы в квадратных скобках указание на номер из библиографического списка. Вопрос - сохранять ли такой стиль оформления или использовать привычный нам формат?
Дело в том, что иногда авторы указывают несколько номеров подряд к одному фрагменту. И подразумевается, что там не строго цитата, а просто указание на источник откуда взята мысль. В таких случаях кажется более целесообразным поставить ссылку, а библиографический список оставить в конце, не переносить текст после каждого абзаца, где есть цитата.
Но! В этой же книге есть ссылки и другого плана: с указанием страницы. Для них такой вариант не годится. Скрины прикладываю.
Как вы думаете, каким образом будет лучше оформить?


В этом случае мне видится, что надо бы разделить “примечание” и “ссылки на литературу”. В одном случае у нас есть некий подстрочный текст, который нужен для понимания текса. В другом - просто ссылка на литературу, которая нужна разве что после прочтения книги. В показанном тобою случае тут ссылки на литературу. Насколько я знаю, в нашем формате пока такой категории нет. Если отмечать такие ссылки как примечания, т. е. через тег [^N],[^N+1],[^N+2] и т. д. то формат требует, чтобы после каждого абзаца с ссылками на примечания были бы соответствующие примечания [^N]:,[^N+1:,[^N+2]:. А значит, в случае первого примера нужно 7 новых строк, что вообще не удобно. И ситуация тут не отличается от ссылок с конкретным указанием страницы.

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

Вероятно, это лучший вариант.

Здесь две особенности:

  1. На каждый элемент списка литературы присуствует несколько ссылок.
  2. С каждой ссылкой связаны номера страниц (а так же может быть указание на главу или что-то подобное)

С пунктом 1 проблемы нет, действительно, можно просто оставить список в конце книги и ссылаться на него как обычно [^1][^2].

С пунктом 2 сложнее. Думаю, на данный момент наиболее перспективный подход который уже применяют в ссылках на библиографию. Например, я пользуюсь Zettlr и там так

Общественный труд создал общество, приводит к развитию и переходу 
общества из одной формы в другую. [@rubinOcherkiPoTeorii1929, p. 7]

Библиографический источник указывается в квадратных скобках, после символа “@”. Кроме этого в квадратных скобках может быть что угодно. Например:

[Смотри вторую часть первой главы @rubinOcherkiPoTeorii1929]

Идентификатор @rubinOcherkiPoTeorii1929 хранятся в отдельном библиографиеском списке, например, в Zotero. В данном же случае они будут просто в конце книги.

Вот здесь описан механизм ссылок на библиографию в Pandoc, он такой же как я описал выше.

Только нужно учесть, что ссылки не могут начинаться с цифры, а если начинаются то их нужно оборачивать в фигурные скобки.

Unless a citation key starts with a letter, digit, or _, and contains only alphanumerics and single internal punctuation characters (:.#$%&-+?<>~/), it must be surrounded by curly braces, which are not considered part of the key.

Чтобы этого избежать можно просто назвать все ссылки например так:

[@bib1][@bib2 стр. 5][@bib3 стр. 8-9]

Причем номера будут точно совпадать с номерами в исходной книге.

Ещё есть довольно интересная часть про то как указывать данные внутри скобок.

Citation items may optionally include a prefix, a locator, and a suffix.

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

@Natalia @Lev_Hudoi @raoof @Book_Keeper Обновил описание формата на основе обсуждения, изменения описаны в истории изменений.

Посмотрите, пожалуйста, может будут ещё дополненния.

Прочитал. Насколько я понимаю, теперь на одно примечание можно будет ссылаться из любого места книги? Но не появляется ли тогда проблема автоматической нумерации примечаний?

Автоматически пронумеровать такие текущим способом не получится. Можно попробовать что-то придумать на эту тему, изменение нумерации относится к этапу подготовки книги и может зависеть от средств (программ редакторов) которыми книга подготавливается.

Так же думаю, что следовало бы формализовать разметку стихотворений в текстах.

Что на мой взгляд необходимо описать в следующией версии формата:
Каким образом выделять стихи. В текстах они разбиты то столбиками по 4, 8 и т.п. строк, то идут сплошным текстом, без пропусков строки. Пока что в нашем формате я не нашёл средств явно определять, где должна быть пустая строка, где нет. Возможным решением является просто ввод в разметку пустой строки как элемента разметки.

Другая проблема когда в тексте абзац прерывается цитатой, стихотворением и т.п., после которых абзац продолжается. Пример:
image
Думаю такую ситуацию нужно тоже предусмотреть. Возможно, тут так же поможет ввод элемента пустой строки.

Схожая проблема в примечаниях, где даются цитаты и стихи. Давайте точно формализируем, как их правильно нужно вставлять в примечания. Вот, что я имею в виду (точки символизируют пробелы в начале нового абзаца):

[89]: Текст примечания
…1 строка стиха \
2 строка стиха \
3 строка стиха \
4 строка стиха
…2 абзац примечания

Как в такой ситуации правильно отметить стихи? Нужно ли перед каждой новой строкой делать 4 пробела? Я пока решил, что не надо, но другой может решить иначе. Предлагаю какой-нибудь вариант утвердить в правилах.

Так же ещё такой момент. Нужно чётко обозначить как правильно использовать тег цитирования “>” когда используются абзацы с переводами строки, например:

Начало абзаца \
Какой нибудь текст \
Продолжение абзаца.

Нужен ли тут знак цитирования один раз, или его необходимо ставить в начале каждой новой строки?

Я думаю, возможно обойтись без символов “\” в конце строки. Возможно, хватит только перевод строк и пустых строк. Примеры

Абзац1

Абзац2

В этом случае это два абзаца, абзацы отделяются пустой строкой.

Абзац1
Вторая страока абзаца1
Третья строка абзаца1

Если пустой строки нет, то считаем это тем же абзацем, но спереводом строк. По сути это полностью равно использованию символа “\” в конце абзаца, но выглядит лучше.

Абзац1 \
Вторая страока абзаца1 \
Третья строка абзаца1

Но для стихов нужно конечно детальнее продумать. За основу можно попробовать взять структуру из fb2, только там я видел разметки для стихов. Логические элементы которые выраженыв xml в fb2, можно попробовать выразить более простыми средствами, проблами и спец. сиволами.

Насчёт символа “\” - согласен, для упрощения можно его убрать.
Разметка фб2 мне кажется логичной и правильной.

Стихи

Чтобы разместить стихотворение в тексте документа, используют тэг . Он может нести внутри себя следующие части в указанном порядке:

  1. Заголовок . От нуля до одного вхождений.
  2. Эпиграф . Любое число вхождений.
  3. Строфы . Одно или более вхождений. Строфа - это группа строк стихотворения, отделенная пустым промежутком от остальных строк. Отдельная строка стихотворения помечается тэгом , который должен быть вложен в . Кроме того в состав могут входить тэги (заголовок) и (подзаголовок).
  4. Автор стихотворения . Любое число вхождений.
  5. Дата написания . От нуля до одного вхождений.

То есть обязательно присутствует как минимум одна строфа , а остальное добавляется при необходимости

Мне даже добавить нечего - это как раз так, как я себе представлял выделение стихов.

Но остаётся проблема прерывания абзаца цитатой как в примере выше. Чтобы это выглядело адекватно, т.е. чтобы цитата была отделена от текста абзаца, необходимо придумать специально выделение. Иначе, как мне кажется, такой текст будет сливаться с текстом абзаца и потеряется авторский замысел. То же самое, если разделять один авторский абзац на 3, 4 и т.д. Если абзац представляет собой одну законченную мысль, то разбив его на части мы также исказим авторский замысел.

В “Капитале” такая штука встречается. Более того, там в примечании бывает ссылка на общее примечание.