[Developers] About plugin documentation

[Bert Bril]

Hi all,

Faiqa is of course right in that I'm vague about how this help stuff
works. Privately, I was asked:

> I cant find documentation you added for
> programming plugin SeisIOSimple. I don't see it in the Programmer's
> manual. Could you provide me with the link to your documentation?

If you look in the code (uiseisiosimple.cc), you see that the object
gets a help ID like: "extra:103.0.1".

This means that OpendTect will look for a help object "103.0.1" in a
subdirectory 'extraDoc' of the 'data/' subdirectory of the OpendTect
tree. Thus, 'Doc' is appended to the help ID scope to construct the
directory that contains the HTML files. Note that most OpendTect help
IDs have no scope, then the directory is dTectDoc.

Now we have the doc subdirectory, the '103.0.1' can be found in the
WindowLinkTable.txt file:

103:    Seismics
        0:      I/O
                1:      uiSeisIOSimple          link-Seis.Simple.Import
                2:      uiSeisIOSimple          link-Seis.Simple.Export

You are completely free to choose your index numbers, if you scope the
help ID. So it could equally well have been "extra:55.999.2". The class
name (i.c. uiSeisIOSimple) is not used but is handy for us, programmers
to know what it is. The link name is also free, as long as it
corresponds to what is in the link-file table.

So the WindowLinkTable.txt specifies the link in a HTML file that needs
to be displayed when the user presses the help button. Then, OpendTect
needs to know what HTML file actually contains this link. That is
specified in the LinkFileTable.txt. We have separated the link name and
link file because we are using DocBook which generates the files with
cryptic names. We then generate the LinkFileTable.txt with our own script.


This is more or less what you need to know about the help system. As you
can see, adding your own help is a matter of putting the right IDs in
the plugin code, and distributing the plugin binary stuff together with
a subdirectory of the data subdirectory.


/Bert

-- 
-- Bert Bril / OpendTect developer at dGB
-- Nijverheidstraat 11-2, 7511 JM Enschede, The Netherlands
-- mailto:Bert.Bril at opendtect.org , http://opendtect.org
-- Tel: +31 534315155 , Fax: +31 534315104