[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: lynx-dev improving documentation
Larry W. Virden
Re: lynx-dev improving documentation
Sun, 2 Aug 1998 08:02:57 -0400
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
> 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,
> & .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
> 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
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.
Re: lynx-dev improving documentation, Al Gilman, 1998/08/03