[csw-maintainers] Need for additional documentation

[Jeffery Small]

I have been using a very old, locally compiled version of mutt for the past
few years because I could never get the CSW version of mutt to work with
my predefined macros and key bindings in my muttrc file, and just didn't
have the time to devote to tracking down the problem.  However, today I bit
the bullet and discovered a great surprise; the CSW mutt binary was a link
pointing to another link back in /etc/opt/csw/alternatives which was using
a slang-compiled version of mutt!  Once I relinked to the ncurses version
of mutt, everything worked just fine!

The point of my story is that I didn't even have any idea that these
alternate versions existed and knew nothing about the "alternatives"
directory.  I keep running across little tricks like this regarding CSW
software packages which would should have been configured at installation
time had I known about them.  Now, maybe there is some note that displays
regarding this during a mutt installation or upgrade, but even if that
were so, we all know that none of these messages can be seen during a
typical install/upgrade if the automatic configuration parameters are set.
Everything just scrolls off the screen much too fast to monitor it.

For some packages, there are very important steps that need to be done
during an installation or checked after an upgrade and this information
needs to be placed in some well known location where every user can review
it.  When I was compiling packages under the old system, I used to include
this information in on the webpage for the packager in the News (I think
that was what it was called) section.  There really ought to me a "Special
Instructions" section added to the current web page which just has this
important information, like tweaking configuration files, starting services,
selection between alternatives, etc.

But I would take this a step further.  If these notes were packaged up into
a file shipped with each package, then the CSW install program could copy
this content to a new temporary file during the installation or upgrade
process, along with any error or warning messages that occurred, and then
display this information to the user for their review after they were
done.  This would allow a major install or upgrade to occur unattended,
with only a need to review the important information immediately after
completion.  This would be extremely helpful to people installing new
CSW packages, since they would get these pointers on how to properly
configure the packages in real time without having to hunt through volumes
of documentation for answers to questions that they probably don't even
know to ask.

I'm not suggesting duplicating a package's documentation here.  Just a
short file with important tips that the packager knows are important for
proper use of the software.  In my case, I was using mutt long before the
the slang/curses split, and it never occurred to me to think that there was
even an issue like this to be investigated.

Just some friendly feedback for your consideration! :-)

Regards,
-- 
Jeff

C. Jeffery Small           CJSA LLC                       206-232-3338
jeff at cjsa.com              7000 E Mercer Way, Mercer Island, WA  98040