Next Previous Contents

14.7 Rules for writing documenentation

In Surprise directory docs/sgml is the centralized storage of documentation for Partition Surprise. The source files are written for SGML-Tools ( version 1.0.x. These documents are incompatible with SGML-Tools Lite series!

As we wanted and needed to compile the documents either as one complete document and also as separate standalone parts, we had to implement some macros for such functionality. Theses macros can be found in "sgml_doc.m4". Each file (to be compilable both standalone and also included into another one) needs to have some headers and footers, takeover them from some existing document, please.

Some rules for writing:

File "sgml_doc.m4" for mandatory-inclusion defines the following macros:


Similiar functionality with default M4 <m4_include> but implements proper handling of doc_sectX macros.


Given text is suppressed if our file is NOT being compiled standalone. Wrap commands like <title > etc. into such section.


Given text is suppressed if our file is NOT being compiled standalone. Wrap commands like </article> etc. into such section.


Print out the given message text to user and abort the compilation. Useful for sanity checking in your own M4 macros.

doc_sect0 ... doc_sect4

Commands similiar to M4 <sectX> but their number (depth) is automatically increased during inclusion between documents. Each document MUST start section-level numbering with doc_sect0! During file inclusion will be the inner file's doc_sect0 placed as subsection of the current outer file's text (and appropriately are also shifted numbers of all successive doc_sects). After the end of included inner file is the numbering of outer file restored to its original behaviour.


Exactly the same as: doc_sectNUMBER


Section numbering will be automatically nested to the current+1 depth during doc_include which may not be always wised. Sometimes you may need to continue with the current level of sectioning although you want to include another file (and other non-trivial cases exist). This doc_sect_set command will work as if doc_sect command would be used instead (with the appropriate level, of course) but NO section is created as the result. Warning: "doc_sect_set(A)doc_sect(B)" will produce "<sectA+B+1>" command! At the start of processing is assumed "doc_sect_set(-1)".

Next Previous Contents