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

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

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



Наш баннер
Вы можете установить наш баннер на своем сайте или блоге, скопировав этот код:
RSS новости