Эта секция рассказывает о новом методе написания LDP документации, используя DocBook 3.1 DTD. Мы расскажем о том как получить,установить и использовать утилиты, а также о тэгах DocBook. Так как существует более 300 DocBook тэгов, мы естественно не сможем описать все их здесь. По настоящему заинтересованные читатели могут зайти на http://www.docbook.org для получения более подробной информации.
Если вы новичок в LDP и хотите взять одно из брошенных HOWTO или написать новый HOWTO/mini-HOWTO документ, то вам необходимо связаться с координатором HOWTO ldp-discuss@lists.linuxdoc.org. Это необходимо, чтобы координатор знал,кто работает над данной документацией. Также заметьте, что все HOWTO должны быть в SGML формате, с использованием DocBook 3.1 DTD. Если это mini-HOWTO, то вы можете использовать как SGML так и HTML форматы, но только SGML-форматированные документы будут включены в печатные версии HOWTO.
LDP включает два набора HOWTO. Большие HOWTO всегда написаны в формате SGML (DocBook или LinuxDoc, но DocBook предпочтителен). HOWTO обычно более масштабны и длинее чем две или три печатных страницы. Mini-HOWTO меньше по размеру, могут быть опубликованы в формате SGML или HTML,и занимают две - три печатных страницы.
Если вы хотите принять участие в работе LDP, то существует несколько листов рассылки, на которые вы можете подписаться. Первый - это ldp-discuss@lists.linuxdoc.org, это главная дискуссионная группа LDP. Для того, чтобы подписаться, пошлите сообщение с темой "subscribe" по адресу: ldp-discuss-request@lists.linuxdoc.org. Для отказа от подписки, пошлите сообщение с темой "unsubscribe" по тому-же адресу.
Это "быстрый и грязный" путь, который должен работать независимо от того, какой дистрибутив вы используете.
Создайте базовую директорию где вы будете хранить все необходимое. Например: /usr/local/sgml. Далее по тексту мы будем называть её $_toolroot.
Установите Jade, DocBook DTD, и DSSSL, так чтобы базовой директорией всех их была $_toolroot (создав $_toolroot/jade-1.2.1, $_toolroot/dtd, $_toolroot/dssl)
Вам нужно установить переменную окружения SGML_CATALOG_FILES указывающую на каталоги которые находятся в $_toolroot. Вы можете сделать это с помощью следующей команды: $ENV{'SGML_CATALOG_FILES'} = “$_toolroot/dtd/docbook.cat;$_toolroot/dsssl/docbook/catalog;$_toolroot/jade-1.2.1/dsssl/catalog”
Теперь вы готовы к использованию Jade. Чтобы создать отдельные HTML файлы: $_toolroot/jade-1.2.1/jade/jade -t sgml -i html -d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml
Чтобы создать один большой HTML файл,добавьте -V nochunks в приведенную выше команду.
Вам понадобятся 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.
Эти утилиты поставляются с дистрибутивом 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 файл.
Большая часть этого вопроса освещена в документе Jorge Godoy "Using DocBook". Если вас это интересует, то вы можете прочесть о написании DocBook документов с помощью вашего любимого текстового редактора, по адресу: http://metalab.unc.edu/godoy/using-docbook/using-docbook.html.
Начать писать новое HOWTO с помощью LyX очень просто. Используйте команду меню File->New from template..., чтобы вызвать на экран список шаблонов. Выберите Templates на правой части экрана, затем выберите docbook_template.lyx в списке файлов. Нажмите OK и вы получите новый документ. Заполните такие вещи как заголовок,краткое описание и имя автора, и приступайте к написанию документа.
Если у вас уже есть LyX, TeX, или текстовый документ, вы можете импортировать его в LyX с помощью команды File->import. Импортировав файл, идите в Layout->Document... . В появившемся окне, под Style, выберите SGML (DocBook Article). Вас спросят хотите ли вы конвертировать весь текст, ответьте "Yes". Вам потребуется изменить большую часть тэгов, но это довольно простое дело: выделяйте текст и изменяйте стиль.Для многих Lyx функций существуют горячие клавиши, они помогут вам сделать это быстрее.
Написав документ или конвертировав его, сохраните его в формате 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/.
Если вы хотите, чтобы 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.
Попробуйте следующий тест. Создайте новый файл, например /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 и введите следующее:
<!DOCTYPE ARTICLE PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> |
Введите C-c C-p и задержите дыхание :) . Если все прошло как планировалось, то через несколько секунд вы увидите Parsing prolog...done в мини-буфере.
Теперь введите C-c C-e RETURN, чтобы вставить <article> элемент и продолжайте написание вашего HOWTO.
Смотрите "Nik Clayton's primer for FreeBSD documentation": http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html