Before generating any output, the SGML source must be validated. Our output generators automatically validate the source during processing, but it can take a little time. If you do it yourself, you can validate it faster, as well as find and change the errors more easily. I recommend using Emacs/PSGML for validating. It works quickly, and has a feature that lets you jump from one error to the next.

To validate a document, you must first find the book's SGML wrapper (main.sgml) in the doc/o/bookname/ subdirectory (as listed in Output file subdirectories), and open it. For example, to validate the Cascade DataHub source code, you would open the doc/o/dh-book/main.sgml file.

Then run your validation program. For example, in Emacs/PSGML, press Ctrl-C Ctrl-V. If there are any errors, the window will split into two, with the bottom window showing what the errors are. Pressing Alt-N opens the SGML source file and puts the cursor at the line where the error occurs. You can then edit the error, save the file, and press Alt-N again to move to the next error. Once all errors have been corrected, you can validate the document again. If there are any uncorrected or new errors, they will be detected. When all errors have been corrected, the document is valid and the following message will appear:

SGML validation finished at day month date time

Now you are ready to generate output.

Many of our books have links between them that are valid only in the Cogent Documentation bookset. When validating or processing a single book, these links have no target, and the processor throws an error that looks like this: jade:../../../i/datahub/dh_man.sgml:281:11:X: reference to \ non-existent ID "APDX-CODE-READPT" Don't worry, your book will still be processed OK as long as these are the only errors. Invalid links still appear in the output, as plain text. Since this type of validation error is of little importance, these errors always appear last in the error message list, separating them from genuine errors. Usually you can ignore them unless you are processing the Cogent Documentation bookset.