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

[Oleg A. Paraschenko]

  Привет!

On Tue, 11 Jan 2005 17:12:42 +0300
Kirill Maslinsky <kirill at altlinux.ru> wrote:

> Ещё раз всем привет. 
> Продолжение. 
> 
> Требования к разметке модуля DOCS 
> =================================
> 
> DocBook не очень годится в качестве формата для модуля документации в 
> DOCS: он слишком велик (около 400 элементов), требует долгого и 
> внимательного изучения. Кроме того, многие полагают разметку в 
> XML неудобной. 

  На всякий случай хочу напомнить недавнее письмо Михаила Шигорина:

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

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

> 
> Задача: разработать (или выбрать) формат, в котором
> будет вся необходимая и достаточная логическая информация для 
> сборки конечных форматов. 

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

"Greenspun's Tenth Rule of Programming: any sufficiently complicated C or
Fortran program contains an ad hoc informally-specified bug-ridden slow
implementation of half of Common Lisp."

> 
> Постулат: такой формат может и должен содержать не более 7--12
> элементов.

  Для автора, который находится непосредственно в процесее написания
текста -- да, постулат верен. Для "Необходимой информации" -- нет.

> 
> Необходимые и достаточные условия для сборки конечных форматов 
> из модуля документации я попробовал сформулировать ниже.
> 
> Необходимая информация
> ----------------------
> 
> ....
> 
> Содержательные требования
> -------------------------
> 
> ...
> 
> Требования к формату
> --------------------
> 
> ...
> 
> Жду комментариев и предложений подходящих форматов.

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

http://docutils.sourceforge.net/

> -- 
> Kirill Maslinsky
> ALT Linux Team * Documentation Project   
> 



-- 
Oleg Paraschenko  olpa@ http://xmlhack.ru/  XML news in Russian