Re: lynx-dev manual denoting feature changes (was 'reloading' lynx.cfg)

[Heather Stern]

Well you asked for comments, so here they are.  Summary:  idea good, 
but could be implemented different than you say and possibly help more.
Also, it's extra work and needs to be a little continuous - anyone want
to volunteer to extra documentation work long term?  Not nice to make
Dickey do it all himself.

David Combs wrote:
> QUESTION and NEED: How does a long-time user of lynx FIND OUT
> about these new features?
> 
> I haven't checked, but such changes probably are NOT yet in
> the manual.  (True, false?)

I favor the idea of a companion to the CHANGELOG (code oriented,
good for programmers, format is solid) that is intended for end
users.  Perhaps FEATURES.  If well formatted from a user perspective
it could also be considered whatever passes for a "marketing"
document in the freely developed world.

This would allow us to change the format of it, so we could have these
date and version refs in a more usable fashion (for end users) without
harming the already present usability (for programmers).  The next
question comes, how to keep them in sync?

> ---
> Of course, some ONE person could do that FOR us all, duplicating
> that .1% into a SECOND "featureCHANGES" file -- that way, the
> work would get done ONCE, instead of HUNDREDS of times, once
> per reader.

One person could do that now, to a current changelog file, but someone
(or some multiple folks) would need to continue to maintain it.

> ---
> I think the date-idea should be done, regardless of hoped-for
> changes to the changes-file.  We have a huge number of users
> of lynx, probably only .1% of them being on this list.
> 
> THOSE people, the 99.9%, need some way to see NOT just a short
> note that "xyz has been added", but the entire doc on it, with examples,
> etc.  Adding that to the manual, with date, would make seeing it much
> easier.

Some folks just want to know if a feature exists.  Others just want to
know how to turn it on or off.  (We want to encourage such, because they
are just plain folks trying to browse.)  Yet others actually want to 
understand it or do powerful things with them.  (And we want to encourage 
such, because they have good ideas, and may yet become dev types one day.)

I think there is a need for a -short- feature list file, in addition
to a code-changes file, and a real manual.  Given my notes above there
might also be room for a "quick guide" or "reference card" which can be
much longer than the option screen, without being onerous to read.

> ---
> Maybe a "rule" (Dickey-enforced) that no new feature goes
> into the released-version UNLESS documented for users?

(applause) Especially if someone speaks up for maintaining such doco...
volunteering Tom for more work to do doesn't mean he has inifinite
time to give to it.

> ---
> ...why the date? ... easily readable to the human eye...

I'm the sort, I want to know the date -AND- the version.  Besides, to an
end user hanging off some telnet-to-freenet lynx, he has no bloody idea
what date his lynx was compiled (unless someone advises him how to ask it)
but = will tell him lynx' version.

On the plus side, lurkers note: you don't have to live in gcc to help
update the manual...

Heck, I'm willing to pour some effort into the feature log I'm describing,
if it doesn't mean I'll be all alone with it from here on, to at least
get it kickstarted faster.

* Heather