Искусство программирования для Unix - Эрик Реймонд

Я сам написал инструмент для troff-DocBook преобразования, поскольку не находил другого, который выполнял бы такую работу с приемлемым качеством. Программа называется doclifter, <http://www.catb.org/~esr/doclifter/>. Она транслирует либо в SGML, либо в XML DocBook из макросов man(7), mdoc(7), ms(7) или me(7). Подробности описаны в документации.

18.5.5. Инструменты редактирования

К середине 2003 года отсутствовал один компонент — хорошая программа с открытым исходным кодом для редактирования структуры SGML/XML-документов.

LyX (<http://www.lyx.org/>) представляет собой текстовый процессор с графическим пользовательским интерфейсом, в котором для печати используется LATEX, а также поддерживается структурное редактирование LATEX-разметки. Существует LATEX-пакет, который генерирует DocBook, а также how-to-документ <http://bgu.chez.tiscali.fr/doc/db4lyx/>, описывающий методику написания SGML и XML в LyX GUI.

GNU TeXMacs <http://www.math.u-psud.fr/~anh/TeXmacs/TeXmacs.html> — проект, направленный на создание хорошего редактора для технических и математических материалов, включая отображаемые формулы. Версия 1.0 была выпущена в апреле 2002 года. Разработчики планируют в будущем включить поддержку XML, но в настоящее время ее пока нет.

Большинство пользователей до сих пор редактируют DocBook-теги вручную, используя vi или emacs.

18.5.6. Связанные стандарты и практические приемы

Для редактирования и форматирования DocBook-разметки инструменты объединяются. Однако сам по себе формат DocBook является средством, а не целью. Кроме DocBook необходимы другие стандарты для достижения поставленной цели — базы данных документации с возможностью поиска. Существует два больших вопроса: каталогизация документов и метаданные.

Непосредственно на достижение данной цели направлен проект ScrollKeeper <http://scrollkeeper.sourceforge.net/>. Данный проект предоставляет набор сценариев, которые могут использоваться в правилах инсталляции и деинсталляции пакетов для регистрации и удаления их документации.

Программа ScrollKeeper использует открытый формат метаданных (Open Metadata Format) <http://www.ibiblio.org/osrt/omf/>. Данный формат является стандартом для индексирования документации по программам с открытым исходным кодом, аналогичный библиотечной карточно-каталоговой системе. Идея заключается в поддержке развитых средств поиска, в которых используются карточно-каталоговые метаданные, а также исходные тексты документации.

18.5.7. SGML

В предыдущих разделах умышленно опускалась большая часть истории развития формата DocBook. Язык XML имеет "старшего брата", SGML (Standard Generalized Markup Language — стандартный обобщенный язык разметки).

До середины 2002 года любая дискуссия о DocBook была бы неполной без длинного экскурса в SGML, объяснения различий между SGML и XML, а также подробного описания инструментальной связки SGML DocBook. Теперь все значительно проще. Инструментальная связка XML DocBook доступна в виде открытого исходного кода, работает так же, как работала связка SGML, и является более простой в использовании.

18.5.8. Справочные ресурсы по XML-DocBook

Одним из факторов, который затрудняет изучение DocBook, является то, что сайты, связанные с данной темой, часто перегружают новичков длинными списками W3C-стандартов, массивными упражнениями по SGML-идеологии и абстрактной терминологией. Хорошее общее введение представляет собой книга "XML in a Nutshell" [32].

Книга Нормана Уолша (Norman Walsh) "DocBook: The Definitive Guide" доступна в печатном виде <http://www.oreilly.com/catalog/docbook/> и в Web — <http://www.docbook.org/tdg/en/html/docbook.html>. Книга представляет собой действительно полный справочник, но в качестве вводного курса или учебного пособия неудобна. Вместо нее рекомендуются материалы, перечисленные ниже.

Написание документов с помощью DocBook (Writing Documents Using DocBook) <http://xml.Web.cern.ch/XML/goossens/dbatcern/> — превосходное учебное пособие.

Существует также одинаково полезный список часто задаваемых вопросов (DocBook FAQ), <http://www.dpawson.co.uk/docbook/> с большим количеством материалов по форматированию HTML-вывода. Кроме того, функционирует DocBook-форум (DocBookwiki) <http://docbook.org/wiki/moin.cgi>.

Наконец, в документе "The XML Cover Pages" <http://xml.coverpages.org/> представлены описания XML-стандартов.

18.6. Лучшие практические приемы написания Unix-документации

Рекомендацию, данную в начале главы, можно рассмотреть с противоположной точки зрения. Создавая документацию для пользователей внутри Unix-культуры, не следует "оглуплять" ее. Автор документации, написанной для идиотов, сам будет "списан со счетов" как идиот. "Оглупление" документации резко отличается от создания доступной документации. В первом случае автор документации ленив и опускает важные сведения, тогда как во втором требуется глубокое осмысление и безжалостное редактирование.

Не следует, однако, полагать, что объем является ошибкой с точки зрения качества. И что особенно важно — никогда не следует опускать функциональные детали, опасаясь, что они могут запутать читателя. Не стоит также опускать предупреждения об имеющихся проблемах, чтобы продукт не выглядел плохо. Именно неожиданные проблемы, а не проблемы, которые разработчик признает открыто, будут стоить ему доверия и пользователей.

Пытайтесь найти золотую середину при подаче информации. Слишком малая насыщенность так же неудачна, как и слишком большая. Расчетливо используйте снимки с экранов; часто они несут мало информации, выходящей за рамки восприятия пользовательского интерфейса, и никогда полностью не заменят хорошего текстового описания.

Если разрабатываемый проект имеет значительные размеры, следует, вероятно, поставлять документацию в трех видах: man-страницы в качестве справочного материала, учебный материал, а также список часто задаваемых вопросов (Frequently Asked Questions — FAQ). Также следует создать Web-сайт, который будет служить центральной точкой распространения продукта (основные принципы взаимодействия с другими разработчиками изложены в главе 19).

Большие man-страницы несколько раздражают пользователей; навигация в них может быть затруднена. Если man-страницы получаются большими, следует рассмотреть возможность написания справочного руководства, а в man-страницах предоставить краткое обобщение и указатели на справочный материал, а также подробности вызова программы (или программ).

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

man-страницы должны быть авторитетными справочниками в традиционном Unix-стиле для обычной Unix-аудитории. Учебные пособия должны быть документацией в развернутой форме для нетехнических пользователей. FAQ-списки должны быть развивающимися ресурсами, которые растут по мере того, как группа поддержки программы выясняет часто задаваемые вопросы и ответы на них.

Существуют более специфические привычки, которые необходимо развить современному разработчику.

1. Поддержка главных документов в XML-DocBook. Даже тап-страницы могут быть документами DocBook RefEntry. Существует очень хорошее методическое руководство (HOWTO) <http://www.linux.doc.org/HOWTO/mini/Man-Page.html> по созданию man-страниц, в котором описана общая организация, ожидаемая пользователями.

2. Поставка документации с главными XML-файлами. На случай, если системы пользователей не имеют xmlto(1), поставляйте исходные тексты troff, которые можно получить, выполнив команду xmlto man над главными документами. Процедура установки дистрибутива должна устанавливать их обычным способом, однако следует направить пользователей к XML-файлам, если они хотят создавать или редактировать документацию.

3. Создание ScrollKeeper-совместимого инсталляционного пакета проекта.

4. Создание XHTML-документов из главных документов (с помощью команды xmlto xhtml) и предоставление к ним доступа с Web-страницы проекта.

Независимо от того используется ли в качестве главного формата XML-DocBook, необходимо найти способ конвертирования документации проекта в HTML. Независимо от того, как поставляется разрабатываемое программное обеспечение — как открытый исходный код или как частная программа, — растет вероятность того, что пользователи найдут ее посредством Web. Непосредственный эффект от размещения документации в Web-среде заключается в том, что это упрощает ее чтение и изучение для потенциальных пользователей и клиентов, знающих о существовании программы. Кроме того, возникает косвенный эффект — повышается вероятность появления программы в результатах Web-поиска.