Chapter2.Making Edits in doc/i/

Table of Contents

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

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.

2.1.Finding the source files

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.sgmlCogent API user's guide.
api/re_*.sgmlCogent API reference pages.
api/apiappendix.sgmlCogent API appendix file.
api/entities.sgmlCogent 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_*.sgmlDriver-specific reference pages for Cascade Compatible Cogent Drivers.
xxdriver/sect_*.sgmlDriver-specific sections for Cascade Compatible Cogent Drivers.
xxdriver/para_*.sgmlDriver-specific paragraphs for Cascade Compatible Cogent Drivers.
xxdriver/entities.sgmlDriver-specific entities file Cascade Compatible Cogent Driver.
cogent_set/*.titleTitles of books in the Cogent Documentation bookset, for the QNX Helpviewer Table of Contents.
common/*.sgmlMaterial 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.sgmlCascade Connect manual.
cserve/cs_man.sgmlCascade Connect Client/Server Protocol manual.
datahub/dh_man.sgmlCascade DataHub manual.
gamma/guide.sgmlGamma user's guide.
gamma/ex_*.gGamma examples.
gamma/*.datGamma data files for examples.
gamma/re_*.sgmlGamma reference pages.
gamma/rs_*.sgmlGamma reference section wrappers.
gamma/t_*.gGamma tutorials.
gamma/frontgam.sgmlA wrapper for PDF output.
gamma/entities.sgmlGamma entities file.
glossary/faq.sgmlFAQ content.
glossary/gl.sgmlGlossary definitions.
glossary/termslist.sgmlAn auto-generated list of glossary terms.
glossary/entities.sgmlGlossary entities file.
gtkgamma/guide.sgmlGamma/GTK user's guide.
gtkgamma/ex_*.gGamma/GTK examples.
gtkgamma/re_*.sgmlGamma/GTK reference pages.
gtkgamma/t_*.gGamma/GTK tutorials.
gtkgamma/frontgam.sgmlA 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.sgmlGamma/GTK entities file.
historian/hi_man.sgmlCascade Historian manual.
historian/re_*.sgmlCascade Historian reference pages.
historian/descriptions/*Descriptions common to the Cascade Historian and Cogent API manuals.
papers/art1.sgmlCadbury Chocolate Project Review white paper.
papers/art2.sgmlInterprocess Communication white paper.
papers/art3.sgmlHot Standby for InTouch white paper.
papers/art4.sgmlGamma Discussion - Interpreted Languages white paper.
papers/art5.sgmlAsynchronous Messages white paper.
papers/art6.sgmlShared Memory vs. Real-Time Database white paper.
papers/p*.sgmlPDF wrappers for the above white papers.
papers/entities.sgmlCogent White Papers entities file.
phgamma/guide.sgmlGamma/Photon user's guide.
phgamma/ex_*.gGamma/Photon examples.
phgamma/WidgetFiles/*Photon Widget files for examples.
phgamma/re_*.sgmlGamma/Photon reference pages.
phgamma/rs_*.sgmlGamma/Photon reference section wrappers.
phgamma/t_*.gGamma/Photon tutorials.
phgamma/*.gGamma/Photon other code.
phgamma/frontphgam.sgmlA wrapper for PDF output.
phgamma/entities.sgmlGamma/Photon entities file.
prepdoc/pd_man.sgmlPreparing Cogent Documentation (this document).
sqlgamma/guide.sgmlGamma/MySQL guide.
sqlgamma/reference*.sgmlGamma/MySQL reference chapters.
sqlgamma/re_*.sgmlGamma/MySQL reference pages.
sqlgamma/entities.sgmlGamma/MySQL entities file.
srripc/sr_man.sgmlSRR Module manual.
sstdrivers/sd_man.sgmlCogent Driver for SST 5136-SD (Data Highway Plus) Cards manual.
sstdrivers/mb_man.sgmlCogent Driver for Modicon SA85 and PC85 (Modbus Plus) Cards manual.
testfile/testset.sgmlA test set.
testfile2/testbook2.sgmlA test book.
textlog/tl_man.sgmlCascade TextLogger manual.
textlog/*.txtCascade TextLogger sample output.
textlog/tl.cfgCascade TextLogger sample config file.
tutorial/tu_man.sgmlLinux and QNX Tools Demo and Tutorials manual.
tutorial/*.gLinux 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.sgmlA wrapper that holds the reference pages.
wrapper.sgmlA wrapper used by cogent-set.
entities.sgmlA collection of entity declarations for the files that this book incorporates.