Руководство по Gentoo GuideXML

1.  Введение

Цели создания GuideXML

Синтаксис GuideXML прост и выразителен настолько, что его очень легко изучить. При этом в нем присутствуют все возможности, необходимые для создания веб-документации. Количество тегов сведено к минимуму — оставлены только самые необходимые. Это облегчает преобразование документации в другие форматы, такие как DocBook, XML/SGML или HTML.

Цель создания GuideXML — облегчить создание и преобразование документации, подготовленной в формате XML.

Дополнительные материалы

Если вы собираетесь участвовать в подготовке документации Gentoo, или хотите протестировать GuideXML, прочитайте советы по разработке документации.

По мере чтения, при желании, вы можете просматривать исходный XML-текст этого документа.

2.  GuideXML

Базовая структура

Давайте приступим к изучению синтаксиса GuideXML. Начнем с титульных тегов, используемых в документах GuideXML:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header$ -->

<guide link="/doc/ru/guide.xml" lang="ru">
<title>Составление документации Gentoo</title>

<author title="Author">
  <mail link="ваше_имя@gentoo.org">Ваше Имя и Фамилия</mail>
</author>

<abstract>
В этом руководстве описывается, как составлять веб-документацию, пользуясь 
новым упрощенным синтаксисом Gentoo GuideXML. Это официальный формат 
документации Gentoo, и данный документ тоже сверстан в GuideXML. При изучении 
руководства предполагаются базовые знания XML и HTML.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<!-- Текст этого документа распространяется на условиях лицензии CC-BY-SA -->
<!-- См. http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>1.0</version>
<date>2004-12-25</date>

В первых строках виден необходимый тег, показывающий, что это XML-документ, и указывающий на его DTD. Строка <!-- $Header$ --> автоматически изменяется сервером CVS, и помогает отслеживать редакции (revisions). Далее следует тег <guide>: внутри пары <guide> </guide> заключен весь документ GuideXML. Желательно, чтобы в обязательном атрибуте link содержался путь к документу, абсолютный относительно его «корня», хотя можно указывать и просто имя файла. Этот атрибут в основном используется для генерации ссылки на версию документа для печати. Если вы укажете неверное значение, ссылка не будет работать или укажет не на тот документ. В переведенных документах необходимо указывать полный путь, потому что он также используется для проверки, существует ли более свежий исходный документ. Атрибут lang следует использовать для указания кода языка, на котором составлен ваш документ. Он используется для форматирования даты, а также для вставки на нужном языке строк типа «Примечание», «Разделы» и т.д. Язык по умолчанию — английский.

Затем следует тег <title>, предназначенный для указания названия всего документа.

Далее идут теги <author>, в которых содержатся сведения о различных авторах документа. В каждом теге <author> можно использовать необязательный элемент title для указания отношения автора к документу (автор, соавтор, редактор, переводчик и т.п; по-английски — author, co-author, editor, translator). В данном примере имена авторов заключены в другой тег, <mail>, который служит для указания адреса электронной почты соответствующего автора. Тег <mail> использовать необязательно. В документах GuideXML нужно указывать хотя бы одного автора.

Далее следуют теги <abstract>, <version> и <date>, предназначенные для указания аннотации, номера текущей версии, и даты текущей версии в формате ГГГГ-ММ-ДД, соответственно. Недопустимые даты, а также даты, указанные не в формате ГГГГ-ММ-ДД, будут выведены в конечный документ как есть.

На этом заканчивается описание тегов, которые должны находиться в начале документа. За исключением <title> и <mail>, эти теги нельзя использовать нигде, кроме как непосредственно внутри тега <guide>, а для единообразия рекомендуется (но не требуется) указывать их перед текстом документа.

И, наконец, есть тег <license/>, предназначенный для публикации документа на условиях лицензии Creative Commons — Attribution / Share Alike, в соответствии с требованиями правил подготовки документации (англ.).

Главы и разделы

Как только написаны титульные теги, можно начинать добавление в документ структурных элементов. Документы GuideXML состоят из глав, а в каждой главе может быть один или несколько разделов. Каждой главе и разделу дается название. Ниже приведен пример главы, состоящей из одного раздела с одним абзацем. Если присоединить этот текст XML к предыдущему отрывку, и добавить в конец файла </guide>, у вас получится минимальный правильно оформленный документ GuideXML:

<chapter>
<title>Моя первая глава</title>
<section>
<title>Первый раздел моей первой главы</title>
<body>

<p>
А это — сам текст первого абзаца первого раздела моей первой главы.
</p>

</body>
</section>
</chapter>

