Re: Documentation proposal

["Harvey J. Stein" <hjstein at bfr dot co dot il>]

"Greg J. Badros" <gjb@cs.washington.edu> writes:

 > "Harvey J. Stein" <hjstein@bfr.co.il> writes:
 > 
 > > <199912030051.QAA25553@endor> <ofd7sktqvv.fsf@chl.tbit.dk>
 > > <qrrvh6bkj2r.fsf@clavicle.cs.washington.edu>
 > > <19991206052736.C550@webcom.com> <ofn1rl4tim.fsf@chl.tbit.dk>
 > > CC: hjstein@bfr.co.il
 > > In-Reply-To: Christian Lynbech's message of "08 Dec 1999 11:27:29
 > > +0100"
 > > Message-ID: <kiw3dtdilk7.fsf@blinky.bloomberg.com>
 > > 
 > > Christian Lynbech <chl@tbit.dk> writes:
 > > 
 > >  > >>>>> "Lalo" == Lalo Martins <lalo@webcom.com> writes:
 > >  > 
 > >  > Lalo> It's easy to generate texinfo from sgml.
 > >  > 
 > >  > This is not quite my experience. I gave up on trying to produce
 > >  > texinfo output from the generated scwm sgml manual (though I admnit
 > >  > I could have tried harder).
 > > 
 > > Same here.  The difficulty being that the scwm sgml is closer to
 > > straight mark-up than semantically tagged text.  However,
 > > scwm-embedded-documentation->texinfo should be straight forward (if
 > > you know what you want the texinfo file to look like).
 > > 
 > > If anyone wants to toy with this, my guile implementation of the scwm
 > > documentation extractor is included in the scwm distribution.  But
 > > talk to me first because I have a newer version on a local hard disk
 > > somewhere...
 > 
 > 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.

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.

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

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

-- 
Harvey Stein
Bloomberg LP
hjstein@bfr.co.il