Помещение в CVS

В CVS документы находятся в отдельных каталогах (модулях), каждый из которых закреплен за своим мантейнером.

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

Если нужно описать две версии одной программы, можно либо объединить описания в один документ, либо сделать два разных документа, если описания сильно отличаются. Если описания взаимоисключающие, нужно делать их в одном документе, используя Profiling. Название основного (корневого) документа в модуле должно совпадать с названием модуля — это нужно для объединения документов. Желательно давать каталогам с документами названия в нижнем регистре.

Для того, чтобы документ из каталога был включен в автоматическое объединение документов для какого-либо раздела (alt, admin и т.д.), в каталоге должен быть пустой файл public-document.

В объединяющих документах не должно быть собственного содержимого, только указание включений — это облегчает редактирование документов.

Замечание

В CVS каталоги с документами должны повторять структуру элементов DocBook. Помещение новых документов в определённые каталоги должно быть оговорено в списке рассылки .

В CVS хранятся только исходные тексты документов и сопровождающие их файлы модуля, например, Makefile, README и TODO. Производные форматы, например, HTML, в CVS недопустимы. Желательно указывать кодировку в сопровождающих файлах, если они написаны простым текстом на русском языке.

В каждом модуле должен находиться файл Makefile, образец такого файла можно получить в CVS, в каталоге $CVSROOT/docs/doc-template. Makefile состоит из включаемых файлов с целями, которые необязательны для включения, но удобны для централизованного обновления правил.

Подсказка

После копирования шаблонного Makefile нужно указать правильное значение относительного пути в MAKEFILES_DIR.

Замечание

Файл с целью dropdtd из CVS удалён — в данный момент документы объединяются с помощью технологии XML Inclusions.

В CVS помещаются только «валидные» документы (не нарушающие правил XML и типа документа). При этом изменения должны быть описаны в самом документе (тег revision), кроме записи при команде cvs commit file.xml.

Таблица 3.1. Структура каталогов в CVS

user — документы для пользователя
 multimedia 
  document1
  document2
 network 
  document1
  document2
 office 
  document1
 publishing 
  document1
 other 
  document1
   
admin — документы для администратора
 network 
  document1
  document2

Таблица 3.2. Элементы DocBook, соответствующие каталогам в CVS

<book>  
 <part> 
  <article>
  <chapter>
 <part> 
  <article>