Re: [docbook-apps] documenting code

["John W. Shipman" <john@nmt.edu>]

+-- Dave Pawson:
| Yet again, quote
|
| A small Python script extracts one or more source files from
| the document,  and these are the executable form of the program.
| /quote
|
| That seems wrong John?
+--

What exactly is wrong with that?  I have a Makefile set up
so I type:

     make code

and it runs my Python script, which extracts the source files.
When I say they are the executable form of the program, they are
exactly that for Python, Relax NG, and XSLT.  For a compiled
language there would clearly be a compile step.  Sorry I didn't
mention that, but I haven't used any compiled languages for
over ten years.

+--
| Another problem I have, a long command line, e.g. calling
| java, saxon for a transform,
| docbook has no
|
| <line>java -cp .....
| <linebreak/>main.class
| <linebreak/>param1
| etc
|
| To enable XSLT to re-build a single line from one
| split, for the sake of convenience?
+--

This is another problem I haven't encountered.  I usually keep my
lines short (75 characters for the current toolchain).  I don't
have any useful ideas at the moment.  In my toolchain, you can
have lines of any length.  I have automatic line wrapping set up
for the documentation side of the toolchain.

Another reply on this thread said that they prefer to keep the
documentation inside the code, rather than the literate approach
wherein the code is inside the documentation.  The drawback to
their approach is that you need a different extractor for each
language.  With the literate approach, it is not necessary to be
sensitive to any particular language's syntax.  Also, one can
have a literate document with fragments in multiple different
languages.  I have some examples that contain both a Relax NG
schema and Python code that operates on XML files that conform to
that schema.

Best regards,
John Shipman (john@nmt.edu), Applications Specialist, NM Tech Computer Center,
Speare 119, Socorro, NM 87801, (505) 835-5950, http://www.nmt.edu/~john
   ``Let's go outside and commiserate with nature.''  --Dave Farber