Preparing Cogent Documentation :
	Chapter 5. Special Organization

Chapter 5. Special Organization

Table of Contents

5.1. The Bookset

The Cogent Documentation Bookset that contains most of our books is based on the DocBook element Set. Because of its size, our processing tools can only generate the HTML version of it. We use it for the HTML and QNX Helpviewer distributions of our documentation.

The o/cogent-set/main.sgml file is significantly different from a typical main.sgml. This is what it looks like:

<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!ENTITY % gammaentities    SYSTEM "../../i/gamma/entities.sgml"> %gammaentities;
<!ENTITY % phgammaentities  SYSTEM "../../i/phgamma/entities.sgml"> %phgammaentities;
<!ENTITY % gtkgammaentities SYSTEM "../../i/gtkgamma/entities.sgml"> %gtkgammaentities;
<!ENTITY % sqlgammaentities SYSTEM "../../i/sqlgamma/entities.sgml"> %sqlgammaentities;
<!ENTITY % ccwentities      SYSTEM "../../i/datahub/ccwcomplete/entities.sgml"> %ccwentities;
<!ENTITY % dhwentities      SYSTEM "../../i/datahub/dhwcomplete/entities.sgml"> %dhwentities;
<!ENTITY % cfentities       SYSTEM "../../i/cfdriver/entities.sgml"> %cfentities;
<!ENTITY % dnentities       SYSTEM "../../i/dndriver/entities.sgml"> %dnentities;
<!ENTITY % pbentities       SYSTEM "../../i/pbdriver/entities.sgml"> %pbentities;
<!ENTITY % gnentities       SYSTEM "../../i/gendriver/setentities.sgml"> %gnentities;
<!ENTITY % apientities      SYSTEM "../../i/api/entities.sgml"> %apientities;
<!ENTITY % hientities       SYSTEM "../../i/historian/entities.sgml"> %hientities;
<!ENTITY % tlentities       SYSTEM "../../i/textlog/entities.sgml"> %tlentities;
<!ENTITY % wpentities       SYSTEM "../../i/papers/entities.sgml"> %wpentities;
<!ENTITY % glentities       SYSTEM "../../i/glossary/entities.sgml"> %glentities;
<!ENTITY % tuindexterms     SYSTEM "../../i/tutorial/indexentities.sgml"> %tuindexterms;
<!ENTITY % commonentities   SYSTEM "../../i/common/entities.sgml"> %commonentities;

<!entity qseman		       SYSTEM "../../i/datahubwin/qse_man.sgml">
<!entity dhman	         SYSTEM "../../i/datahub/dh_man.sgml">
<!entity drsdbook        SYSTEM "../../i/sstdrivers/sd_man.sgml">
<!entity drmbbook        SYSTEM "../../i/sstdrivers/mb_man.sgml">
<!entity srbook          SYSTEM "../../i/srripc/sr_man.sgml">
<!entity drcfbook        SYSTEM "../../i/cfdriver/complete/wrapper.sgml">
<!entity drdnbook        SYSTEM "../../i/dndriver/complete/wrapper.sgml">
<!entity drpbbook        SYSTEM "../../i/pbdriver/complete/wrapper.sgml">
<!entity drgnbook        SYSTEM "../../i/gendriver/bookset/wrapper.sgml">
<!entity tubook          SYSTEM "../../i/tutorial/tu_man.sgml">
<!entity wpbook          SYSTEM "../../i/papers/papers.sgml">
<!entity gloss           SYSTEM "../../i/glossary/gl.sgml">
<!entity faq             SYSTEM "../../i/glossary/faq.sgml">
<!entity extrabooks      SYSTEM "../../i/cogent_set/extrabooks.sgml">
<!entity gamindex        SYSTEM "indexGamma.sgml">
<!entity phgamindex      SYSTEM "indexGammaPhoton.sgml">
<!entity gtkgamindex     SYSTEM "indexGammaGTK.sgml">
<!entity sqlgamindex     SYSTEM "indexGammaMySQL.sgml">
<!entity dhwindex		     SYSTEM "indexCascadeDataHubforWindows.sgml">
<!entity ccwindex		     SYSTEM "indexCascadeConnectforWindows.sgml">
<!entity dhindex         SYSTEM "indexCascadeDataHub.sgml">
<!entity ccindex         SYSTEM "indexCascadeConnect.sgml">
<!entity tlindex         SYSTEM "indexCascadeTextLogger.sgml">
<!entity hiindex         SYSTEM "indexCascadeHistorian.sgml">
<!entity cfindex         SYSTEM "indexCogentDriverforHilscherFieldbu.sgml">
<!entity dnindex         SYSTEM "indexCogentDriverforSST5136DNPDevic.sgml">
<!entity pbindex         SYSTEM "indexCogentDriverforSST5136PFBProfi.sgml">
<!entity gnindex         SYSTEM "indexCascadeGenericDriver.sgml">
<!entity sdindex         SYSTEM "indexDriverforSST5136SDDHDH+Card.sgml">
<!entity mbindex         SYSTEM "indexDriverforSA85ModbusPlusCard.sgml">
<!entity srindex         SYSTEM "indexSRRModule.sgml">
<!entity apiindex        SYSTEM "indexCogentAPIandUtilities.sgml">
<!entity tuindex         SYSTEM "indexCogentToolsDemoandTutorials.sgml">
<!entity setindex        SYSTEM "indexset.sgml">

]>

<set id="CogentDocs">
	<setinfo>
		<title>Cogent Documentation</title>
		<!-- 
		<abstract>
			Add an ASA-related statement here, with web site link. 
		</abstract>-->
		&titlestandard;
		&legalnotes;
		<pubdate>&today-date;</pubdate>
