Re: Doc Tasks (was RE: docstrings in Guile!)

["Harvey J. Stein" <hstein at mail dot ixpres dot com>]

CC: hjstein@bfr.co.il
--text follows this line--
Telford Tendys <telford@eng.uts.edu.au> writes:

 > >  No reason your docstrings strategy couldn't be used to snarf
 > > chunks of doco in c comments, like
 > >
 > >    /*<metasnarf> blah <emph>BLAH</emph> ... blah </metasnarf>*/
 >
 > Triggering the snarfer on the <metasnarf> tag has the problem that
 > it could trigger on:
 >
 >      char *a = "<metasnarf">;
 >
 > So you have to trigger on the comment introducer plus the metasnarf
 > tag which is always safe but at that point why make the tag an XML style
 > tag when it can equally be ANY other string that gets dropped after the
 > comment introduction?

Yes, I believe Greg meant for it to only match within comments.
Otherwise you'd be doing literate programming, not embedded
documentation.

I'm not sure why he wants to make them XML tags.

 > I guess a lot of people see XML tags as the answer to everything
 > but the < and > symbols get used a fair bit in programming

The documentation snarfer can use a heuristic for detecting and
escaping them.  Something like, "if it's an isolated angle bracket,
then escape it", where isolated means having whitespace or bol or eol
on each side.  I agree it's ugly, and means that we're not really
embedding XML (we'd be embedding some weird variant), but given that
people embedding docs would have to have some short overview of what's
expected, we can add the above comment.

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