Re: [htdig] is there a problem with the documentation?


Subject: Re: [htdig] is there a problem with the documentation?
From: Gilles Detillieux (grdetil@scrc.umanitoba.ca)
Date: Thu Aug 10 2000 - 08:58:00 PDT


According to David Adams:
> I think that the Ht://Dig documentation is very high quality, and it is a pity
> that so many users appear to email this list before looking at it. There are
> omissions though.
>
> I havn't seen a well documented list of all the $(WHAT) variables that can be
> used in wrapper.html, etc. What are they all, and what variations are
> acceptable, ${WHAT}, $WHAT, $(what), etc.?

As Geoff pointe out, these are briefly describe in hts_templates.html.
Marcel Hicking has offered to beef up the descriptions of template
variables, as some of them are described only very tersely right now.

> They also need to be distinguished
> from the variables used in config files which are entirely different (arn't
> they ?) - I once put a variable in a configuration file in upper case and it
> took me a long time to work out why htdig (3.1.2)was looping!

That's a good point. Users do seem to confuse input parameters, config
attributes and template variables. They are three very distinctly
different things, used in different contexts. Adding to the confusion
is the fact that some input parameters override some config attributes,
and many template variables are derived directly or indirectly from
input parameters or config attributes. The interrelationships between
all of these, and the often inconsistent names going from one to the
other, should all be clearly documented.

I'm not sure why an incorrect (uppercase) variable name in the config
file would cause looping. Could you describe this in more detail?

> The diagnostic information output by htdig and htmerge is not too fully
> described. Numerous times people have asked for the meaning of the +---*-
> lines produced by htdig -v, but I don't think that is in the documentation.
> Nor are the meanings of the "Deleted, noindex:", etc. messages from htmerge.

As htmerge is on its way out, at least for this particular function,
there's less of a need to document this. However, for actual database
merging, it would be good to have a summary of error messages and their
meanings.

For htdig, we now have (in 3.2) a description of -t output, but nothing
yet for -v. We should include the meanings of +-* output with -v, and
also meanings of error messages at higher verbosity levels (e.g. reasons
for URL rejections, etc.).

-- 
Gilles R. Detillieux              E-mail: <grdetil@scrc.umanitoba.ca>
Spinal Cord Research Centre       WWW:    http://www.scrc.umanitoba.ca/~grdetil
Dept. Physiology, U. of Manitoba  Phone:  (204)789-3766
Winnipeg, MB  R3E 3J7  (Canada)   Fax:    (204)789-3930

------------------------------------ To unsubscribe from the htdig mailing list, send a message to htdig-unsubscribe@htdig.org You will receive a message to confirm this.



This archive was generated by hypermail 2b28 : Wed Aug 09 2000 - 22:57:47 PDT