[Developers] Help documentation question

[Bert Bril]

Hi all,

Robin wrote:

> I'm working on Windows on some bits and pieces of a plugin and am
> snagged on the help documentation in my plugin. I reviewed the info in
> the programmers manual and implemented my interpretation of what it
> says. It didn’t work, so I dutifully went in search for the tutDoc Help
> files as examples...

Oops - I think we didn't communicate that the documentation has been
moved from 'data' to a separate 'doc/Users' directory. The 'doc' from
the directory name needs to go. The reason is that the 'data' directory
became a mess. It seemed tidy to create a separate 'doc' directory.

You can see this in action by clicking on any help button; the URL in
the browser shows where the new location is.


> I didn't find the "data" or the "tutDoc" directory
> anywhere in the latest
> releases including 3.2.2.a./ Is it online somewhere?

Hmmm - it isn't. We didn't want to install the Tutorial and doc by
default: people would think it's actual, good stuff (OK it does work but
it's toy stuff).

We didn't really think about how to deliver the tutorial stuff. All in
all, we have a need for a separate development package with source code,
tutorial stuff, programmer's docs and other tools. I discussed this with
Nanne and he'll get one in place in the next (patch) releases.

So in coming releases watch out: no source code in the 'all' package!


> My ui plugins reference the directory/help ID with  
> "SRI_HorzTools:105.0.5". I put the files in $WORK/data/SRI_HorzToolsDoc
> and nothing comes up when I click on the question icon at the bottom of
> the plugin. I don't know if there's a broken link in my environment or
> what...

OK - the resolution of your prob is: move the directory
data\SRI_HorzTools to doc\User\.

I'm a bit puzzeld by the '_HorzTools'. It looks like you want to add a
directory for every plugin coming from SRI. It's not really intended
that way; the idea is that each vendor uses one subdirectory. I can see
the problem if people install one plugin but not the other, but hey -
that's free marketing! Thus, 'SRI' or better, 'sri' (as it's just like
the others) would be a better name. If we don't keep to this, the
submenu menu in the 'Help' menu will grow very large.


> In the LinkFileTable,
> I notice that the links are in caps, such as: LINK-2DHORIZON x1168.htm.
> Is that a requirement or is it just a visual aid to help differentiate
> between the link and the htm file we are linking to?

It's historical. You know, the base manual is made by users (some of
them are geologists!), and they need all the clarity they can get :-)

In the end, it's simply an HTML anchor which is case-insensitive.


> I could use some guidance. The tut example would be nice. I've reviewed
> what's in the OpenDtect/data folders (dgbDoc, dTectDoc, etc)... /Does
> the tut example do anything different?

The reason we didn't notice is that in our development environments, we
have doc/User/tut because it's simply in CVS - it works. For the
release, we didn't add it to the script that collects the data.


/Bert

-- 
-- dGB Earth Sciences B.V.
-- Nijverheidstraat 11-2, 7511 JM Enschede, The Netherlands
-- mailto:Bert.Bril at dgbes.com , http://www.dgbes.com
-- Tel: +31 534315155 , Fax: +31 534315104