This is the mail archive of the guile@sourceware.cygnus.com mailing list for the Guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: Documentation proposal


"Harvey J. Stein" <hjstein@bfr.co.il> writes:

<snip>
>  > 
>  > And the guile version is not updated to support the recently-changed
>  > docstring format that includes the docstring as a final argument to the
>  > macro, rather than as a comment immediately after the entity in
>  > question.  Only the perl version of the documentation extractor works
>  > right now;  it doesn't use the new *.doc files that are created from the 
>  > .c files, though-- it just scans the source code rather dumbly and will, 
>  > e.g., include docstrings for primitives that are #if 0'd out.
> 
> That's absolutely right.  It's been too much of a moving target for me
> to keep it up to date.  Not that it's a horrendous amount of work to
> do such.  It's that a) the only documentation for the scwm embedded
> documentation format is the perl script used for extracting it (the
> script itself not conforming to the format, and thus not not being
> documented ;), and b) I only hear of format changes/extractor
> enhancements after the fact, and often not at all.

I didn't mean my comment as a criticism, just as a statement of fact.
I was grateful to you for doing the work on the guile extractor, but I
didn't see the point in keeping two implementations of the same thing
current, and think you did exactly the right thing to provide a
proof-of-concept and a benchmarking prototype of the extractor. 

> So, once I notice the format's been changed, and I eventually have the
> time to & interest in updating the script, I go about updating it.  In
> that reading perl scripts makes me ill, my only recourse is to reverse
> engineer the behavior of the perl script by running it and trying to
> reasonably duplicate its output.

I'll be documenting things better for the Guile system (which will
mirror the Scwm system).

> Typically, the format changes are much more amenable to the perl
> script's implementation than my implementation, adding to the effort
> required.
> 
> Between this, the (lack of) speed of guile vs perl on extracting
> the documentation, and the unwillingness of scwm to drop the perl
> script in favor of my scheme script, I was sufficiently demoralized to
> consider working on the script not much more than an exercise in the
> use of guile.  Certainly not of use to the general public, in spite of
> some of the cool features (front end fcns for converting C & scm files
> -> internal doc ref format, and back end fcns for converting internal
> doc ref format to various outputs (such as the identity fcn for
> writing the internal format to a file, text output, a Scheme SGML
> format I developed), and a Scheme SGML -> SGML format converter).

For Guile, I intend to have an initial tool ported from the Scwm one
written in Perl, and then wouldn't be surprised if someone re-implements
in Guile (perhaps using your Scwm extractor as an
example/starting-point) and then perhaps throw the Perl script
away. (Especially if Guile internals folks are willing to use the script 
as a benchmark and try to improve the horrible performance of string
processing in Guile).

> None the less, it's typically not that big a deal to enhance it.  In
> this particular case (after not having looked at the script since last
> March), I see that accommodating the new SCWM_PROC format would
> require one to change the parse-proc-regexp variable to add an extra
> parameter, the parse-proc function to grab the extra field, and
> extract-proc-n-doc to expect that (i.e. - use the doc in the list
> returned by parse-proc & not call parse-proc-doc).  So I guess it's
> maybe 20 or so minutes work...
> 
> I'd probably do it if I felt there was general interest, but I don't
> think there is...

I don't see any problem with using Perl for documentation extraction for 
Guile, but I could imagine some Guile fanatics not wanting Perl to be
required for building the documentation.  (Note that I don't want Perl
to be required for *building* guile the library or the interpreter).

Greg

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]