В CVS документы находятся в отдельных каталогах (модулях), каждый из которых закреплен за своим мантейнером.
В каждом каталоге может быть только один основной документ. XML-файлов может быть несколько, например, для включения их в основной документ.
Если нужно описать две версии одной программы, можно либо объединить описания в один документ, либо сделать два разных документа, если описания сильно отличаются. Если описания взаимоисключающие, нужно делать их в одном документе, используя Profiling. Название основного (корневого) документа в модуле должно совпадать с названием модуляљ— это нужно для объединения документов. Желательно давать каталогам с документами названия в нижнем регистре.
Для того, чтобы документ из каталога был включен в автоматическое объединение документов для какого-либо раздела (alt, admin и т.д.), в каталоге должен быть пустой файл public-document.
В объединяющих документах не должно быть собственного содержимого, только указание включенийљ— это облегчает редактирование документов.
Замечание
В CVS каталоги с документами должны повторять структуру элементов DocBook. Помещение новых документов в определённые каталоги должно быть оговорено в списке рассылки <docs@altlinux.ru>.
В 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> |