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

в 15:20, , рубрики: asciidoc, docbook, doconce, latex, markdown, open source, XML, xslt, документирование, Семантика, семантическая разметка

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

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

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

Автор: worldmind

Источник

Поделиться

* - обязательные к заполнению поля