Gammon Forum : MUSHclient : Announcements : MUSHclient documentation generator source released

Entire forum ➜ MUSHclient ➜ Announcements ➜ MUSHclient documentation generator source released

MUSHclient documentation generator source released

Postings by administrators only.

Refresh page

Posted by Nick Gammon Australia (23,162 posts) Bio Forum Administrator

Date

Sun 21 Sep 2008 10:59 PM (UTC)

Amended on Sun 21 Sep 2008 11:05 PM (UTC) by Nick Gammon

Message

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.


  1 General
  2 Notepad=DOC_notepad 
  2 Notes=DOC_note

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:


; This file is maintained by HCW. Do not modify this file directly.

[OPTIONS]
COMPRESS=12 Hall Zeck
LCID=0xc09 0x0 0x0 ; English (Australian)
REPORT=Yes
CONTENTS=DOC_CONTENTS
TITLE=MUSHclient help
COPYRIGHT=Copyright 2003 Gammon Software Solutions
HLP=..\mushclient.hlp

[FILES]
help.rtf

[MAP]
#include help.hm

[WINDOWS]
main="",,27904,(r14876671),(r12632256),f2

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 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 or tags.

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

You can use HTML entities, such as < > and & - in fact all HTML entities are supported. Use, for instance, \ 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>
</code> would become </code></pre>

- Nick Gammon

www.gammon.com.au, www.mushclient.com

Top

Posted by Nick Gammon Australia (23,162 posts) Bio Forum Administrator

Date Reply #1 on Sun 21 Sep 2008 11:03 PM (UTC)

Message

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:


int iHelpType = RTF;    // default to this for now

to:


int iHelpType = HTML;

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.

- Nick Gammon

www.gammon.com.au, www.mushclient.com

Top

The dates and times for posts above are shown in Universal Co-ordinated Time (UTC).

To show them in your local time you can join the forum, and then set the 'time correction' field in your profile to the number of hours difference between your location and UTC time.

10,440 views.

Postings by administrators only.

Refresh page

Go to topic: Search the forum

top