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

Материал из ALT Linux Wiki
Перейти к: навигация, поиск
(Документация в репозитории/дистрибутивах)
 
(не показано 9 промежуточных версий 2 участников)
Строка 10: Строка 10:
  
 
В рамках проекта создаётся печатная и электронная документация, призванная помочь пользователям в освоении Linux.
 
В рамках проекта создаётся печатная и электронная документация, призванная помочь пользователям в освоении Linux.
 +
 +
{{Note|Документация должна быть корректно написана и структурирована, и НЕ должна ориентироваться на способ публикации, печатный или сетевой.}}
  
 
Коллективное обсуждение всех вопросов, касающихся документации, происходит в списке рассылки [https://lists.altlinux.org/mailman/listinfo/docs docs@].
 
Коллективное обсуждение всех вопросов, касающихся документации, происходит в списке рассылки [https://lists.altlinux.org/mailman/listinfo/docs docs@].
  
 
=== Печатная документация ===
 
=== Печатная документация ===
Печатная документация прилагается к дистрибутивам, выпускаемым ALT Linux, в виде брошюр, руководств и т. п.
+
Печатная документация прилагается к дистрибутивам, выпускаемым ALT Linux, в виде брошюр, руководств и т. п.
Другой вид печатной документации — отдельные книги, учебники и т. п.
+
Другой вид печатной документации — отдельные книги, учебники и т. п.
  
 
Как правило, печатная документация составляется на основе существующей электронной.
 
Как правило, печатная документация составляется на основе существующей электронной.
Строка 22: Строка 24:
  
 
=== Электронная документация ===
 
=== Электронная документация ===
Главное в документации — это конечно сами тексты. Каждый отдельно взятый текст, должен раскрывать в той либо иной степени определённый аспект использования системы. Для наиболее гибкого использования, документация, создаваемая в рамках проекта, может существовать в трёх видах:
+
Главное в документации — это конечно сами тексты. Каждый отдельно взятый текст, должен раскрывать в той либо иной степени определённый аспект использования системы. Для наиболее гибкого использования, документация, создаваемая в рамках проекта, может существовать в двух видах:
  
 
* '''Текст'''
 
* '''Текст'''
Строка 28: Строка 30:
 
: Текст может писаться с нуля, или заимствоваться из сторонних легальных источников.
 
: Текст может писаться с нуля, или заимствоваться из сторонних легальных источников.
 
: Технически может представлять из себя файл(ы) в любом читабельном формате: 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
 
 
 
=== Паспортизация документации ===
 
 
 
Для целей архивного хранения, идентификации, поиска и т. п. тексты электронной документации паспортизируются. К тексту добавляется два дополнительных файла:
 
  
* [[#Формат файла docinfo|'''docinfo''']]
+
== Пакет электронной документации ==
* [[#Формат файла License|'''License''']]
 
  
Паспортизированные тексты именуются '''модулями'''. Такие модули гораздо удобнее сортировать, осуществлять поиск, публиковать onlinе и т. п.
+
Электронная документация в виде rpm-пакета присутствует в репозиториях/дистрибутивах.
  
==== Формат файла docinfo ====
+
Документация может описывать процесс установки дистрибутива, обзор приложений, входящих в дистрибутив, руководсво по установке дополнительного ПО.
docinfo — один из двух файлов, необходимых для [[#Паспортизация документации|паспортизации]] документации.
 
Для этого файла используется одноимённый формат <tt>docinfo</tt> — специально придуманный для этой задачи и разработанный так, чтобы быть одновременно человеко- и машинночитаемым. Поскольку в самой документации метаданные могут быть расположены как угодно и вообще отсутствовать, то без такого «заголовка» не обойтись. <tt>docinfo</tt> позволяет хотя бы минимально контролировать наличие всей необходимой для архивирования, поиска и т. п. информации. Метаинформацию можно двух родов:
 
# об авторе, правах, названии и т. п.
 
# классификаторы документа.
 
: Был выдуман закрытый список классификаторов, предложенный к использованию.
 
  
Подробное описание поддерживаемых полей в файле docinfo доступно на: http://heap.altlinux.org/Titlepage/sample.docinfo.html
+
Процедура опакечевания документации максимально автоматизированна, при условии использования соответствующих инструментов.
  
Пример содержимого файла docinfo:
+
Пример: [http://sisyphus.ru/ru/srpm/Sisyphus/docs-simply-linux docs-simply-linux]
<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/
 
* docbook
 
* docbook
 
:Описание формата: http://www.docbook.org/specs/
 
:Описание формата: http://www.docbook.org/specs/
* m-k
 
:Описание формата содержится в документации к пакету [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).
* git: http://git.or.cz/
 
* [[#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
+
==== Именование пакетов ====
------------
+
Пакеты следует именовать по следующей схеме: docs-<''название_дистрибутива''>
Утилита, которая из указанного архива с документом (из Кучи)
 
вынимает docinfo и на основе данных из него строит типичный спек-файл.
 
Она умеет также обновлять уже имеющийся спек-файл (если он был
 
некогда сгенерён этой же утилитой и не испорчен до неузнаваемости).
 
  
docsbuild
+
Группа для указания в spec-файле: Documentation
---------
 
Скрипт, который запускает процесс сборки документации из исходного
 
формата в html. В одном из аргументов ему передаётся название исходного
 
формата. Дальше он смотрит по таблице, какая функция отвечает за сборку
 
из этого формата в html и запускает эту функцию. Принципиально
 
разрабатывался как расширяемый — чтобы легко было добавлять новые
 
функции для сборки html из других форматов.
 
  
Пользователь не должен вручную запускать docsbuild, он запускается при
+
Пример:
сборке пакета при помощи rpm-макроса, которому docs_genspec проставит нужные
 
аргументы. У пользователя остаётся возможность добавить в спеке этому
 
макросу любые дополнительные параметры для сборки (Естественно, их
 
должна понимать сборочная функция для этого формата).
 
  
RPM-макросы
+
<pre>Name: docs-simply-linux
-----------
 
Нужны для того, чтобы не повторять стандартные операции в каждом спеке.
 
Кроме того, последовательное использование макросов позволит при любых
 
изменениях в этих стандартных операциях (то есть в сборочной среде)
 
''автоматически'' пересобирать пакеты с документацией, ''ничего'' не изменяя
 
в самих спеках (то есть полностью без вмешательства человека).
 
  
=== alt-docs-genextras ===
+
Group: Documentation</pre>
  
В ALT Linux предусмотрена стандартизованная процедура для
+
==== Каталог установки ====
включения вновь установленных выпусков документации
 
в общую структуру электронной документации.
 
  
Сценарий alt-docs-genextras, находящийся в данном пакете
+
Файлы пакета документации (html, стили, логотипы и т. п.) устанавливаются в каталог /usr/share/doc/documentation/
служит для автоматической генерации и обновления списка
 
ссылок на установленные выпуски документации (пакеты docs-issue-*)  
 
на главной странице документации ALT Linux (пакет alt-docs-main).
 
  
Этот сценарий вызывается после установки и удаления любого выпуска
+
==== Конфликты ====
документации, для удобства есть rpm-макросы, находящиеся в пакете
+
Так как пакеты документации устанавливают свои файлы в один и тот же каталог, в системе не должно одновременно присутствовать более одного пакета документации.
rpm-build-docs.
+
Для обеспечения этого пакеты должны иметь конфликты на каждый docs-distro пакет, то есть содержать в своём spec-файле:
  
Информация о пакете (файл docinfo)
+
<pre>Cоnflicts: docs-firstdistro, docs-seconddistro, docs-thirddistro</pre>
  
Текст ссылок, размещаемых на главной странице документации,
+
== Соглашения при написании документации ==
автоматически генерируется на основании файла docinfo.  
+
* Ссылки на сайты даются с указанием завершающего слэша:
По умолчанию такие файлы ищутся  в подкаталогах
+
*: <s><nowiki>http://www.altlinux.ru</nowiki></s> <nowiki>http://www.altlinux.ru/</nowiki>
/usr/share/doc/alt-docs/.
+
<!-- *: wiki — <nowiki>http://www.altlinux.org/</nowiki>
 +
*: forum — <nowiki>http://forum.altlinux.org/</nowiki>
 +
*: company — <nowiki>http://altlinux.ru/</nowiki> (уточнить) -->
 +
* Буква '''ё''' используется:
 +
*: [http://python.anabar.ru/yo.htm Скрипт для полуавтоматической расстановки букв ё в тексте].
 +
* Обращение '''вы''' пишем со строчной:
 +
*: Обращаем <s>Ваше</s> ваше внимание …
 +
* Дистрибутивонезависимые модули. Стараться избегать в текстах модулей названий конкретных дистрибутивов. Это облегчает использование текста применительно к разным дистрибутивам ALT.
 +
*: В ALT Linux <s>4.0 Server</s> настройка производится …
 +
* Linux пишем как Linux, но не Линукс. (Исключение: документация для школ — ПСПО)
 +
*: <s>Линукс</s> Linux не имеет географического центра разработки.
 +
* Желательно следить за тем, чтобы в теги попадали те слова, которые к эти тегам относятся, например, не нужно писать внутри тегов точку или знак деления:
 +
*: который завершается нажатием клавиши <s><nowiki><keycap>Enter.</keycap></nowiki></s> <nowiki><keycap>Enter</keycap>.</nowiki>
 +
* В заголовках статей и разделов точки ставить не нужно
 +
* В списках в конце перечислений лучше ставить точку с запятой
  
Если файл docinfo содержит русскоязычный текст (что предполагается),
+
=== Множественное число и использование акронимов со словом «сервер» ===
он должен быть в кодировке koi8-r!                                 
 
  
В файле docinfo должна содержаться следующая информация:
+
Множественное число в именительном падеже — '''серверы'''. [http://gramota.ru/spravka/buro/29_332846]
  
* '''Title: Название документа'''
+
Сервер (кроме названий продуктов) — через дефис, после сокращения: ''DHCP-сервер, RAS-сервер, OLE-сервер''.
:Название будет текстом гиперссылки на стартовую страницу документа (index.html).
 
* '''Abstract: Аннотация документа.'''
 
:Этот текст будет включён в оглавление и должен давать представление о тематике документа и о том, для кого он предназначен (опытный пользователь, новичок, любознательный и т. п.). Строгих требований к аннотации нет, но из неё читатель должен иметь возможность понять, что это за документ и нужно ли ему его читать.<br>Допустимо и даже желательно, чтобы краткое описание пакета (поле %description -l ru_RU.KOI8-R в spec-файле пакета) совпадало с аннотацией.
 
* '''Section:  Тематическая рубрика.'''
 
:Тематическая рубрика, в которую нужно поместить ссылку. В настоящее время пакет для помещения на главную страницу документации (alt-docs-main) здесь должно быть значение ''distrib''. Другие значения игнорируются.
 
 
 
Текущий формат файла docinfo таков:
 
 
 
<pre>
 
Section: Название документа
 
 
 
Abstract: Аннотация документа (достаточно информативная,
 
поэтому длиной в несколько строк).
 
 
 
Section: textbook
 
</pre>
 
 
 
Обратите внимание: точки после текста в поле Section нет!<br>
 
Обратите внимание: поля в файле docinfo должны быть разделены пустыми строками!
 
 
 
Подробное описание формата файла docinfo: http://heap.altlinux.org/Titlepage/sample.docinfo.html
 
 
 
== Пример создания модуля документации ==
 
 
 
* Выбрать один из поддерживаемых [[#Форматы электронной документации|форматов]]
 
* Создать паспорт модуля
 
:docinfo-файл с синтаксисом,
 
* Создать spec-файл
 
:При написании spec-файла следует придерживаться общих правил. (Дать ссылку).
 
  
Шаблоны docinfo-файла и spec-файла можно взять c http://git.altlinux.org/ (Дать точную ссылку)
+
Сервер (с названием продукта) — перед сокращением: ''сервер UNIX, сервер Windows''. [http://www.microsoft.com/downloads/details.aspx?familyid=25018024-2DFD-4229-9763-05F78FEAF2FF&displaylang=en]
  
== Cоглашения при написании документации ==
+
Возможно и написание ''сервер FTP''. [http://lists.kde.ru/pipermail/kde-russian/2008-August/008019.html]
* Ссылки на сайты даются с указанием завершающего слэша
 
:<nowiki>http://www.altlinux.ru/</nowiki> <s><nowiki>http://www.altlinux.ru</nowiki></s>
 
: wiki -- http://www.altlinux.org/
 
: forum -- http://forum.altlinux.org/
 
: company -- http://altlinux.ru/ (учтонить)
 
* Буква '''ё''' используется. [http://python.anabar.ru/yo.htm Скрипт для полуавтоматической расстановки букв ё в тексте].
 
* Обращение '''вы''' пишем со строчной
 
:Обращаем ваше внимание
 
:<s>Обращаем Ваше внимание</s>
 
* Дистрибутивонезависимые модули
 
: Стараться избегать в текстах модулей названий конкретных дистрибутивов. Это облегчает использование текста применительно к разным дистрибутивам ALT.
 
: В ALT Linux <s>4.0 Server</s> настройка производится ...
 
* Linux пишем как Linux, но не Линукс. (Исключение: документация для школ -- ПСПО)
 
: Linux не имеет географического центра разработки.
 
: <s>Линукс не имеет географического центра разработки.</s>
 
  
 
=== Глоссарий терминов ===
 
=== Глоссарий терминов ===
  
* ALT Linux — дистрибутивы
+
* ALT Linux — дистрибутивы
* ALT Linux — компания (в англоязычных текстах)
+
* ALT Linux — компания (в англоязычных текстах)
 
* Компания «Альт Линукс», ООО «Альт Линукс», ООО «Альт Линукс Технолоджи»
 
* Компания «Альт Линукс», ООО «Альт Линукс», ООО «Альт Линукс Технолоджи»
  
Строка 293: Строка 145:
 
== Исторический раздел ==
 
== Исторический раздел ==
  
Тут будет информация, описывающая для архивных целей технологии, использовавшиеся ранее при работе с документацией в рамках проекта.
+
{{discuss|Тут будет информация, описывающая для архивных целей технологии, использовавшиеся ранее при работе с документацией в рамках проекта.}}
  
Основной источник информации: http://heap.altlinux.org/
+
Основной источник информации: [http://heap.altlinux.org/ heap.altlinux.org]

Текущая версия на 13:18, 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/

Генерация 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>.
  • В заголовках статей и разделов точки ставить не нужно
  • В списках в конце перечислений лучше ставить точку с запятой

Множественное число и использование акронимов со словом «сервер»[править]

Множественное число в именительном падеже — серверы. [1]

Сервер (кроме названий продуктов) — через дефис, после сокращения: DHCP-сервер, RAS-сервер, OLE-сервер.

Сервер (с названием продукта) — перед сокращением: сервер UNIX, сервер Windows. [2]

Возможно и написание сервер FTP. [3]

Глоссарий терминов[править]

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

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

Исторический раздел[править]

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

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