Искусство программирования для Unix

GNU TeXMacs — проект, направленный на создание хорошего редактора для технических и математических материалов, включая отображаемые формулы. Версия 1.0 была выпущена в апреле 2002 года. Разработчики планируют в будущем включить поддержку XML, но в настоящее время ее пока нет.

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

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

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

Непосредственно на достижение данной цели направлен проект ScrollKeeper . Данный проект предоставляет набор сценариев, которые могут использоваться в правилах инсталляции и деинсталляции пакетов для регистрации и удаления их документации.

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

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" доступна в печатном виде и в Web — . Книга представляет собой действительно полный справочник, но в качестве вводного курса или учебного пособия неудобна. Вместо нее рекомендуются материалы, перечисленные ниже.

Написание документов с помощью DocBook (Writing Documents Using DocBook) — превосходное учебное пособие.

Существует также одинаково полезный список часто задаваемых вопросов (DocBook FAQ), с большим количеством материалов по форматированию HTML-вывода. Кроме того, функционирует ОосВоок-форум (DocBookwiki) .

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

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

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

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