[docs] Re: новый ALT Docs HOWTO: черновик раздела

[Vitaly Ostanin]

Kirill Maslinsky пишет:
> Всем привет!

С возвращением!

<skipped/>

> Правила разметки документации ALT Linux
> 
> Формат DOCBOOK XML был избран для документации потому, 

Скорее, DocBook/XML

> что он позволяет производить смысловую разметку документа, 
> не ориентированную непосредственно на тот или иной конечный 
> формат электронной или печатной публикации. Однако 
> DOCBOOK XML -- это очень обширная спецификация, включающая 
> около 400 понятий. Поэтому у автора или редактора документации 

Здесь Вы называниете понятием теги, а далее в тексте - сущности. 
Если придерживаться устоявшихся терминов, будет меньше путанницы.

> возникают две проблемы, затрудняющие эффективное использование 
> этого инструмента: во-первых, на изучение DOCBOOK XML требуется много 
> времени, которым редко располагает разработчик, документирующий 
> программу. И во-вторых, при разметке документа в DOCBOOK возникают 
> трудности с тем, какой из многочисленных доступных элементов 
> следует выбрать для разметки той или иной части документа. 

Кстати, обе эти проблемы решаются использованием редактора, 
понимающего допустимые в контексте теги, и показывающего 
соответствущий html для тега из DocBook TDG.

> Когда над документацией работает одновременно несколько человек,
> нередко получается разнобой в разметке одинаковых по смыслу 
> элементов, теряется единообразие оформления, в результате документация 
> выглядит неаккуратно, уменьшаются возможности автоматического 
> построения указателей &ITD;
> 
> Для разметки документации в рамках конкретного проекта, в 
> частности, ALTDOCS, достаточно гораздо меньшего количества
> понятий, чем предлагает DOCBOOK. Использование для разметки 
> сравнительно небольшого подмножества DOCBOOK позволяет 
> и быстро освоить разметку, и избежать разнобоя и при этом 
> сохранить все преимущества технологии DOCBOOK.

Уже есть такое подмножество в рамках того же DocBook TC, там 106 
тегов:
http://www.oasis-open.org/docbook/xml/simple/sdocbook/

> Далее описаны принятые в 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 для частей. 

Это не так, docs.dtd не вносит никаких ограничений на типа 
документа. Ограничений на корневые типы вообще не бывает в DTD - 
только в стилях XSLT.

> Обычно пишутся отдельные разделы для
> включения в документацию, для которых нужно использовать
> DOCTYPE section.
> 
> <Пример заголовка>
> 
> 
> <Разделы документа>
> 
> В документах типа section используется один универсальный тег 
> для разметки разделов всех уровней: <section>. Внутри каждого 
> <section> должен обязательно присутствовать <title> -- 
> заголовок соответствующего раздела. За ним следует необязательный
> элемент <sectioninfo>, содержащий информацию о разделе (см. 
> <Информация о документе>) и собственно содержание раздела. 
> Каждый section может содержать как другие разделы <section>, 
> так и собственно текстовые элементы: абзацы, списки, примеры &ITP; 
> (см. ...)
 >
> Элементы <section> могут быть сколько угодно раз вложены друг в друга, причем 
> правильный уровень заголовка и, соответственно, его оформление 
> и нумерация в конечном документе определяется по уровню 
> вложенности элемента <section>.

Здесь можно явно указать, что использование явных уровней 
вложенности (sect1, sect2 и т.д.) недопустимо.

> <Информация о документе>
> 
> В начале документа, непосредственно после открывающего тега 
> <section>, включается элемент <sectioninfo>, в котором следует 
> указать всю необходимую информацию о документе: автора(ов) 
> или переводчиков документа, сведения о существенных изменениях 
> в документе. 
> 
> Автор(ы) должны быть указаны в любом документе. Причем если документ
> состоит из нескольких значительных по объему частей, написанных разными 
> людьми, то желательно указать автора в <sectioninfo> каждого раздела. 
> Впрочем, если несколько человек работали над текстом совместно, то 
> лучше указать всех авторов в общем <sectioninfo> всего документа.

