Советы по разработке документации

1.  Настройка вашей собственной среды

Локальная среда для участников

Создайте отдельный каталог, предназначенный исключительно для разработки документации. В качестве примера мы используем ~/work/gentoo/doc. В этом каталоге создайте подкаталог, в котором вы будете хранить актуальную английскую документацию (например, en/).

Загрузите архив самой свежей английской документации:

$ wget http://www.gentoo.org/dyn/doc-snapshots/docs-latest-en.tar.bz2

Распакуйте документацию в каталог en/. Теперь у вас есть актуальный снимок английской документации. Каждый раз, при желании обновить снимок, вы можете заново загрузить архив, но также можно загрузить документ с сайта, добавив ?passthru=1 к его адресу URL. Например:

$ wget http://www.gentoo.org/doc/en/alsa-guide.xml?passthru=1 -O alsa-guide.xml

Если вы собираетесь участвовать в переводе документов, создайте каталог для хранения текущих переводов на ваш язык:

$ mkdir ${LANG}
$ cd ${LANG}
$ wget http://www.gentoo.org/dyn/doc-snapshots/docs-latest-${LANG}.tar.bz2
$ tar xvjf docs-latest-*.tar.bz2

При обновлении документа всегда сначала копируйте его из ${LANG}/ в корневой каталог (~/work/gentoo/doc) , а затем редактируйте копию. Вам нужно сохранять оригинал, чтобы создать файл исправлений:

$ diff -U6 ${LANG}/alsa-guide.xml alsa-guide.xml > alsa-guide.diff

Веб-доступ в репозиторий CVS

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

Локальный репозиторий (для разработчиков)

Создайте рабочий каталог специально для Gentoo, например, ~/work/gentoo/doc. Затем создайте подкаталог cvs/, чтобы поместить в него снимок CVS:

$ mkdir cvs; cd cvs/
$ export CVSROOT=<ваш ник>@cvs.gentoo.org:/var/cvsroot
$ cvs co doc

Для обновления снимка CVS запускайте команду cvs update -dP в каталоге cvs/doc.

2.  Тестирование GuideXML

Cреда тестирования

Сначала создайте каталог test/, где будут находиться guide.dtd, main.css и несколько картинок:

$ mkdir -p test/{css,images}
$ cd test
$ wget -P css/ http://www.gentoo.org/css/main.css
$ wget -P images/ http://www.gentoo.org/images/gridtest.gif \
  http://www.gentoo.org/images/gentoo-new.gif \
  http://www.gentoo.org/images/gtop-www.jpg

Теперь загрузите специальную версию guide.xsl, расположенную на странице neysx. Эта версия приспособлена для преобразования GuideXML в HTML на локальных машинах и поддерживает множество языков. Также есть ссылка на значительно более краткий вариант, поддерживающий только английский.

$ wget http://dev.gentoo.org/~neysx/guide.xsl
( или, если все что нужно - это английский)
$ wget -O guide.xsl http://dev.gentoo.org/~neysx/guide-en.xsl

Наконец, от имени root добавьте в /etc/xml/catalog следующую строку (между тегами catalog - прим. пер.):

<rewriteURI uriStartString="/dtd" rewritePrefix="/usr/portage/metadata/dtd/"/>

Если ваш /etc/xml/catalog пуст или не содержит ни одной записи, вам потребуется вставить элемент <rewriteURI> внутри элемента <catalog>:

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>
</catalog>

Кроме того, в некоторых файлах может быть указан DTD, находящийся в сети, с адресом URI, подобным http://www.gentoo.org/dtd/guide.dtd. Такие ссылки вы также можете заменить, исключив медленное обращение к сети:

<rewriteURI uriStartString="http://www.gentoo.org/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>

Тестирование документации Gentoo

Чтобы протестировать документ Gentoo, сначала запустите xmllint (из dev-libs/libxml2), чтобы убедиться, что в нем используется корректный XML:

$ xmllint --valid --noout alsa-guide.xml

Если xmllint ничего не возвращает, то файл не содержит ошибок (относящихся к тегам XML). Затем нужно преобразовать его в HTML с помощью xsltproc (из dev-libs/libxslt)

$ xsltproc test/guide.xsl alsa-guide.xml > test/alsa-guide.html

Если не выводятся сообщения об ошибках, вы скорее всего сможете открыть в браузере файл file:///home/user/work/gentoo/doc/test/alsa-guide.html для просмотра получившегося документа. В противном случае, исправляйте документ, пока он не станет безошибочным.

Тестирование настольной книги Gentoo

