HOWTO-HOWTO

В этом документе собраны полезные советы,описания утилит и приемов работы, которые призваны помочь авторам документов HOWTO ускорить их написание.

[Mark F. Komarinski (markk@linuxdoc.org). Перевод Александр Михайлов (alexmikh@linux.ru.net)]

Введение

Копирайты и торговые марки.

(c) 1999-2000 Mark F. Komarinski

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

  • Сообщение о копирайте приведенное ниже и данное предложение должны быть сохранены без изменений во всех полных или частичных копиях.

  • Любой перевод или основанная на этом документе работы должны быть одобрены автором в письменном виде до их публикации.

  • Если вы распространяете фрагмент данного документа, должны быть включены инструкции по получению полной версии данного пособия, и даны соответвующие ссылки.

  • Небольшие фрагменты данного документа могут быть включены в качестве иллюстрации или цитаты в другие работы без копирования данного документа, если дано правильное цитирование. Исключения могут быть сделаны для научных целей: Напишите автору и спросите его. Эти ограничения сделаны для того, чтобы защитить нас как авторов, а некоем случае не для ограничения вас как читателей и обучающихся. Любой исходный код (помимо sgml кода данного документа) в данном документе подпадает под действие GNU General Public License, доступной через анонимный FTP доступ в архиве GNU.

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

Эта секция рассказывает о новом методе написания LDP документации, используя DocBook 3.1 DTD. Мы расскажем о том как получить,установить и использовать утилиты, а также о тэгах DocBook. Так как существует более 300 DocBook тэгов, мы естественно не сможем описать все их здесь. По настоящему заинтересованные читатели могут зайти на http://www.docbook.org для получения более подробной информации.

Загрузка и установка необходимых утилит.

Непосредственное использование 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 файл.

Написание SGML с использование LyX

Написание SGML с использованием PSGML

Обновление вашего .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. 
;; *******************************************************************
[Текст был разбит на строки небольшой длины для повышения его удобочитаемости. Чтобы восстановить оригинальный вариант, необходимо объединить строки, разделенные "пустотой" (\n\n), в одну,-прим. ред.]

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

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

Эта секция рассказывает о новом методе написания LDP документации, используя DocBook 3.1 DTD. Мы расскажем о том как получить,установить и использовать утилиты, а также о тэгах DocBook. Так как существует более 300 DocBook тэгов, мы естественно не сможем описать все их здесь. По настоящему заинтересованные читатели могут зайти на http://www.docbook.org для получения более подробной информации.

Загрузка и установка необходимых утилит.

Непосредственное использование 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 файл.

Написание SGML с использование LyX

Написание SGML с использованием PSGML

Обновление вашего .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.

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

В этой секции описывается как начать писать вашу собственную LDP документацию. Установка и настройка утилит, связь с LDP и распространение ваших знаний всем пользователям Линукс.

Для новых авторов

Если вы новичок в LDP и хотите взять одно из брошенных HOWTO, или написать новый HOWTO/mini-HOWTO документ, то вам необходимо связаться с координатором HOWTO ldp-discuss@lists.linuxdoc.org. Это необходимо, чтобы координатор знал,кто работает над данной документацией. Также заметьте, что все HOWTO должны быть в SGML формате, с использованием DocBook 3.1 DTD. Если это mini-HOWTO, то вы можете использовать как SGML так и HTML форматы, но только SGML-форматированные документы будут включены в печатные версии HOWTO.

Загрузка и установка необходимых утилит

sgmltools

Загрузите пакет sgmltools по адресу http://www.sgmltools.org/, или возьмите его из вашего дистрибутива. Пакеты на sgmltools.org содержат исходный код, так что вам придется скомпилировать их для вашей системы. Использование скомпилированных пакетов для вашего дистрибутива проще,т.к. вам не придется компилировать исходные коды и разбираться с возможными ошибками в ходе компиляции (если вы не программист конечно). Sgmltools включены в новые версии RedHat. Если нет, вы можете загрузить соответвующие пакеты с ftp.redhat.com или с одного из зеркал, как часть основного дистрибутива. Если вы используете Debian (пакет с sgmltools также включен в новые версии), вы можете использовать команду apt-get, чтобы загрузить и установить пакет:

# apt-get install sgml-tools
   

Узнать больше о пакете для Debian, вы можете по адресу http://www.debian.org/Packages/stable/text/sgml-tools.html. Если вы компилируете пакет из исходников,то вам нужно сделать следующее:

# tar -zxvf sgmltools-x.x.x.tar.gz
# cd sgmltools-x.x.x
# ./configure
# make
# make install
   

