Ключевым фактором для по-настоящему массового продукта является простота использования, функциональность и стоимость. Как принципиальный сторонник бесплатного ПО я являюсь давним пользователем технологии АsciiDoc и считаю, что на сегодняшний день она располагает самым большим потенциалом.
Функциональность Markdown и даже reStructuredText ограничена, а порог входа для DocBook и DITA достаточно высок, чтобы поставить на них крест как на массовом продукте. Нужна золотая середина между функциональностью и простотой. Система документации должна быть одинаково удобна на всех этапах жизненного цикла программного продукта: проектирование, реализация, сопровождение. В идеале она должна прекрасно применяться и вне задач создания программных продуктов.
Основной проблемой, с которой я сталкивался при подготовке документации в АsciiDoc – это отсутствие полноценного конвертера в docx (MS Word) или odt (OpenOffice/LibreOffice) для сдачи документации заказчику в этих его любимых форматах. Также эти форматы очень удобны для сравнения выходных документов.
Об этом я написал здесь, задумался, и попробовал решить задачу.
Мне кажется, первое (возможно даже уже и не первое) приближение получилось адекватно. Проект обеспечивает формирование так называемого plain Open Document формата (Open Document в формате xml, имеет расширение fodt). Проект легко расширяем. Позволяет изменять форматирования на уровне стилей, препроцессинга документа, а также на уровне наследования классов, отвечающих за выставление тех или иных свойств. Libre Office SDK обеспечивает функции конвертирования полученного файла в форматы docx (MS Word), pdf, odt (обычный Open Document формат). Пример конвертации также приведен в проекте.
Есть ограничения, связанные с принципиальным различием форматов текстовых процессоров и иерархических систем разметки типа Asciidoc, Docbook, DITA, html и т.п. Но в большинстве случаев они не должны носить критический характер. Случаи, когда в списке нужно размещать таблицу, внутри которой другой список, внутри которого еще таблицу, внутри которой исходный код с примером — достаточно редки.
Из проблем, которые также необходимо решить по развитию технологии АsciiDoc, вижу следующие:
- Нужен редактор, который поддерживает работу с таблицами, как с сеткой. Для Docbook и DITA таких редакторов много (например, Oxygen XML, XMLmind). Для Asciidoc всё ограничивается подсветкой синтаксиса. Конечно, поменять столбцы местами в тексте быстрее, но только если вы используете Vim. Рекомендовать это делать никак не могу
- Заказчик обычно рецензирует выходные документы (тот же odt или docx). Необходима возможность быстро находить исходный документ и место в нём, куда должны быть внесены правки.
- Поскольку Asciidoc — это язык текстовой разметки, то нужен статический анализатор кода («линтер»). Например, один перенос в Asciidoc означает продолжение абзаца. Однако в реальности в документации лучше не допускать переносов, т.к. это ведёт к ошибкам (например, забыли поставить два переноса строк перед списком и Asciidoc считает, что весь список — один большой абзац, а статический анализатор бы запретил такую конструкцию сразу ещё до сборки выходной документации).
Буду признателен всем, кто протестирует конвертер и выскажет свои замечания и предложения.