Настольная книга Gentoo разделена на главы. Для обработки отдельной главы, практически такой же, какая выполняется нашим веб-сервером, нужно использовать как файл handbook-x86.xml, так и требуемый hb-файл (например, hb-install-about.xml). Еще нужно передать xsltproc те же параметры, которые используются при просмотре настольной книги, а именно part и chap. Ниже приведен пример проверки hb-install-about.xml. Имейте в виду, что требуется наличие всех файлов, из которых состоит книга.

$ xmllint --valid --noout handbook-x86.xml
$ xmllint --valid --noout hb-install-about.xml
$ xsltproc --stringparam part 1 --stringparam chap 1 test/guide.xsl handbook-x86.xml > test/hb-install-about.html

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

$ xmllint --valid --noout hb-install-about.xml
$ xsltproc test/guide.xsl hb-install-about.xml > test/hb-install-about.html

3.  Использование axkit

Некоторые разработчики документации предпочитают использовать конфигурацию axkit, подобную той, что запущена на http://www.gentoo.org. Здесь приведены рекомендации, которые помогут настроить сходную конфигурацию.

Сначала установите требуемые пакеты:

(проверка доступности пакетов для portage)
# emerge -vp =dev-libs/libxml2-2.6.17 =dev-libs/libxslt-1.1.12 \
=dev-perl/AxKit-1.6.1 =dev-perl/XML-XPath-1.13 =dev-perl/XML-LibXML-1.58 \
=dev-perl/XML-LibXSLT-1.57 =dev-perl/XML-Parser-2.34 =net-www/apache-1.3.33

These are the packages that I would merge, in order:

Calculating dependencies ...done!
[ebuild   R   ] dev-libs/libxml2-2.x.17  -debug -ipv6 +python +readline  0 kB 
[ebuild   R   ] dev-libs/libxslt-1.1.12  +crypt +python  0 kB 
[ebuild   R   ] dev-perl/AxKit-1.6.1  +gnome  0 kB 
[ebuild   R   ] dev-perl/XML-XPath-1.13   0 kB 
[ebuild   R   ] dev-perl/XML-LibXML-1.58   0 kB 
[ebuild   R   ] dev-perl/XML-LibXSLT-1.57   0 kB 
[ebuild   R   ] dev-perl/XML-Parser-2.34   0 kB
[ebuild   R   ] net-www/apache-1.3.33  +pam  0 kB

(установка пакетов)
# emerge =dev-libs/libxml2-2.6.17 =dev-libs/libxslt-1.1.12 \
=dev-perl/AxKit-1.6.1 =dev-perl/XML-XPath-1.13 =dev-perl/XML-LibXML-1.58 \
=dev-perl/XML-LibXSLT-1.57 =dev-perl/XML-Parser-2.34 =net-www/apache-1.3.33

Затем измените следующие конфигурационные файлы:

(внутри)
<IfModule mod_dir.c>
  (добавьте index.xml в список)
  DirectoryIndex index.xml index.html index.php index.php3 index.shtml index.cgi index.pl index.htm Default.htm default.htm
</IfModule>

(добавьте следующие строки)
<IfDefine PERL>
  LoadModule perl_module extramodules/libperl.so
#  AddModule mod_perl.c
  PerlModule AxKit
  SetHandler perl-script
  PerlHandler Apache::AxKit::StyleChooser::PathInfo AxKit
  AddHandler axkit .xml .xsp
  AxAddPlugin Apache::AxKit::StyleChooser::QueryString
  AxAddXSPTaglib AxKit::XSP::Util
  AxAddXSPTaglib AxKit::XSP::IfParam
  AxAddXSPTaglib AxKit::XSP::Param
  AxAddStyleMap application/x-xsp Apache::AxKit::Language::XSP
  AxAddStyleMap text/xsl Apache::AxKit::Language::LibXSLT
  <AxStyleName "#default">
    AxAddProcessor text/xsl /xsl/guide.xsl
  </AxStyleName>
  <AxStyleName printable>
    AxAddProcessor text/xsl /xsl/guide-print.xsl
  </AxStyleName>
</IfDefine>

(внутри)
<IfModule mod_alias.c>
    Alias /icons/ /var/www/localhost/icons/
(закомментируйте следующую строку)
    #Alias /doc /usr/share/doc

(добавьте -D PERL к списку параметров)
APACHE_OPTS="-D PERL"

