MUSHclient documentation generator source released

For completeness of releasing MUSHclient, here is the source code of the program I use to generate the documentation (27 Kb):

http://www.gammon.com.au/files/mushclient/src/docgen_22_Sept_2008.tgz

Here is the SQL of the documentation itself (223 Kb):

http://www.gammon.com.au/files/mushclient/src/documentation.sql.bz2

It may take a bit of fiddling to get it to work, you would need to adjust hard-coded path names in the source, import the SQL into a mySQL database, and set up an ODBC source to point to that SQL database.

---

Help data organisation ...

Help comes from seven tables in the database:

• commands - menu commands (ID_xxx)
• dialogs - dialogs (IDD_xxx) and views (IDR_xxx)
• functions - script functions
• general_doc - miscellaneous documentation
• errors - error codes
• lua_functions - Lua functions
• tblUnixControl - RTF preamble and postamble
  

Run this program to output a help.rtf file (see stdafx.h for location) which then calls the help compiler to generate the output help file (xxx.hlp).

The contents file (mushclient.cnt) is a simple text file - it is not compiled in any way. Simply put topics and their topic IDs in it using an editor.

eg.



The initial number gives the "level". If there is no = sign then it is a topic "group" otherwise it is an item.

There are various SQL statements in the source to simplify pulling out lists of things like functions and dialogs from the database.

The general help topics have "special" fields (eg. 1 = contents ) which tell this program to do extra things (eg. contents adds each general item to the page, functions lists each function and so on).

The help compiler needs an xxx.hpj file. It is quite simple, like this:

---

The program automatically calls "hcw" the Windows help file compiler. You would need that installed to run this.

The map file (which maps topic names to numbers) is generated by this program. It assumes ID offets as documented in map.cpp to avoid name clashes beteen dialogs, commands and general topics.

---

HELP DATABASE FORMAT

The topics in the databases (excepting the functions at present, for historical reasons) are in a pseudo-HTML (or XML-like) format. This program uses a recursive-descent parser to interpret them, and then outputs the appropriate tags (for the target format, eg. RTF). If we were outputting HTML then they would be converted back to roughly what they were.

We use a subset of HTML because it needs to be supported by the output format, eg. underlines have a special meaning in the help file, so there is no <u> tag.

Also, for easier parsing, tags with no content (eg. <hr>) must be added as <hr/> (like XML) so the parser knows not to descend. Similarly for <li/>.

Newlines in the file become newlines in the help, so there is no need for <p> or <br> tags.

See output.cpp which has a table of currently-supported tags.

You can use HTML entities, such as &lt; &gt; and &amp; - in fact all HTML entities are supported. Use, for instance, &#x5C; to represent a backslash.

To turn the text into HTML online (eg. in PHP) all you would need to do is run nl2br on the text to fix up line breaks, and convert any special cases

eg. <code> would become <pre><code><font size=2>
</code> would become </font></code></pre>

This exact same database is uploaded to this web site to provide online help - which is accessible from this page:

http://www.gammon.com.au/scripts/doc.php

That reads the database used to generate the help file and dynamically generates HTML web pages.

The program documented above can also generate the "flat" HTML web pages by changing one line in docgen.cpp:

From:



to:



Then when executing the program it generates a web page per documentation page, which can then be zipped up together and distributed for offline web browsing.