Основы работы с DocBook

Что мне писать ? HOWTO или mini-HOWTO?

LDP включает два набора HOWTO. Большие HOWTO всегда написаны в формате SGML (DocBook или LinuxDoc, но DocBook предпочтителен). HOWTO обычно более масштабны и длинее чем две или три печатных страницы. Mini-HOWTO меньше по размеру, могут быть опубликованы в формате SGML или HTML,и занимают две - три печатных страницы.

Непосредственное использование jade/openjade

Это "быстрый и грязный" путь, который должен работать независимо от того, какой дистрибутив вы используете.

1. Создайте базовую директорию где вы будете хранить все необходимое. Например: /usr/local/sgml. Далее по тексту мы будем называть её $_toolroot.

2. Установите Jade, DocBook DTD, и DSSSL, так чтобы базовой директорией всех их была $_toolroot (создав $_toolroot/jade-1.2.1, $_toolroot/dtd, $_toolroot/dssl)

3. Вам нужно установить переменную окружения SGML_CATALOG_FILES указывающую на каталоги которые находятся в $_toolroot. Вы можете сделать это с помощью следующей команды: $ENV{'SGML_CATALOG_FILES'} = “$_toolroot/dtd/docbook.cat;$_toolroot/dsssl/docbook/catalog;$_toolroot/jade-1.2.1/dsssl/catalog”

4. Теперь вы готовы к использованию Jade. Чтобы создать отдельные HTML файлы: $_toolroot/jade-1.2.1/jade/jade -t sgml -i html -d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml

5. Чтобы создать один большой HTML файл,добавьте -V nochunks в приведенную выше команду.

sgmltools

Вам понадобятся sgmltools версии 2.x для использования с DocBook. Так как все бэк-энд программы также сменились, вам придется забыть о программах типа sgml2xxx. А так как с большинством дистрибутивов поставляются sgml 1.x, вам придется удалить пакет sgml 1.x и установить CVS версию или версию 2.0. Чтобы получить последнюю версию CVS кода,вы можете использовать следующие команды.

CVSROOT=:pserver:cvs@cvs.sgmltools.org:/home/cvs
export CVSROOT
cvs login
cvs -z6 get sgmltools
   

Пароль для CVS - 'cvs'. Загрузив исходный код, вы можете использовать

./compile 
make
make install
   

чтобы установить sgmltools. Для Red Hat (или основанных на них) систем вы можете использовать команду rpmfind чтобы получить последнюю версию sgmltools. Эту программу можно найти по адресу http://www.rpmfind.net/. Убедитесь в том, что вы скачали именно sgmltools а не sgml-tools, т.к. последний - это sgmltools версии 1.0.9. Для систем базирующихся на Debian, используйте apt-get, чтобы получить нужный вам пакет:

# apt-get install sgmltools
   

Также как и в случае с RedHat, убедитесь, что скачали sgmltools а не sgml-tools.

Cygnus DocBook Tools

Эти утилиты поставляются с дистрибутивом Red Hat 6.2. Убедитесь,что установлены следующие пакеты:

• sgml-common

• docbook

• stylesheets

Последнии версии всегда доступны на сайте RedHat: http://www.redhat.com/support/errata/RHBA-2000022-01.html.

Загрузите/возьмите/утяните RPMки на вашу машину и установите как обычно (станьте root и дайте команду rpm -Uvh имя_файла). Установив соответвующие RPM пакеты вы можете использовать следующие команды, для визуализации DocBook:

db2html имя_файла
   

Визуализирует DocBook в HTML. Будет создана поддиректория с именем имя_файла (минус расширение .sgml), в которой будут размещены HTML файлы.

db2pdf имя_файла
   

Визуализирует DocBook в PDF файл.

Новые документы

Начать писать новое HOWTO с помощью LyX очень просто. Используйте команду меню File->New from template..., чтобы вызвать на экран список шаблонов. Выберите Templates на правой части экрана, затем выберите docbook_template.lyx в списке файлов. Нажмите OK и вы получите новый документ. Заполните такие вещи как заголовок,краткое описание и имя автора, и приступайте к написанию документа.

Существующие документы.

Если у вас уже есть LyX, TeX, или текстовый документ, вы можете импортировать его в LyX с помощью команды File->import. Импортировав файл, идите в Layout->Document... . В появившемся окне, под Style, выберите SGML (DocBook Article). Вас спросят хотите ли вы конвертировать весь текст, ответьте "Yes". Вам потребуется изменить большую часть тэгов, но это довольно простое дело: выделяйте текст и изменяйте стиль.Для многих Lyx функций существуют горячие клавиши, они помогут вам сделать это быстрее.

Экспорт документов в SGML

Написав документ или конвертировав его, сохраните его в формате LyX. Это позволит вам легко редактировать следующие версии. Затем идите в File->Export->as DocBook..., и файл будет экспортирован в DocBook.

Введение

Если у вас установлен один из новых дистрибутивов, у вас уже должен быть установлен PSGML для использования с Emacs. Чтобы проверить, запустите Emacs и взгляните на документацию по PSGML (C-h i m psgml).

Далее, мы будем считать, что у вас установлена новая версия PSGML для использования с новый версией GNU Emacs. Если это слишком краткие инструкции для вас, просмотрите бесплатную главу из книги Bob Ducharme's SGML CD book: http://www.snee.com/bob/sgmlfree/.