Здесь неясно, нужно ли указывать авторов в sectioninfo вложенных 
section.

> Пример оформления авторов.
> 
> Сведения о постоянных участниках ALTDOCS и авторах многих документов 
> включены в пакет alt-entities (файл persons.xml). Если авторы 
> перечислены в этом файле, то следует использовать более общую форму
> указания автора: 
> 
> пример persons.xml
> 
> Помимо авторов, следует указывать и вклад других людей, работавших над 
> документом: редакторов, переводчиков и пр. 
> 
> пример: <editor>, <othercredit>.

Здесь есть небольшая деталь - в нынешнем состоянии DTD в теге 
othercredit нельзя указать нескольких персон на одно описание 
помощи. Поэтому нужно либо дублировать описание помощи в каждом 
othercredit, либо придумать тег alt:othercredit.

> Если условия распространения документа не отличаются от стандартной лицензии
> FDL, в <sectioninfo> не нужно указывать лицензию и условия распространения -- 
> они указаны для всей документации. Если же документ распространяется на каких-то 
> специфических условиях, следует заполнить тег <legalnotice>: в нем может содержаться
> любой текст, заключенный в элементы <para>.

"в нем может содержаться" - замена Ё на Е сознательна или это 
опечатка?

> <Разметка абзацев>
> 
> Каждый абзац текста в DOCBOOK оформляется при помощи элемента <para>. 

Чтобы было проще запомнить, IMHO, стоит указать, что para - это 
параграф. Ну и абзац тоже.

> Однако сам текст абзаца, особенно в технической документации, не является
> совершенно однородным: в нем встречаются вводимые в первый раз термины, на
> которые пользователю стоит обратить внимание, примеры командной строки, ссылки
> на экранную документацию (man pages), имена файлов, пункты меню, комбинации
> клавиш &ITP;  Чтобы такой текст можно было эффективно использовать для поиска
> информации, стоит так или иначе выделить эти элементы графически.  К некоторым
> из них, например, к именам файлов, также должны применяться особые правила
> переноса. А чтобы текст выглядел аккуратно, очень важно соблюдать единообразие
> оформления, при этом графически выделенных элементов не должно быть слишком
> много. Поэтому очень важно во всем корпусе документации одинаковые по смыслу
> элементы оформлять одними и теми же тегами DOCBOOK.  Ниже приведен список
> внутритекстовых (inline) элементов, которые принято оформлять в проекте
> ALTDOCS. 
> 
> 
> 	<Первое употребление термина>
> 
> Когда вы впервые употребляете термин, важный для дальнейшего понимания 
> документа, или в тот момент, когда вы даете определение этого термина, 
> стоит привлечь к нему внимание читателя, например, выделив курсивом.
> Для этого используется элемент <firstterm>. Последовательное употребление
> <firstterm> также упростит в дальнейшем составление указателя терминов.

Можно добавить, что если нет уверенности, впервые ли употреблён 
термин, и нет желания просматривать на эту тему весь документ, 
можно повторить выделение firstterm - первое вхождение можно 
найти и стилями при обработке документа.

> 	<Имена файлов и каталогов>
> 
> Имена файлов оформляются при помощи элемента <filename>. Полезно отличать
> имена файлов от имен каталогов, добавляя в последнем случае атрибут
> class="directory". 
> При подготовке печатной документации очень важно правильное оформление 
> имен файлов, &IE; это позволит автоматически переносить длинные 
> имена файлов при подготовке печатной документации.
> 
> ВНИМАНИЕ:
> Не следует использовать элемент <filename> не по назначению: в частности, 
> названия пакетов (в базовой форме, например, coreutils) и прочих системных ресурсов 
> не являются именами файлов, их следует оформлять при помощи элемента <systemitem>, 
> подробнее см. раздел <Системные ресурсы>.
> 
> 
> 
> Пример:
> 
> 	<Примеры командной строки>
> 
> Нередко возникает необходимость привести пример команды или команды с 
> аргументами, которую должен будет ввести пользователь. Если этот 
> пример довольно краткий -- ни к чему делать из него выносной пример
> отдельным абзацем (см. <screen>), достаточно графически выделить 
> часть текста (например, другой гарнитурой, общепринято выделение 
> таких фрагментов моноширинным шрифтом или шрифтом без засечек). 
> 
> Пример: 
> 
> Не нужно использовать элементы DOCBOOK <option> и <parameter>, поскольку 
> чрезмерное дробление усложняет и разметку, и восприятие документа, 
> особенно если для каждого элемента используется свой способ 
> графического выделения. Во всех случаях вместо <option> и <parameter>
> следует использовать элемент <command>.

