Создание документации: различия между версиями

Материал из ALT Linux Wiki
Нет описания правки
Строка 14: Строка 14:


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


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


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


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


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


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


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


* [[#Формат файла docinfo|'''docinfo''']]
Документация может описывать процесс установки дистрибутива, обзор приложений, входящих в дистрибутив, руководсво по установке дополнительного ПО.
* [[#Формат файла License|'''License''']]


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


==== Формат файла docinfo ====
Пример: [http://sisyphus.ru/ru/srpm/Sisyphus/docs-simply-linux docs-simply-linux]
docinfo — один из двух файлов, необходимых для [[#Паспортизация документации|паспортизации]] документации.
Для этого файла используется одноимённый формат <tt>docinfo</tt> — специально придуманный для этой задачи и разработанный так, чтобы быть одновременно человеко- и машинночитаемым. Поскольку в самой документации метаданные могут быть расположены как угодно и вообще отсутствовать, то без такого «заголовка» не обойтись. <tt>docinfo</tt> позволяет хотя бы минимально контролировать наличие всей необходимой для архивирования, поиска и т. п. информации. Метаинформацию можно двух родов:
# об авторе, правах, названии и т. п.
# классификаторы документа.
: Был выдуман закрытый список классификаторов, предложенный к использованию.
 
Подробное описание поддерживаемых полей в файле docinfo доступно на: http://heap.altlinux.org/Titlepage/sample.docinfo.html
 
Пример содержимого файла docinfo:
<pre>
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: Многоплатформенный
</pre>
 
==== Формат файла License ====
License — один из двух файлов, необходимых для [[#Паспортизация документации|паспортизации]] документации.
Этот файл представляет из себя текстовый файл, содержащий текст лицензии на паспортизируемый текст.
 
Пример содержимого файла License:
<pre>
Данный документ распространяется на условиях свободной лицензии
FDL (Free Documentation License) версии 1.1 или любой более поздней версии.
 
Данный документ не содержит текста, помещаемого на первой или последней
странице обложки. Данный документ не содержит неизменяемого текста.
</pre>
 
== Комплект опакеченной электронной документации ==
 
Электронная документация в виде rpm-пакетов присутствует в репозиториях/дистрибутивах.
 
Обычно комплект электронной документации состоит из rpm-пакетов:
* '''модулей''' (rpm-модуль)
:Модуль представляет из себя опакеченный текст, и соответственно раскрывает в той либо иной степени определённую тему. Например модуль может описывать процесс установки дополнительного ПО.
:Прцедура опакечевания модулей максимально автоматизированна, при условии использования соответствующих инструментов.
:Пример: [http://sisyphus.ru/srpm/Sisyphus/docs-packages_apt docs-packages_apt]
* '''выпуска''' (rpm-выпуск)
:Выпуск не несёт в себе информативной части, а служит лишь для объединения модулей. Выпуск -- это аналог оглавления в печатном издании.
:Пример: [http://sisyphus.ru/srpm/Sisyphus/docs-issue-server docs-issue-server]
* '''indexhtml-пакета'''
:indexhtml-пакеты предоставляют простую html-страничку, которая по умолчанию является домашней для всех браузеров.
:Такая html-страничка содержит
#Приветствие
#Ссылки на наиболее востребованную документацию. Как правило на '''выпуск''' конкретного дистрибутива.
:Черновик полиси на indexhtml-пакеты: [[IndexhtmlPolicy]]
:Пример: [http://sisyphus.ru/srpm/Sisyphus/indexhtml-sisyphus indexhtml-sisyphus]


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


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


* [[#Форматы для модулей|Форматы для модулей]] (rpm-модулей)
* [[#Форматы для выпусков|Форматы для выпусков]] (rpm-выпусков)
==== Форматы для модулей ====
Принципиально, оригинальный текст может создаваться в любом формате. Однако существует несколько форматов, для которых поддерживается конвертация в html, что особенно удобно для опакеченной документации.
Принципиально, оригинальный текст может создаваться в любом формате. Однако существует несколько форматов, для которых поддерживается конвертация в html, что особенно удобно для опакеченной документации.


Модули документации создаются разработчиком в одном из поддерживаемых форматов:
Документация создаётся разработчиком в одном из поддерживаемых форматов:
* html
* html
:Описание формата: http://www.w3.org/html/
:Описание формата: http://www.w3.org/html/
Строка 131: Строка 60:
:Описание формата содержится в документации к пакету [http://sisyphus.ru/srpm/Sisyphus/ALDConvert ALDConvert]
:Описание формата содержится в документации к пакету [http://sisyphus.ru/srpm/Sisyphus/ALDConvert ALDConvert]


Генерация html происходит в момент создания rpm-пакета. Кроме генерации html-а, Начальная страница каждого модуля получает ссылку на [[#Паспортизация документации|'''паспорт''']] модуля. Паспорт содержит различную мета-информацию: Автор, Версия, Тема, Краткое описание и т.д.
Генерация html происходит в момент создания rpm-пакета.  


Процесс опакечивания автоматизирован описан в разделе XXX.
Процесс опакечивания автоматизирован описан в разделе XXX.
==== Форматы для выпусков ====
Для '''выпусков''' поддерживается только html-формат, расширенный возможностью использовать в ссылках '''adt''':
<source lang="html4strict">
<ul>
<li><a href="adt:packages_apt">Управление пакетами (APT)</a></li>
<li><a href="adt:init_d">Стартовые сценарии</a></li>
</ul>
</source>
В этом примере в результирующем html автоматически создаются ссылки на модули docs-packages_apt и docs-init_d а в сам пакет выпуска проставляеюся зависимости на эти два модуля.


== Цикл разработки ==
== Цикл разработки ==
Строка 156: Строка 73:
== Инструменты документатора ==
== Инструменты документатора ==


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


Инструменты, облегчающие работу документатора:
[http://fedorahosted.org/publican/ Publican] - утилита для создания документации на базе стандарта DocBook. Утилита предназначена для автоматизации и сокращения сроков развертывания и настройки под конкретный проект DocBook-инфраструктуры, операций экспорта в нужные форматы (в том числе PDF и HTML).
* [http://git.or.cz/ git]
* [[#rpm-build-docs|rpm-build-docs]]
* [[#alt-docs-genextras|alt-docs-genextras]]


=== rpm-build-docs ===
== Пример создания пакета документации ==


В пакете rpm-build-docs содержится несколько средств для автоматизации
* Выбрать один из поддерживаемых [[#Форматы электронной документации|форматов]]
процесса превращения документа в пакет в Сизифе.
* Создать spec-файл
 
*: При написании [http://www.altlinux.org/Spec spec]-файла следует придерживаться общих правил.  
Общая задача — сделать процесс подготовки пакетов максимально
автоматизированным, сведя необходимое участие в нём человека
к однократному созданию первоначального спека. А последующую
пересборку пакета при всех обновлениях самого документа
сделать по возможности автоматической.
 
В пакет входят следующие компоненты:
 
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-макросы, находящиеся в пакете
Пакеты следует именовать по следующей схеме: docs-<''название_дистрибутива''>
rpm-build-docs.


Информация о пакете (файл docinfo)
Группа для указания в spec-файле: Documentation


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


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


В файле docinfo должна содержаться следующая информация:
Group: Documentation</pre>


* '''Title: Название документа'''
==== Каталог установки ====
:Название будет текстом гиперссылки на стартовую страницу документа (index.html).
* '''Abstract: Аннотация документа.'''
:Этот текст будет включён в оглавление и должен давать представление о тематике документа и о том, для кого он предназначен (опытный пользователь, новичок, любознательный и т. п.). Строгих требований к аннотации нет, но из неё читатель должен иметь возможность понять, что это за документ и нужно ли ему его читать.<br>Допустимо и даже желательно, чтобы краткое описание пакета (поле %description -l ru_RU.KOI8-R в spec-файле пакета) совпадало с аннотацией.
* '''Section:  Тематическая рубрика.'''
:Тематическая рубрика, в которую нужно поместить ссылку. В настоящее время пакет для помещения на главную страницу документации (alt-docs-main) здесь должно быть значение ''distrib''. Другие значения игнорируются.


Текущий формат файла docinfo таков:
Файлы пакета документации (html, стили, логотипы и т. п.) устанавливаются в каталог /usr/share/doc/documentation/


<pre>
==== Конфликты ====
Section: Название документа
Так как пакеты документации устанавливают свои файлы в один и тот же каталог, в системе не должно одновременно присутствовать более одного пакета документации.
 
Для обеспечения этого пакеты должны иметь конфликты на каждый docs-distro пакет, то есть содержать в своём spec-файле:
Abstract: Аннотация документа (достаточно информативная,
поэтому длиной в несколько строк).
 
Section: textbook
</pre>
 
Обратите внимание: точки после текста в поле Section нет!<br>
Обратите внимание: поля в файле docinfo должны быть разделены пустыми строками!
 
Подробное описание формата файла docinfo: http://heap.altlinux.org/Titlepage/sample.docinfo.html
 
== Пример создания модуля документации ==
 
* Выбрать один из поддерживаемых [[#Форматы электронной документации|форматов]]
* Создать паспорт модуля
*: docinfo-файл с синтаксисом,
* Создать spec-файл
*: При написании spec-файла следует придерживаться общих правил. {{discuss|(Дать ссылку).}}


Шаблоны docinfo-файла и spec-файла можно взять с [http://git.altlinux.org/ git.altlinux.org] {{discuss|(Дать точную ссылку)}}
<pre>Cоnflicts: docs-firstdistro, docs-seconddistro, docs-thirddistro</pre>


== Соглашения при написании документации ==
== Соглашения при написании документации ==
* Ссылки на сайты даются с указанием завершающего слэша:
* Ссылки на сайты даются с указанием завершающего слэша:
*: <s><nowiki>http://www.altlinux.ru</nowiki></s> <nowiki>http://www.altlinux.ru/</nowiki>
*: <s><nowiki>http://www.altlinux.ru</nowiki></s> <nowiki>http://www.altlinux.ru/</nowiki>
<!-- *: wiki — <nowiki>http://www.altlinux.org/</nowiki>
<!-- *: wiki — <nowiki>http://www.altlinux.org/</nowiki>
*: forum — <nowiki>http://forum.altlinux.org/</nowiki>
*: forum — <nowiki>http://forum.altlinux.org/</nowiki>
*: company — <nowiki>http://altlinux.ru/</nowiki> (уточнить) -->
*: company — <nowiki>http://altlinux.ru/</nowiki> (уточнить) -->
* Буква '''ё''' используется:
* Буква '''ё''' используется:
*: [http://python.anabar.ru/yo.htm Скрипт для полуавтоматической расстановки букв ё в тексте].
*: [http://python.anabar.ru/yo.htm Скрипт для полуавтоматической расстановки букв ё в тексте].
Строка 278: Строка 118:
* Дистрибутивонезависимые модули. Стараться избегать в текстах модулей названий конкретных дистрибутивов. Это облегчает использование текста применительно к разным дистрибутивам ALT.
* Дистрибутивонезависимые модули. Стараться избегать в текстах модулей названий конкретных дистрибутивов. Это облегчает использование текста применительно к разным дистрибутивам ALT.
*: В ALT Linux <s>4.0 Server</s> настройка производится …
*: В ALT Linux <s>4.0 Server</s> настройка производится …
* Linux пишем как Linux, но не Линукс. (Исключение: документация для школ — ПСПО)
* Linux пишем как Linux, но не Линукс. (Исключение: документация для школ — ПСПО)
*: <s>Линукс</s> Linux не имеет географического центра разработки.
*: <s>Линукс</s> Linux не имеет географического центра разработки.
* Желательно следить за тем, чтобы в теги попадали те слова, которые к эти тегам относятся, например, не нужно писать внутри тегов точку или знак деления:
*: <s><nowiki>который завершается нажатием
клавиши<keycap>Enter.</keycap></nowiki></s> <nowiki>который завершается нажатием
клавиши<keycap>Enter</keycap>.</nowiki>
* В заголовках статей и разделов точки ставить не нужно
* В списках в конце перечислений лучше ставить точку с запятой


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


* ALT Linux — дистрибутивы
* ALT Linux — дистрибутивы
* ALT Linux — компания (в англоязычных текстах)
* ALT Linux — компания (в англоязычных текстах)
* Компания «Альт Линукс», ООО «Альт Линукс», ООО «Альт Линукс Технолоджи»
* Компания «Альт Линукс», ООО «Альт Линукс», ООО «Альт Линукс Технолоджи»


Версия от 10:49, 9 февраля 2017

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


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

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

Коллективное обсуждение всех вопросов, касающихся документации, происходит в списке рассылки docs@.

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

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

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

Краткая инструкция по сборке печатной документации.

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

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

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

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

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

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

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

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

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

Пример: docs-simply-linux

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

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

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

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

  • html
Описание формата: http://www.w3.org/html/
  • docbook
Описание формата: http://www.docbook.org/specs/
  • m-k
Описание формата содержится в документации к пакету ALDConvert

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

Процесс опакечивания автоматизирован описан в разделе XXX.

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

  • Тексты коллективно создаются и модифицируются в git.altlinux.org
При этом git используется не только при создании текстов с нуля, но и при опакечивании сторонних текстов.
  • При необходимости создаются пакеты
  • Пакеты оказываются в нужном репозитории

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

git как нельзя лучше подходит для хранения документации.

Publican - утилита для создания документации на базе стандарта DocBook. Утилита предназначена для автоматизации и сокращения сроков развертывания и настройки под конкретный проект DocBook-инфраструктуры, операций экспорта в нужные форматы (в том числе PDF и HTML).

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

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

Требования к пакетам документации

Именование пакетов

Пакеты следует именовать по следующей схеме: docs-<название_дистрибутива>

Группа для указания в spec-файле: Documentation

Пример: 

Name: docs-simply-linux

Group: Documentation

Каталог установки

Файлы пакета документации (html, стили, логотипы и т. п.) устанавливаются в каталог /usr/share/doc/documentation/

Конфликты

Так как пакеты документации устанавливают свои файлы в один и тот же каталог, в системе не должно одновременно присутствовать более одного пакета документации. Для обеспечения этого пакеты должны иметь конфликты на каждый docs-distro пакет, то есть содержать в своём spec-файле: 

Cоnflicts: docs-firstdistro, docs-seconddistro, docs-thirddistro

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

  • Ссылки на сайты даются с указанием завершающего слэша:
    http://www.altlinux.ru http://www.altlinux.ru/
  • Буква ё используется:
    Скрипт для полуавтоматической расстановки букв ё в тексте.
  • Обращение вы пишем со строчной:
    Обращаем Ваше ваше внимание …
  • Дистрибутивонезависимые модули. Стараться избегать в текстах модулей названий конкретных дистрибутивов. Это облегчает использование текста применительно к разным дистрибутивам ALT.
    В ALT Linux 4.0 Server настройка производится …
  • Linux пишем как Linux, но не Линукс. (Исключение: документация для школ — ПСПО)
    Линукс Linux не имеет географического центра разработки.
  • Желательно следить за тем, чтобы в теги попадали те слова, которые к эти тегам относятся, например, не нужно писать внутри тегов точку или знак деления:
    который завершается нажатием клавиши<keycap>Enter.</keycap> который завершается нажатием клавиши<keycap>Enter</keycap>.
  • В заголовках статей и разделов точки ставить не нужно
  • В списках в конце перечислений лучше ставить точку с запятой

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

  • ALT Linux — дистрибутивы
  • ALT Linux — компания (в англоязычных текстах)
  • Компания «Альт Линукс», ООО «Альт Линукс», ООО «Альт Линукс Технолоджи»

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

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

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

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