В этом примере я дал название главе, поместив вложенный элемент <title> внутри элемента <chapter>. Затем я создал раздел, вставив элемент <section>. Внутри элемента <section> видны два вложенных элемента: <title> и <body>. С <title> вы уже знакомы, а <body> содержит сам текст раздела. Давайте взглянем на теги, допустимые внутри элемента <body>.

Пример «тела» — элемента <body>

Изучим разметку текста документа. Вот пример XML-кода элемента <body>:

<p>
Это — абзац. А <path>/etc/passwd</path> — это файл.
<uri>http://forums.gentoo.org</uri> — мой любимый веб-сайт.
Введите <c>ls</c>, если хотите. Мне <e>очень</e> хочется спать!
</p>

<pre caption="Пример кода">
Это вывод сообщений программы или отрывок исходного кода.
# <i>а это текст, вводимый пользователем</i>

Выделение части текста облегчает восприятие HTML/XML:
<foo><i>bar</i></foo>

<comment>(так внутрь отрывка кода вставляется комментарий)</comment>
</pre>

<note>
Это — примечание.
</note>

<warn>
Это — предупреждение.
</warn>

<impo>
А это — важное замечание.
</impo>

Вот как выглядит представление приведенного элемента <body>:

Это — абзац. А /etc/passwd — это файл. http://forums.gentoo.org — мой любимый веб-сайт. Введите ls, если хотите. Мне очень хочется спать!

Это вывод сообщений программы или отрывок исходного кода.
# а это текст, вводимый пользователем
  
Выделение части текста облегчает восприятие HTML/XML:
<foo>bar</foo>

(так внутрь отрывка кода вставляется комментарий)

Теги элемента <body>

В предыдущем разделе мы представили множество новых тегов, а здесь расскажем все, что о них требуется знать. Внутрь любого из тегов <p> (абзац), <pre> (листинг), <note> (примечание), <warn> (предупреждение) и <impo> (важное замечание) можно поместить одну или несколько строк текста. Кроме элементов <table>, <ul>, <ol> и <dl> к которым мы вернемся позже, только эти теги могут находиться непосредственно внутри элемента <body>. И еще: эти теги не допускают вложенности, иными словами, не помещайте элемент <note> внутрь элемента <p>! Как вы уже могли догадаться, элемент <pre> обеспечивает точное сохранение форматирования и пробелов своего содержимого, что очень кстати для представления листингов. Тегу <pre> необходимо давать название с помощью атрибута caption:

<pre caption="Информация, выводимая uptime">
# <i>uptime</i>
16:50:47 up 164 days,  2:06,  5 users,  load average: 0.23, 0.20, 0.25
</pre>

Эпиграфы

Делегаты от изначальных 13 штатов образовали Довольный Конгресс. Томас Джефферсон, Дева и Бенджамин Франклин стали двумя глашатаями Декларации независимости. Франклин открыл электричество, потерев двух кошек друг о друга, и объявил: "Лошадь не вынесет деления на себя". Франклин умер в 1790 г., и все еще мертв.

—Неизвестный студент

Эпиграфы иногда используются в начале глав для иллюстрации последующего материала. Эпиграф — это просто абзац с атрибутом by, содержащим подпись автора.

<p by="Неизвестный студент">
Delegates from the original 13 states formed the...
</p>

Элементы <path>, <c>, <b>, <e>, <sub> и <sup>

Элементы <path>, <c>, <b>, <e>, <sub> и <sup> можно использовать внутри любого тега, вложенного в <body>, кроме <pre>.

Элемент <path> (путь) предназначен для оформления текста, указывающего на дисковый файл: как абсолютного или относительного пути, так и просто имени файла. Этот элемент обычно представляется моноширинным шрифтом, чтобы отличаться от набора обычного абзаца.

Элемент <c> используется для оформления команд или текста, вводимого пользователем. Применение <c> подсказывает читателю: если он кое-что введет, это приведет к выполнению какого-либо действия. Например, все теги XML, описываемые в этом документе, помещены в элемент <c>, так как их может вводить пользователь, и в то же время они не являются путем к файлу. Пользуясь элементами <c>, вы поможете своим читателям быстро выделять из всего текста команды, которые необходимо вводить. Кроме того, поскольку элементы <c> уже отличаются от обычного текста, практически не требуется заключать текст, вводимый пользователем, в кавычки. Например, не ссылайтесь на элемент "<c>" так, как я сделал в этом предложении. Избегая лишних кавычек, вы сделаете документ более удобочитаемым и радующим глаз!

