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: Tue Aug 08 2000 - 10:06:21 PDT


Hi, Marcel. Thanks for all the suggestions. I'm replying back to the list,
as I'm not the one who'll be implementing all of this...

According to Marcel Hicking:
> - We might need more sample setups.
> - I remeber I found it quite difficult to track what
> files are where and what for when I started working
> with htdig.

Yes, a few others pointed this out. I'm hoping some of you on the list can
help out with this, e.g. with more concrete samples or with a step by step
setup guide.

> - I usually end up reading lots of stuff from the
> list archive when I actually want to search for
> something in the docs since there is no checbox
> to limit the search to, say, the website.

Yes, a few others mentioned this as a problem as well. I don't know if we
can give the mailing list stuff less weight, as Avi suggested, but we could
certainly put restrict and exclude to good use to help out with this.

> (I will try to think of more ;-)

And so you did...
> The contrib section needs a redesign.
> Lots of interesting stuff there, but hard
> to find out _what_ exactly all this is.

That's a good point. We take submissions as-is and add them to the
site as we get them, so their descriptions are only as good as the
README files we get with them. Unfortunately, neither Geoff nor I
has the time to go though and evaluate, test and document everything,
so we rely on contributors' help with this. Now, if someone wanted to
volunteer to look after and summarize all this stuff, and maintain it
as new submissions came in, that would be a big help.

And...
> The htsearch template variable description
> could need some more details info:
> TITLE - The title of the document for the current match
> It should say also that the documents url is used as
> defautlt if there's no <TITLE></TITLE> tag.
>
> And most other could need some output examples.
>
> I could do that, if you like.

That would be great. I and a few others have added bits and pieces to
this document, but it needs work. Better descriptions, links to related
attributes, examples of usage and such would all add greatly to this
document. It would also be wonderful to have a how-to for templates,
explaining how to set up the header and footer, or a wrapper in one file,
and how to set up result templates. This latter point seems to be a
frequent source of confusion, because users don't know they can do this,
or if so, how (e.g. they don't realize you have to enable template_map
as well as editing long.html and short.html).

If you have CVS access, then you can go ahead and make updates to
the htdoc subdirectory of htdig3-2-x, or for the FAQ, directly in the
maindocs directory. If you don't have CVS access, you can grab the FAQ
from the web site, or the other docs from the latest snapshot, edit them,
and submit a patch. We'd appreciate any improvements to the docs.

-- 
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 : Tue Aug 08 2000 - 00:05:55 PDT