| Preparing Cogent Documentation : | ||
|---|---|---|
 | Chapter 2. Making Edits in doc/i/ |  |
| Preparing Cogent Documentation : | ||
|---|---|---|
| | Chapter 2. Making Edits in doc/i/ | |
Table of Contents
For simple editing such as correcting typos and adding punctuation marks, editing SGML is pretty much the same as editing any other document. Open it, make the changes, save it, and close it. But if your edit involves, for example, moving text, adding software terminology, putting in a list or table, removing a section, or making any structural changes, you're going to need a a pretty good understanding of the material in this chapter.
To edit the source code you first have to know where to find it. Cogent document source files fall into two basic categories: one-file books and multi-file books. Our smaller manuals are one-file books, whose main SGML source text is contained in one file. These books include Cascade Connect, Cascade DataHub, Cascade Historian, Cascade TextLogger, individual white papers, and the SST Driver manuals.
The other books would be awkward to edit as one file since they have dozens or hundreds of reference pages. So their SGML source is put into one file for the manual, and additional files--one for each reference page. These books include Gamma, Gamma/Photon, Gamma/GTK, Cogent API, and the CIF Driver manual (whose unique organization is explained in the Cascade Driver manuals section of the Special Organization chapter).
All the SGML source files can be found in the doc/i/ directory, each book having its own subdirectory. Here is a list of the doc/i/ subdirectories, with their files and the book(s) they correspond to:
| api/guide.sgml | Cogent API user's guide. |
| api/re_*.sgml | Cogent API reference pages. |
| api/apiappendix.sgml | Cogent API appendix file. |
| api/entities.sgml | Cogent API entities file. |
| cfdriver/* | Cogent Driver for Hilscher Fieldbus CIF Cards |
| dndriver/* | Cogent Driver for SST 5136-DNP (DeviceNet) Cards |
| pbdriver/* | Cogent Driver for SST 5136-PFB (Profibus) Cards |
| gendriver/* | Cogent Driver generic content. |
| xxdriver/re_*.sgml | Driver-specific reference pages for Cascade Compatible Cogent Drivers. |
| xxdriver/sect_*.sgml | Driver-specific sections for Cascade Compatible Cogent Drivers. |
| xxdriver/para_*.sgml | Driver-specific paragraphs for Cascade Compatible Cogent Drivers. |
| xxdriver/entities.sgml | Driver-specific entities file Cascade Compatible Cogent Driver. |
| cogent_set/*.title | Titles of books in the Cogent Documentation bookset, for the QNX Helpviewer Table of Contents. |
| common/*.sgml | Material common to most or all books, such as legal boilerplate, title page graphic, etc., as well as the entities common to all books. |
| connect/cc_man.sgml | Cascade Connect manual. |
| cserve/cs_man.sgml | Cascade Connect Client/Server Protocol manual. |
| datahub/dh_man.sgml | Cascade DataHub manual. |
| gamma/guide.sgml | Gamma user's guide. |
| gamma/ex_*.g | Gamma examples. |
| gamma/*.dat | Gamma data files for examples. |
| gamma/re_*.sgml | Gamma reference pages. |
| gamma/rs_*.sgml | Gamma reference section wrappers. |
| gamma/t_*.g | Gamma tutorials. |
| gamma/frontgam.sgml | A wrapper for PDF output. |
| gamma/entities.sgml | Gamma entities file. |
| glossary/faq.sgml | FAQ content. |
| glossary/gl.sgml | Glossary definitions. |
| glossary/termslist.sgml | An auto-generated list of glossary terms. |
| glossary/entities.sgml | Glossary entities file. |
| gtkgamma/guide.sgml | Gamma/GTK user's guide. |
| gtkgamma/ex_*.g | Gamma/GTK examples. |
| gtkgamma/re_*.sgml | Gamma/GTK reference pages. |
| gtkgamma/t_*.g | Gamma/GTK tutorials. |
| gtkgamma/frontgam.sgml | A wrapper for PDF output. |
| gtkgamma/autodocs/* | Tools used for auto-generating Gamma/GTK reference pages. |
| gtkgamma/code/* | Code used for creating Gamma/GTK examples. |
| gtkgamma/entities.sgml | Gamma/GTK entities file. |
| historian/hi_man.sgml | Cascade Historian manual. |
| historian/re_*.sgml | Cascade Historian reference pages. |
| historian/descriptions/* | Descriptions common to the Cascade Historian and Cogent API manuals. |
| papers/art1.sgml | Cadbury Chocolate Project Review white paper. |
| papers/art2.sgml | Interprocess Communication white paper. |
| papers/art3.sgml | Hot Standby for InTouch white paper. |
| papers/art4.sgml | Gamma Discussion - Interpreted Languages white paper. |
| papers/art5.sgml | Asynchronous Messages white paper. |
| papers/art6.sgml | Shared Memory vs. Real-Time Database white paper. |
| papers/p*.sgml | PDF wrappers for the above white papers. |
| papers/entities.sgml | Cogent White Papers entities file. |
| phgamma/guide.sgml | Gamma/Photon user's guide. |
| phgamma/ex_*.g | Gamma/Photon examples. |
| phgamma/WidgetFiles/* | Photon Widget files for examples. |
| phgamma/re_*.sgml | Gamma/Photon reference pages. |
| phgamma/rs_*.sgml | Gamma/Photon reference section wrappers. |
| phgamma/t_*.g | Gamma/Photon tutorials. |
| phgamma/*.g | Gamma/Photon other code. |
| phgamma/frontphgam.sgml | A wrapper for PDF output. |
| phgamma/entities.sgml | Gamma/Photon entities file. |
| prepdoc/pd_man.sgml | Preparing Cogent Documentation (this document). |
| sqlgamma/guide.sgml | Gamma/MySQL guide. |
| sqlgamma/reference*.sgml | Gamma/MySQL reference chapters. |
| sqlgamma/re_*.sgml | Gamma/MySQL reference pages. |
| sqlgamma/entities.sgml | Gamma/MySQL entities file. |
| srripc/sr_man.sgml | SRR Module manual. |
| sstdrivers/sd_man.sgml | Cogent Driver for SST 5136-SD (Data Highway Plus) Cards manual. |
| sstdrivers/mb_man.sgml | Cogent Driver for Modicon SA85 and PC85 (Modbus Plus) Cards manual. |
| testfile/testset.sgml | A test set. |
| testfile2/testbook2.sgml | A test book. |
| textlog/tl_man.sgml | Cascade TextLogger manual. |
| textlog/*.txt | Cascade TextLogger sample output. |
| textlog/tl.cfg | Cascade TextLogger sample config file. |
| tutorial/tu_man.sgml | Linux and QNX Tools Demo and Tutorials manual. |
| tutorial/*.g | Linux and QNX Tools Demo and Tutorials Gamma program source code. |
| tutorial/chunks/* | Auto-generated chunks of source code that are included as entities in tu_man.sgml. |
In addition to the above list, the multi-file books have some extra files used to organize the SGML and give us the correct output. Generally you won't be editing these unless you make structural changes to a document. Among these extra files are:
| reference.sgml | A wrapper that holds the reference pages. |
| wrapper.sgml | A wrapper used by cogent-set. |
| entities.sgml | A collection of entity declarations for the files that this book incorporates. |
| |  | |
| 1.2. Single-sourcing with DocBook |  | 2.2. Elements and tags |
Copyright © 1995-2004 by Cogent Real-Time Systems, Inc. All rights reserved.