CreateHelp

Help Functionality in XTrackCAD

Overview

To assist the user a lot of effort has gone into creating and maintaining a help system that can be used on all supported platforms.
This page describes the implementation. It is useful for developers who want to extend the XTrackCAD functionality and for documentation writers.
* Writing Help explains the source format and the link between application and the help system. Information is useful for writers and coders.
* Conventions describes the structure of the help source and is mostly oriented towards documentation writers.
* Adding help explains how help is implemented on the different supported platforms.
Core for the creation of help is the Halibut Document Preparation System: [http://www.chiark.greenend.org.uk/~sgtatham/halibut/] that was slightly extended for the use in XTrackCAD. This extended version is included in the source code distribution of XTrackCAD and can be built with the CMakeBuild.

Writing Help

Conventions

XTrackCAD uses Halibut for writing help for its functions.
Their user manual: [http://www.chiark.greenend.org.uk/~sgtatham/halibut/doc-1.1/] has a description of the syntax.

For XTrackCAD including bitmaps as an additional feature was implemented.

\G{png.d/colorw.png}

The bitmap png.d/colorw.png is loaded and placed at the current position. Note Usage of bitmaps is only supported for HTML output.

Screenshots and other images are stored in the png.d subdirectory of the halibut source.
Help is mostly organized according to the structure of the pulldown menus. A few additional files are used for general information.

Adding Help

The following is a snippet from optionm.but, the help file for the Option menu:

\S{cmdRgbcolor} Colors Dialog
The \f{Colors} dialog is invoked from the Options (\K{optionM}) menu
\G{png.d/colorw.png}
The \f{Colors} dialog controls the color that various objects are drawn.

//cmdRgbcolor// is the anchor point for that help topic. In the C code it is referenced from the dialog definition:

static paramGroup_t colorPG = { "rgbcolor", PGO_RECORD|PGO_PREFGROUP, colorPLs, sizeof colorPLs/sizeof colorPLs[0] };

Notice that the 'cmd' prefix has to be omitted.
//png.d/colorw.png// is the screenshot for that dialog box.
{optionM} links to additional information.

Linux

Individual HTML files are generated from the but source. The filename of the HTML file is created from the anchor:

\S{cmdRgbcolor} Colors Dialog

creates a HTML file called ##cmdRgbcolor.html##
During program execution these files are displayed by an embedded browser. This browser uses the webkit2 rendering engine.
The platform specific configuration is in Linux Configuration: [https://sourceforge.net/p/xtrkcad-fork/xtrkcad/ci/default/tree/app/doc/linconf.but]
The CSS definition is stored in Linux Webkit2 CSS: [https://sourceforge.net/p/xtrkcad-fork/xtrkcad/ci/default/tree/app/doc/xtrkcad_lin.css]

MacOSX

Work in progress

Windows

On Windows the compressed HTML format (CHM) is used. This is one of the native formats for this platform and should be familiar to users.
The platform specific configuration is in CHM Configuration: [https://sourceforge.net/p/xtrkcad-fork/xtrkcad/ci/default/tree/app/doc/chmconf.but]
The CSS definition is stored in Windows Compressed Help CSS: [https://sourceforge.net/p/xtrkcad-fork/xtrkcad/ci/default/tree/app/doc/xtrkcad_win.css]

CategoryDevel