[docs] черновик описания структуры документации

[Kirill Maslinsky]

Всем добрый день!

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

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

См. аттачмент.

-- 
Kirill Maslinsky
ALT Linux Team * Documentation Project   
-------------- next part --------------
Структура каталогов документации ALT Linux

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

Документация ALT Linux разделена на несколько разделов
(часть из этих разделов пока не заполнена): 

1. Знакомство с Linux. Основные понятия

Здесь должны быть описаны: история UNIX и Linux, экономика 
свободного ПО, дистрибутивы, сообщество, эргономика, терминология.
Тексты свободных лицензий.
(пока нет)

2. Документация по конкретным дистрибутивам

Здесь для каждого дистрибутива содержатся: краткие сведения 
об ALT Linux, инструкции по установке и настройке системы, 
сведения о специфических особенностях данного дистрибутива,
справочные сведения о доступных в дистрибутиве пользовательских 
приложениях и основах работы с ними.

3. ЧАсто задаваемые ВОпросы. ALT Linux FAQ

ALT Linux FAQ

4. Дополнительная документация

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

5. Документация для разработчика ALT Linux Team

Документы ALT Linux Team: ALT Linux Maintainer HOWTO, ALT-Docs HOWTO etc.


структура пакетов (существующих)


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

alt-docs-main

Этот пакет нужен как раз для организации удобного доступа к документации: 
он создает пункт меню "Документация/ALT Linux" и ссылку "Документация 
ALT Linux" на десктопе KDE. По этим ссылкам вызывается броузер, 
открывающий главную страницу документации, которая и содержится 
в этом пакете. На этой странице приведены ссылки на 
все разделы документации ALT Linux (см. предыдущий раздел), с кратким 
описанием этих разделов. 

Пакет alt-docs-main не требует устанавливать никаких других пакетов 
с документацией. Поэтому если на главной странице документации 
перейти по ссылке к разделу, документация которого не установлена, 
вы увидите "страницу-заглушку", на которой сообщается, что данная 
документация не установлена и даны инструкции, как соответствующую 
документацию установить. В пакет alt-docs-main входят "страницы-заглушки" 
для всех разделов документации. Пакеты с документацией при установке 
замещают эти заглушки своими главными странцами при помощи механизма
альтернатив (alternatives, подробнее см. ). 

Все тексты пакета (главная страница и "страницы-заглушки") находятся
в каталоге %_docdir/%name-%version, например, /usr/share/doc/alt-docs-main-0.2.

alt-docs-basics

<Пока не реализовано.> 
Основные понятия системы Linux, экономика и право свободного ПО, 
сообщество, дистрибутивы. Словарь терминов. Тексты свободных 
лицензий.


alt-docs-<distrib>

В названии пакета <distrib> следует заменить на название конкретного 
дистрибутива, например junior или master. Собственно основная 
документация в этом пакете и содержится. Все файлы пакета 
находятся в %_docdir/%name-%version, например, 
/usr/share/doc/alt-docs-junior-2.3, а не в /usr/share/doc/alt-docs (!).
%version в названии пакета совпадает с версией дистрибутива, 
к которому относится данная документация. 

alt-docs-faq

<Пока не реализовано.>
Список ЧАсто задаваемых ВОпросов ALT Linux. Все файлы пакета находятся 
в %_docdir/%name-%version. 

alt-docs-extras-*

Пакетов с дополнительной документацией может быть неограниченное число. 
Такие пакеты содержат свободно распространяемые тексты, которые 
не были написаны специально для ALT Linux, но могут пригодиться 
пользователям. Создать такой пакет может любой участник ALT Team, 
для этого достаточно следовать нескольким простым правилам при 
сборке пакета. Если пакет alt-docs-extras-* собран правильно, то 
при установке ссылка на содержащуюся в нем документацию будет автоматически
добавлена в оглавление раздела "Дополнительная документация". При удалении 
пакета ссылка будет удалена. Таким образом, документация в пакетах 
alt-docs-extras-* доступна пользователям через стандартный интерфейс -- 
с главной страницы документации. Подробнее об этой технологии см. 
раздел ...

alt-docs-devel

В этом пакете содержится документация для разработчика. Все файлы 
устанавливаются в %_docdir/%name-%version. 

===========================================================

структура каталогов

Основной каталог для доступа к документации ALT Linux -- 
%_docdir/alt-docs. %_docdir, в данном случае, это макрос, 
используемый в rpm-пакетах для подстановки стандартного 
пути к каталогу с документацией[Подробнее о макросах, 
используемых в .spec-файлах в пакетах ALT см. ]. В настоящее
время макрос %_docdir указывает на /usr/share/doc. 

Ни один из пакетов alt-docs-* не помещает документацию в каталог
/usr/share/doc/alt-docs, она всегда хранится в каталогах 
/usr/share/doc/<имя-версия_пакета>. Однако в каталоге 
/usr/share/doc/alt-docs находятся файлы-символические ссылки, 
указывающие на главные страницы каждого раздела документации.
Эти символические ссылки создаются при установке пакетов 
с документцией и управляются при помощи механизма альтернатив
(alternatives). Подробнее о работе механизма альтернатив в ALT Linux
можно прочитать в документации к пакету alternatives. 
Если несколько пакетов предоставляют один и тот же раздел 
(один и тот же файл в каталоге alt-docs), механизм альтернатив решает, 
на который из них будет указывать ссылка на основании _приоритета_ 
данного пакета. Значения приоритетов для пакетов с документацией 
см. в таблице. ...

В каталоге alt-docs могут находиться следующие ссылки:

index.html 

Ссылка на главную страницу документации. Если установлен пакет alt-docs-main, 
то это сслыка на главную страницу документации ALT Linux, на которой
есть ссылки на все остальные разделы документации. Если он не установлен, 
то это ссылка на главную страницу документации по дистрибутиву, 
если нет и этой документации, то данный файл указывает на главную страницу
любого из установленных пакетов с документацией.

basics.html

Ссылка на главную страницу раздела "Знакомство с Linux. Основные понятия"

distrib.html

Ссылка на главную страницу раздела "Документация по дистрибутиву"

Если в системе
установлено одновременно несколько пакетов с документацией к разным 
дистрибутивам или версиям дистрибутивов, этот файл будет указывать 
на пакет с наивысшим приоритетом. Все дистрибутивы имеют равный приоритет, 
поэтому будет выбран первый по алфавиту, специальные выпуски дистрибутивов 
(например, специально разработанный для поставки в школы Junior) имеют 
более высокий приоритет, поэтому файл distrib.html будет ссылаться на них. 

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

extras.html

Ссылка на главную страницу раздела "Дополнительная документация". 
Если установлен хотя бы один пакет из alt-docs-extras-*, по этой 
ссылке будет доступно автоматически сгенерированное оглавление 
всей установленной дополнительной документации 
(файл /usr/share/doc/alt-docs-extras/index.html), в противном случае 
это "заглушка" из пакета alt-docs-main.

faq.html

Ссылка на главную страницу раздела "ЧАсто задаваемые ВОпросы".

devel.html

Ссылка на главную страницу раздела "Документация для разработчика ALT Linux".