lynx-dev
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: lynx-dev improving documentation


From: Larry W. Virden
Subject: Re: lynx-dev improving documentation
Date: Mon, 3 Aug 1998 07:07:30 -0400

From: Philip Webb <address@hidden>

> 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).


Well, that's certainly one approach.  Distributions are generaly a
philosophical decision.  For instance, the perl folk work on a philosophy
similar to what the lynx-dev distribution builders have worked on in the
past - stuff everything someone might some day ask about in the distribution
and hopefully they won't post questions asking for it...

> > 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.

Yep.  However, I know that I myself don't have access to a PC and know
nothing about it.  It takes input from folk encountering problems as well
as expertise in resolving problems on a platform to get files updated.


> >  .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.

Well - okay.  Where there _are_ intros, the intros have evolved along
with the code.  Lynx was written apparently as a college project - and
apparently in a course where documentation of each module was not emphasised...
Or perhaps it was - and the modules undocumented were written later.
I can't explain it - I seldom go looking thru the source code.

> > 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).

I don't recommend reading strange code as a way to learn C.  However,
I do recommend it as a means to resolving problems one has with a particular
program.

> 
> > 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.

It would be nice, wouldn't it?  I also encourage folk who have taken a
C class or two and are looking to keep their skills fresh to take a crack
at this as well.  As I said, we are unlikely to find folk who know the code
well to do this project.  Even those making changes are in most cases
familar with small portions or have stated they don't consider themselves
experts.

> 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.

Perhaps you could provide 'task leadership'.  Come up with a list of the
most critical modules.  Begin recruitment for assigning modules.  Collect
the info found.  Write up the comments or at least integrate the comments.

> 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)?

Post information to this mailing list.  Put some string in the subject
to flag the info as destined for the distribution.
-- 
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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]