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

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

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

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

Коллективное обсуждение всех вопросов, касающихся документации происходит в списке рассылки docs@: https://lists.altlinux.org/mailman/listinfo/docs

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

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

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

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

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

• Текст

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

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

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

• Модуль

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

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

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

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

Наброски на тему автоматического публикатор документации online: ALT_Linux_Wiki:Heap

• rpm-модуль

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

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

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

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

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

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

• docinfo
• License

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

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

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

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

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

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

Пример содержимого файла docinfo:

Title: Как самому собрать аппарат
Language: ru
Author: Иван Купала (перевод)
Version: 2.718281828459045
License: FDL
Url: http://www.example.com/
Format: plain text
Abstract: Полное руководство по самостоятельной сборке и отладке аппарата с примерами, таблицами истинности и выдержками из интернет-рекламы
Supported: yes
Updated: yes
Section: Научно-популярный
Section: Инструкция
Section: Персональное
Section: Аппаратное обеспечение
Section: Многоплатформенный

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

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

Пример содержимого файла License:

Данный документ распространяется на условиях свободной лицензии
FDL (Free Documentation License) версии 1.1 или любой более поздней версии.

Данный документ не содержит текста, помещаемого на первой или последней
странице обложки. Данный документ не содержит неизменяемого текста.

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

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

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

• модулей (rpm-модуль)

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

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

Пример: docs-packages_apt

• выпуска (rpm-выпуск)

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

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

• indexhtml-пакета

indexhtml-пакеты предоставляют простую html-страничку, которая по умолчанию является домашней для всех браузеров.

Такая html-страничка содержит

1. Приветствие
2. Ссылки на наиболее востребованную документацию. Как правило на выпуск конкретного дистрибутива.

Черновик полиси на indexhtml-пакеты: Drafts/indexhtml

Пример: indexhtml-sisyphus

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

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

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

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

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

Принципиально, оригинальный текст может создаваться в любом формате. Однако существует несколько форматов, для которых поддерживается конвертация в 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: http://git.or.cz/
• 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

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

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

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

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

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

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

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

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

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

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

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

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

Глоссарий терминов

Тут будет глоссарий

Руководство_по_написанию_документации

Исторический раздел

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

Основной источник информации: http://heap.altlinux.org/