Как вы, наверно, уже догадались, элемент <b> служит для выделения участка текста полужирным.

Элемент <e> применяется для выделения слова или фразы, например: «Мне действительно стоит чаще пользоваться запятыми!» Выделенный текст заметно отличается от обычного набора абзаца. Выделение поможет придать вашей прозе выразительность!

Элементы <sub> и <sup> используются для оформления _{подстрочного} и ^{надстрочного} текста.

Примеры кода и выделение цветом

Для улучшения восприятия примеров кода, внутри блоков <pre> допускаются следующие теги:

<i>

обозначение текста, вводимого пользователем, в отличие от сообщений

<comment>

комментарий, относящийся к последующим действиям

<keyword>

обозначение ключевого слова на языке, использованном в листинге

<ident>

обозначение идентификатора

<const>

обозначение константы

<stmt>

обозначение выражения

<var>

обозначение переменной

Пример блока с цветовой <pre> разметкой:

# Copyright 1999-2006 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

DESCRIPTION="Exuberant ctags generates tags files for quick source navigation"
HOMEPAGE="http://ctags.sourceforge.net"
SRC_URI="mirror://sourceforge/ctags/${P}.tar.gz"

LICENSE="GPL-2"
SLOT="0"
KEYWORDS="~mips ~sparc ~x86"
IUSE=""

src_compile() {
    econf --with-posix-regex || die "econf failed"
    emake || die "emake failed"
}

src_install() {
    make DESTDIR="${D}" install || die "install failed"

    dodoc FAQ NEWS README
    dohtml EXTENDING.html ctags.html
}

<mail> и <uri>

Тег <mail> мы уже рассматривали раньше; он служит для привязки части текста к конкретному адресу электронной почты, и принимает форму <mail link="vasya@pupkin.com">г-н Василий Пупкин</mail>. Для отображения самого адреса электронной почты, например, vasya@pupkin.com, используйте <mail>vasya@pupkin.com</mail>.

Тег <uri> используется для ссылки на файлы и ресурсы интернета. У него есть две формы: первая применяется, когда в тексте нужно отобразить само значение URI (однородного идентификатора ресурса), как, например, в этой ссылке на http://forums.gentoo.org. Чтобы создать такую ссылку, я набрал <uri>http://forums.gentoo.org</uri>. Альтернативная форма используется для связывания URI c каким-либо другим текстом, например, форумы Gentoo. Для создания такой ссылки я набрал <uri link="http://forums.gentoo.org">Форумы Gentoo</uri>. Для ссылки на другие страницы веб-сайта Gentoo не нужно указывать http://www.gentoo.org/. Например, ссылка главная страница документации должна выглядеть просто как <uri link="/doc/ru/index.xml">главная страница документации</uri>. Ссылаясь на индекс каталога, можно также опускать index.xml, например: <uri link="/doc/ru/">главная страница документации</uri>.

Рисунки

Рисунки в текст можно вставлять так: <figure link="mygfx.png" short="мой рисунок" caption="мой любимый рисунок во веки веков"/>. Атрибут link указывает на само графическое изображение, атрибут short устанавливает краткое описание (которое в настоящее время используется для задания атрибута рисунка alt в HTML), а подпись — задается атрибутом caption=. Не слишком сложно, не так ли :) Для вставки рисунков без подписей, рамок и т.п., также поддерживается стандартный тег в стиле HTML <img src="foo.gif"/>.

Таблицы

GuideXML поддерживает упрощенный синтаксис разметки таблиц, похожий на HTML. Для создания таблицы служит тег <table>, а строка начинается с тега <tr>. Однако, тег HTML <td> для описания данных таблицы не поддерживается. Вместо него для вставки заголовка используйте <th>, а для вставки обычного информационного блока — <ti>. Тег <th> можно указывать везде, где можно использовать <ti>: требование, чтобы элементы <th> присутствовали только в начале, отсутствует.

Кроме того, как в заголовке таблицы (<th>), так и в ячейках (<ti>) можно использовать атрибуты colspan и rowspan для объединения нескольких строк, столбцов или и тех и других, как показано ниже:

Списки

Для создания нумерованных или маркированных списков, пользуйтесь тегами <ol>, <ul> и <li> в стиле XHTML. Списки можно использовать только внутри тегов <body> и <li>, то есть можно вставлять списки внутри списков. Не забывайте, что вы пишете на XML, и все теги, включая элементы списков, необходимо закрывать (в отличие от HTML).

Также поддерживаются списки определений (<dl>). Заметьте, что ни в теге термина (<dt>), ни в теге определения (<dd>) не допускаются никакие блочные теги, типа абзацев или предупреждений. Список определений содержит:

