Delphi Inspiration

Components and Applications

User Tools

Site Tools


products:pasdoc:index

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

products:pasdoc:index [2016/01/22 15:08] (current)
Line 1: Line 1:
 +====== PasDoc ======
  
 +{{page>​header}}
 +
 +===== Overview =====
 +
 +DIPasDoc is the only free help generator that flawlessly follows compiler defines and include files. DIPasDoc is the ideal tool for source code documentation,​ both for your company'​s in-house library and your customers.
 +
 +===== Usage =====
 +
 +The DIPasDoc syntax tries to immitate commands from the Delphi command line compiler BCC32.exe if possible, even though it is heavily extended by special preprocessor functionality. Type:
 +
 +  * ''​DIPasDoc -?''​ for the full syntax, or
 +  * ''​DIPasDoc -? | more''​ to display one screen at a time only.
 +
 +To test DIPasDoc.exe creating HTML output, run ''​Create_Help.bat''​. This will run DIPasDoc on its own sources, and place the documentation files in the ''​.\Help''​ directory. Open any of the HTML files in your browser to see the result. Since the DIPasDoc source comments are not specially beautified for HTML documentation,​ it looks a bit odd at times. However, you will still get an impression of the possibilities of DIPasDoc.
 +
 +===== MS HTML Help =====
 +
 +{{htmlhelp.gif |HTML Help}}To create a MS HTML Help project, run ''​Create_HtmlHelp.bat''​. This will again run DIPasDoc on its own sources but create optiomized HTML files as well the HTML Help project files in the ''​.\Help''​ directory. DIPasDoc will then try to located the MS HTML Help compiler on your system and run it. After successful compilation,​ a new ''​Help.chm''​ file will be placed in the ''​.\Help''​ directory, ready to be used.
 +
 +If DIPasDoc does not find the MS HTML Help compiler, you must manually compile the HTML Help project. Run the HTML Help Workshop, go to the DIPasDoc Help directory and open Help.hpp. Then click compile. All the rest works as with automatic compilation.
 +
 +===== Custom Contents =====
 +
 +{{ tdipasdoc_properties.png|TDIPasDoc Component Properties}}The ''​-C<​FILE>''​ switch allows you to specify a file from which DIPasDoc generates the HTML Help contents file. This can be used to restructure the default order of items, to include additional topics, or to link additional HTML files. If no custom file is used, DIPasDoc generates a default contents file.
 +
 +The "​grammar"​ of the custom contents file is simple. It is set up as a "tree of lines",​ where each line is one item. All lines must contain a ''​Text=Link''​ pair separated by the equal sign, where ''​Text''​ shows up as text in the HTML Help context tree and ''​Link''​ points to a file relative to the path where the HTML Help project file will be located. Lines beginning with white-space start new hierarchies.
 +
 +As an example, this is the custom contents file used by ''​Create_HtmlHelp.bat'':​
 +
 +<​code>​
 +Introduction=
 + Read me first=..\ReadMe.htm
 + ​License=..\License.txt
 + ​=@Legend
 +AllUnits=@Units
 +=@ClassHierarchy
 +=@Classes
 +Other files generated=@Overview
 +</​code>​
 +
 +The various combinations of ''​Text=Link''​ lines have the following meaning:
 +
 +  * **Line 1** does not have a link (no text after "​="​),​ "​Introduction"​ will only be a book for other items.
 +  * The next three **lines 2, 3, 4** are indented by one white-space character, which makes them subitems of line 1.
 +  * Notice that **lines 6 & 7** do not have Text parts (no characters in front of "​="​),​ so the HTML Help compiler will take the title of the linked page as the text.
 +
 +There are some shortcuts which DIPasDoc automatically expands. Their names are self-explanatory,​ so run ''​CreateHtmlHelp.bat''​ to see their effects. Notice that you can also link custom HTML documents, like lines 2 and 3 do.
 +
 +===== TDIPasDoc Component =====
 +
 +{{ tdipasdoc_events.png|TDIPasDoc Component Events}}The core Pascal source code documentation engine is available as a its own ''​TDIPasDodc''​ class, which inherites from ''​TComponent''​. This allows other applications to use DIPasDoc as their documentation engine. Examples are the official DIPasDoc_Console application,​ as well as GUI applications (also included) or automatic build systems.
 +
 +===== Future Features =====
 +
 +Lots could be improved, but time is precious. Below is a list of suggestions. If anybody is interested, grab the source and start coding:
 +
 +  * More customizations (colors, fonts, etc.) should be among the more simple things on the list. Speaking in more general terms, templates would be nice to have.
 +  * Frames -- loved by some, hated by others -- might improve HTML layout and make it look more like the Delphi Help with class properties and methods in a frame on the left and their descriptions to the right.
 +  * Language-dependent stopword lists for HTML Help full text search to create smaller *.chm files.
 +  * mproved parsing is needed to incorporate new Delphi language extensions.
 +  * More output styles. If someone could add RTF-output this would be more than welcome, even if Vista no longer installs WinHelp by default. Also, LaTeX has been requested once.
 +
 +===== Contribute =====
 +
 +DIPasDoc does a nice job, so have fun with it. If you are using it for something useful and would like to let others know, feel free to add yourself to the [[wiki:​users|users page]] or share your thoughts and code at the [[wiki:​pasdoc:​|DIPasDoc Wiki]].
 +
 +{{tag>​docs documentation "​documentation generator"​ help html htmlhelp}}
products/pasdoc/index.txt · Last modified: 2016/01/22 15:08 (external edit)