[docs] требования к формату модуля документации

[Kirill Maslinsky]

Привет!

>   На всякий случай хочу напомнить недавнее письмо Михаила Шигорина:
> 
> [quote]
> Да, ещё имеет смысл разделить "создание" и "модификацию" -- если
> создать исходный документ мне, например, проще в text/plain, то
> мелко-средние правки по ходу смогу вносить и в сконвертированный
> в docbook/ALT вариант.
> [/quote]

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

>   А проблема точно в формате? Он ли узкое место? Будут ли авторы писать
> тексты при наличие суперудобного формата?

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

>   DocBook (точнее, часть его). Всё равно свой велосипед рано или поздно
> превратится в DocBook. По аналогии с:

Почему бы нет. Главное, чтобы он был обозрим, и сопровождающие 
легко соглашались работать с ним.

> > Постулат: такой формат может и должен содержать не более 7--12
> > элементов.
> 
>   Для автора, который находится непосредственно в процесее написания
> текста -- да, постулат верен. Для "Необходимой информации" -- нет.

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

1. Автоматически собраться в html в качестве интегрированной части 
документации ALT наравне с другими модулями.

2. Автоматически собраться в некоторый вариант LaTeX-разметки, 
описанный специальным LaTeX-стилем для подготовки макетов в ALT.
Текст, размеченный таким способом -- исходная точка для 
подготовки макета книжки. Автоматическая сборка таких текстов в
PS или PDF должна (и будет) давать нечто вроде распечатки для 
корректуры (но не макет).

Автоматическая сборка в PDF -- это не подготовка макета, а _другая
задача_. Макет книжки без ручного вмешательства не получается.

На самом деле, обе задачи могут быть детализированы, я пытался 
сделать это, предлагая требования к формату, но, видимо,
получилось неочевидно. Попробую ещё раз другим письмом.

>   Например, [часть] DocBook для хранилища и Restructured Text для авторов
> для написания первой версии текста:
> 
> http://docutils.sourceforge.net/

Это, на самом деле, близко к тому, что требуется для формата модуля 
документации. _Если_ там есть все средства решить перечисленные задачи, 
и _не слишком много_ возможностей решать их по-разному. 

Ещё раз повторюсь: а зачем авторам учить какой-либо формат? Его должны
знать _сопровождающие модулей_, а авторы должны легко его _читать_
и вносить правку (прочтя кратчайшее руководство).

-- 
Kirill Maslinsky
ALT Linux Team * Documentation Project