Chapter 1. Introduction

Preparing Cogent documentation is easy and fun if you have a good SGML editor and are comfortable using the DocBook DTD. Here are the basic steps:

These steps are explained in more detail in the following chapters of this guide. For best results, we strongly recommend reading this material carefully before editing or generating documents, and refer to it as necessary while doing so.

1.1. File system overview: the doc/ directory

One way to understand the Cogent documentation system is by looking at the directories and files that make it up. The main directory is the doc/ directory, which contains the following subdirectories and files:

i/	SGML source code.
o/	Output files and makefiles.
bin/	Processing scripts.
export/	Preparation area for distribution.
distribution/	Distribution files.
config/	Stylesheet customization files, etc.
docbook.ced	The Emacs PSGML mode DocBook DTD cache file.
sgml.mak	The fundamental, book-level, output-specific makefile.
Makefile	A top-level makefile, for system-wide makes.

Here is a way to visualize how these files and directories are used to create the documentation:

1. The text editor, Emacs, is used to create the SGML source files located in the i/ and o/ directories.
2. The makefiles call cogsgml, which calls the processing tools and puts the output into the html/, help/, and pdf/ directories (and others).
3. A makefile in the export/ directory collects, tars, and zips the output, and puts it in the distribution/ directory.