Это мой конспект для выступления на семинаре, проводившемся нашей LUG. См. также презентацию к докладу.
Глава 1. Актуальность, цели и задачи
Вобще говоря, разработка технической документации — это достаточно обширная область. Техническая документация, по идее, прилагается чуть ли не ко всему подряд — инструкция к чайнику, проектная документация к мосту, мануал к программе. Конечно, в разных случаях аудитория у документов разная, разные и цели подготовки документации, а потому используются разные подходы. Я буду говорить в основном о подготовке документации к программным продуктам, хотя практически всё это применимо и к разработке других видов документации (хотя, вероятно, предлагаемой методики недостаточно).
Целью разработки документации к программному продукту является предоставление пользователю достаточно полной информации о продукте в том виде, в котором это удобно пользователю. Отсюда вытекают следующие задачи:
- Полная документация к большому продукту будет большой. Поэтому необходимо обеспечить автору документации простые и удобные средства для её подготовки, стараться не тратить время автора на посторонние вещи типа оформления этой документации или тонкостей xml-разметки;
- Пользователи у продукта, возможно, будут разные, а потому документацию необходимо предоставлять в разных форматах; самые популярные форматы — PDF, HTML и CHM;
- Так как пользователи разные, разной должна быть комплектация документации. В одних случаях нужно только руководство пользователя, в других — только руководство программиста, в третьих — и то, и другое.
Ниже приводится обзор различных технологий, используемых для подготовки технической документации, с оценкой их соответствия поставленным задачам, а затем предлагается собственная методика использования существующих технологий (с использованием свободного ПО).
Глава 2. Обзор технологий
Я начну с краткого обзора технологий, которые применяются для подготовки технической документации. Наиболее известны следующие технологии:
- MS Word и подобные системы;
Системы «единого источника»:
- Help&Manual и аналоги;
- DocBook;
- DITA;
- и другие.
Рассмотрим некоторые из этих технологий несколько подробнее.
Глава 3. Help&Manual
Главным плюсом этой системы часто является то, что она уже внедрена и работает. Также несомненный плюс — это система единого источника, т.е. из одного текста можно получить документ в разных форматах. Особенность этой программы и аналогов: это WISIWYG-системы. Насчёт того, является ли эта особенность плюсом или минусом, по сей день не утихают споры. Плюс WISIWYG-технологий очевиден, он заложен в названии: можно сразу видеть, как будет выглядеть текст в результате. К минусам WISIWYG относят следующие пункты:
- Есть такое высказывание: если система предоставляет возможность что-нибудь настраивать, она, фактически, заставляет вас это настраивать. В данном случае это относится к тому, что автор тратит время не только на написание текста, но и на его оформление, хотя это, по идее, не его задача.
- Такие системы склонны порождать совершенно дикую и нечитаемую разметку при конвертировании в HTML, LaTeX и другие подобные форматы. Например, легко можно получить разметку наподобие:
разметка. Это сказывается, как только появляется необходимость поправить такую разметку «руками». - При работе в таких системах люди склонны использовать не логическую, а физическую разметку (например, помечать кусок текста жирным шрифтом, вместо того чтобы отмечать этот текст как заголовок). Что интересно, большинство таких систем предоставляют возможность использования логической разметки, иногда даже удобную, но по каким-то психологическим соображениям люди не склонны её использовать. Это приводит к проблемам при изменении общего стиля оформления документа, а также зачастую при конвертировании в другие форматы.
В связи с послед
Изготовление презентаций из Asciidoc с помощью Beamer
В одном из недавних постов я говорил, что из Asciidoc-разметки можно сделать много всяких разных выходных форматов. Среди всего прочего, можно делать и презентации. Не слишком «навороченные», правда, но для многих случаев этого хватает.
Схема такая:
Сначала из Asciidoc делаем DocBook. Это можно сделать командой вида asciidoc -b docbook input.txt. Только вот по такой команде получится файл в формате DocBook 4.5, а моя XSL-таблица понимает только DocBook 5.0+. Поэтому берём конфигурационные файлы asciidoc для изготовления DocBook 5.0, например, отсюда, и даём команду вида
asciidoc -b topic input.txt
Получается файл input.xml. Теперь берём XSL-таблицу, преобразующую DocBook 5.0+ в TeX-овский исходник, например, здесь (эта таблица заведомо не полная, но для моих задач хватает; кому не хватит — добавляйте туда свои шаблоны :)), и даём команду вида
xsltproc beamer.xsl input.xml > presentation.tex
Ну а теперь компилируем этот исходник командой вида
xelatex presentation.tex
(может понадобиться запустить эту команду несколько раз, чтобы проставились все ссылки и т.п).
Таким образом сделана, в частности, упомянутая в одном из предыдущих постов презентация (из вот такого исходника).
Автор: Portnov
Все форматы документа из одного исходника: asciidoc сотоварищи
Я уже давно использую asciidoc для написания сколько-нибудь больших текстов. Почти все статьи в этом блоге, включая эту, подготовлены с помощью Asciidoc.
Asciidoc — это транслятор простейшего языка разметки текста в любой другой язык разметки. Разметка asciidoc очень простая, практически вы пишете plain text, только выделяете заголовки знаками = в начале строки, полужирный текст — *звёздочками*, курсив — 'кавычками', итд. Абзацы разделяются пустой строкой. А на выходе может быть всё что угодно, это зависит от так называемого backend-a, поведение которого описывается в конфиге. В поставке доступны бэкенды для xhtml, html4 и docbook. Docbook, в свою очередь, теоретически можно отконвертировать во что угодно.
На днях я готовил доклад для одного семинара, и мне хотелось получить его сразу в нескольких форматах: html и pdf, как минимум. И ещё бы надо к нему презентацию… И хорошо бы план доклада. И, конечно, не хочется для каждого формата готовить текст.
HTML (точнее, xhtml 1.1) делается с помощью asciidoc. Все остальные форматы, теоретически, можно получить из docbook, который можно получить с помощью asciidoc. Только вот на практике мне так и не удалось за полдня заставить ни один из конверторов docbook нормально работать с русскими буквами. Также в комплекте asciidoc есть экспериментальный бэкенд latex, но он как-то странно работает с кусками кода, которые мне нужно поместить в tex-файл в неизменном виде (речь идёт о формулах): половина формул куда-то проглатываются.
Кроме всего прочего, мне нужно в доклад включать фрагменты диалога с консольными программами (в данном случае — с maxima и с R). Так как в ходе подготовки доклада что-то может меняться, неохота каждый раз делать copy-paste из консоли. Надо бы, чтобы в исходник вставлять только запросы к программам — а вызываются программы и вставляется вывод пусть автоматически.
В общем, в итоге я написал скрипт lmaxima.py, который делает следующее: читает входной файл, и копирует его в выходной. Если встречает строку вида «program>> команды», то по пайпу передаёт эти команды указанной программе, и её ответ вставляет в выходной файл. Если встречает строку вида «program|tex>> команды» — то указанные команды оборачивает в функцию tex(). Таким образом, lmaxima.py работает как препроцессор для asciidoc. Одна из тонкостей состоит в том, как вставлять в документ формулы, которые выдаёт maxima. Если выводить надо в html, то формулы пропускаются через tex, и в выходной файл вставляется картинка (строка image:chtoto.png[]). Если же выводить надо в pdf, то lmaxima указывается ключ -i, и в выходной файл вставляется непосредственно tex-код.
Т.к. latex-бэкенд к asciidoc работает странно, пришлось писать свой конвертер из подмножества asciidoc-разметки в tex (благо, основная часть разметки asciidoc очень простая). Называется он у меня vsml.py. Заодно vsml.py умеет следующее:
С ключом -c — добавляет в документ оглавление (latex-овская команда tableofcontents),
с ключом -p — «выдирает» из исходника только заголовки, и составляет содержание документа (план доклада, в моём случае),
с ключом -b — создаёт исходник для презентации (класс beamer); в презентацию попадают заголовки и картинки.
vsml понимает ещё и некоторые «надстройки» над синтаксисом asciidoc. Так, с помощью строчек «//{» и «//}» (asciidoc их воспринимает как комментарии) можно создавать вложенные куски текста. По умолчанию они выводятся как обычно, однако vsml.py можно задать ключ -l с числовым параметром, и он будет выводить только текст с «уровнем вложенности» не больше заданного; это позволяет оформлять более и менее необязательные части текста, и из одного исходника создавать документы разной степени подробности. А с помощью строчки вида «//.Тут заголовок» можно создавать (под)заголовки, которые не будут видны нигде, кроме презентации.
Конечно, вручную писать все эти команды с ключами каждый раз долго, поэтому я написал небольшой Makefile:
all: report.pdf report.html presentation.pdf plan.pdf
clean:
rm report.pdf report.html presentation.pdf
rm presentation.tex report.asciidoc report.vsml
rm plan.tex plan.pdf
plan.pdf: plan.tex
pdflatex $<
plan.tex: report.vsml
vsml.py -p < $< > $@
report.pdf: report.tex
pdflatex $<
presentation.pdf: presentation.tex
pdflatex $<
report.html: r eport.asciidoc
asciidoc $<
report.asciidoc: math-report
lmaxima.py $< $@
presentation.tex: report.vsml
vsml.py -b < $< > $@
report.tex: report.vsml
vsml.py < $< > $@
report.vsml: math-report
lmaxima.py -i $< $@
PS: мне тут подсказывают: добавь ещё festival, оно за тебя и доклад прочитает 🙂
Автор: Portnov