How to use DocMaker v5.00 to build the official PureBasic and SpiderBasic documentation, or to document your custom libraries and modules.
Introduction
If you want to build help files following the PureBasic format, you should use the DocMaker tool as it will lift all the hard work from you.
DocMaker.exe ships with the PureBasic SDK for Windows, and can be found inside the SDK/DocMaker/ subfolder of the PureBasic installation.
DocMaker currently supports the following output formats:
| RTF |
Word 97+ compatible. |
| CHM Help |
for Windows. |
| Multiview |
for Amiga. |
| plain HTML |
for Linux. |
To create help files for your own libraries, modules or applications, you’ll have to write a template file with some special tags, which DocMaker will convert to the target output format.
| For more info on DocMaker’s tags, see the PureBasic DocMaker Tags Guide. |
1. Installing DocMaker
DocMaker is a multi-language tool, which means it has to be in a directory containing a subdirectory for each target language, correctly named after the language. The contents of a DocMaker working directory should be organized in the following manner:
German\
|
subfolder containing all German library files. |
English\
|
subfolder containing all English library files. |
French\
|
subfolder containing all French library files. |
DocMaker.exe
|
the DocMaker application. |
If the working directory is correctly steup, DocMaker should work as expected; just click on the Start button and it will process all the files in the subfolder (according to the selected language).
2. User Library Mode
The ‘User Library’ mode allows to create an help file for a third part library, which will be in the same format as the regular PureBasic help.
It will also be recognized when pressing F1 over a user library command in the IDE, like any built-in command.
In order to enable the F1 Help feature, the generated .chm file must to be placed inside the Help\ directory of the PureBasic installation folder.
|
3. Command Line Usage
You can also invoke DocMaker with the following command line parameters, which are useful to set-up an automated workflow using scripts:
/DOCUMENTATIONPATH
|
Specify the path of the documentation sources (as explained above). |
/OUTPUTPATH
|
The output directory. |
/OS
|
The OS for which the documentation will be compiled.
It can be either |
/LANGUAGE
|
The target language.
The source directory corresponding to the selected language must exist in the folder indicated via |
/FORMAT
|
The output format in which the documentation will be generated.
It can be either |
/CHM
|
Will create a CHM Help file (only supported on Windows).
The |
/HTMLWORKSHOP
|
The full path and filename of the |
/USERLIBRARY
|
Enable the User Library Mode. |
4. Windows CHM Help
Compiled CHM Help files are perfect because they are compact (compressed) and support indexing and searching the help file. Nevertheless creating these files is a long and rather boring process. Don’t worry, DocMaker will handle all the work for you (almost :-).
First, you’ll need to download and install the HTML Help Workshop, a free tool by Microsoft. The application is no longer available from Microsoft’s website, but fortunately it’s still possible to download its archived copy via the Wayback Machine (aka “The Web Archive”, a free service by the Internet Archive):
-
htmlhelp.exe— HTML Help Workshop (3.3 MB, English Installer)
Then launch DocMaker.
A PureBasic Help.hhp file will be created.
If you have installed HTML Help Workshop correctly, it will be launched when double clicking on the PureBasic Help.hhp file.
Then look for the compile button in the toolbar and go for it — you’ve just compiled your first CHM Help file, with index and menus!
5. PureBasic Documentation
The source files of the entire PureBasic Documentation (in three different languages) are now available on GitHub, and can be recompiled using DocMaker, without any problems:
Contributing and Support
Feel free to contribute to this document by submitting your own fixes and improvements via Git and creating a pull request on the PureBasic Open Source repository:
If you have any questions, remarks or suggestions, just write to: <support@purebasic.com>.