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

Материал из ALT Linux Wiki
Stub.png
Данная страница находится в разработке.
Эта страница ещё не закончена. Информация, представленная здесь, может оказаться неполной или неверной.


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

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

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

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

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

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

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

  • Текст
Минимальная форма хранения информации.
Текст может писаться с нуля, или заимствоваться из сторонних легальных источников.
Технически может представлять из себя файл(ы) в любом читабельном формате: txt, odt, pdf, html
  • Модуль (придумать другое название, иначе пересекается с rpm-пакетом-модулем)
Это паспортизированный текст. Добавляются 2 файла: docinfo и License
Паспотризация позволяет хранить метаинформацию о тексте, необходимую для архивирования, поиска и т. п.
В таком виде документацию уже можно граздо удобнее сортировать и публиковать online
Такая попытка сделана на: http://heap.altlinux.org/
  • rpm-пакет
Это опакеченный в соответствии с принятыми правилами упаковки документации модуль
В этом виде документация может быть легко установлена в систему.

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

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

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

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

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

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

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

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

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

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

тут будет пример
вторая строка
третья

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

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

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

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

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

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

Электронная документация в виде 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-пакетов (перефразировть).

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

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/ (Дать точную ссылку)