HOWTO-HOWTO
Пред.След.

Основы работы с 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.

Листы рассылки

Если вы хотите принять участие в работе LDP, то существует несколько листов рассылки, на которые вы можете подписаться. Первый - ldp-discuss@lists.linuxdoc.org, это главная дискуссионная группа LDP. Для того, чтобы подписаться пошлите сообщение с темой "subscribe" по адресу :ldp-discuss-request@lists.linuxdoc.org. Для отказа от подписки, пошлите сообщение с темой "unsubscribe" по тому-же адресу.

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

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. Обе этих версии доступны на указанном выше сайте. Установив эти утилиты,вы получите в своё распоряжение следующие команды:

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

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

Начнем

Чтобы начать писать новый документ, создайте новый документ в вашем любимом ASCII редакторе и начните его с этого: <!doctype linuxdoc system>. Эта запись определяет тип документа (LinuxDoc в данном случае), который использует SGML процессор при визуализации документа в выходной формат. Сам этот тэг не визуализируется. После этого вам необходимо ограничить ваш документ тэгами <article> и </article>. Это означает начало содержимого (статьи). Если вы знакомы с HTML, то вы можете представить это как ограничение вашего документа тэгами <html> и </html>.

Заголовок

Документ должен начинаться с информации о его содержании. Это похоже на несколько первых страниц книги, где находиться заглавная страница (название работы, имя автора, дата публикации, оглавление, и тому подобное). Название документа заключено в тэги <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) не перечисляются в оглавлении, но, если возможно, выделяются в тексте.

Обычные параграфы

Создание параграфов текста, очень похоже на то, как это делается в HTML. Используйте тэг <p>, для указания новой строки и начинайте писать. SGML игнорирует пустые места, такие как символы табуляции, многократные пробелы, и символы новой строки. Когда SGML встречает тэг <p>, он начинает новый параграф. Корректный SGML код должен содержать также и завершающий тэг </p>, в конце параграфа.

Выделение текста

Иногда вам может понадобится отделить один фрагмент текста от другого. Например, чтобы выделить код или имя команды. Первое (выделение текста) делается с помощью тэгов <em> и </em>. Эффект печатной машинки (второй пример) создается с помощью <tt> и </tt>.

Списки

В 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>. Остаток строки рассматривается как описание предшествующего термина.

Неформатированный текст

Иногда нужно заставить текст выглядеть точно так, как он набран. Для этого вы можете использовать тэги <verb> и </verb>, чтобы определить неформатируемый параграф. Пробелы, возвраты строки, и другой текст (включая специальные символы) будут отображены так как они были набраны, вплоть до закрывающего тэга </verb>. Это неформатированный текст.

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 документация обычно публикуется в печатном виде большой коллекцией, то возникает необходимость создание в конце публикации индекса слов и тем.

Специальные символы

Как и в HTML вы должны защищать многие не алфавитно-цифровые символы, чтобы SGML процессор не интерпретировал их как SGML код. Здесь приведен список часто использующихся SGML кодов для символов. Более полный список есть в sgmltools User's Guide расположенному по адресу http://www.sgmltools.org/guide/guide.html.

Пред.НачалоСлед.
Основы работы с DocBook CVS