Замените sgmltools-x.x.x на номер версии, которую вы используете. На момент написания последней версией использующей LinuxDoc была версия 1.0.9. Версия поддерживающая DocBook это 2.0.2. Обе этих версии доступны на указанном выше сайте. Установив эти утилиты,вы получите в своё распоряжение следующие команды:

  • sgmlcheck file.sgml- Checks the syntax of a given document. sgmlcheck file.sgml- Проверит синтаксис заданного документа.

  • sgml2html file.sgml- Визуализирует SGML файл в HTML. Создает file.html который содержит Оглавление, затем создает file-x.html файлы, где x это номер секции.

  • sgml2rtf file.sgml- Конвертирует SGML файл в Rich Text Format (RTF). Создает два файла, первый - это file.rtf содержащий оглавление, и файл file-0.rtf,который содержит все секции.

  • sgml2txt file.sgml- Конвертирует SGML файл в ASCII текст. Оглавление и все секции помещаются в файл file.txt.

  • sgml2info file.sgml- Конвертирует SGML файл в формат INFO, используемый командой info. Весь документ будет помещен в file.info.

  • sgml2latex file.sgml- Конвертирует SGML в TeX.

  • sgml2lyx file.sgml- Конвертирует SGML в формат фронт-енд редактора LyX. Это поможет вам конвертировать уже существующие SGML файлы для использования с LyX.

Написание SGML вручную

Как и в случае с HTML, вы можете писать SGML документы вручную, если знаете все необходимые управляющие коды. В качестве пособия для начинающего вполне может быть использован и этот документ, в SGML формате (сайт с которого можно скачать его, указан в секции "Введение"). Т.к. SGML может обрабатываться различно, в зависимости от формата создаваемого файла, я постараюсь перечислить некоторые вещи, которые пригодятся вам в процессе написания документов.

Заголовок

Документ должен начинаться с информации о его содержании. Это похоже на несколько первых страниц книги, где находиться заглавная страница (название работы, имя автора, дата публикации, оглавление, и тому подобное). Название документа заключено в тэги <title> и </title>. Автор указывается с помощью тэгов <author> и </author>. Дата с помощью <date> и </date>. Следующие два информационных поля это <abstract> и </abstract>, которые кратко описывают содержание документа, и тэг <toc>, который указывает куда нужно поместить оглавление. Оглавление автоматически генерируется SGML процессором. О секциях мы расскажем далее. А сейчас давайте посмотрим, как это выглядит все вместе. Возьмем фрагмент SGML кода (который использовался при создании этого документа):

<!doctype linuxdoc system>
<!-- LinuxDoc file was created by LyX 1.0
(C) 1995-1999 by <markk> Tue Dec 14 15:24:03 1999-->
<article>
<title>HOWTO HOWTO </title>
<author>Mark F. Komarinski </author>
<date>v1.1, 14 Декабрь 1999 </date> 
<abstract>
Здесь перечислены утилиты, процедуры, и советы, призванные помочь 
авторам HOWTO ускорить их написание.
</abstract>
<toc> 
   

Этот фрагмент кода создает главную страницу документа,которую вы видите, когда вы просматриваете документ в RTF или HTML форматах, и размещает на ней оглавление.

Секции

Чтобы создать оглавление, документ должен содержать некоторую информацию. Секции в случае с SGML, это все равно,что главы в традиционной печати. Документ обычно состоит из множества секций, каждая из секций содержит под-секции, которые в свою очередь могут содержать свои под-секции и так далее. Полезно начать свой документ с описания секций, так как это позволит вам выделить основные темы, которые будет покрывать ваш документ. Затем вы можете разбивать эти секции на более мелкие,пока не получите фрагменты, которые будут содержать всего несколько параграфов. При написании этого документа, я начал свою работу именно так. Секции - это одни из немногих SGML тэгов, которые не надо закрывать. То есть, не существует тэга </sect>. Также вам не нужно думать о нумерации. SGML процессор сам позаботиться о ней, когда вы будете визуализировать SGML во что нибудь другое. Секции начинаются с тэга <sect>. Каждый <sect> тэг, означает начало новой секции. Первая секции носит номер 1. Под-секции (например 1.1) создаются с помощью тэга <sect1>. Нумерации под-секций также начинается с единицы. Под-секции под-секций (1.1.1) создаются с помощью тэгов <sect2>, и также нумеруются начиная с 1.Когда SGML процессор встречает тэг <toc>, он просматривает остальной документ и создает оглавление, основываясь на количестве тэгов секций, найденных в документе. Секции перечисляются и нумеруются в оглавлении и затем используются в остальном документе. Под-секции (1.1.1) не перечисляются в оглавлении, но, если возможно, выделяются в тексте.

Списки

