Учебник Guide-XML от Gentoo Linux
Автор: Daniel Robbins
Перевод: Алексей Потанин
Этот учебник поможет научиться создавать документацию для публикации в Интернете, используя новый простой синтаксис guide-XML от Gentoo. Описанный здесь синтаксис является официальным форматом документации для Gentoo Linux, и этот документ сам был создан с использованием guide-XML (это относится к оригинальному документу и его официальному переводу на www.gentoo.org; настоящий же документ, как нетрудно догадаться, представляет собой pure HTML). Это руководство предполагает знание основ XML и HTML.
1.1
6 February 2003
Основы guide-XML
Цель создания guide-XML
Синтаксис guide-XML прост, но выразителен. Его легко изучить, тем не менее он обеспечивает все возможности, нужные для создания интернет-документации.Количество используемых тегов сведено к минимуму - есть только самые необходимые.
Это облегчает преобразование из формата guide-XML в другие форматы, такие как
DocBook, XML/SGML или HTML.
Наша задача - облегчить создание и преобразование документов guide-XML.
Как из guide-XML получить законченный HTML
Прежде чем рассмотреть собственно синтаксис guide-XML, не лишним будет узнать как guide-XML превращается в HTML. Для этого используется специальный файл guide.xsl совместно с консольным XSLT-обработчиком (a command-line XSLT processing tool) (называемым также "движком" ("engine")). Файл guide.xsl досконально описывает как преобразовать содержимое исходного guide-XML документа для получения конечного HTML файла. Парой популярных XSLT-обработчиков являются sabcmd (включен в пакет app-text/sablotron) и xsltproc (находится в пакете dev-libs/libxslt). По нашему опыту, xsltproc - более качественный и обеспечивающий большие возможности XSLT-обработчик.
Если у Вас установлен xsltproc либо sabcmd, то Вы готовы переводить guide-XML в законченный HTML. Чтобы заняться этим, нужно, однако, еще получить последнюю версию копии нашего вебсайта.
Сжатый (gzipped) архив (tarball) сайта находится здесь.
Теперь Вы можете получить полный комплект имеющихся документов Gentoo Linux на нужном Вам языке не загружая полную копию сайта. Загляните, пожалуйста, на http://www.gentoo.org/dyn/doc-snapshots, чтобы выбрать подходящий архив.
Теперь распакуйте архив. В нем находится каталог htdocs. Далее, найдите файл htdocs/doc/<язык>/gentoo-x86-install.xml (Руководство по установке). Это будет наш исходный guide-XML документ. Простейший способ превратить его в HTML -- это перейти в каталог, где находится файл guide.xsl, а затем запустить xsltproc, как показано ниже:
Преобразование gentoo-x86-install.xml
$ cd gentoo-web/xsl
$ xsltproc guide.xsl ../doc/<язык>/gentoo-x86-install.xml > /tmp/install.html
Если все пройдет нормально, Вы должны получить готовую версию gentoo-x86-install.xml в файле /tmp/install.html. Чтобы этот документ должным образом отображался браузером, может потребоваться скопировать некоторые файлы из htdocs в /tmp. Например, css/main-new.css и (для спокойствия) весь каталог images.
Guide-XML
Основная структура
Теперь, когда Вы знаете, как преобразовать guide-XML, можно приступить к изучению синтаксиса guide-XML. Начнем с титульных тегов, используемых в guide-XML документах.
Титульная часть guide-XML документа
<?xml version='1.0' encoding="UTF-8"?>
<guide link="relative_link_to_your_guide">
<title>Документация Gentoo Linux. Руководство.</title>
<author title="Author"><mail link="drobbins@gentoo.org">
Daniel Robbins</mail>
</author>
<author title="Editor"><mail link="zhen@gentoo.org">
John P. Davis</mail>
</author>
<author title="Translator">
Alexey Potanin
</author>
Прежде чем публиковать документ, обязательно прочтите
Политику Разработчиков Документации.
<abstract>
Этот учебник поможет научиться создавать документацию для
публикации в Интернете, используя новый простой синтаксис
guide-XML от Gentoo. Описанный здесь синтаксис является
официальным форматом документации для Gentoo Linux, и этот
документ сам был создан с использованием guide-XML.
Это руководство предполагает знание основ XML и HTML.
</abstract>
<version>1.1</version>
<date>29 Jan 2003</date>
В первой строке мы видим необходимый тег, показывающий, что перед нами XML документ. За ним следует тег <guide> - весь guide-XML документ заключен внутри пары <guide> </guide>. Далее идет тег <title>, используемый для присвоения названия всему документу.
Затем перейдем к тегам <author>, содержащих информацию о различных авторах документа. Каждый тег <author> допускает использование дополнительного элемента title=, уточняющего отношение автора к документу (автор, соавтор, редактор и т.д.). На этом примере видно, что имя автора может быть заключено в еще одном теге -- <mail>, используемом для указания адреса его электронной почты. Тег <mail> является дополнительным и может быть опущен. Для guide-XML документа вполне достаточно одного элемента <author>.
Потом идут теги <abstract>, <version> и <date>, внутри которых помещаются аннотация, текущий номер версии документа и дата (в формате DD MMM YYYY) его написания соответственно. На этом заканчивается описание тегов, которые должны находиться в начале guide-XML документа. За исключением <title> и <mail>, эти теги не должны использоваться нигде, кроме как непосредственно внутри тега <guide>. И, для приличия, желательно (хотя и не требуется), чтобы эти теги появились перед текстом самого документа.
Главы и разделы
Теперь, когда титульные теги определены, можно приступать к заполнению документа структурными элементами. Документ делится на главы. Каждая глава состоит из одного или более разделов. Каждая глава и каждый раздел имеют свои заголовки. Здесь приведен пример главы с единственным разделом, состоящим из одного абзаца. Если объединить этот фрагмент XML с предыдущим отрывком и добавить в конце файла </guide>, то получится минимально возможный документ.
<chapter>
<title>Это моя глава</title>
<section>
<title>Это первый раздел моей главы</title>
<body>
<p>А это фактическое текстовое наполнение моего раздела.</p>
</body>
</section>
</chapter>
Здесь видно, как добавлением в элемент <chapter> элемента <title> присвоено название этой главе. Затем, добавлением элемента <section>, создается раздел. Внутри элемента <section> есть два элемента: <title> и <body>. Про <title> добавить уже нечего - опять присваивает название, только теперь разделу. А элемент <body> содержит все фактическое текстовое наполнение этого раздела. Давайте теперь вкратце рассмотрим теги, которые можно использовать внутри элемента <body>.
В элементе <guide> может находиться несколько элементов <chapter>, а элемент <chapter>, в свою очередь, может содержать несколько элементов <section>. Однако, в элементе <section> может быть только один элемент <body>.
Пример <body>
Настало время научиться размечать фактический текст. Это пример guide-XML кода для элемента <body>:
<p>
Это абзац. <path>/etc/passwd</path> - это файл.
<uri>http://www.gentoo.org</uri> - мой любимый вебсайт.
Введите <c>ls</c>, если хотите.
Мне уже <e>действительно</e> пора ложиться спать.
</p>
<pre>
Это распечатка или исходник. (This is text output or code.)
# <i>это набрано пользователем (this is user input)</i>
Выборочное выделение делает HTML/XML проще для чтения:
<foo><i>bar</i></foo>
<codenote>Это вставка комментария в распечатку</codenote>
</pre>
<note>Это примечание.</note>
<warn>Это предупреждение.</warn>
<impo>Это важно.</impo>
А так этот элемент <body> выглядит:
Это абзац. /etc/passwd - это файл.
http://www.gentoo.org - мой любимый вебсайт.
Введите ls , если хотите. Мне уже действительно пора ложиться спать.
Это распечатка или исходник. (This is text output or code.)
# это набрано пользователем (this is user input)
Выборочное выделение делает HTML/XML проще для чтения:
<foo>bar</foo>
Это вставка комментария в распечатку
Это примечание.
Это предупреждение.
Это важно.
Теги элемента <body>
В предыдущем разделе мы представили несколько новых тегов - теперь расскажем, что о них надо знать. Все теги - <p> (абзац), <pre> (распечатка), <note> (примечание), <warn> (предупреждение) и <impo> (важно) - могут заключать в себе одну и более строк текста. Они, а также элемент <table> (который разберем чуть позже), должны использоваться непосредственно внутри элемента <body>. Иначе говоря - эти теги не должны быть вложенными. Другими словами - не вставляйте элемент <note> в элементе <p>. Как Вы уже сами могли догадаться, элемент <pre> в точности сохраняет расположение своего содержимого, что делает его вполне пригодным для отображения фрагментов распечаток.
<path>, <c> и <e>
Элементы <path>, <c> и <e> могут быть использованы внутри любого подшефного для <body> тега, кроме <pre>.
Элемент <path> используется для выделения текста, указывающего на локальный файл -- как то абсолютный или относительный путь, либо просто имя файла. Этот элемент обычно отображается моноширинным шрифтом для отличия от основного вида абзаца.
Элемент <c> используется для выделения команд или набираемого пользователем текста. Думайте о <c> как о способе обратить внимание читателя на то, что он должен ввести для выполнения какого-либо действия. Например, все демонстрируемые в этом документе XML теги заключены в элемент <c>, потому что они представляют нечто отличное от пути, что может быть напечатано пользователем. Используя элемент <c> Вы поможете своим читателям быстро опознать команды, которые им надо набирать. К тому же, так как элементы <c> уже отличаются от обычного текста, крайне редко бывает необходимым заключать пользовательский ввод в кавычки. Например, не выделяйте элемент "<c>" так, как сделано в этом предложении. Избегая использования ненужных кавычек, Вы делаете документ более удобочитаемым - и восхитительным!
<e> применяется для выделения слова или фразы курсивом; например: Я на самом деле должен чаще использовать запятые. Как Вы можете заметить, этот текст отличается от обычного вида абзаца наклоном. Это позволяет придать Вашей прозе больше энергии!
<mail> и <uri>
Мы уже сталкивались с тегом <mail> ранее; он используется для связи какого-либо текста с соответствующим адресом электронной почты, и имеет форму <mail link="foo@bar.com">Mr. Foo Bar</mail>.
Тег <uri> применяется для указания на файлы/расположение в Интернете. У него две формы - первая может применяться, если в тексте надо показать действительный адрес, такой как ссылка на http://www.gentoo.org. Для создания такой ссылки достаточно написать <uri>http://www.gentoo.org</uri>. Другая форма используется для связи адреса с каким-нибудь другим текстом - например, the Gentoo Linux website. Чтобы создать такую ссылку, следует напечатать <uri link="http://www.gentoo.org">the Gentoo Linux website</uri>.
Рисунки
Так в документ вставляется рисунок - <figure link="myphoto.png" short= "Наша Прелесть" caption="любимейший образ во веки веков"/>. Атрибут link= указывает на действительное изображение, атрибут short= определяет краткое описание (используется аналогично HTML атрибуту alt=), и caption= - заголовок. Не слишком уж и сложно :) Также поддерживается тег в стандартном HTML-стиле <img src="foo.gif"/> для вставки изображений без подписей, рамок и пр.
Таблицы и списки
Guide-XML поддерживает упрощенное описание таблиц, похожее на HTML. Начинается таблица тегом <table>. Строка открывается тегом <tr>. Однако, для вставки информации не поддерживается HTML тег <td>; вместо него применяется <th> для вставки заголовка, и <ti> и вставки нормального информационного блока. Вы можете использовать <th> везде, где допускается использовать <ti> -- совсем не требуется, чтобы элемент <th> появлялся только в первой строке. Сейчас этими тегами не поддерживаются какие-либо атрибуты, однако вскоре кое-какие атрибуты появятся (к примеру, атрибут caption= для тега <table>).
Для создания нумерованных или ненумерованных списков используются теги в HTML-стиле <ol>, <ul> и <li>. Теги списков можно использовать только внутри тегов <p>, <ti>, <note>, <warn> или <impo>.
Ссылки внутри документа
Guide-XML позволяет легко и просто обращаться к другим частям документа используя гиперссылки. Вы можете создать указатель Глава Первая напечатав <uri link="#doc_chap1">Глава Первая</uri>. Указать на второй раздел Первой Главы можно введя <uri link="#doc_chap1_sect2">второй раздел Первой Главы</uri>. Чтобы сослаться на рисунок 3 в главе 1 напишите <uri link="doc_chap1_fig3"> рис. 1.3</uri>. Обратиться к распечатке 2 в главе 2 поможет <uri link="doc_chap2_pre2">распечактка 2.2</uri>. Вскоре будут добавлены и другие возможности для автоссылок (вроде поддержки таблиц).
Возможности
Начните писать
Guide-XML специально был задуман как "поддержка и опора", чтобы разработчики могли больше времени уделить написанию документации и меньше времени затрачивали изучая фактический синтаксис XML. Надеемся, это позволит разработчикам, которые обычно не "доки в док-ах", начать писать качественную документацию для Gentoo Linux. Если желаете помочь (или у Вас есть вопросы о guide-XML), пожалуйста, пишите (на английском !) письмо в список рассылки the gentoo-dev mailing list (разработка) и the gentoo-doc mailing list (документация) в зависимости от того, за что хотите взяться. Удачи!