Потом скопируйте файлы документации, включая DTD и таблицы стилей, в /var/www/localhost/htdocs/. Вам потребуются каталоги css/,doc/, dtd/, images/ и xsl/. Разработчики Gentoo могут скопировать их из своей локальной копии CVS, или создать на нее символические ссылки. Другим участникам потребуется загрузить файлы через наш интерфейс viewCVS.

Остается только запустить apache сервер:

# /etc/init.d/apache start
# (добавьте его к своему уровню запуска, если хотите, чтобы)
# (он запускался автоматически во время загрузки)
# rc-update add apache default

Если вы установили axkit на свою рабочую станцию, перейдите в браузере по адресу http://your_server/doc/en/ или просто http://localhost/doc/en/. Журнал доступа можно проверить в /var/log/apache/access_log, а журнал ошибок - в /var/log/apache/error_log.

4.  Часто задаваемые вопросы

Как преобразовать файл в UTF-8?

Существует немало утилит, которые могут помочь вам. Одна из популярных - app-text/recode. Еще одна - iconv, входящая в sys-libs/glibc.

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

Например, преобразовать документ из ISO-8859-15 (также известной как Latin-9) в UTF-8, можно следующей командой:

(l9 = ISO-8859-15, u8 = UTF-8)
$ recode l9..u8 file.xml

5.  Советы по подготовке документации к публикации

Проверка правильности тегов <guide>

Убедитесь, что атрибут <guide link> указывает на верное расположение руководства, обычно /doc/${LANG}/filename.xml. Если у вас перевод документа, всегда указывайте абсолютный путь к документу (например, (/doc/${LANG}/). При написании руководства, использующего DTD guide или book, можно указывать как /doc/${LANG}/filename.xml, так и filename.xml. Обычно в GDP рекомендуется использование первого варианта.

Проверка ссылок

Необходимо убедиться, что все гиперссылки в вашем документе работают. Если это перевод документа, удостоверьтесь, что все ссылки на другие переведенные документы указывают на существующие файлы.

Проверка знаков табуляции

Знаки табуляции категорически запрещены в документах GuideXML, кроме случаев, когда их использование обязательно (например, когда документ указывает пользователю использовать знаки табуляции). Для проверки документа на знаки табуляции запустите grep "CTRL+V<TAB>" file.xml. Исправьте все строки, которые выведет grep.

Система Bugzilla

Закончив свой документ, направьте его команде документации через Bugzilla (англ.). Сведения о платформе, сообщениях emerge info, архитектуре, действиях по воспроизведению и т.п., указывать не надо. Если у вас перевод документа, обязательно укажите в запросе компонент Doc Translations. Также включите осмысленное краткое описание своего перевода в принятом формате: "[ru] New translation: /doc/ru/gnupg-user.xml". [ru] замените на двухбуквенный код своего языка.

По умолчанию, ваш запрос назначается docs-team@gentoo.org; изменять поле назначенца не нужно.

При приложении файлов и заплаток к запросу указывайте формат «plain text (text/plain)». Не выбирайте «XML source (application/xml)», даже если прикладываете файл .xml. Для заплаток нужно отметить пункт «Patch». Не направляйте архивы, полные документов: прикладывайте каждый документ или заплатку по отдельности.

6.  Часто допускаемые опасные ошибки

Не учтена архитектурная независимость настольной книги Gentoo

Файлы в [gentoo]/xml/htdocs/doc/en/handbook, которые не оканчиваются на "-<arch>.xml", используются во всех настольных книгах. Это значит, что все в них должно быть архитектурно независимым.

Если необходимо внести изменения, отражающие вашу архитектуру, и вам кажется, что это следует сделать в подобном файле, сначала спросите в gentoo-doc@gentoo.org, как с этим разобраться. Иногда находятся способы, позволяющие не создавать трудности пользователям других архитектур.

Не изменена или неправильно изменена версия/дата

В соответствии с требованиями, вы должны обновлять версию/дату, внося определенные изменения. Хотя версия менее важна (SwifT все равно убьет вас, если вы о ней забудете), с помощью даты наши пользователи определяют, когда документ изменялся в последний раз.

Увеличение номера версии обязательно, когда вы вносите изменения в содержание документа (инструкции, примеры кода и т.д.). При изменениях не по содержанию (например, при исправлении опечатки или разметки GuideXML) обновление версии обычно не нужно.

При обновлении настольной книги исправляйте дату и версию только тех файлов, которые вы действительно изменяли. Не трогайте файлы handbook-ARCH.xml, если вы не изменяли именно их.

Еще одна распространенная ошибка — обновление номера версии, как будто он является десятичным числом. Это не так. 3.9 должен становиться 3.10, а не 4.0 или 3.91.

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