Семантическая разметка: LaTeX, DocBook или ???

    Писал комментарий к статье и понял, что надо выносить в отдельный пост.
    Как многие отмечают там в комментариях статья отстой, человек не разбирается и смешал всё в кучу, попробую поделиться своими выводами от использования разных разметок.

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

    И вот однажды пришло время оставить работу и предаться графоманизму. Я всегда держал в голове LaTeX, как известный и интересный формат, но для простых статеек начал использовать Markdown т.к. его поддерживали GitHub/GitLab, потом мне стало мало его возможностей, я перешёл на AsciiDoc, он тоже поддерживается, но потом и его возможностей стало не хватать и пришлось переходить на LaTeX.

    LaTeX хорош следующим:

    1. Он распространён, большая часть вопросов легко решается — поиск приводит на stackoverflow и почти всё начинает работать.
    2. Попытка разделить содержание и оформление это отлично, это один из лучших и универсальных паттернов в ИТ (все же используют MVC, многие перешли на SPA, не думаю что нужно пояснять чем это хорошо).
    3. LaTeX достаточно хорошо читается и вполне пригоден для набора человеком.
    4. LaTeX отлично подходит для работы через git.

    К сожалению LaTeX тоже не идеален, да — можно получить хороший pdf, но:

    1. Разделения содержания и оформления в LaTeX'е на самом деле нет, для того чтобы это было так надо стараться сделать так, но всё равно какие-то артефакты оформления просочатся в ваше содержимое, если вы делаете что-то сложнее тривиального примера.
    2. LaTeX это скорее псевдосемантическая разметка — человеку-то понятно, но конвертеры не знают какая семантика за конкретным тегом (стандарта нет). Поэтому конвертация работает очень плохо, какое-то время я обходился plastex'ом, но он совсем сломался как только я задействовал чуть больше возможностей LaTeX, хотя и до этого он не был идеален.
    3. Ещё одна проблема отсутствия стандарта это несогласованность пакетов — у меня был случай когда один пакет для списков имел хорошее решение для одной фичи, но не имел решения для другой, а второй пакет наоборот, при этом они конфликтовали так как определяли одно окружение.
    4. Хоть читаемость и хороша, есть куда улучшать — разметки типа Markdown, конечно, лучше подходят для человека.

    Когда конвертация из LaTeX'а окончательно сломалась я был вынужден обратиться к великому DocBook'у, это XML стандарт на семантическую разметку текстов для которого есть готовые XSLT для преобразования в некоторые форматы. Но у него тоже есть проблемы:

    1. Докбук это «секретная» технология — очень мало информации (про информацию на русском я даже не говорю), очень трудно начинать разбираться как сделать даже минимальный пример, а тем более решать какие-то нестандартные проблемы (если кому нужно сохранилась пара полезных ссылок).
    2. Это XML. Считаю, что человек это не должен видеть, а тем более редактировать. Через гуй конечно можно было бы, но хочется иметь все возможности и не привязываться к гуям.
    3. В git можно положить xml, но дефолтные diff'ы будут читаться не очень, можно прикручивать специальные утилиты для просмотра xml diff'ов, но это нужно делать, когда-то даже пробовал, но не помню насколько хорошо получилось в итоге. Точно помню что это настраивается локально и надо повторять настройку после клонирования.
    4. PDF по умолчанию выглядит не очень, кастомизировать в теории можно, но не хочется из-за пункта 1
    5. Несмотря на то что это стандарт и стандарт который развивается уже давно, там тоже есть недоделки, например я столкнулся что в библиографии не предусмотрен тег для url источника.

    Большой плюс докбука — это семантическая разметка, особенно это важно когда вам надо конвертировать в разные форматы, мы же хотим чтобы читателям было удобно, а значит надо выдать им в том формате который им удобен — pdf разных размеров для разных экранов и печати, mobi для амазоновских читалок, кому-то fb2 (с этим как раз проблема — надо делать свой xslt, готового нет), многостраничная html версия нужна для чтения онлайн и т.д.

    Я думаю всем понятно, что семантическая разметка не запрещает иметь «чтовижутопойю» редактор, поэтому это не может быть аргументом против семантической разметки. Правда, я не исследовал тщательно вопрос гуёв, на первый взгляд под Linux как-то всё не очень с гуями для docbook, хотя варианты есть.

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

    В итоге я «доработал» (добавил пустых тегов) разметку LaTeX, чтобы простыми регексами конвертить в докбук, а из него делать все форматы кроме PDF т.к. pdf проще и красивее сразу из латеха делать.

    Т.е. для себя я сделал костыль скрещивающий плюсы LaTeX'а и DocBook'а — у меня разметка более человеческая чем xml (и дающая хороший pdf), но при этом она легко мапится в docbook, чтобы получить его преимущества в виде качественной конвертации во многие форматы.
    Конечно трудно назвать это хорошим решением, но лучшего не придумал.

    Правильным решением было бы создание человекочитаемой разметки вроде DocOnce, но с полным набором возможностей DocBook (можно было бы из этой разметки конвертить в докбук, а из него уже в остальные форматы), но что-то у меня уже упало желание — надо было подобрать библиотеку и описать синтаксис в какой-нибудь нотации типа BNF, но не пошла у меня эта задача, может у кого больше энтузиазма будет.

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

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

    Подробнее
    Реклама
    Комментарии 53
    • +1

      Тот же XML можно писать в формате xml.tree, а потом конвертировать в собственно xml. Например:


      ? xml
          version \1.0
          encoding \UTF-8
      book
          @ xml:id \simple_book
          @ xmlns \http://docbook.org/ns/docbook
          @ version \5.0
          title \Very simple book
          chapter
              @ xml:id \chapter_1
              title \Chapter 1
              para \Hello world!
              para
                  \I hope that your day is proceeding 
                  emphasis \splendidly
                  \!
          chapter
              @ xml:id \chapter_2
              title \Chapter 2
              para \Hello again, world!

      <?xml version="1.0" encoding="UTF-8"?>
       <book xml:id="simple_book" xmlns="http://docbook.org/ns/docbook" version="5.0">
         <title>Very simple book</title>
         <chapter xml:id="chapter_1">
           <title>Chapter 1</title>
           <para>Hello world!</para>
           <para>I hope that your day is proceeding <emphasis>splendidly</emphasis>!</para>
         </chapter>
         <chapter xml:id="chapter_2">
           <title>Chapter 2</title>
           <para>Hello again, world!</para>
         </chapter>
       </book>
      • 0
        Интересный вариант, хотя полностью проблемы это не решает — всё равно штуки вроде DocOnce читаемее.
        • 0

          В чём-то — да, а в чём-то просто вымораживает:


          We address the initial-value problem
          
          !bt
          \begin{align}
          u'(t) &= -au(t), \quad t \in (0,T], label{ode}\\
          u(0)  &= I,                         label{initial:value}
          \end{align}
          !et

          Или таблички аски-разметкой — это такой ад их редактировать и вручную выравнивать.

          • 0
            Ну да, идеала нет.
            С таблицами вообще всё печально — не очень понятно какой синтаксис наилучший.
            • 0

              Я когда пилил свой маркдаун-подобный синтаксис делал так:


              --
              | 
              | *Колонка 1*
              | *Колонка 2*
              | *Колонка 3*
              --
              | *Строка 1*
              | Значение 1х1
              | Значение 1х2
              | Значение 1х3
              --
              | *Строка 2*
              | Значение 2х1
              | Значение 2х2
              | Значение 2х3

              Когда колонок не слишком много — вполне норм. Когда много — лучше что-нибудь типа такого:


              --
              | name
              | field1 : *Колонка 1* 
              | field2 : *Колонка 2* 
              | field3 : *Колонка 3* 
              | field4 : *Колонка 4* 
              | field5 : *Колонка 5* 
              | field6 : *Колонка 6* 
              --
              | name : *Строка 1*
              | field1 : Значение 1х1
              | field2 : Значение 1х2
              | field3 : Значение 1х3
              | field4 : Значение 1х4
              | field5 : Значение 1х5
              | field6 : Значение 1х6
              --
              | name : *Строка 2*
              | field1 : Значение 2х1
              | field2 : Значение 2х2
              | field3 : Значение 2х3
              | field4 : Значение 2х4
              | field5 : Значение 2х5
              | field6 : Значение 2х6
              • +1
                Что-то типо того, минус такого представления в том что таблица не выглядит как таблица — когда данные небольшого размера можно и руками отформатировать, чтобы получить наглядность.
                Возможность такая должна быть, в принципе такой синтаксис этого не запрещает.
                • 0

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

                • 0
                  Чем не понравился MD-синтаксис (c любым количеством пробелов и тире)?
                  |          |*Колонка 1*|*Колонка 2*|*Колонка 3*
                  |----------|:-|--|-:
                  |*Строка 1*|Значение 1х1|Значение 1х2|Значение 1х3
                  |*Строка 2*|Значение 2х1|Значение 2х2|Значение 2х3
                  • 0
                    он читается хорошо если размер данных в ячейке небольшой, а если там длинная строка, то будет менее наглядно
                    • +1
                      |          |*Колонка 1*|*Колонка 2*|*Колонка 3*
                      |----------|:-|--|-:
                      |*Строка 1*|Значение 1|Значение 2|Значение в ячейке по координатам 1х3|Ещё одно значение 4|И опять 25
                      |*Строка 2*|Значение в ячейке по координатам 2x1|2|3|4|Значение 5

                      Попробуйте не запутаться.

                      • –1
                        Здесь такой же принцип, как у CSV.
                        • +1

                          И что с того?

                          • –1
                            Я не запутаюсь считая разделители.
                            • +1
                              Зачем делать дурную работу когда можно сделать по человечески?
                              • 0
                                Конечно, лучше использовать специализированную программу. Считать в уме — дурная работа? Видимо, я давно «отстал от жизни».
                                • +1
                                  Во-первых, дурная работа эта та которую можно не делать и ничего не потерять, в данном случае грамотная разметка позволила бы не тратить время впустую, а сразу увидеть нужное.
                                  Во-вторых, да, считать в уме это дурная работа (хотя уметь нужно) т.к. компьютер делает это сильно эффективнее, надо мозги загружать тем, что компьютер не умеет делать.
                • 0

                  Нормальный такой теховский код. Всяко проще, чем ноты с листа читать, например. :)

                  • 0
                    Касательно нот вспоминается LilyPond, тоже разметка.
            • 0
              И беда при конвертировании из LaTeX ещё в том, что его можно (и в каком-то смысле нужно) использовать как язык программирования. Главы я нумерую словами («Глава пятая») через макрос, а нумерованные файлы и картинки подтягиваю в цикле. Pandoc это не осилил сконвертировать :-(

              Плюс ещё бывают несколько разных указателей в конце, для которых нужен xindy, а как должны быть представлены указатели в электронной книге формата epub или mobi, я пока для себя не уяснил.
              • 0
                А зачем вам из LaTeX собирать epub? Мне кажется, он многое не потянет, а если нужен просто размер, можно попробовать собрать а5 книжку.
                • 0
                  Я исследований не проводил, но насколько понял pdf на всяких девайсах хуже масштабируется, даже если делать несколько вариантов размера (делаю A4, A5, A6).
                  Но точно мне говорили что fb2 шустрее работает, товарищ просил сделать именно его т.к. остальное у него тормозило на телефоне.
                  • 0

                    Да, но проблема в том, что epub и fb2, как мне кажется, гораздо беднее чем pdf, и скажем, формулы им надо передавать рисунками, скорее всего.

                    • 0
                      Об этом конвертер должен думать — сделает и картинки если будет нужно, да и формулы не всегда есть.
                      • 0
                        По идее (это тут ключевое слово), формулы в epub можно включать в виде MathML. Поддерживается только подмножество MathML, но его хватит для большинства формул. Правда, есть один небольшой нюанс — читалки далеко не всегда поддерживают эту фичу. А если я читаю epub с компа, то я с тем же успехом могу прочитать и pdf.
                    • +1
                      Чтобы продать книжку не только бумажную, но и электронную. А для этого лучше иметь её во всех возможных форматах.
                      • 0
                        Вобщем-то как правильно заметили — не надо за пользователя решать какой ему формат нужен, надо дать ему выбор.
                    • 0

                      Позвольте добавить свои пять копеек: в свое время я также долго перебирал, пробовал и использовал разные форматы, включая все вышеупомянутые. Для начала хотел бы напомнить про современный HTML — он имеет всю нужную семантику, например теги <section> и <article>. Явное преимущество — не нужно никаких дополнительных компиляций, простое обновление страницы достаточно. Из недостатков, конечно, отсутствие расширяемости и макроподстановок. Лично для меня главный недостаток — нельзя вставлять код с подсветкой синтаксиса (конечно, можно прикрутить highlight.js, но тогда уже можно забыть про конвертацию в PDF).


                      На данный момент я остановился на Scalateχ. Это весьма специфическое решение, но для моих нужд вполне подходит:


                      • используются HTML-теги, не нужно изучать новый язык разметки;
                      • полное расширение функциональности, например, вместо того, чтобы использовать встроенный Highlighter (основанный на highlight.js), я написал свой, с генерацией подсветки синтаксиса в процессе компиляции (основано на Highlight.java);
                      • дополнительные фичи использования полноценной компиляции (например, проверка всех ссылок на работоспособность).

                      Если интересует, как это выглядит, вот ссылка на мою последнюю статью сделанную с помощью Scalateχ: Running arbitrary containers in LinuxKit (ссылка на исходник в конце статьи).

                      • 0
                        А как у HTML нынче с разбиением на страницы?
                        • 0

                          Это уже зависит от конечного пользователя. Чтобы соответствовала семантика, можно просто применить стиль page-break-before для тега article. Но в целом: стили — CSS, контент — HTML.


                          Естественно, будет соблазн все понамешать, но это применимо для многих систем разметки: я видел, как и в LaTeX все в box-ы помещают, и в итоге код становится нечитабельным. А в том же Markdown уж слишком много ограничений и упрощений. В этом плане современный HTML с моей точки зрения — разумный компромисс (к тому же, это может быть просто промежуточный формат, как в моем случае).

                        • 0
                          Хоть и не следил, но уверен, что даже современный html не содержит всех нужных семантических тегов, как впрочем и всякие иные поделки.
                          Разве там есть теги для библиографии? глоссария? предметного указателя?
                          • 0

                            Типография — это все-таки немного другое. На Visual Basic наверное тоже можно написать систему управления банковскими транзакциями, но никто (я надеюсь?!) не делает этого. Правда, справедливости ради, отмечу, что HTML содержит все нужные теги (с точки зрения семантики, а не конечного оформления):


                            • a — ссылки (соответственно, по ним формируется библиография, но конечно, нужна постобработка);
                            • dfn — термины (соответственно, глоссарий);
                            • предметный указатель — это использование того же тега a, но только в другом контексте — как якорь.

                            Ну и плюс к тому же, никто не мешает использовать собственные теги. Вопрос в использовании — когда уже есть готовые инструменты, незачем городить огород. Естественно, с чистого HTML книгу не сверстаешь, для этого есть другие, более подходящие форматы (и соответствующие инструменты).

                            • 0
                              Так речь не про типографику, а про семантику. Докбук ничего про типографику не знает, это голая семантика, но семантика достаточно полная и универсальная и поэтому её можно успешно конвертировать в любое представление, в том числе и типографическое.
                              • 0
                                > Естественно, с чистого HTML книгу не сверстаешь, для этого есть другие, более подходящие форматы (и соответствующие инструменты).

                                книги и вёрстка тут ни при чём, например научные статьи также принято делать с библиографией т.е. есть такие семантические понятия — библиографическая ссылка, библиография и т.д.
                          • 0
                            Добавлю про AsciiDoc. У себя в работе применяю ее как систему генерации документов для программ (хелп + инструкция пользователя). Для инструкций используем бекэнд AsciiDoc в DocBook + FOP, на выходе вполне сносный pdf с оглавлением и всем прочим.
                            Да, кроме официальных тулсетов есть реализация AsciiDoc на Ruby: asciidoctor. Со сложными документами там пока неважно (приемлемый pdf получить можно, но гибкости в настройке не хватает), но гораздо проще в установке и использовании для простых целей (небольшие статьи, одностраничники, простые pdf)
                            • 0
                              AsciiDoc насколько помню урезан до нуля, там вроде даже не было возможности сделать ссылку на другой раздел этого же документа.
                              • +1
                                Это было или слишком давно (хотя я, вроде, на AsciiDoc уже много лет) или Вы что — то путаете. Прекрасные ссылки на что угодно, единственное для «что угодно» нужно делать именованный якорь.
                                • 0
                                  Да, возможно проглядел, глянул доку, вроде много чего есть, надо будет ещё раз глянуть при случае.
                                  • 0
                                    Но чего-то я там не находил, может это был тег для эпиграфа.
                                  • +1
                                    Хабр слишком быстро закрывает возможность редактировать… Пример синтаксиса на на оф сайте.
                                • +1
                                  Добавлю свои 5 копеек.
                                  Мне очень понравился reStructuredText.
                                  Идея очень близка к markdown, тоже очень хорошо читается. По сравнению с markdown предоставляет больше возможностей. Из него легко делается latex, odt, html.

                                  P.S. LaTeX есть очень интересная альтернатива ConTeXt. Это тоже набор макросов. Главное отличие: писать стили легко, очень легко, и (но) это надо делать самому. Не очень распространен, поэтому обмен с коллегами затруднен.

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

                                      Насколько я понимаю, у ConTeXt есть ряд ограничений:



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

                                      • 0

                                        Я сразу скажу, я не большой специалист по ConTeXt. Чуть-чуть покопался, но не серьезно.


                                        Есть две нетехнические вещи, которые меня в нем настораживают:


                                        • скудная документация и отсутствие «комьюнити»;
                                        • система развивается только одной компанией, она может в любой момент закрыться.

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


                                        Я за ConTeXt не агитирую. Вещь специфическая, со многими недостатками. Просто написал, что есть такое.


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

                                    • +1
                                      Выше FurryCat писал про restructuredText. Полностью поддерживаю. Читаемый, лёгкий, чуть менее костыльный, на мой взгляд, чем MD. Латех инкорпорируется легко.

                                      А почему все так привязаны к PDF? Мне кажется, что жёстким форматам вёрстки, заточенным для печати, пора на покой. Читать двухколоночный текст даже с лопатофона совсем не удобно. Можно сделать «ревёрстку», в том же акробат ридере, но она часто отрабатывает с ошибками. В качестве конечного формата идеален HTML, его производные и аналоги, вроде CHM, FB2 и EPUB. Формулы — в MathML. Это, однако, стратегический вопрос и он регулируется издательской индустрией. Как только могучие научные издательства начнут переходить на семантически ориентированные форматы, PDF ждёт участь DJVU — формата для хранения памятников эпохи печати.
                                      • 0
                                        > Мне кажется, что жёстким форматам вёрстки, заточенным для печати, пора на покой.

                                        в теории да, а на практике масса людей ещё предпочитает бумажные книги, пока они есть, надо делать и pdf
                                      • 0
                                        Мне кажется странным рассуждать об идеальной разметке в отрыве от задачи. Кому-то нужен PDF, а другим нет, ну и так далее.

                                        Если же вспоминать вообще о разных вариантах, ещё я бы добавил про разметку MediaWiki — внутренняя разметка для страниц Википедии.
                                        • 0
                                          В этом и состоит принцип семантической разметки с разделением содержания и оформления — она не зависит от того что нужно на выходе, это уже задача соответствующих стилевых файлов.
                                        • +1
                                          Несмотря на то что это стандарт и стандарт который развивается уже давно, там тоже есть недоделки, например я столкнулся что в библиографии не предусмотрен тег для url источника

                                          Все там есть. Просто в DocBook'e нужно именно сидеть и вдумчиво разбираться. Касательно ссылки — это не тег, а атрибут для biblioentry. Если говорить про DocBook 5.1. А для 4.5 можно какой нибудь ulink использовать. Вся прелесть в том, что схему можно полностью перекроить под себя, при необходимости. Особенно это касается 5.0 и 5.1, т.к. там перешли от DTD к RelaxNG схемам.
                                          А вообще, по сабжу — всерьез можно говорить только DITA и DocBook. Первая технология больше подходит для контекстных топиков, вторая — для больших книг. Впрочем, 5я версия DocBook сильно вильнула в сторону топико-ориентированности. Все остальное с точки зрения авторинга — так себе технологии.
                                          Что касается GUI — Oxygen наше все. Там и докбук, и дита из коробки — пиши да публикуй. А если ты еще и в XSLT волокешь, то вообще никаких проблем не будет все это кастомизировать под свои нужды. Вон, люди умудряются доки по стандартам ЕСПД/ЕСКД выпускать в докбуке. И нет там ничего секретного.
                                          • 0
                                            > Все там есть. Просто в DocBook'e нужно именно сидеть и вдумчиво разбираться. Касательно ссылки — это не тег, а атрибут для biblioentry.

                                            а можно ссылку, я на 5.0 смотрел, ща глянул в 5.1 — не нахожу такого атрибута, да и это не может быть атрибутом, это должен быть тэг
                                          • 0
                                            Ну, если прям тегом надо, такой вариант не подойдет? Собственно, непосредственно URL никогда в докбуке не указывался в качестве содержимого тега, только в качестве атрибута для link, ulink. А вот его отображение в публикуемом документе — это уже дело другое. Можно показывать в явном виде, можно в неявном.
                                            <biblioentry>
                                                 <citetitle pubwork="book">
                                                      <link xlink:href="http://....."></link>
                                                 </citetitle>
                                            </biblioentry>
                                            

                                            В biblioentry есть точно такой же, кстати, атрибут xlink:href.
                                            Немного промахнулся с ответом…
                                            • 0
                                              Вы похоже не понимаете о чём я говорю, костыль-то сделать можно, но это уже не семантическая разметка.
                                              Семантика такова, что у записи в библиографии есть свойства — название, издательство и т.д., для этих свойств есть соответствующие семантические теги, а для свойства «url источника» тэга нет.
                                            • +1
                                              Ну, вообще то понимаю. И если не ошибаюсь, вот то, о чем идет речь tdg.docbook.org/tdg/5.1/bibliosource.html Либо tdg.docbook.org/tdg/5.1/biblioid.html, в общем то, то же самое.
                                              Т.к. URL не является единственным возможным видом ресурса.
                                              Для URL конструкция будет иметь вид:
                                              ...
                                                 <bibliosource class="uri">
                                                    <link href="..."/>
                                                 </bibliosource>
                                              ...
                                              

                                              • 0
                                                Отлично! Похоже на то что нужно, видимо я пропустил сие, благодарю.

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