[docs] Making docs status in cvs

[cornet]

Vitaly Ostanin wrote:
> 
> Hello, All!
> 
> Есть предложение (пока только теоретическое) создавать в
> каталогах с документами дополнительный xml-файл, что-то вроде
> document-status.xml (лишь бы не пересекалось с реальными доками).
> 
> В этом файле можно хранить информацию об основном файле
> документа, о мантейнере (или нескольких), статусе документа.
> 
> Например:
> 
> <document>
>   <filename>example.xml</filename>
>   <mantainer>
>     <name>Foo</name>
>     <email>Bar</email>
>   </mantainer>
>   <mantainer>
>     <name>Foo1</name>
>     <email>Bar1</email>
>   </mantainer>
>   <status>
>     <valid status="ok"/>
>     <techreview status="bad"/>
>     <litreview status="process"/>
>   </status>
>   <comment>
>     Надо бы найти автора.
>   </comment>
> </document>
> 
> Можно оформить это в DTD. Берусь.
> 
> Полезно это тем, что позволит искать в CVS все
> document-status.xml и генерить из них html со статусом.
> 
> Туда же можно запихать TODO.

После длительного осмысления пришел к следующим выводам:
1. У каждого документа может быть несколько авторов.
2. У каждого документа единовременно может быть только один
майнтейнер - как у rpm-пакета.
Фактически это лицо ответственное за выпуск документа и
поддержание его в актуальном состоянии.
Разумеется этот человек одновременно может быть (и как правило
будет) одним из авторов.
Всё общение с авторами документа возлагается на майнтейнера.

Вот, отсюда следствия - необходимо оставить в данном документе
только одну запись:
   <mantainer>
     <name>Foo</name>
     <email>Bar</email>
   </mantainer>
а список авторов всегда можно взять из основного документа,
статус которого мы описываем.


Ну и в качестве общего предложения:
Вытеснить ВСЕХ авторов в общий ent/authors.ent а в документах
соответственно использовать только сущности. В этом случае мы
отстреливаем сразу двух ушастых - имеем общий список авторов в
одном общем файле, причем со всеми их атрибутами, и можем с
минимальными изменениями вносить правки - если например у кого
то из плодовитых авторов изменился почтовый адрес то менять
прибется только в одном файле ent/authors.ent а не во всех,
автором которых он является. Так же существенно упрощается
изменение списка атрибутов авторов если мы захотим что либо
менять в будущем.

Например, в ent/authors.ent записываем:
<!ENTITY cornet
"<firstname>Vlasenko</firstname><surname>Oleg</surname><affiliation><address><email>cornet на altlinux.ru</email><otheraddr></otheraddr></address></affiliation>">

А в теле документа пишем:
<authorgroup>
  <author lang="en">
    &cornet;
  </author>
</authorgroup>


Мнения?

-- 
Власенко Олег.
Отдел технической поддержки ALT Linux Team.
mailto:cornet на altlinux.ru