According to George Herson:
> Thanks for ht://Dig. The rpm install of v3.1.5 went perfectly and the
> documentation is very well organized. I just want to make a few doc
> suggestions to make it easier for the newbie to get started with
> ht://Dig
> post-install.
>
> The installation page says: "SEARCH_FORM A sample HTML document that
> contains a search form". The file this is talking about is an important
> file--it's the newbie's best hope of easily doing a test search, so the
> documentation should say that one can find the name of this file in the
> CONFIG
> file (a file an rpm installer doesn't have in mind because he hasn't
> used
> it).
Thanks for your valuable suggestions. Dealing with RPM installations
always adds an extra wrinkle or two, because of these factors: a) the
RPM .spec file will almost always change some installation defaults in
the package, such as file name paths for instance, as well as configuration
options. The documentation on the web site usually reflects the package
as distributed in source form, and can't necessarily reflect the specifics
of RPM or other binary distribution packages which are out of our hands.
Even though I personally have put together some of the htdig RPM packages
on the htdig site, they're still considered third-party or contributed
software. While we could add notes to the documentation to describe the
differences in my RPMs, it still wouldn't cover all the other possible
RPMs or other binary distributions out there, such as Red Hat's powertools,
SuSE, Debian, and probably others I'm not aware of. They all have their
own unique quirks, and they're all outside of our control.
This situation is not unique to ht://Dig. If you look at just about any
source RPM from Red Hat, you'll see the spec file quite commonly patches
the source in all sorts of ways, changes configuration defaults, or even
replaces parts of the source or configuration files to suit the packager's
preferences.
As for knowing the configure paths, my RPM puts CONFIG in
/usr/doc/htdig-3.1.5 for this purpose. Red Hat's RPM doesn't, so you
pretty much have to figure it out by looking at the list of installed
files (rpm -qilv htdig).
> A little lower it's said that "After the installation, you will be ready
> to
> test out everything. You can use the rundig script to make a test
> database of
> the online documentation at http://www.htdig.org/." But my (unmodified)
> rundig
> made a test db out of my site, not yours. (This was because the end of
> my
> default htdig.conf pointed start_url to my site). And the installer
> should
> modify the htdig.conf before, not after running rundig. But the
> installation
> page ends with "The only thing left to do is to modify the htdig.conf
> config
> file which was placed in CONFIG_DIR/htdig.conf. The _Configuration
> manual_ has
> the details on how [<-delete] what attributes are needed. " I disagree.
> The
> installer has a good bit of learning to do, and should start with the
> material
> in the config.html page, not the "Alphabetical list of attributes"
> (confindex.html), which is what "Configuration manual" links to. Then,
I would tend to agree. The whole list of attributes is too much to chew
on all at once, and the config.html page is probably a better starting
point. However, this latter page would probably need to be beefed up
with links to other documentation pages, to steer users to the right
places for more information. Too many users mistakenly assume that
what's in htdig.conf is all there is, and are unaware of a whole world
of other attributes you can set that aren't in the fairly minimal
initial htdig.conf file.
> the
> installer should take the advice of the htdig.conf and set things like
> where
> htdig should start and the maintainer's email address: "# Automatically
> set up
> by htdig RPM, from your current Apache httpd.conf... # Verify and
> configure
> these, and set maintainer above, before running # /usr/sbin/rundig. "
> (The
> htdig.conf puts this somewhat differently in the non-rpm install, i'm
> sure.)
Yes, that's right. My post-install script in the RPM pretty clearly
labels what it adds to the file, to distinguish it from the unmodified
htdig.conf.
> The attribute url_part_aliases is for "e.g. changing
> www.example.com/~htdig
> to www.htdig.org" it says in the Configuration manual on the htdig
> website.
> Your suggestion should be used in the examples to show what is the
> to-string
> and what is the from string. The actual examples used, eg,
> url_part_aliases:
> http://search.example.com/~htdig *site \ use an unexplained asterisk
> that make
> confident interpretation difficult.
We're at a bit of a quandry as to how to better document url_part_aliases.
It seems to baffle a lot of users, but we can't seem to get any good
recommendations from anyone about specific wording changes to make it more
clear. The problem seems to be that anyone who understands the attribute
finds the documentation perfectly understandable and clear, while those
who don't understand the documentation don't understand the functioning
of the attribute well enough to suggest a newbie-friendly description.
The documentation does clearly say that two "different configuration
files for digging and searching are then used, with url_part_aliases
having different from strings, but identical to-strings", yet this seems
to be the key piece of information that users miss fairly consistently.
The idea is that when digging, the URL parts in the from strings are
encoded to the corresponding to strings, and at search time the reverse
decoding takes place. By changing the from strings in the search
config, you end up decoding to new values for the encoded URL parts.
There's nothing special about the asterisk, but it's a good choice as a
lead in character in the to string because it's very unlikely to appear
in an URL ahead of time. If anyone can suggest a newbie-friendly way
of explaining all this, we'd love to hear it.
> Finally, clicking Configuration file - General on the htdig website
> reveals
> "If a program needs a particular attribute and it is not in the
> configuration
> file, it will use the default value which is defined in
> htcommon/defaults.cc."
> This appears to be old or less-than-universal information, because such
> a file
> was not created on my (working) system.
No, this is a reference to a source file, which you don't get in a binary
RPM. However, all the attributes and defaults in defaults.cc are documented
in attrs.html. The documentation should point this out more clearly, and
steer users to the docs rather than to the source, when the docs do exist.
> regards,
> george herson
>
> (i first submitted to the bug db on http://htdig.sourceforge.net/
> 1/29/01 and 2/4/01
> but it bounced with "[EMAIL PROTECTED]>: Sorry, no mailbox here by
> that name" then on 3/26/01 I got "File Upload: ArtifactFile: File must
> be > 20 bytes and < 256000 bytes in length" when trying to attach this
> small file to the SourceForge bug tracker. I suggest a sentence there
> saying to just email [EMAIL PROTECTED] if there's a
> submission problem.)
Yes, we've been finding the SourceForge bug tracker to be woefully
inadequate. Our migration to sourceforge.net was rather hasty, because we
very suddenly lost our former hosting service, so there have been a lot of
growing pains in the process. We have yet to determine how much of the
current problems can be resolved through tweaking our configuration, and
how much we're stuck with. Unfortunately, Geoff is just about the only
developer who knows enough about the current setup to fix things up, and
he's swamped this month. (I'm just barely resurfacing myself right now.)
--
Gilles R. Detillieux E-mail: <[EMAIL PROTECTED]>
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
_______________________________________________
htdig-dev mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/htdig-dev
