This is the mail archive of the
guile@sourceware.cygnus.com
mailing list for the Guile project.
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