[lazarus] pasdoc update

Marco Schmidt marcoschmidt at geocities.com
Sun Apr 9 18:05:34 EDT 2000


I read the Lazarus mailing list archive with the discussions about
documentation and what pasdoc needs to have to be more useful. I
modified pasdoc and now send some information on the update to this
list because most pasdoc users seem to read it ;-) The latest version
(0.6.15) is now available on the homepage at

1) External file switch -c

Pasdoc now supports loading of descriptions from one or more external
files. You specify such a text file with the -c switch:

> pasdoc src/*.pas -c descr1.txt -c descr2.txt

In theory you could put /all/ descriptions in a single file, but that
wouldn't make much sense for distributed development as in the case of
Lazarus. Let's say you take one description text file per unit, e.g.
buttons.txt for the buttons unit. It could look like this:
-- beginning of file buttons.txt
# Buttons.TButton.FDefault
This is a description of the field
FDefault of class TButton in unit Buttons.
If you feel lucky, you can leave out the unit or even class
name, but chances are that there may be other items called FDefault.
Specifying the whole 'path' to an item also makes it easy to merge
description files.
Anyway, it is important to have one line with # at the beginning
by whitespace and then the item name. After that an arbitrary number
descriptive lines like these.
That's why # characters cannot appear as the first character of a
description line, I hope that's not a problem.
Those description lines are treated the same way as a comment that
precedes the item in the interface section of a unit.
# buttons.TButton.FModalResult
Description of FModalResult...
-- end of file buttons.txt

Note that there is a possible problem now in cases where you have
specified descriptions in an external file /and/ the interface section
of the unit. Pasdoc writes a warning to stdout in these cases and
takes the description from the interface section.

This switch needs more thorough testing, so please tell me about
problems here!

2) Include file switch -u DIR

This is relatively new - to tell pasdoc where to look for include
files, use the -u DIR switch:

> pasdoc src/*.pas -u inc -u src

will make pasdoc look in the current directory first, then in
subdirectory inc,
then in subdirectory src. As soon as one include file could be opened,
the search
is over (in case you have include files of the same name in two or
more of the
specified directories).

3) Pasdoc homepage has changed

It has moved to http://pasdoc.sourceforge.net/, there is a mailing
list as well.

4) Implementation section of units

Just to make it clear, pasdoc never touches the implementation section
of a unit. As soon as it encounters the implementation keyword in a
unit, it closes the file!

5) Translators wanted

Pasdoc currently knows English, French, German, Catalan and Spanish.
Slovak may be added soon. If you speak another language (Dutch,
Russian, ...), please translate the 45-50 string constants in
gendoc.TDocGenerator.GetEnglishString and send them to me! Or drop me
a mail and I'll send you these strings! I learnt from feedback that
people like to use their native language for documentation.

6) Author tags

Within an author tag you don't have to escape the @ character by using
@@ - simply use the following (nested parentheses are possible),

@author(Marco Schmidt (marcoschmidt at geocities.com))

BTW, email addresses in author tags are now recognized and appear in
HTML output as mailto links.


More information about the Lazarus mailing list