Создание документации

Документация в репозитории/дистрибутивах

В рамках проекта создаётся документация, призванная помочь пользователям в освоении Linux.

• Печатная документация
• Электронная документация

Печатная документация

Печатная документация прилагается к дистрибутивам, выпускаемым ALT Linux в виде брошюр, руководств и т.п. Другой вид печатной документации -- отдельные книги, учебники и т.п.

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

Электронная документация

Главное в документации -- это конечно сами тексты. Каждый отдельно взятый текст, должен раскрывать в той либо иной степени определённый аспект использования системы. Для наиболее гибкого использования, документация, создаваемая в рамках проекта, может существовать в трёх видах:

• Текст

Минимальная форма хранения информации.

Текст может писаться с нуля, или заимствоваться из сторонних легальных источников.

Технически может представлять из себя файл(ы) в любом читабельном формате: txt, odt, pdf, html

• Модуль (придумать другое название, иначе пересекается с rpm-пакетом-модулем)

Это паспортизированный текст. Добавляются 2 файла: docinfo и License

Паспотризация позволяет хранить метаинформацию о тексте, необходимую для архивирования, поиска и т. п.

В таком виде документацию уже можно граздо удобнее сортировать и публиковать online

Такая попытка сделана на: http://heap.altlinux.org/

• rpm-пакет

Это опакеченный в соответствии с принятыми правилами упаковки документации модуль

В этом виде документация может быть легко установлена в систему.

Таки образом имеем:

• Текст в любом читабельном формате
• Модуль = Текст + паспорт
• rpm-пакет = Текст + паспорт + spec

Паспортизация документации

Для целей архивного хранения, идентификации, поиска и т. п. тексты документации паспортизируются. К тексту добавляется два дополнительных файла:

• docinfo
• License

Паспортизированные тексты именуются Модулями (дать другое именование). Такие модули гораздо удобнее сортировать, осуществлять поиск, публиковать onlinе и т.п.

Формат файла docinfo

docinfo -- один из двух файлов, необходимых для паспортизации документации. Для этого файла используется одноимённый формат docinfo — специально придуманный для этой задачи и разработанный так, чтобы быть одновременно человеко- и машинночитаемым. Поскольку в самой документации метаданные могут быть расположены как угодно и вообще отсутствовать, то без такого «заголовка» не обойтись. docinfo позволяет хотя бы минимально контролировать наличие всей необходимой для архивирования, поиска и т. п. информации. Метаинформацию можно двух родов:

1. об авторе, правах, названии и т. п.
2. классификаторы документа.

Был выдуман закрытый список классификаторов, предложенный к использованию.

Формат файла License

License -- один из двух файлов, необходимых для паспортизации документации. Этот файл представляет из себя текстовый файл, содержащий текст лицензии на паспортизируемый текст.

Комплект опакеченной электронной документации

Электронная документация в виде rpm-пакетов присутствует в репозиториях.

Комплект электронной документации состоит из rpm-пакетов:

• модулей

Модуль представляет из себя самодостаточный текст, раскрывающий в той либо иной степени определённую тему. Например модуль может описывать процесс установки дополнительного ПО.

Пример: docs-packages_apt

• выпуска

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

Пример: docs-issue-server

• indexhtml-пакета

описание

Пример: indexhtml-lite

Форматы электронной документации

Электронная документация присутствует в установленной системе в виде html-файлов. Начальная страница каждого модуля содержит ссылку на паспорт модуля. Паспорт представляет из себя файл, содержащий различную мета-информацию: Автор, Версия, Тема, Краткое описание. Паспорт позволяет легче ориентироваться в большом количестве модулей.

• Форматы для модулей
• Форматы для выпусков

Форматы для модулей

Модули документации создаются разработчиком в одном из поддерживаемых форматов:

• html

Описание формата: http://www.w3.org/html/

• docbook

Описание формата: http://www.docbook.org/specs/

• m-k

Описание формата содержится в документации к пакету ALDConvert

Генерация html происходит в момент создания пакета. Этот процесс автоматизирован и описан в разделе Цикл разработки.

Форматы для выпусков

Для выпусков поддерживается только html-формат, расширенный возможностью использовать в ссылках adt:

<ul>
 <li><a href="adt:packages_apt">Управление пакетами (APT)</a></li>
 <li><a href="adt:init_d">Стартовые сценарии</a></li>
</ul>

В этом примере в результирующем html автоматически создаются ссылки на модули docs-packages_apt и docs-init_d а в сам пакет выпуска проставляеюся зависимости на эти два модуля.

Цикл разработки

• Тексты коллективно создаются и модифицируются в git.altlinux.org

