How to use program.

This chapter contains detailed information about dHelp usage and formats of input and output files. Here you can find information about:

• Command line parameters describes the format, meaning and default values of all command line parameters. 
• Project management controls describes the main element of the user interfaces through which help project can be managed.
• Format of the topic description files describes in detail the structure and process of the creation of the topic description files. Provides an example of the single topic description.
• Precompiled headers (.DPU files) describes what precompiled headers are, how they can be used and how you can generate them.

Command line parameters

dHelp has number of command line parameters that define program behavior and allow you to include dHelp into automatic generation routines. The format of the command line of the dHelp Pro program is:

    dHelp <op_type> <project_file> [[-<parameter_1> [-<parameter_2> [...]]]]

<op_type> – this parameter can have one of the following values:
 

<project_file>–specifies the name of the file with project options.

Note: When <op_type> is i or u then <project_file> must be a name of the help file, which will be installed or uninstalled.

Parameters - a set of the following parameters:

Here is the sample command line that can be passed to dHelp:

Project management 

You can use main menu to open, save, and to add new units to the open project.

File - group contains controls for help projects loading and savings.
 

Item	Description
New	Creates a new project and initializes its properties.
Load	Loads existing projects.
Save	Saves the current help project using its current name
Save As ...	Saves the current help project using a new name.
Team work support	dHelp supports team work on a single help project. Each member of a team writes help in separate files in plain text format. Team leader can distribute task in the form of description frames . To do so he can export empty topics description to files with plain text format and then merge team members' work in a help project using importing descriptions of the topics from text files.  Export can be used for further storing topics description in archive. Export/Import options are also very useful if you need to share the description of several topics between several help projects.
Exit	Closes the open project and exits dHelp.

Help project is stored in a single “.hpc” file. It contains project options, the list of source code units and entered help descriptions. Information stored in project file allows you to work on the help project even if you have no source code of the units.

Use Project menu to manage project options. Here you can add new units to the open project, update the project contents using the latest changes in source code, customize different project options and build help files.
 

Item	Description
Add units	Chooses 'Add units' item to add source code units into open help project.
Refresh contents tree	Rescans the source units and updates the help contents. New topics will be added into contents section. dHelp will inform user about topics that are no longer exist and suggest you to choose whether to delete inactive descriptions or store them in files with plain text format.
Build help	Generates help file. When you select this file help building options dialog is displayed as a start of help building process.
Options	Shows dialog for customizing help project options.

Use View menu to manage the current view of the project contents section. Here you can highlight not described or partially described topics, manage the contents section and customize what diagnostic windows are displayed by the program.

Use the Help menu to access the online Help system, which is displayed in a special Help window.

Custom help project options window.

Main help project options are divided into three groups:

• General options - contains common management information about project contents, and Delphi version which will be used while parsing source code units.
• Directories/Conditions - specifies the location of files used while parsing the units, and the place where generated files and diagnostic information will be stored. Group also contains conditional defines and module aliases used while parsing source code units.
• Help generation - options that customize the contents of the generated help. Here you can specify used images, and rules used to generate contents section.

General options.

Directories/Conditions.

Help generation.

Help building options dialog.

Help building option dialog contains options that are important for building help. Here you can specify the kind of generated help file and the location of help compilers. Help building options dialog starts the help generation process. All options specified in this dialog are saved in the help project file along with other options.
 

Item	Description
Kind of help	Specifies what kind of help file will be generated. dHelp support following kinds of help/manuals: WinHelp format (HLP file). Microsoft HTML Help (CHM file). Manual in RTF format. Manual in HTML format.
Delete temporary file	Indicates whether the temporary files will be deleted after the help is generated. When program generates help file it creates temporary files with topic descriptions in RTF or HTML format in the project destination folder. These files are used by a help compiler. You can use temporary files as a source of the descriptions for your custom manual. When dHelp creates help in the HLP format all topic descriptions are gathered in to the single RTF file. When dHelp creates help in the CHM format there will be separate file for each topic, list of properties, methods, events and hierarchy tree in the HTML format.
Ignore existent DPU files	Determines whether to ignore existing DPU files. If this parameter is not specified, parser will use previously compiled information for modules that have not been changed. Parameter can also be set from the command line through the -IGNDPU parameter.
Path to the help compilers	Specifies the location of the compiler which can be used to generate the help in the format specified in Kind of help property. dHelp finds installed compiler itself. If you don't have help compiler installed you can download it from: Microsoft Help Workshop (HLP compiler): http://support.microsoft.com/download/support/mslfiles/HCWSETUP.EXE http://support.microsoft.com/support/downloads/DP2677.ASP HTML Help Workshop (CHM compiler): http://msdn.microsoft.com/workshop/author/htmlhelp

Format of the topic description files

dHelp uses text files for storing topic descriptions.  When file with descriptions is imported by dHelp, the following rules take place:

• Topics can include only tags with reserved names, other tags are treated as a start of the new topic description and tag name serves as the name of the topic. Units, procedures, variables, types and classes are shown by their name. For methods, properties and events you must indicate class name before topic name and separate them with dot.
   

  <MyUnit> <MyClass> <MyClass.NewProperty> <MyClass.CustomEvent> <MyProcedure>

• Every tag name is started from open triangle bracket "<" and ended with close triangle bracket ">". The tag contents continues until the next tag definition.

• File can have comments enclosed in “<!--” and “-->” symbols. The text inside these symbols is ignored when descriptions are imported.

Here is an example of the descriptions file structure:

Description can contain the following tags:

<Definition> - the contents of this tag is ignored during help file generation. When dHelp generates empty frames for the topic descriptions it inserts there an example of the topic declaration as it will be displayed in the generated help.

<Description> - tag contains the full description of the topic.

<See Also> - heads reference section. All elements must be a reference to the valid topic within your library or standard VCL library. When you reference to the topic you must specify it's name using the following rules:

• Procedures, variables, types and classes are referenced by their names.

• Class members (methods, properties, events) must be referenced with the class name before it (for example: TPSCCalendar.Multiselect). If topic is a member of the class that is currently described class name can be omitted. Multiple elements can be separated by comma or entered in the separate lines.

Brief description must be included in the section right after new topic is started.

Warning: '<' and '>' symbols are reserved words. If you want to use such characters in your description you must use two sequential brackets. For example:
 

<Description> .. procedure returns the full path: "C:\WINDOWS>>" ...

Note: You can point program to get topic description from another topic. In this case dHelp will ignore Brief description, Description, See Also sections of the topic and substitute them by the corresponding sections from the referenced topic. To do this you must specify the referenced topic inside the tag that begins topic with '=' symbol between topic and referenced topic.

<Topic=Referencing_Topic>

Example:
 

<TPSCCustomDateEdit.Kind=TPSCPopupCalendar.PopupKind>

dHelp validates description files and informs about errors using pscFH_FailedTopic, pscFH_NoBodyDesc, pscFH_NoBriefDesc, pscFH_BadLinks diagnostic files.

Precompiled headers (.DPU files)

dHelp uses source code parser that processes Delphi units. Unit parser stores information about every parsed unit in files with DPU extension so that the next time it needs to parse the file it loads DPU file which is much faster. dHelp creates directory DPU_<Compiler_Version> in folder for temporary files and generates DPU files there.

To use DPU files for the VCL, you must specify path where these DPU files are stored in the -INC parameter of the dHelp command line.

Example: