guile-devel
[Top][All Lists]
Advanced

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

Re: What's going on?


From: Alex Schroeder
Subject: Re: What's going on?
Date: Tue, 25 Sep 2001 20:36:22 +0200
User-agent: Gnus/5.090004 (Oort Gnus v0.04) Emacs/20.7

Tom Lord <address@hidden> writes:

> Nevertheless, what Systas documentation there is is a breeze to
> maintain, thanks to my handy-dandy documentation-comment extractor.

Hm, that sounds good, but there seem to be two problems right now:
How to get the function and variable documentation back into the
source, and second, how do you mix the documentation in the source
with other documentation?

Right now I'm really enjoying the Guile Reference manual.  A lot of
information is not in the plain reference format, eventhough it is
called a reference manual.  Let me give two examples:

What you suggest would produce manual pages like the "Objects" node in
the current manual (CVS, a few days old), right?

What will be missing, however, is structure like the "Modules" node,
where you have more information and more structure.

You may claim that putting this extra information into the source is
possible.  I am sure it is.  But the sheer volume of non-code related
information produces a situation where changes in the documentation
require access to and changing source files.  I am not sure I like
that.  Perhaps all our current manual writers are also code
contributors.  If so the problem would not be as bad.  But should we
ever get manual-only contributors, then there will be not only a
separation in focus, but also a separation in people -- but no
separation in the files used.

Currently, there is perhaps no separation in people but there is
separation in focus and files.  This will cause a little inefficiency:
It takes time before things get documented in the manual.  When they
are, however, it will hopefully be superior, but at least equal, to
documentation extracted from the source a la javadoc, perldoc, etc.

A collection of function and variable doc strings doesn't make a good
Emacs manual.  It makes a manual -- but not a good one.

Furthermore, merging things like the SRFI and R5RS documents with the
Guile Reference seems like a very good idea.  Here again, a workaround
would have to be found.

That's why I would prefer *not* to merge documentation and source.

Alex.
-- 
http://www.geocities.com/kensanata/
Coffee should be black as hell, strong as death and sweet as love.
        -- Turkish proverb



reply via email to

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