Re: lynx-dev improving documentation

[Larry W. Virden]

From: Philip Webb <address@hidden>

> does anyone else feel there's too much obsolete material
> in the Lynx distribution package?  or that we should try to improve

Well, I myself have not noticed any _obsolete_ material.  However, if
you have found info that is incorrect, feel free to submit patches.
This kind of think happens once a year or so.

> documentation in modest ways to make Lynx easier to maintain
> & encourage new people to get into bits of programming?

I'm always trying to encourage folk who ask this kind of question to jump
right in and start writing.

> i would like to practise & learn with bits of coding, but am intimidated
> by what adds up to  69 545  lines in the  .c  files in  /src ,
> quite apart from the WWW stuff elsewhere & all the  .h  files.

That's the gotcha of large systems of software - figuring where to start.
Typically folk just sit down and start working on a small corner of the
program.

> eg there's CHANGES files going back to the Roman Empire or nearly

Having a full history is, to me, a good thing.  However, perhaps someone
who is concerned about this could think of other ways of organizing things
- breaking the file into a set of per version files, or per year files,
or whatever.

> &  .announce  documents which by now are very stale news;

And perhaps instead of .announce documents, these could be reorganizied into
a Lynx features document if that's what you would prefer to write.

> there's a document on IBM-PCs & character sets,
> which may be useful in some contexts, but looks rather dated
> & in fact for me would have been rather misleading (see below).

As always, bugs and soultions found should always be reported.  What I
have noticed in the past, particularly on the PC, is that folk find
'solutions' which turn out to appear to be right, but are specific to
the hardware and software they are running.

> also, the  .c  files themselves have minimal & very varied introductions,

This reflects their heritage of being modified by a dozen or more folk over
their lifetime.

> could anyone who feels familiar with the functions of these files
> within the Lynx corpus possibly find the time to add eg  10 lines

I suspect there are few such folk around.  However, I would bet that someone
who wants to contribute 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.

> i'm very conscious of the current lack of programmer time out there
> & would like to get a bit closer to actual bits of programming myself.

But as you mention, little of this has a lot to do with programming time -
it's documentation.  Many folk find it more useful if someone other than
the original programmer do the documentation - that way unconcious 
assumptions can be fleshed out.

> i'ld say a small amount of effort in tidying up the distribution package
> & the commenting of the actual source files would go a long way
> towards ensuring Lynx remains viable for maintenance & development.

Since few if any of the original programmers are around, it seems to me
that the best step would be for all of those on this list 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 thousands of new projects folk dream up for this
program.
-- 
Larry W. Virden                 INET: address@hidden
<URL:http://www.teraform.com/%7Elvirden/> <*> O- "We are all Kosh."
Unless explicitly stated to the contrary, nothing in this posting should 
be construed as representing my employer's opinions.