<dl>

тег списка определений (definition list), и вложенные

<dt>

пары из тега термина (definition term)

<dd>

и тега определения (definition data)

В следующем списке, скопированном из w3.org, показано, что в списке определений могут содержаться упорядоченные и неупорядоченные списки. Тем не менее, внутрь его нельля поместить другой список определений.

Состав:

• 100 г муки
• 10 г сахара
• 1 чашка воды
• 2 яйца
• соль, перец

Приготовление:

1. тщательно перемешать сухие компоненты
2. влить жидкие компоненты
3. взбить в течение 10 минут
4. выпекать один час при 300 градусах

Примечание:

Для улучшения вкуса можно добавить изюм

Ссылки внутри документа

В GuideXML по-настоящему легко ссылаться на другие части документа, пользуясь гиперссылками. Вы можете создать ссылку, указывающую на главу 1, набрав <uri link="#doc_chap1">главу 1</uri>. Чтобы указать на раздел 2 главы 1, наберите <uri link="#doc_chap1_sect2">раздел 2 главы 1</uri>. Чтобы сослаться на рисунок 3 главы 1, введите <uri link="doc_chap1_fig3">рисунок 1.3</uri>. Или, чтобы указать на листинг 2 главы 2, введите <uri link="doc_chap2_pre2">листинг 2.2</uri>.

В то же время, некоторые руководства настолько часто изменяютсяя, что использование подобных «счетчиков» может привести к «битым» ссылкам. Чтобы избежать этого, можно с помощью атрибута id устанавливать имя главы (<chapter>), раздела (<section>) или строки таблицы (<tr>), а затем ссылаться на значение этого атрибута, как показано здесь:

<chapter id="foo">
<title>Это глава foo!</title>
...
<p>
Дополнительные сведения находятся в <uri link="#foo">главе foo</uri>
</p>

Дискламации и указания на устаревшие документы

Для отображения в начале документа стандартной дискламации (оговорки об ограничении прав или ответственности), предназначен атрибут disclaimer. Имеющиеся варианты дискламаций:

• articles (статьи) используется для пометки перепечатанных статей (англ.) из других источников
• draft (черновик) указывает на то, что над документом все еще идет работа, и его не следует считать официальным
• oldbook (старая книга) служит для пометки старых настольных книг, которые больше не поддерживаются
• obsolete (устаревший) помечает документ как устаревший

Помечая документ как устаревший, есть смысл добавлять ссылку на новую версию. Для этого служит атрибут redirect (перенаправить). При этом пользователь, вероятно, будет автоматически перенаправляться на новую страницу, но рассчитывать на такое поведение вам не следует.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header$ -->

<guide link="/doc/ru/gentoo-x86-install.xml" disclaimer="obsolete" redirect="/doc/ru/handbook/handbook-x86.xml">
<title>Руководство по установке Gentoo x86</title>

<author title="автор">
...

3.  Стиль оформления

Введение

Так как документация Gentoo — коллективная работа, и, скорее всего, каждый существующий документ будут изменять разные люди, необходим общий стиль оформления. Стиль оформления состоит из двух частей. Первая касается внутренней разметки — как размещать теги XML. Вторая относится к оформлению содержимого — как не запутать читателя.

Обе части описаны далее.

Стиль внутренней разметки

Перевод строки необходимо делать непосредственно после каждого тега GuideXML (как открывающего, так и закрывающего), кроме: <version>, <date>, <title>, <th>, <ti>, <li>, <i>, <e>, <uri>, <path>, <b>, <c>, <comment>, <mail>.

Пустые строки необходимо добавлять сразу после каждого употребления <body> (только открывающий тег), и перед каждым <chapter>, <p>, <table>, <author> (перед списком), <pre>, <ul>, <ol>, <warn>, <note> и <impo> (только открывающие теги).

Перенос текста на новую строку должен выполняться при достижении границы в 80 знаков, за исключением содержимого тега <pre>. Отклонение от этого правила допускается, только если нет другого выбора (например, адрес URL превышает максимальную длину строки). Затем текстовый редактор должен перенести остаток строки, начиная с первого же пробела. Следует по возможности ограничивать отображаемое содержимое элементов <pre> в пределах 80 знаков для облегчения восприятия у пользователей консоли.

Отступы использовать нельзя, кроме XML-конструкций, вложенных в теги XML <tr> (в таблице — <table>), <ul>, <ol>, <dl> и <author>. Если отступы используются, каждый отступ должен быть равен ровно двум пробелам. Это означает, что не должно быть знаков табуляции, и не должно быть дополнительных пробелов. Более того, знаки табуляции не разрешены в документах GuideXML.

