[docs] Re: merge

[Vitaly Ostanin]

On Wed, 12 Mar 2003 12:52:30 +0300
Alexandre Prokoudine <avp на altlinux.ru> wrote:

<skipped/>

> > > Есть ли возражения против слияния
> > > http://docs.altlinux.ru/alt/devel/ch03.html и "правил
> > > совместной работы над документами в CVS"?
> > 
> > Пока есть. Кто будет поддерживать слитый документ? 

? (1)

> > Какого его назначение, почему сливается только 3 глава?
> 
> Я глубоко сомневаюсь, что правила совместной работы над
> документацией в CVS могут иметь отношение к Гл.1. "ALT
> Packaging" или Гл.2 "ALT Linux Maintainer HOWTO".

Это я ступил, прошу прощения. Решил, что речь идёт о части
docs-howto.

> > Удобно было бы иметь всё о доках в одном документе. 
> 
> К чему я и веду
> 
> > А вот насчёт стиля и авторства я тебе в jabber писал.
> 
> Тогда повтори это, пожалуйста, публично.

Мне не совсем понятно, зачем был сделан ещё один документ, если
уже есть docs-howto.

Я бы не хотел поддерживать документ, который я не писал. (1)
Стили написания
http://lrn.ru/~avp/index.html
http://docs.altlinux.ru/alt/devel/ch03.html
всё-таки различаются.

Кстати, этапы подготовки документов до сих пор не оговорены,
поскольку не готов document-info.xml для каждого документа.

document-info не готов, поскольку ещё не все книги валидны и
переехали в $CVSROOT/docs/books и неизвестна технология
публикации релизов.

По поводу docs/books (если будем развивать, то лучше отдельным
тредом):

В docs/books/master-2.2/admin лучше класть всё-таки не только
включения, а ещё и сами документы. Иначе потом будет невозможно
собрать релиз из состояния именно на момент релиза.

Почему используются не ветки cvs, а отдельные каталоги - потому
что в один момент времени могут готовиться несколько книг,
например, master/user и junior/user.

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

От всего этого зависит document-info.xml, а также (IMHO)
этапы подготовки документов.

Прошу прощения за некоторую сумбурность изложения.


> > > Если нет, то я до конца недели выкладываю новую версию, а
> > > затем переводим весь docs.altlinux.ru на website уже с
> > > новой версий"Правил".
> > 
> > :))) Кто именно переводит? Там работы прилично.
> > 
> > Norman Walsh в website не пошёл путём XML технологий :(
> 
> Твои предложения?

Править - убрать завязку на java extensions, перевести включения
страниц на XML Inclusions, сделать поддержку публикации книг.

После чего отправить патч Уолшу с просьбой включить в upstream и
аргументами.

Уже сейчас ему можно задавать наводящие вопросы, например, почему
в layout.xml (файл, задающий структуру сайта) документы
включаются через 
<toc>
<tocentry page="1.xml"/>
<tocentry page="2.xml"/>
а не через XInclude, что дало бы возможность включать документы,
уже содержащие включения (те самые книги, которые нужно
публиковать).

<skipped/>

-- 
Regards, Vyt
mailto:  vyt на vzljot.ru
JID:     vyt на vzljot.ru
----------- следущая часть -----------
Было удалено вложение не в текстовом формате...
Имя     : отсутствует
Тип     : application/pgp-signature
Размер  : 189 байтов
Описание: отсутствует
Url     : /pipermail/docs/attachments/20030312/2611452d/attachment.bin