This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: OT: DocBook and Literate Programming?
- To: docbook at lists dot oasis-open dot org
- Subject: Re: DOCBOOK: OT: DocBook and Literate Programming?
- From: Mike Sangrey <mike at sojurn dot lns dot pa dot us>
- Date: Tue, 11 Jul 2000 12:10:15 -0400
- cc: jeff at duska dot com
- Reply-To: docbook at lists dot oasis-open dot org
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."