J.4. Написание документации

Форматы SGML и DocBook не страдают от обилия средств их редактирования с открытым исходным кодом. Чаще всего для написания документации используется редактор Emacs/XEmacs в подходящем режиме. В некоторых системах эти редакторы устанавливаются при типичной полной установке.

J.4.1. Emacs/PSGML

Режим PSGML — наиболее популярный и мощный режим редактирования документов SGML. При правильной настройке в Emacs он позволяет вставлять теги и проверять корректность разметки. Его также можно использовать для редактирования HTML. Загружаемые файлы, инструкции по установке и подробную документацию вы можете найти на сайте PSGML.

Необходимо отметить важный момент относительно PSGML: его автор предполагал, что вашим основным каталогом с DTD SGML будет /usr/local/lib/sgml. Если же у вас, как и в приводимых ранее примерах, это каталог /usr/local/share/sgml, вам нужно дополнительно скорректировать предопределённый путь, либо воспользовавшись переменной окружения SGML_CATALOG_FILES, либо настроив соответственно вашу инсталляцию PSGML (как это сделать, можно узнать из его описания).

Поместите следующие строки в файл ~/.emacs (изменив пути на подходящие для вашей системы):

; ********** для режима SGML (psgml)

(setq sgml-omittag t)
(setq sgml-shorttag t)
(setq sgml-minimize-attributes nil)
(setq sgml-always-quote-attributes t)
(setq sgml-indent-step 1)
(setq sgml-indent-data t)
(setq sgml-parent-document nil)
(setq sgml-exposed-tags nil)
(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))

(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )

и добавьте в тот же файл запись для SGML в существующее определение auto-mode-alist:

(setq
  auto-mode-alist
  '(("\\.sgml$" . sgml-mode)
   ))

Используя PSGML, вы можете найти удобным вставлять подходящие объявления DOCTYPE в отдельные файлы книги, когда вы редактируете их. Например, редактируя текущий текст, который относится к главе приложений (appendix), вы можете обозначить документ как экземпляр документа «appendix», добавив в него следующую первую строку:

<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN">

Это будет означать, что всё и вся, читающее этот SGML, сможет прочитать его правильно, и его корректность можно будет проверить командой nsgmls -s docguide.sgml. (Но вы должны будете убрать эту строку, прежде чем собирать весь комплект документации.)

J.4.2. Другие режимы Emacs

GNU Emacs предлагает другой режим SGML, не такой мощный как PSGML, но при этом менее запутанный и тяжеловесный. Кроме того, в нём реализована подсветка синтаксиса (привязка шрифтов), которая бывает весьма полезна. Пример конфигурации для этого режима содержится в src/tools/editors/emacs.samples.

Норм Уолш предложил главный режим специально для DocBook, в котором также реализовал привязку шрифтов и ряд возможностей для оптимизации ввода текста.