Re: Schemey markup (was Re: Doc Tasks)

[Greg Harvey <Greg dot Harvey at thezone dot net>]

Lalo Martins <lalo@webcom.com> writes:

> On Fri, Dec 17, 1999 at 06:47:29PM -0330, Greg Harvey wrote:
> > 
> > A better approach that could keep all of us happy :) might be to
> > define a simple set of tags that'll handle any formatting we might
> > want for docstrings.
> 
> I see all the arguments against that, but I can also give a
> handful of arguments _for_ that. And I was the guy who asked
> for sgml originally, I think.

A few more things that occurred to me:

1) It's totally semantic (leveraging what I'll have to assume to be
   the only decent argument for docbook ;). If we just use a system of
   declaring something to be a type, function, variable, example,
   xref, we do nothing but assign very precise semantic information.

2) It would be a very simple thing to convert this to anything we
   wanted; on the flip side, both directions for texi and docbook are
   non-trivial.

3) Easy to learn; if we go with a full blown markup language, with a
   ton of `great and wonderful, industry standard, buzzword compliant'
   crap splattered all over the docstrings and source (I guess I might
   not be talking about texinfo here >;'), then anybody who wants to
   modify the source has to know that markup language; it's a lot
   easier to have to remember a handful of different tags that can be
   documented in a page or two.

4) We're obviously not going to have the whole mess of this all over
   the source (lifted from an earlier post by Per Bothner):

<funcsynopsis>
<funcprototype>
<funcdef><function>make-string</function></funcdef>
<paramdef><parameter>count</parameter></paradef>
<paramdef>[<parameter>init</parameter>]</paradef>
</funcprototype>
</funcsynopsis>

   So some amount of shorthand is going to be done anyway; I don't see
   any big loss to making it all shorthand.  It does mean you can't
   slap a table or image or figure in the middle of the source
   (thankfully), and you lose the ability to say "look! docbook right
   in the source!  Mmm, modern", but if that's the only reason we have
   for using docbook for the docstrings... 

-- 
Gregh: the artist formerly confused with Greg Badros :)