Preparing Cogent Documentation

August 13, 2004

An in-house manual for training and reference.

Go to the Cogent Web Site.


Table of Contents

1. Introduction
1.1. File system overview: the doc/ directory
1.2. Single-sourcing with DocBook
2. Making Edits in doc/i/
2.1. Finding the source files
2.2. Elements and tags
2.2.1. DocBook elements
2.2.2. Element attributes
2.3. Emacs/PSGML tips
2.3.1. Settings in .emacs
2.3.2. Some important Emacs/PSGML key bindings
2.4. Entities
2.4.1. Entity declarations
2.4.2. Types of entities in Cogent documents
2.5. Links
2.6. Reference entries and sections
2.7. Images
2.7.1. Creating images
2.7.2. Including images
2.8. Screens and program listings
2.8.1. Program listings in XML
2.9. Updating version and revision numbers
2.10. Publication Dates
3. Creating Output from doc/o/
3.1. Output file subdirectories
3.2. A typical output subdirectory
3.3. The main.sgml file
3.4. Validating the SGML source
3.5. Generating output
3.6. Checking the output
3.7. Generating all distributed books
4. Making the Distribution from doc/export/
4.1. Step by step
4.2. In one step, and copied to the server
5. Special Organization
5.1. The Bookset
5.1.1. Adding new books
5.1.2. The QNX Help Book Sets
5.2. DataHub and Connect for Windows manuals
5.3. The Cascade Historian manual
5.4. The Cascade Compatible Cogent Driver manuals
5.5. Linux and QNX Tools Demo and Tutorials manual
5.6. White Papers
5.7. Glossary and FAQ
5.8. Gamma/GTK manual
5.9. Windows HTML Help
6. Tools
6.1. Overview
6.1.1. SGML Tools
6.1.2. XML Tools
6.2. Installing a new version of DocBook
6.2.1. Catalog files
6.2.2. Set up Emacs
6.3. Installing new stylesheets
6.4. DSSSL stylesheets
6.4.1. Making changes
6.4.2. The cogent-both.dsl file
6.5. XSL stylesheets
6.5.1. Making changes
6.5.2. XSL file organization
6.6. Installing JadeTeX
6.7. Installing other tools
6.8. More information
A. Frequently Used DocBook Tags
A.1. Document Organization
A.2. Front Matter
A.3. Reference Entries
A.4. Paragraphs
A.5. General Text
A.6. Software Terminology
A.7. Admonitions
A.8. Lists
A.9. Tables
A.10. Graphics
A.11. Addresses
B. Entity declaration files
B.1. doc/i/common/entities.sgml
B.2. doc/i/api/entities.sgml
B.3. doc/i/cfdriver/entities.sgml
B.4. doc/i/gamma/entities.sgml
B.5. doc/i/gendriver/entities.sgml
B.6. doc/i/glossary/entities.sgml
B.7. doc/i/phgamma/entities.sgml
C. Makefiles
C.1. An individual book makefile
C.2. The Cogent Documentation bookset makefile
C.3. A Cogent Documentation auxiliary makefile
C.4. The fundamental makefile: doc/sgml.mak
C.5. The Export makefile in doc/export/
C.6. The Do-Everything makefile in doc/o/
C.7. The Top-Level makefile in doc/
D. Scripts in doc/bin/
D.1. cogsgml
D.2. collate-all
D.3. collateindex.pl
D.4. docs2andrewgate.sh
D.5. latestdocs2andrewgate.sh
D.6. book2set.sh
D.7. checkdir.sh
D.8. copydatahub.sh
D.9. dvipdf
D.10. fixentities
D.11. latestdate.sh
D.12. revnum
D.13. replacer.pl
D.14. splitter.g
D.15. toc2toc
D.16. prex.sed
E. Stylesheets
E.1. html-prex.xsl
F. Building Gamma/GTK docs
F.1. doc/o/gtkgamma-book/Makefile
F.2. doc/bin/sort_and_arrange.pl
F.3. doc/i/gtkgamma/autodocs/function_processor.g
F.4. doc/i/gtkgamma/autodocs/gtkwidgets2docs.g
F.5. doc/i/gtkgamma/autodocs/gg_utils.g
F.6. Sample SGML output file: re_GtkContainer.sgml

List of Tables

A.1. Table title