Обязательны отступы в переносимых строках, когда перенос происходит в конструкциях <ti>, <th>, <li> или <dd>.

Примеры отступов:

<table>
<tr>
  <th>Foo</th>
  <th>Bar</th>
</tr>
<tr>
  <ti>Это пример оформления отступов</ti>
  <ti>
    Если текст не помещается в строки шириной 80 знаков, вы должны делать
    отступы, если родительский тег это позволяет 
  </ti>
</tr>
</table>

<ul>
  <li>Первый пункт</li>
  <li>Второй пункт</li>
</ul>

В атрибутах не допускается использование пробелов между названием атрибута, знаком «=» и значением атрибута. Например:

Неверно:     <pre caption = "Attributes">
Верно  :     <pre caption="Attributes">

Стиль внешнего оформления

В таблицах (<table>) и списках (<ul>, <ol> и <dl>) не следует ставить точки («.»), кроме как между несколькими предложениями. В это случае каждое предложение должно заканчиваться точкой (или другим знаком препинания).

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

<ul>
  <li>Без точки</li>
  <li>С точкой. Несколько предложений, помните?</li>
</ul>

У листингов всегда должна быть подпись (caption).

Старайтесь как можно чаще использовать <uri> с атрибутом link. Иными словами, форумы Gentoo лучше, чем http://forums.gentoo.org.

Комментируя что-либо внутри конструкции <pre>, используйте <comment> и заключайте текст в круглые скобки, или указывайте метку комментария используемого языка (# в сценариях bash и многих других, // в коде C и т.д.) Помещайте комментарий перед предметом комментирования.

(Замените "john" на свое имя пользователя)
# id john

4.  Формат книги

Руководство или книга?

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

Главный файл

Первое изменение — потребность в «главном» документе. Этот документ содержит не сам текст, а ссылки на отдельные модули документации. Синтаксис близок к GuideXML:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<book link="example.xml">
<title>Пример использования книги</title>

<author...>
  ...
</author>

<abstract>
  ...
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<!-- Текст этого документа распространяется на условиях лицензии CC-BY-SA -->
<!-- См. http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>...</version>
<date>...</date>

До этого места нет особенных отличий (кроме указания тега <book>, а не <guide>). Вместо отдельных глав (<chapter>), определяется часть (<part>), которая эквивалентна отдельной «части» книги:

<part>
<title>Часть первая</title>
<abstract>
  ...
</abstract>

(определение нескольких глав)
</part>

Определение каждой части сопровождается названием (<title>) и аннотацией (<abstract>), в которой дается краткое описание содержания части.

В каждой части определяются отдельные главы (<chapter>). Каждая глава должна быть вынесена в отдельный документ. В результате неудивительно, что добавлен специальный тег включения (<include>), позволяющий подключать отдельные документы.

<chapter>
<title>Глава первая</title>
<abstract>
  Это краткое описание первой главы.
</abstract>

  <include href="путь/первая-глава.xml"/>

</chapter>

Создание отдельных глав

Структура отдельной главы организована так:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<!--  The content of this document is licensed under the CC-BY-SA license -->
<!--  See http://creativecommons.org/licenses/by-sa/2.5 -->
<!-- Текст этого документа распространяется на условиях лицензии CC-BY-SA -->
<!-- См. http://creativecommons.org/licenses/by-sa/2.5 -->

<sections>

<version>...</version>
<date>...</date>

(Определите несколько разделов (<section>) и подразделов
(<subsection>))

</sections>

В каждой главе можно определить разделы (<section>), эквивалентные главам (<chapter>) в формате руководства, и подразделы (<subsection>), соответствующие разделам (<section>) в руководстве.

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

5.  Ресурсы

Начинайте писать!

Формат GuideXML специально создан «простым как пробка», чтобы разработчики тратили больше времени на написание документации, и меньше — на изучение общего синтаксиса XML. Мы надеемся, что это позволит разработчикам, которые обычно не «доки в доках», начать самим писать качественную документацию к Gentoo. Возможно, вас заинтересуют наши советы по разработке документации. Если вы желаете помочь (или у вас есть вопросы по GuideXML), пожалуйста, напишите (на английском!) в список рассылки gentoo-doc, указав, что именно вы хотите обсудить, или в чем готовы поучаствовать. Наслаждайтесь!

Текст этого документа распространяется на условиях лицензии Creative Commons - Attribution / Share Alike.