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

1. Нужен редактор, который поддерживает работу с таблицами, как с сеткой. Для Docbook и DITA таких редакторов много (например, Oxygen XML, XMLmind). Для Asciidoc всё ограничивается подсветкой синтаксиса. Конечно, поменять столбцы местами в тексте быстрее, но только если вы используете Vim. Рекомендовать это делать никак не могу
2. Заказчик обычно рецензирует выходные документы (тот же odt или docx). Необходима возможность быстро находить исходный документ и место в нём, куда должны быть внесены правки.
3. Поскольку Asciidoc — это язык текстовой разметки, то нужен статический анализатор кода («линтер»). Например, один перенос в Asciidoc означает продолжение абзаца. Однако в реальности в документации лучше не допускать переносов, т.к. это ведёт к ошибкам (например, забыли поставить два переноса строк перед списком и Asciidoc считает, что весь список — один большой абзац, а статический анализатор бы запретил такую конструкцию сразу ещё до сборки выходной документации).

Буду признателен всем, кто протестирует конвертер и выскажет свои замечания и предложения.