Re: DOCBOOK: OT: DocBook and Literate Programming?

[Mike Sangrey <mike at sojurn dot lns dot pa dot us>]

jeff@duska.com said:
> One of the suggestions a few people on other list have suggest where
> mentioned here. This is using XML and then use a preprocessor to
> create the documentation and the source code. This could work, but
> wouldn't it really be creating a new language. I've thought this might
> not be a bad idea creating GPML General Program Markup Language - XML
> application. I figure VB, Delphi, Powerbuilder and the whole IDE type
> programmers wouldn't mind if the source code because XML. C/C++/Perl/
> Java programmers would most like never touch it. It could be quite
> powerful to store your source code in this type of metadata format.
> You might even be able to port programs from one language to another
> using advanced XSLT. 

This, IMO, is not such a petunia brained idea as the first blooms might 
indicate.

However, the problem is two-fold--one human, the other techy:

1.  Literate programming is by definition bilingual or bi-literate.

By this I mean the person must be proficient in both their native
language (ie. C/C++/PERL/Java/whatever) and also the language in
which they speak to their fella dudes.  There are issues here, none of
which are intractable as far as I can see, but the problem of
__non-bi-literacy__ is what we have to overcome.

Generally, this is handled by using people of different skill sets.
What would be valuable then, is enabling efficient development and
collaboration between these two sets of people?  And that brings
me to...

2.  The techy problem is rather simple, and yet somewhat pervasive.

The core to the solution is that the code is wrapped in a DTD defined
XML document.  This becomes the source.  In interpreted languages, the
"executable" is generated by auto-commenting out the XML (and there
are various ways of doing that).

Here are some rather random thoughts.

    Emacs: SGML-mode (psgml) be taught to enter outline-mode within which
    the specific language mode would be active.  The idea is to use the
    outline features of emacs to interface the language modes to XML.
    The desired result is for Josephine C. Programmer not to lose in
    anyway her interface to emacs.  She can still code C in the way she
    wants to. I think teaching emacs to do this would be rather tricky;
    but the challenge would be rather neat and I think it is doable.
    See `Makefiles' below.

    Then, and here I've walked off the edge of my knowledge, a stylesheet
    be created which can do two things:  create the doc in one format
    or another, OR pipe the code to the compiler.  Intuitively to me,
    since stylesheets "render" documents, I think they could "render"
    the code by passing it to a compiler.  Indeed, this may not even
    be needed other than the stylesheet being told to just ignore
    <code>...</code>.  Again, see `Makefiles' below.

    Vi:  I use vi, so I'm not bigoted here.  The XML appears as just
    fancy comments.  We don't have all the capabilities emacs brings,
    but that hasn't stopped us before.  BTW, I also use emacs--I'm
    bi-editate. :-)

    XML editors:  I'm not familiar with what these creatures can
    do (other than emacs, of course), but generally this would be
    for documentation editing.  Anyway, the code is wrapped in <code>
    ...</code> tags.  So, even though you don't have the capabilities
    of code development, you're not using this editor for that anyway.

    IDE:  This is the really tricky one.  If you're using some
    commercial IDE and want literate programming, then call
    1-800-I'm-the-user,-give-me-what-I-want.  Perhaps the help desk
    can help you. Otherwise, fixing the IDE shouldn't be that hard if
    all you want is for it to deal with the code and ignore the XML.
    Teaching the IDE XML is what we really want, but that will take a
    little longer (especially for the commercial packages;-).

    Makefiles:  Tar balls would contain a simple PERL script that could
    adjust the source files to compile "out-of-the-box". I see something
    as simple as wrapping the XML in a comment.  In C this could be
    something as simple as

   #undef XML_COMMENT   /* Enforces convention */
   #if defined (XML_COMMENT)

... xml dee doe dee xml

   #end if /* XML_COMMENT */

    The Makefiles would just do the right thing based on what `autoconf'
    and `configure' told it.

Well, this is not likely a `DOCBOOK' event, so we should probably move
the discussion somewhere else.  

-- 
Mike Sangrey
mike@sojurn.lns.pa.us
Landisburg, Pa.
       Every Christian library should have a plaque which states:
              "There is one book which explains all these."