</setinfo>
 <toc>
	</toc>

	&extrabooks;
	
<!--
 <book id="bookwp">
  &wpbook;
	&wpcolophon;
 </book>
-->
 <book id="bookgl">
  &glosswrapper;
	&glcolophon;
 </book>
 <book id="booktu">
  &tubook;
  &tuindex;
	&tucolophon;
 </book>
</set>

<!-- The following code is for test purposes, etc. -->


<!--
<book id="bookdrgn">
 &drgnbook;
 &gnreference;
 &gnindex;
 </book>


&setindex;

-->

5.1.1. Adding new books

Most new books that we create are added to the Cogent Documentation bookset. The procedure below explains how to modify the various files and scripts to add the new book. All steps are to be done from the doc/ directory. The examples use the string nb for the new book internal code name, newbook for its directory name in doc/i/, and nb_man.sgml for its sgml file name.

The existing internal code names for books are show below. For those with two codes, the first code is used more often.

`gam, gm`	Gamma
`phgam, gp`	Gamma/Photon
`gtkgam, gg`	Gamma/GTK
`sqlgam, gq`	Gamma/MySQL
`cc`	Cascade Connect
`ccw`	Cascade Connect in Windows
`cs`	Cascade Connect Client/Server Protocol (not currently published)
`dh`	Cascade DataHub
`dhw`	Cascade DataHub in Windows
`tl`	Cascade TextLogger
`hi`	Cascade Historian
`api, ap`	Cogent API
`cf`	CIF Driver
`drdn, dn`	5136-DNP Driver
`drpb, pb`	5136-PFB Driver
`drsd, sd`	5136-SD Driver
`drmb, mb`	SA85 Driver
`sr`	SRR Module
`tu`	Linux and QNX Tools Demo and Tutorials
`wp`	Cogent White Papers
`gl`	Glossary and FAQ
`pd`	Preparing Cogent Documentation

Procedure 5.1. Procedure

In doc/o/cogent-set/main.sgml add these entities:

<!entity nbbook  SYSTEM "../../i/newbook/nb_man.sgml">
<!entity nbindex SYSTEM "indexNewBook.sgml">

and where necessary:

<!ENTITY % nbentities       SYSTEM "../../i/newbook/entities.sgml"> %nbentities;

Determine in which distribution the book is to appear. Currently we have an "all" distribution that includes everything in the online docs, and "help4" and "help6" distributions for QNX 4 and QNX 6 Helpviewer versions, respectively. Each of these three versions has it's own SGML source file, in doc/i/cogent_set/. The files are
SGML source Used in
extrabooksall.sgml Online HTML docs
extrabooksqnx4.sgml QNX 4 Helpviewer
extrabooksqnx6.sgml QNX 6 Helpviewer
Depending on which version of the bookset gets created, the processing tools copy one of these files to extrabooks.sgml, which appears in the output, as determined by the &extrabooks; entity in the doc/o/cogent-set/main.sgml file.
Most books will go into all three files. Generally speaking, books that are Linux-specific will not go into either of the QNX files, and those that are specific to either QNX 4 or QNX 6 will go into those files, as well as the "all" file. Once you have chosen the correct source file(s), copy these lines of SGML into it:
```
<book id="booknb">
      &nbbook;
      &nbindex;
    </book>
```
In doc/o/Makefile add a new value to the DOCS variable:
```
BOOKS = ... nb-book
```
In doc/o/cogent-set/Makefile add a new value to the .sgml line:
```
.sgml $(wildcard ... ../../i/newbook/nb_man.sgml)
```
If the book is to be included in either QNX Helpviewer distributions, in doc/i/cogent-set/ add the following file:
```
booknb.title 
```
The contents of the file should be of this form:
```
2|New Book Title|booknb/booknb.html
```

SGML source	Used in
`extrabooksall.sgml`	Online HTML docs
`extrabooksqnx4.sgml`	QNX 4 Helpviewer
`extrabooksqnx6.sgml`	QNX 6 Helpviewer

In doc/export/Makefile add these values to their respective lines:

INDS = ... nb-book
      
version: ... .nb-book-pdf

Also add this code towards the end of the file, after the other, similar code:

.nb-book-pdf: pdf/nb-book.pdf.zip 
         rm -f ../distribution/newbook*; \
         cp pdf/nb-book.pdf.zip \
            ../distribution/$$(../bin/revnum newbook pdf \
            vsn-nb-book rev-nb-book all).zip; \
         touch .nb-book-pdf

In doc/i/comon/entities.sgml enter the Software Version number and Document Revision number entity declarations::
```
<!entity vsn-newbook "number">

    <!entity rev-newbook "number">
```

Edit the doc/bin/latestdate.sh file by adding this line in the appropriate place:

echo '<!entity nb-date "' $(recentdate newbook '*') '">' >> ../../i/common/dates.sgml

5.1.2. The QNX Help Book Sets

Our book set for Linux contains more books than the QNX Help book sets, and the QNX 4 and QNX 6 Help book sets contain different books as well. Thus, we have to process each book set separately. Unlike other makefiles, the bookset Makefile differentiates between these two help files, calling them help4 and help6 respectively. Thus, when you make up the bookset for QNX, you have to make each help file separately, calling them like this:

[sh]$ cd ~/doc/o/cogent-set/
[sh]$ make help4
...
[sh]$ make help6


4.2. In one step, and copied to the server		5.2. DataHub and Connect for Windows manuals