[docs] новый ALT Docs HOWTO: черновик раздела
Kirill Maslinsky
kirill на altlinux.ru
Пн Авг 9 02:14:30 MSD 2004
Всем привет!
Мир не стоит на месте и проект docs@ меняется, причем довольно
значительно, а главный (и единственный) текст, который описывает,
что такое проект docs@ и как с ним работать не обновляется уже
давно, да многих разделов там и в принципе нет (например задач, истории
и участников проекта). Для любого нового человека это очень серьезный барьер
для вступления в проект. Поэтому чтобы избежать бесконечного
бега по кругу по граблям, я начал записывать собственный
опыт работы в docs@ -- получились наброски для нескольких
разделов ALT Docs HOWTO.
Сейчас почти готов раздел про требования к разметке текстов,
какими они представляются мне (а сейчас именно мне приходится
заниматься разметкой и это большой объем работы).
Осталось только добавить в этот текст примеры на XML и разметить
в описанном формате ;). Но прежде я надеюсь, что все заинтересованные
его хотя бы просмотрят и (хотя он вышел и не очень коротким)
выскажут свои замечания и соображения (см. аттачмент).
Продолжение следует.
--
Kirill Maslinsky
ALT Linux Team * Documentation Project
-------------- next part --------------
Правила разметки документации ALT Linux
Формат DOCBOOK XML был избран для документации потому,
что он позволяет производить смысловую разметку документа,
не ориентированную непосредственно на тот или иной конечный
формат электронной или печатной публикации. Однако
DOCBOOK XML -- это очень обширная спецификация, включающая
около 400 понятий. Поэтому у автора или редактора документации
возникают две проблемы, затрудняющие эффективное использование
этого инструмента: во-первых, на изучение DOCBOOK XML требуется много
времени, которым редко располагает разработчик, документирующий
программу. И во-вторых, при разметке документа в DOCBOOK возникают
трудности с тем, какой из многочисленных доступных элементов
следует выбрать для разметки той или иной части документа.
Когда над документацией работает одновременно несколько человек,
нередко получается разнобой в разметке одинаковых по смыслу
элементов, теряется единообразие оформления, в результате документация
выглядит неаккуратно, уменьшаются возможности автоматического
построения указателей &ITD;
Для разметки документации в рамках конкретного проекта, в
частности, ALTDOCS, достаточно гораздо меньшего количества
понятий, чем предлагает DOCBOOK. Использование для разметки
сравнительно небольшого подмножества DOCBOOK позволяет
и быстро освоить разметку, и избежать разнобоя и при этом
сохранить все преимущества технологии DOCBOOK.
Далее описаны принятые в ALTDOCS правила оформления
документа. Предполагается, что читатель знаком с основами
языка XML, терминами "элемент" (element) и "понятие" (entity).
<!--FIXME: поставить ссылку на электронный ресурс с документацией по XML -->
<Указание типа документа>
В проекте ALTDOCS используется не стандартный формат docbookx,
а его расширение docs.dtd. В него включается весь docbookx
целиком и добавляются специфические для ALT Linux понятия
(entities), а также дополнительное пространство имен (xmlns:alt)
и тег для ссылки на названия дистрибутивов ALT Linux (alt:distro).
Поэтому во всех документах, оформленных в docbook для ALT Linux,
в качестве DTD следует указывать docs.dtd. docs.dtd поддерживает
два основных типа документа: book для объединяющих документов
и section для частей. Обычно пишутся отдельные разделы для
включения в документацию, для которых нужно использовать
DOCTYPE section.
<Пример заголовка>
<Разделы документа>
В документах типа section используется один универсальный тег
для разметки разделов всех уровней: <section>. Внутри каждого
<section> должен обязательно присутствовать <title> --
заголовок соответствующего раздела. За ним следует необязательный
элемент <sectioninfo>, содержащий информацию о разделе (см.
<Информация о документе>) и собственно содержание раздела.
Каждый section может содержать как другие разделы <section>,
так и собственно текстовые элементы: абзацы, списки, примеры &ITP;
(см. ...)
Элементы <section> могут быть сколько угодно раз вложены друг в друга, причем
правильный уровень заголовка и, соответственно, его оформление
и нумерация в конечном документе определяется по уровню
вложенности элемента <section>.
<Информация о документе>
В начале документа, непосредственно после открывающего тега
<section>, включается элемент <sectioninfo>, в котором следует
указать всю необходимую информацию о документе: автора(ов)
или переводчиков документа, сведения о существенных изменениях
в документе.
Автор(ы) должны быть указаны в любом документе. Причем если документ
состоит из нескольких значительных по объему частей, написанных разными
людьми, то желательно указать автора в <sectioninfo> каждого раздела.
Впрочем, если несколько человек работали над текстом совместно, то
лучше указать всех авторов в общем <sectioninfo> всего документа.
Пример оформления авторов.
Сведения о постоянных участниках ALTDOCS и авторах многих документов
включены в пакет alt-entities (файл persons.xml). Если авторы
перечислены в этом файле, то следует использовать более общую форму
указания автора:
пример persons.xml
Помимо авторов, следует указывать и вклад других людей, работавших над
документом: редакторов, переводчиков и пр.
пример: <editor>, <othercredit>.
Если условия распространения документа не отличаются от стандартной лицензии
FDL, в <sectioninfo> не нужно указывать лицензию и условия распространения --
они указаны для всей документации. Если же документ распространяется на каких-то
специфических условиях, следует заполнить тег <legalnotice>: в нем может содержаться
любой текст, заключенный в элементы <para>.
<Разметка абзацев>
Каждый абзац текста в DOCBOOK оформляется при помощи элемента <para>.
Однако сам текст абзаца, особенно в технической документации, не является
совершенно однородным: в нем встречаются вводимые в первый раз термины, на
которые пользователю стоит обратить внимание, примеры командной строки, ссылки
на экранную документацию (man pages), имена файлов, пункты меню, комбинации
клавиш &ITP; Чтобы такой текст можно было эффективно использовать для поиска
информации, стоит так или иначе выделить эти элементы графически. К некоторым
из них, например, к именам файлов, также должны применяться особые правила
переноса. А чтобы текст выглядел аккуратно, очень важно соблюдать единообразие
оформления, при этом графически выделенных элементов не должно быть слишком
много. Поэтому очень важно во всем корпусе документации одинаковые по смыслу
элементы оформлять одними и теми же тегами DOCBOOK. Ниже приведен список
внутритекстовых (inline) элементов, которые принято оформлять в проекте
ALTDOCS.
<Первое употребление термина>
Когда вы впервые употребляете термин, важный для дальнейшего понимания
документа, или в тот момент, когда вы даете определение этого термина,
стоит привлечь к нему внимание читателя, например, выделив курсивом.
Для этого используется элемент <firstterm>. Последовательное употребление
<firstterm> также упростит в дальнейшем составление указателя терминов.
<Имена файлов и каталогов>
Имена файлов оформляются при помощи элемента <filename>. Полезно отличать
имена файлов от имен каталогов, добавляя в последнем случае атрибут
class="directory".
При подготовке печатной документации очень важно правильное оформление
имен файлов, &IE; это позволит автоматически переносить длинные
имена файлов при подготовке печатной документации.
ВНИМАНИЕ:
Не следует использовать элемент <filename> не по назначению: в частности,
названия пакетов (в базовой форме, например, coreutils) и прочих системных ресурсов
не являются именами файлов, их следует оформлять при помощи элемента <systemitem>,
подробнее см. раздел <Системные ресурсы>.
Пример:
<Примеры командной строки>
Нередко возникает необходимость привести пример команды или команды с
аргументами, которую должен будет ввести пользователь. Если этот
пример довольно краткий -- ни к чему делать из него выносной пример
отдельным абзацем (см. <screen>), достаточно графически выделить
часть текста (например, другой гарнитурой, общепринято выделение
таких фрагментов моноширинным шрифтом или шрифтом без засечек).
Пример:
Не нужно использовать элементы DOCBOOK <option> и <parameter>, поскольку
чрезмерное дробление усложняет и разметку, и восприятие документа,
особенно если для каждого элемента используется свой способ
графического выделения. Во всех случаях вместо <option> и <parameter>
следует использовать элемент <command>.
Более развернутые примеры, особенно длиной в несколько строк,
нужно оформлять при помощи элемента <screen>. Обратите внимание,
что в этом элементе сохраняются все пробелы, табуляции и концы строк
(как в окружении verbatim в TeX), поэтому старайтесь следить за тем,
чтобы в начале строк внутри <screen> не оставалось лишних пробельных
символов. Элемент <screen> можно использовать
как внутри абзаца, так и между абзацами.
<Цитаты, заменяемый текст и кавычки>
Для включения цитат в текст используется элемент <quote>. Обратите
внимание, что его следует использовать именно для цитат или слов,
употребленных в непрямом значении. Если вы хотите взять в кавычки
какую-то строку, чтобы отличить ее от простого текста (привести пример
записи в конфигурационном файле, пароля для пользователя,
значения какого-либо параметра &ITP;), следует использовать элемент <literal>.
Для строк, которые пользователь должен при вводе заменить на конкретную
нужную ему строку, подходит элемент <replaceable>, текст, заключенный в
этот элемент, будет выделен графически (обычно курсивом или наклонным
шрифтом).
Для развернутых цитат (длиной в абзац и более) желательно использовать специальный элемент
<blockquote>, он может встречаться как внутри абзаца, так и между
абзацами.
ВНИМАНИЕ!
Нельзя ставить знак кавычек в явной форме. Используйте элементы
<quote> и <literal>. Если вы хотите закавычить названия элементов
графического интерфейса, используйте соответствующие элементы DOCBOOK
(см. раздел "Элементы графического интерфейса").
<Элементы графического интерфейса: меню, кнопки, поля>
При описании графического интерфейса программ более чем часто возникает
необходимость ссылаться как на отдельные пункты меню, так и на
последовательность подпунктов меню, которые должен выбрать пользователь.
Отдельные меню оформляются элементом <guimenu>, конкретные пункты
меню -- <guimenuitem>.
Путь к определенному пункту в структуре меню (последовательный выбор
подменю) должен быть заключен в элемент <menuchoice>, внутри
которого содержится последовательность из элементов <guimenu>,
<guisubmenu>, <guimenuitem>. Такое оформление позволяет
автоматически расставлять знаки перехода к следующему меню (обычно
это что-то, напоминающее стрелки), обеспечивая единообразие в
оформлении и выбор подходящих символов при электронной и печатной
публикации документа.
В случае, если нужно обозначить элемент графического интерфейса, который
не является меню, но представляет одну из возможностей выбора для
пользователя, например, поле, которое нужно заполнить, или checkbox,
который нужно отметить, используйте элемент <guilabel>.
Названия графических кнопок (buttons) оформляются при помощи <guibutton>.
<Сочетания клавиш>
Отдельная клавиша оформляется при помощи элемента <keycap>, если нужно
описать сочетание клавиш -- используйте элемент <keycombo>. <keycombo>
содержит последовательность элементов <keycap>. Обратите внимание,
что в проекте ALTDOCS заранее определены понятия (entities) для
большинства часто используемых клавиш (см. раздел про entities).
<Системные ресурсы>
Для разного рода ресурсов, составляющих часть описываемой системы
используется элемент <systemitem> с различными значениями параметра
class. В настоящее время systemitem используется для обозначения
- имен пользователей
<systemitem class="username"/>
- названий групп пользователей
<systemitem class="groupname">
- IP-адресов
<systemitem class="ipaddress">
- названий пакетов
<systemitem class="resource">
Обычно текст, оформленный при помощи тега systemitem, никак не выделяется
графически в конечном документе, однако этот тег может указывать на важные
особенности обработки содержащегося в нем текста (например, правила
переноса IP-адресов).
Есть надежда впоследствии использовать теги systemitem для составления
указателя.
<Понятия (entities)>
Если в вашем тексте много раз используется название той или иной программы,
протокола, устройства и др., есть смысл оформить его при помощи сущности
(entity), которая представляет собой просто сокращение, макроопределение,
раскрывающееся в строку с разметкой или без разметки DocBook.
Использование entities позволяет урегулировать разное обозначение
одних и тех же понятий (например, GNU General Public License) и
избежать лишних опечаток. В проекте ALTDOCS уже определены многие часто
употребляющиеся в документации ALTLINUX сущности, поэтому прежде
чем создавать собственные entities, посмотрите, нет ли нужных вам
сущностей среди уже определенных. Все сущности для документации
ALTLINUX находятся в пакете alt-entities, в файлах common.ent, keys.ent,
faq.ent, jabber.ent.
Внимание!
Список entities периодически пополняется, поэтому прежде чем браться
за написание или разметку документации, убедитесь, что у вас установлен
самая последняя версия пакета alt-entities.
Если среди существующих entities все же нет нужных вам, определите
их локально, в преамбуле вашего файла документации:
Пример:
Стандартное понятие, которое должно всегда определяться локально в
преамбуле документа -- &BASEID; -- содержит указание, в какую часть
дерева документов должен быть включен ваш документ.
Подробнее об этом см. раздел "ссылки между документами".
<Ссылки и сноски>
<Сноски>
Сноски могут присутствовать в любом тексте: абзацах, заголовках разделов
любого уровня.
Для сносок используется элемент <footnote>. Обратите внимание,
текст сносок должен быть также заключен в элемент <para>, вложенный
в <footnote>.
Пример:
<Ссылки на ресурсы URL>
Для ссылок на ресурсы при помощи URL в DocBook предусмотрен элемент
<ulink>. Внутрь элемента помещается текст ссылки, а в значение атрибута
url -- адрес.
Пример:
<Ссылки на экранную документацию>
Для ссылок на экранную документацию (man pages) предназначен элемент
<citerefentry>. Номер раздела, к которому относится документация, оформляется
при помощи элемента <manvolnum>.
<Ссылки на литературу>
Группа элементов DocBook, предназначенная для оформления ссылок на литературу,
требует для оформления каждой ссылки заполнить достаточно громоздкую
конструкцию библиографического описания в виде XML. Пока не придуман
удобный способ упростить или автоматизировать эту разметку, используйте
обычные сноски для ссылок на литературу.
<Ссылки на другие части документа>
/использовать Останинский текст/
DocBook предлагает развитый и гибкий механизм гиперссылок. Из них могут
пригодиться: элемент <link> -- обычная гиперссылка на любой элемент в
в том же документе, в атрибуте endterm помещается id элемента, на который
вы хотите сослаться. Соответственно, нужно убедиться, что этот id
будет указан как атрибут искомого элемента. Если вы хотите сослаться
на конкретное место в тексте, а не элемент, (например, "см. ниже"),
можно использовать элемент <anchor> с соответствующим id. В самом элементе
<link> должен содержаться текст ссылки.
Пример:
Более универсальный механизм ссылок предлагает элемент <xref>, когда
текст ссылки генерируется автоматически, на основе названия и
специальных атрибутов того элемента, на который указывает ссылка.
Подробнее о вариантах работы <xref> см. в документации по DocBook.
Пример:
ВНИМАНИЕ!
В настоящий момент элементы <xref> не вполне корректно обрабатываются
db2latex при создании печатной версии документа. В этом случае
не происходит автоматической генерации текста ссылки, поэтому
нужно убедиться, что элемент <xref> имеет атрибут endterm, указывающий
на id элемента, содержимое которого будет использовано как текст ссылки.
Скорее всего, таким элементом окажется <title>. В случае генерации
html это не требуется, <xref> будет обработан правильно.
<Списки>
Обычно в документации используются списки трех основных видов:
нумерованные, ненумерованные (аналогично окружению itemize в TeX), поименованные
(окружение description в TeX). Нумерованные списки в DocBook размечаются
при помощи элемента <orderedlist> (окружение enumerate в TeX).
Пример:
Ненумерованные списки -- элемент <itemizedlist>
Пример:
Поименованные списки -- элемент <variablelist>
Пример:
Обратите внимание, что каждый элемент <varlistitem> может
содержать более одного <term>.
DocBook позволяет давать название любому типу списка
(элемент <title>), однако с точки зрения оформления
и логической структуры документа такие названия обычно
нежелательны. Поэтому прежде чем использовать элемент <title>,
внутри списка, подумайте, насколько он действительно необходим.
<Предостережения и замечания>
В пользовательской документации часто полезно обращать внимание
читателя на "опасные места" и подводные камни, где многие
пользователи совершают ошибки. Такие замечания обычно
выделяются из основного текста при помощи рамок
и цветных или серых плашек. В DOCBOOK предусмотрен ряд элементов
для подобного рода замечаний разного уровня строгости.
В документации для ALT Linux рекомендуется использовать два из
них: <note> и <important>. В русскоязычных документах
эти элементы будут озаглавлены "Важно" и "Внимание" соответственно.
Пример:
<Названия дистрибутивов ALT Linux>
Нередко документация, написанная для одного из дистрибутивов
ALT Linux, с незначительными изменениями применима и к другим
дистрибутивам. При этом некоторые изменения оказываются
вполне регулярными и могут быть выполнены автоматически.
В частности, так происходит с названием документируемого
дистрибутива, которое периодически встречается в тексте.
В docs.dtd определен специальный элемент для названия
документируемого дистрибутива: <alt:distro/>. Этот элемент
не имеет парного закрывающего тега и не содержит текста
внутри. Вариант написания (краткое-полное) названия
дистрибутива определяется значением атрибута longname.
По умолчанию тег раскрывается в название линейки
дистрибутивов (без номера версии), например, если описывается
дистрибутив ALT Linux 2.3 Junior, <alt:docs/>
может быть раскрыто в Junior.
<alt:distro longname="version"/> даст в этом случае
ALT Linux 2.3, а <alt:distro longname="full"/> --
ALT Linux 2.3 Junior. Строки, в которые будет раскрыт
тег <alt:distro/>, определяются при сборке документации
при помощи параметров XSL alt-distro, alt-distro-version, alt-distro-full.
Другие возможности автоматического профилирования документа
для другого дистрибутива или новой версии могут быть реализованы
при помощи механизма профилирования DOCBOOK.
(см. об этом ненаписанный пока раздел).
Подробная информация о списке рассылки docs