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 ( http://www.sgmltools.org 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:

• M4 compilation is done with -P flag so please be aware of "m4_" prefixes for all M4 commands!
• Any anchors (defined by label SGML-Tools command) should be unique for the whole Partition Surprise project! Prefixing of your anchors by document name shortcut is recommended.
• NEVER use <sect> (or <sectX>), use doc_sectX keyword instead, see its definition below.
• NEVER use <m4_include>, use doc_include keyword instead, see its definition below.

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

doc_include(FILENAME)

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

doc_header(TEXT)

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

doc_footer(TEXT)

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

doc_fatal_error(MESSAGE)

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.

doc_sect(NUMBER)

Exactly the same as: doc_sectNUMBER

doc_sect_set(NUMBER)

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)".