При этом git используется не только при создании текстов с нуля, но и при опакечивании сторонних текстов.

• При необходимости создаются пакеты
• Пакеты оказываются в нужном репозитории

Инструменты документатора

git как нельзя лучше подходит для хранения всех трёх видов документации: Текстов и Модулей и rpm-пакетов (перефразировть).

Инструменты, облегчающие работу документатора:

• git
• rpm-build-docs
• alt-docs-genextras

rpm-build-docs

В пакете rpm-build-docs содержится несколько средств для автоматизации процесса превращения документа в пакет в Сизифе.

Общая задача — сделать процесс подготовки пакетов максимально автоматизированным, сведя необходимое участие в нём человека к однократному созданию первоначального спека. А последующую пересборку пакета при всех обновлениях самого документа сделать по возможности автоматической.

В пакет входят следующие компоненты:

docs_genspec

---

Утилита, которая из указанного архива с документом (из Кучи) вынимает docinfo и на основе данных из него строит типичный спек-файл. Она умеет также обновлять уже имеющийся спек-файл (если он был некогда сгенерён этой же утилитой и не испорчен до неузнаваемости).

docsbuild

---

Скрипт, который запускает процесс сборки документации из исходного формата в html. В одном из аргументов ему передаётся название исходного формата. Дальше он смотрит по таблице, какая функция отвечает за сборку из этого формата в html и запускает эту функцию. Принципиально разрабатывался как расширяемый — чтобы легко было добавлять новые функции для сборки html из других форматов.

Пользователь не должен вручную запускать docsbuild, он запускается при сборке пакета при помощи rpm-макроса, которому docs_genspec проставит нужные аргументы. У пользователя остаётся возможность добавить в спеке этому макросу любые дополнительные параметры для сборки (Естественно, их должна понимать сборочная функция для этого формата).

RPM-макросы

---

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

alt-docs-genextras

В ALT Linux предусмотрена стандартизованная процедура для включения вновь установленных выпусков документации в общую структуру электронной документации.

Сценарий alt-docs-genextras, находящийся в данном пакете служит для автоматической генерации и обновления списка ссылок на установленные выпуски документации (пакеты docs-issue-*) на главной странице документации ALT Linux (пакет alt-docs-main).

Этот сценарий вызывается после установки и удаления любого выпуска документации, для удобства есть rpm-макросы, находящиеся в пакете rpm-build-docs.

Информация о пакете (файл docinfo)

Текст ссылок, размещаемых на главной странице документации, автоматически генерируется на основании файла docinfo. По умолчанию такие файлы ищутся в подкаталогах /usr/share/doc/alt-docs/.

Если файл docinfo содержит русскоязычный текст (что предполагается), он должен быть в кодировке koi8-r!

В файле docinfo должна содержаться следующая информация:

• Title: Название документа

Название будет текстом гиперссылки на стартовую страницу документа (index.html).

• Abstract: Аннотация документа.

Этот текст будет включён в оглавление и должен давать представление о тематике документа и о том, для кого он предназначен (опытный пользователь, новичок, любознательный и т. п.). Строгих требований к аннотации нет, но из неё читатель должен иметь возможность понять, что это за документ и нужно ли ему его читать.
Допустимо и даже желательно, чтобы краткое описание пакета (поле %description -l ru_RU.KOI8-R в spec-файле пакета) совпадало с аннотацией.

• Section: Тематическая рубрика.

Тематическая рубрика, в которую нужно поместить ссылку. В настоящее время пакет для помещения на главную страницу документации (alt-docs-main) здесь должно быть значение distrib. Другие значения игнорируются.

Текущий формат файла docinfo таков:

Section: Название документа

Abstract: Аннотация документа (достаточно информативная,
поэтому длиной в несколько строк).

Section: textbook

Обратите внимание: точки после текста в поле Section нет!
Обратите внимание: поля в файле docinfo должны быть разделены пустыми строками!

Подробное описание формата файла docinfo: http://heap.altlinux.org/Titlepage/sample.docinfo.html

Cоглашения при написании документации

• Ссылки на сайты даются с указанием завершающего слэша

http://www.altlinux.ru/ http://www.altlinux.ru

• Буква ё используется. Скрипт для полуавтоматической расстановки букв ё в тексте.
• Обращение вы пишем со строчной

Обращаем ваше внимание

Обращаем Ваше внимание

Пример создания модуля документации

• Выбрать один из поддерживаемых форматов
• Создать паспорт модуля

docinfo-файл с синтаксисом,

• Создать spec-файл

При написании spec-файла следует придерживаться общих правил. (Дать ссылку).

Шаблоны docinfo-файла и spec-файла можно взять c http://git.altlinux.org/ (Дать точную ссылку)