Re: lynx-dev improving documentation

[Philip Webb]

980802 Larry Virden commented on my remarks re documentation etc:
> I myself have not noticed any _obsolete_ material.
> I'm always trying to encourage folk who ask this kind of question
> to jump right in and start writing.

ok, now we refine a bit:
a lot of the material shouldn't be in the DISTRIBUTION package,
but available somewhere on the Internet via l.b.o ;
this would include ALL the changes & announcements
apart from those since the previous release (eg 2.7.1 -> 2.8 ).
is there someone who would be willing to host that material?
(maybe incidentally we could build a file of good reviews,
eg the one from a user today; i seem to remember there is such a file,
but it hasn't been updated recently).

> Having a full history is, to me, a good thing.
980802 Al Gilman added:
> So long as the full history is also available under one text search.
> Two questions I have used the history to answer are "Has this changed?"
> and "When did this change?"  It is reasonably easy to pursue that
> with a monolithic changes file visible once on the web and '/' by Lynx.
> Answering "When did this change?" when the log is segmented is tedious.

so this is further reason to create a WWW historic changes file.

> What Joe Kincaid did with the changes from 2.6 to 2.7 was excellent:
> a user's guide to the changes from the last major release.

obviously, someone has to have the time & motivation to do that;
usually it will have to be dispensed with.

980802 LV also commented:
> perhaps instead of .announce documents,
> these could be reorganizied into a Lynx features document.

this would be another file for the WWW Lynx history site.

> What I have noticed in the past, particularly on the PC, is
> folk find 'solutions' which turn out to appear to be right,
> but are specific to the hardware and software they are running.

the IBM-PC file needs updating & should be somewhere in on-line Help.

>  .c  files introductions reflect their being modified by  >= 12  folk.

i don't think that's the problem: most of them never had intro's at all
or only painfully inadequate ones; their dates tend to be 1990-4, if any.

> someone could pick one and study it for a while
> and make a first stab at commenting the file.
> If others find corrections or additions
> they could then have a structure to build upon.
> Many find it more useful if someone other than the original programmer
> does the documentation - that way unconcious assumptions can be fleshed out.

i'll read this as encouragement to have a go myself,
inexperienced with big C programs as i am (grin).

> Since few if any of the original programmers are around,
> the best step would be for all those who have desired better documentation
> to take on a few modules and work on documenting them.
> At the end of that project, a whole new generation of lynx programmers
> would be available for the new projects folk dream up for this program.

this should be encouragement to others to put in a bit of time,
esp those few who do know some of the code rather well.
let's try to do the  .c  &  .h  files bit-by-bit as we can:
it should really provide a better foundation for future development.
it's not detailed comments thro'out the code which we need,
so much as  10 - 25  lines of introduction saying what each one does.
 
how should i make available material which might go in the distribution?
it won't be HTML, nor is it likely to be patches:
i don't know how you set up an FTP directory, if that's what's needed;
or should it be in the  /pub  directory (which i've never done)?

-- 
========================,,============================================
SUPPORT     ___________//___,  Philip Webb : address@hidden
ELECTRIC   /] [] [] [] [] []|  Centre for Urban & Community Studies
TRANSIT    `-O----------O---'  University of Toronto