05.10.2017 15:20
worldmind 47 4800 Источник
Писал комментарий к статье и понял, что надо выносить в отдельный пост.
Как многие отмечают там в комментариях статья отстой, человек не разбирается и смешал всё в кучу, попробую поделиться своими выводами от использования разных разметок.

Сразу скажу, что тема удобного формата меня интересовала всегда, но не хватало времени заняться вплотную, был случай когда по работе было нужно — писали пользовательскую документацию и там все проблемы бинарных форматов всплыли — неудобно отслеживать изменения, неудобно совместно работать, много копипаста (который был бы не нужен если бы была возможность делать 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, также неплохо чтобы формулы он умел не только отрисовывать, но и вычислять подставляя результат и так далее.

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

Комментарии (47)


  1. vintage
    05.10.2017 19:05
    #10456252
    +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>


    1. worldmind Автор
      05.10.2017 19:10
      #10456260

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


      1. vintage
        05.10.2017 19:35
        #10456312

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


        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

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


        1. worldmind Автор
          05.10.2017 21:17
          #10456552

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


          1. vintage
            05.10.2017 22:19
            #10456734

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


            --
| 
| *Колонка 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. worldmind Автор
              05.10.2017 22:27
              #10456754
              +1

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


              1. vintage
                05.10.2017 22:35
                #10456778

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


            1. bopoh13
              06.10.2017 11:28
              #10457762

              Чем не понравился MD-синтаксис (c любым количеством пробелов и тире)?
              |          |*Колонка 1*|*Колонка 2*|*Колонка 3*
              |----------|:-|--|-:
              |*Строка 1*|Значение 1х1|Значение 1х2|Значение 1х3
              |*Строка 2*|Значение 2х1|Значение 2х2|Значение 2х3


              1. worldmind Автор
                06.10.2017 11:32
                #10457784

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


              1. vintage
                06.10.2017 11:55
                #10457874
                +1

                |          |*Колонка 1*|*Колонка 2*|*Колонка 3*
|----------|:-|--|-:
|*Строка 1*|Значение 1|Значение 2|Значение в ячейке по координатам 1х3|Ещё одно значение 4|И опять 25
|*Строка 2*|Значение в ячейке по координатам 2x1|2|3|4|Значение 5

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


                1. bopoh13
                  06.10.2017 12:03
                  #10457920
                  -1

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


                  1. vintage
                    06.10.2017 12:24
                    #10457994
                    +1

                    И что с того?


                    1. bopoh13
                      06.10.2017 15:25
                      #10458738
                      -1

                      Я не запутаюсь считая разделители.


                      1. worldmind Автор
                        06.10.2017 16:34
                        #10458970
                        +1

                        Зачем делать дурную работу когда можно сделать по человечески?


                        1. bopoh13
                          06.10.2017 16:36
                          #10458974

                          Конечно, лучше использовать специализированную программу. Считать в уме — дурная работа? Видимо, я давно «отстал от жизни».


                          1. worldmind Автор
                            06.10.2017 16:41
                            #10458984
                            +1

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


        1. Arastas
          05.10.2017 22:34
          #10456774

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


          1. worldmind Автор
            05.10.2017 23:18
            #10456894

            Касательно нот вспоминается LilyPond, тоже разметка.


  1. pantlmn
    05.10.2017 22:52
    #10456816

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

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


    1. SirEdvin
      05.10.2017 23:09
      #10456872

      А зачем вам из LaTeX собирать epub? Мне кажется, он многое не потянет, а если нужен просто размер, можно попробовать собрать а5 книжку.


      1. worldmind Автор
        05.10.2017 23:16
        #10456890

        Я исследований не проводил, но насколько понял pdf на всяких девайсах хуже масштабируется, даже если делать несколько вариантов размера (делаю A4, A5, A6).
        Но точно мне говорили что fb2 шустрее работает, товарищ просил сделать именно его т.к. остальное у него тормозило на телефоне.


        1. SirEdvin
          06.10.2017 09:46
          #10457462

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


          1. worldmind Автор
            06.10.2017 09:52
            #10457478

            Об этом конвертер должен думать — сделает и картинки если будет нужно, да и формулы не всегда есть.


          1. windgrace
            06.10.2017 11:29
            #10457766

            По идее (это тут ключевое слово), формулы в epub можно включать в виде MathML. Поддерживается только подмножество MathML, но его хватит для большинства формул. Правда, есть один небольшой нюанс — читалки далеко не всегда поддерживают эту фичу. А если я читаю epub с компа, то я с тем же успехом могу прочитать и pdf.


      1. pantlmn
        05.10.2017 23:29
        #10456924
        +1

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


      1. worldmind Автор
        06.10.2017 09:45
        #10457456

        Вобщем-то как правильно заметили — не надо за пользователя решать какой ему формат нужен, надо дать ему выбор.


  1. nuald
    06.10.2017 01:49
    #10457132

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


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


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

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


    1. neit_kas
      06.10.2017 09:23
      #10457410

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


      1. nuald
        06.10.2017 09:46
        #10457460

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


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


    1. worldmind Автор
      06.10.2017 09:36
      #10457438

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


      1. nuald
        06.10.2017 10:11
        #10457518

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


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

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


        1. worldmind Автор
          06.10.2017 10:43
          #10457616

          Так речь не про типографику, а про семантику. Докбук ничего про типографику не знает, это голая семантика, но семантика достаточно полная и универсальная и поэтому её можно успешно конвертировать в любое представление, в том числе и типографическое.


        1. worldmind Автор
          06.10.2017 16:36
          #10458976

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

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


  1. shakespear
    06.10.2017 14:47
    #10458624

    Добавлю про AsciiDoc. У себя в работе применяю ее как систему генерации документов для программ (хелп + инструкция пользователя). Для инструкций используем бекэнд AsciiDoc в DocBook + FOP, на выходе вполне сносный pdf с оглавлением и всем прочим.
    Да, кроме официальных тулсетов есть реализация AsciiDoc на Ruby: asciidoctor. Со сложными документами там пока неважно (приемлемый pdf получить можно, но гибкости в настройке не хватает), но гораздо проще в установке и использовании для простых целей (небольшие статьи, одностраничники, простые pdf)


    1. worldmind Автор
      06.10.2017 16:37
      #10458978

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


      1. shakespear
        06.10.2017 18:59
        #10459522
        +1

        Это было или слишком давно (хотя я, вроде, на AsciiDoc уже много лет) или Вы что — то путаете. Прекрасные ссылки на что угодно, единственное для «что угодно» нужно делать именованный якорь.


        1. worldmind Автор
          06.10.2017 22:43
          #10460016

          Да, возможно проглядел, глянул доку, вроде много чего есть, надо будет ещё раз глянуть при случае.


        1. worldmind Автор
          06.10.2017 22:47
          #10460020

          Но чего-то я там не находил, может это был тег для эпиграфа.


      1. shakespear
        06.10.2017 19:04
        #10459550
        +1

        Хабр слишком быстро закрывает возможность редактировать… Пример синтаксиса на на оф сайте.


  1. FurryCat
    07.10.2017 10:30
    #10460462
    +1

    Добавлю свои 5 копеек.
    Мне очень понравился reStructuredText.
    Идея очень близка к markdown, тоже очень хорошо читается. По сравнению с markdown предоставляет больше возможностей. Из него легко делается latex, odt, html.

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

    Я бы сказал так: штука может быть удобна для внутреннего использования.


    1. worldmind Автор
      07.10.2017 11:34
      #10460574

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


    1. pantlmn
      07.10.2017 12:31
      #10460622

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



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


      1. FurryCat
        07.10.2017 13:00
        #10460664

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


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


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

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


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


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


  1. eugenero
    07.10.2017 12:44
    #10460638
    +1

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

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


    1. worldmind Автор
      07.10.2017 14:13
      #10460742

      > Мне кажется, что жёстким форматам вёрстки, заточенным для печати, пора на покой.

      в теории да, а на практике масса людей ещё предпочитает бумажные книги, пока они есть, надо делать и pdf


  1. nzeemin
    07.10.2017 17:29
    #10460976

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

    Если же вспоминать вообще о разных вариантах, ещё я бы добавил про разметку MediaWiki — внутренняя разметка для страниц Википедии.


    1. worldmind Автор
      07.10.2017 19:29
      #10461082

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