Способ графического выделения в данном случае не аргумент. Если 
автор считает нужным выделить option или parameter, это его право 
и обязанность. К тому же есть ещё refentry, где эти теги особенно 
важны.

Я бы вообще предложил не ограничивать авторов в разметке - только 
от ошибочных тегов.

> Более развернутые примеры, особенно длиной в несколько строк, 
> нужно оформлять при помощи элемента <screen>. Обратите внимание, 
> что в этом элементе сохраняются все пробелы, табуляции и концы строк 
> (как в окружении verbatim в TeX), поэтому старайтесь следить за тем, 
> чтобы в начале строк внутри <screen> не оставалось лишних пробельных
> символов. Элемент <screen> можно использовать
> как внутри абзаца, так и между абзацами.

Здесь можно указать про особенности обработки screen и ему 
подобных стилем tuning.xsl - удаляются пустые строки до и после 
текста. Пустые строки внутри листинга остаются.

<skipped/>

> <Понятия (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. 

Здесь можно добавить ссылку на этот пакет:
http://www.altlinux.ru/index.php?module=sisyphus&package=alt-entities

> Если среди существующих entities все же нет нужных вам, определите 
> их локально, в преамбуле вашего файла документации: 
> 
> Пример:
> 
> Стандартное понятие, которое должно всегда определяться локально в
> преамбуле документа -- &BASEID; -- содержит указание, в какую часть
> дерева документов должен быть включен ваш документ.
> Подробнее об этом см. раздел "ссылки между документами".
> 
> <Ссылки и сноски>
> 
> 	<Сноски>
> 
> Сноски могут присутствовать в любом тексте: абзацах, заголовках разделов
> любого уровня. 
> Для сносок используется элемент <footnote>. Обратите внимание, 
> текст сносок должен быть также заключен в элемент <para>, вложенный
> в <footnote>. 
> 
> Пример: 
> 
> 
> 	<Ссылки на ресурсы URL>
> 
> Для ссылок на ресурсы при помощи URL в DocBook предусмотрен элемент
> <ulink>. Внутрь элемента помещается текст ссылки, а в значение атрибута 
> url -- адрес. 
> Пример:
> 
> 	<Ссылки на экранную документацию>
> 
> Для ссылок на экранную документацию (man pages) предназначен элемент
> <citerefentry>. Номер раздела, к которому относится документация, оформляется 
> при помощи элемента <manvolnum>. 
> 
> 	<Ссылки на литературу>
> 
> Группа элементов DocBook, предназначенная для оформления ссылок на литературу, 
> требует для оформления каждой ссылки заполнить достаточно громоздкую 
> конструкцию библиографического описания в виде XML. Пока не придуман 
> удобный способ упростить или автоматизировать эту разметку, используйте 
> обычные сноски для ссылок на литературу. 

Удобный способ - это WYSIWYM редактор.

> 	<Ссылки на другие части документа>
> 
> /использовать Останинский текст/

Пока не надо. Например, благодаря работе Олега Паращенко в 
tuning.xsl добавлено преобразование olink в link в случае 
нахождения ссылки и цели в одном документе.

> DocBook предлагает развитый и гибкий механизм гиперссылок. Из них могут 
> пригодиться: элемент <link> -- обычная гиперссылка на любой элемент в 
> в том же документе, в атрибуте endterm помещается id элемента, на который
> вы хотите сослаться. Соответственно, нужно убедиться, что этот id 
> будет указан как атрибут искомого элемента. Если вы хотите сослаться
> на конкретное место в тексте, а не элемент, (например, "см. ниже"), 
> можно использовать элемент <anchor> с соответствующим id. В самом элементе 
> <link> должен содержаться текст ссылки.
> 
> Пример: 
> 
> Более универсальный механизм ссылок предлагает элемент <xref>, когда 
> текст ссылки генерируется автоматически, на основе названия и 
> специальных атрибутов того элемента, на который указывает ссылка. 
> Подробнее о вариантах работы <xref> см. в документации по DocBook.
> 
> Пример:
> 
> ВНИМАНИЕ!
> В настоящий момент элементы <xref> не вполне корректно обрабатываются
> db2latex при создании печатной версии документа. В этом случае 
> не происходит автоматической генерации текста ссылки, поэтому 
> нужно убедиться, что элемент <xref> имеет атрибут endterm, указывающий
> на id элемента, содержимое которого будет использовано как текст ссылки. 
> Скорее всего, таким элементом окажется <title>. В случае генерации 
> html это не требуется, <xref> будет обработан правильно.

Есть предложение забить на db2latex полностью, и использовать для 
создания печатного вывода OpenOffice. Насколько я понял, 
существуют стили для преобразования DocBook -> OOo. У OOo сейчас 
вполне симпатичные pdf получаются.

> <Списки>
> 
> Обычно в документации используются списки трех основных видов: 
> нумерованные, ненумерованные (аналогично окружению itemize в TeX), поименованные 
> (окружение description в TeX). Нумерованные списки в DocBook размечаются
> при помощи элемента <orderedlist> (окружение enumerate в TeX).

Элемент variablelist предназначен также для разметки любых 
структур, например, дерева каталогов (уточнялось в рассылке 
docbook at oasis-open.org).

> Пример:
> 
> Ненумерованные списки -- элемент <itemizedlist>
> 
> Пример:
> 
> Поименованные списки -- элемент <variablelist>
> 
> Пример:
> 
> Обратите внимание, что каждый элемент <varlistitem> может
> содержать более одного <term>.
> 
> DocBook позволяет давать название любому типу списка 
> (элемент <title>), однако с точки зрения оформления 
> и логической структуры документа такие названия обычно 
> нежелательны. 

У DocBook TC на этот счёт другое мнение :) Действительно, чем 
мешает title ?