В SGML существует два вида списков. Первый это нумерованный список, в котором каждый элемент списка пронумерован (как секции) начиная с единицы. 1. Это первый элемент нумерованного списка. 2. Это второй. 3. Третий. Код приведенного выше списка выглядит как: <enum> <item>Это первый элемент нумерованного списка. <item>Это второй. <item>Третий. </enum> Тэг <enum> открывает нумерованный список. Второй тип списков - не нумерованные, в которых возле каждого элемента стоит звездочка, или кружок, или точка, либо существует какое то еще выделение элементов.

  • Это первый элемент не нумерованного списка

  • Это второй

  • Третий

Вот как выглядит SGML код этого списка.

<itemize>
<item>Это первый элемент не нумерованного списка
<item>Это второй
<item>Третий
</itemize>
   

Как вы можете видеть, тэг <item> одинаков для нумерованных и не нумерованных списков. Третья форма списков - это описательные списки. Они состоят из терминов и соответвующие им описаний. LDP The Linux Documentation Project SGML Standard Generalized Markup Language. Код для этого примера выглядит так: <descrip> <tag>LDP</tag>The Linux Documentation Project <tag>SGML</tag>Standard Generalized Markup Language </descrip> Это не совсем как для нумерованных или не нумерованных списков, но весь список также окружен общим тэгами (<descrip> и </descrip>) а определяемые слова заключены в <tag> и </tag>. Остаток строки рассматривается как описание предшествующего термина.

URL

SGML также поддерживает Универсальные указатели ресурсов (URL), любого типа. Правда работать они будут только при визуализации в HTML, но другие форматы также могут использовать их тем или иным способом. URL не имеет завершающего тэга, т.к сама информация размещена внутри тэга <url>. Этот URL указывает на домашнюю страницу LDP : http://www.linuxdoc.org/. А это его SGML код: <url url="http://www.linuxdoc.org/" name="http://www.linuxdoc.org/"> Параметр url=\"{}http://www.linuxdoc.org/\"{}, указывает браузеру куда направится по этой ссылке, в то время как параметр name=\"{}http://www.linuxdoc.org/\"{}, говорит браузеру о том как отобразить ссылку на экране. В данном случае они совпадают, но можно создать URL тэг выглядящий так: <url url="http://www.linuxdoc.org/" name="LDP"> В визуализированной форме это будет выглядеть как: LDP. Хотя обычно, более корректно указывать URL в качестве имени. Так как при визуализации в Text или RTF, преведущий тэг потеряет своё значение и пользователь не узнает какой URL использовать.

Внутренние ссылки

В то время как URLы являются великолепным способом сослаться на внешний документ, они не удобны для создания ссылок на информацию внутри самого документа. Для таких ссылок нужно использовать тэги <label> и <ref>. Тэг <label> указывает точку в документе, на которую впоследствии можно ссылаться (метку). Создать <label> просто. Найдите точку на которую вы будете ссылаться в дальнейшем, и вставьте возле неё следующее: <label id="Введение"> Все, вы создали метку на которую вы можете ссылаться так: "Введение". В этом документе такая метка размещена в самом начале. После этого, когда вам необходима сослаться на метку (Например: Введение (Здесь)), вам нужно вставить следующий фрагмент SGML кода в документ: <ref id="Введение" name="Здесь"> и SGML процессор разместит в нужном месте метку с именем "Здесь" (смотрите выше), которая будет ссылаться на секцию введение. Другое применение ссылок - создание индекса. Так как LDP документация обычно публикуется в печатном виде большой коллекцией, то возникает необходимость создание в конце публикации индекса слов и тем.

CVS

LDP находиться в процессе предоставления CVS доступа авторам. На это есть несколько причин:

  1. В CVS всегда будет храниться копия ваших документов. В случае если вы передадите ответственность за свой документ другим авторам, им нужно будет просто получить документ из CVS и продолжить его написание. В случае если вам понадобиться одна из приведущих версий документа, вы всегда сможете получить её.

  2. Также CVS будет крайне полезен в случае, если над документом работает несколько человек. Вы сможете узнать какие изменения были сделаны другими авторами и объединить их с вашими.

  3. CVS хранит историю изменений. Эту историю (и дату) можно автоматически разместить внутри документа, когда вы используете специальные тэги,обрабатываемые до визуализации документа SGML процессором.

  4. C помощью CVS и специальной программы веб сайт LDP может быть автоматически обновлен, когда выкладывается новая документация. Это еще не сделано, но является одной из целей.

Если вы никогда не работали с CVS, то вам возможно поможет информация размещенная по следующим адресам.

Получение CVS аккаунта