Обновление вашего .emacs для использования PSGML.

Если вы хотите, чтобы GNU Emacs входил в PSGML режим, когда вы открываете .sgml файл и был готов к редактированию SGML, убедитесь, что PSGML может найти DocBook DTD. Если ваш дистрибутив уже имеет поддержку PSGML для GNU Emacs,вам скорее всего ничего не придеться делать, чтобы заставить это работать как надо. Иначе, вам будет нужно установить переменную окружения, которая сообщит PSGML, где находится SGML catalog (список DTD).

Например:

bash$ export SGML_CATALOG_FILES=/usr/lib/sgml/catalog
   

Затем добавьте что нибудь в этом духе в ваш .emacs файл.

;; ******************************************************************* ;; set up psgml mode...
;; use psgml-mode instead of emacs native sgml-mode ;; (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
(setq auto-mode-alist (append (list '("\\.sgm$" . sgml-mode) '("\\.sgml$" . sgml-mode)) auto-mode-alist))
;; set some psgml variables (setq sgml-auto-activate-dtd t) (setq sgml-omittag-transparent t) (setq sgml-balanced-tag-edit t) (setq sgml-auto-insert-required-elements t) (setq sgml-live-element-indicator t) (setq sgml-indent-step nil)
;; create faces to assign to markup categories (make-face 'sgml-comment-face) (make-face 'sgml-start-tag-face) (make-face 'sgml-end-tag-face) (make-face 'sgml-entity-face) (make-face 'sgml-doctype-face) ; DOCTYPE data (make-face 'sgml-ignored-face) ; data ignored by PSGML (make-face 'sgml-ms-start-face) ; marked sections start (make-face 'sgml-ms-end-face) ; end of marked sections (make-face 'sgml-pi-face) ; processing instructions (make-face 'sgml-sgml-face) ; the SGML declaration (make-face 'sgml-shortref-face) ; short references
;; view a list of available colors with the emacs-lisp command: ;; ;; list-colors-display ;; ;; please assign your own groovy colors, because these are pretty bad (set-face-foreground 'sgml-comment-face "coral") ;(set-face-background 'sgml-comment-face "cornflowerblue") (set-face-foreground 'sgml-start-tag-face "slateblue") ;(set-face-background 'sgml-start-tag-face "cornflowerblue") (set-face-foreground 'sgml-end-tag-face "slateblue") ;(set-face-background 'sgml-end-tag-face "cornflowerblue") (set-face-foreground 'sgml-entity-face "lavender") ;(set-face-background 'sgml-entity-face "cornflowerblue") (set-face-foreground 'sgml-doctype-face "lavender") ;(set-face-background 'sgml-doctype-face "cornflowerblue") (set-face-foreground 'sgml-ignored-face "cornflowerblue") ;(set-face-background 'sgml-ignored-face "cornflowerblue") (set-face-foreground 'sgml-ms-start-face "coral") ;(set-face-background 'sgml-ms-start-face "cornflowerblue") (set-face-foreground 'sgml-ms-end-face "coral") ;(set-face-background 'sgml-ms-end-face "cornflowerblue") (set-face-foreground 'sgml-pi-face "coral") ;(set-face-background 'sgml-pi-face "cornflowerblue") (set-face-foreground 'sgml-sgml-face "coral") ;(set-face-background 'sgml-sgml-face "cornflowerblue") (set-face-foreground 'sgml-shortref-face "coral") ;(set-face-background 'sgml-shortref-face "cornflowerblue")
;; assign faces to markup categories (setq sgml-markup-faces '((comment . sgml-comment-face) (start-tag . sgml-start-tag-face) (end-tag . sgml-end-tag-face) (entity . sgml-entity-face) (doctype . sgml-doctype-face) (ignored . sgml-ignored-face) (ms-start . sgml-ms-start-face) (ms-end . sgml-ms-end-face) (pi . sgml-pi-face) (sgml . sgml-sgml-face) (shortref . sgml-shortref-face)))
;; tell PSGML to pay attention to face settings (setq sgml-set-face t)
;; ...done setting up psgml-mode. ;; *******************************************************************
   

Затем перезапустите Emacs.

SGML тест

Попробуйте следующий тест. Создайте новый файл, например /tmp/test.sgml,и введите следующее.

 
<!DOCTYPE test [ 
<!ELEMENT test - - (#PCDATA)> 
]> 
   

Введите C-c C-p.Если Emacs использует ваше DTD, вы увидите Parsing prolog...done в мини-буфере. Попробуйте нажать C-c C-e RETURN, чтобы вставить элемент <test>. Если все работает правильно вы увидите следующее:

 
<!DOCTYPE test [ 
<!ELEMENT test - - (#PCDATA)> 
]> 
<test></test> 
   

Написание нового HOWTO в формате DocBook

Создайте новый файл для вашего HOWTO и введите следующее:

 
<!DOCTYPE ARTICLE PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> 
   

Введите C-c C-p и задержите дыхание :) . Если все прошло как планировалось, то через несколько секунд вы увидите Parsing prolog...done в мини-буфере.

Теперь введите C-c C-e RETURN, чтобы вставить <article> элемент и продолжайте написание вашего HOWTO.

Краткий справочник PSGML режима Emacs

Смотрите "Nik Clayton's primer for FreeBSD documentation": http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html