> Поэтому прежде чем использовать элемент <title>, 
> внутри списка, подумайте, насколько он действительно необходим.
> 
> <Предостережения и замечания>
> 
> В пользовательской документации часто полезно обращать внимание
> читателя на "опасные места" и подводные камни, где многие 
> пользователи совершают ошибки. Такие замечания обычно 
> выделяются из основного текста при помощи рамок
> и цветных или серых плашек. В DOCBOOK предусмотрен ряд элементов 
> для подобного рода замечаний разного уровня строгости. 
> В документации для ALT Linux рекомендуется использовать два из 
> них: <note> и <important>. В русскоязычных документах 
> эти элементы будут озаглавлены "Важно" и "Внимание" соответственно.

Поскольку такие замечания со временем могут устаревать, например:
"Текущая версия установщика может некорректно определить 
встроенное оборудование на чипсетах .... "
можно размечать такие замечания с атрибутом @role='temp' для 
последующего отлова стилями и передачи корректору на предмет 
актуальности.

> Пример:
> 
> <Названия дистрибутивов 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. 
> (см. об этом ненаписанный пока раздел).

Я бы всё-таки предпочёл сделать этот текст не новым ALT Docs 
HOWTO, и параллельным ALT Docs Guidelines или что-нибудь в этом 
роде. У меня тлеет надежда обновить docs-howto, но несколько 
другим образом, в частности, используя litprog из стилей и Makefiles.

-- 
Regards, Vyt
mailto:  vyt at vzljot.ru
JID:     vyt at vzljot.ru
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 252 bytes
Desc: OpenPGP digital signature
Url : http://lists.altlinux.ru/pipermail/docs/attachments/20040809/252e7911/signature-0001.bin