Прежде всего вам необходимо получить аккаунт в CVS репозитарии LDP. Это корневая директория используемая CVS, с различными проектами (HOWTO,mini-HOWTO и т.д.) размещенными в поддиректориях.

Вам будет нужно создать зашифрованный пароль и идентификатор пользователя для аккаунта. Зашифрованный пароль можно послать в CVS группу, при этом им не нужно будет знать ваш пароль. Вы можете сделать это с помощью следующих комманд, из bash (или sh):

$ echo это_ваш_пароль | \
perl -e "print crypt(<>, \
join '',('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]),\"\n\"" 

Пошлите вывод этой команды вместе с идентификатором пользователя (выберите сами) по адресу cvsadmin@cvslist.linuxdoc.org. Будет создан ваш уникальный CVSROOT и вам будет выслано уведомление по почте. Получив подтверждение, войдите в ваш CVSROOT и убедитесь что все работает правильно:

$ export CVSROOT=:pserver:your_userid@cvs.linuxdoc.org:/cvsroot
$ cvs -d $CVSROOT login 
  

(Замените CVSROOT на то , что было выслано вам по почте).

Вас спросят о вашем пароле, и затем вы получите доступ к CVS репозитарию с разрешением на чтение/запись. При первом использовании cvs login и получении доступа к системе, ваш пароль будет сохранен в .cvsroot и вам не придется больше использовать cvs login. Просто установите CVSROOT и продолжайте работу. Вы можете получить весь linuxdoc репозитарий с помощью команды:

$ cvs get LDP
  

Или вы можете получить SGML код вашего собственного документа с помощью следующих команд:

$ cvs get howto/ВАШЕ-HOWTO.sgml
$ cvs get minihowto/ВАШ-ДОКУМЕНТ.sgml
  

Также существует The Commit List, лист рассылки в котором сообщается обо всех изменениях в репозитарии. Будьте осторожны, этот список обладает большим трафиком. Вы можете подписаться послав e-mail по адресу: commits-subscribe@cvslist.linuxdoc.org. Отменить подписку можно послав пустое письмо по адресу commits-unsubscribe@cvslist.linuxdoc.org.

Распространение вашей документации

Перед тем как начать распространение

Перед тем, как вы предложите ваш код миллионам потенциальных читателей, есть несколько вещей, которые нужно сделать.

Прежде всего, убедитесь, что вы проверили правописание вашего документа. Большинство утилит, которые используются для написания SGML имеют плагины для проверки орфографии. Если нет, вы всегда можете воспользоваться программой aspell.

Во вторых, найдите кого нибудь, кто проверит вашу документацию и сделает комментарии. Документация публикуемая LDP должна быть как можно более корректна, так как её могут прочитать миллионы пользователей Линукс. Если вы являетесь членом какого-нибудь подписного листа, обсуждающего данную проблему, попросите его членов помочь вам.

В третьих создайте веб сайт, где вы можете разместить вашу документацию. Это необязательно, но полезно, чтобы люди всегда могли найти оригинальную версию вашего документа.

Права и лицензирование

Чтобы ваш документ был принят LDP, он должен быть залицензирован так, чтобы разрешить его свободное (в смысле пива :)) распространение и публикацию. Как автор, вы можете удерживать копирайт и добавлять другие ограничения (например потребовать чтобы работы основанные на вашей или переводы были одобрены вами). Пример лицензии вы можете найти по адресу http://www.linuxdoc.org/COPYRIGHT.html. Если вы выберите полномасштабный копирайт, просто скопируйте его в исходный код в секцию "Copyright and Licenses" или подобную её. Также включите ваш собственный копирайт (так как вы все таки владелец документа). Если вы продолжаете чьё-то HOWTO вы обязаны включить заметки о копирайте приведущих авторов и даты, когда они занимались документом.

Опубликование в LDP

После того как ваш документ был просмотрен несколькими людьми, и были приняты во внимание их замечания, вы можете опубликовать его в рамках LDP. Пошлите e-mail с SGML кодом в качестве вложения (можете сжать его gzip, если хотите) по адресу ldp-submit@lists.linuxdoc.org.

Обязательно включите название вашего HOWTO в строке тема, в теле письма отметьте сделанные изменения и приложите к письму ваше HOWTO. Это позволить людям занимающимся HOWTO, сделать свою работу быстрее и вам не придется ждать, пока ваше HOWTO будет обновлено на веб сайте LDP. Если вы не услышите ничего в течении 7 календарных дней, пошлите письмо, чтобы убедиться, что работа идет.

[ опубликовано 17/06/2003 ]

Mark F. Komarinski (markk@linuxdoc.org). Перевод Александр Михайлов (alexmikh@linux.ru.net) - HOWTO-HOWTO   Версия для печати