Tools for generating Docbook programlisting fragments?

Do anyone know of a library for generating DocBook
programlisting  
fragments from
source code listings marked up with special comments.
The purpose is to generate the Docbook source and program
language  
source,
from a common specification. I've tested filtering a xml
file  
containing a programlisting
DocBook element through a custom stylesheet, but so far I've
been  
unable to avoid
getting extra whitespace, when doing it this way.

----------------------------------
Skinheads are so tired of immigration, that they are going
to move to  
a country that don't accept immigrants!
Tommy Nordgren
tommy.nordgrencomhem.se




------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-apps-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-apps-helplists.oasis-open.org

On Sat, 25 Aug 2007, Tommy Nordgren wrote:

+--
| Do anyone know of a library for generating DocBook
| programlisting fragments from source code listings marked
up
| with special comments.  The purpose is to generate the
Docbook
| source and program language source, from a common
| specification.
+--

If single-sourcing is your goal, why not make the DocBook
document your single source?  Then you need only strip out
the
executable parts with a simple filter.  My colleague Dr.
Allan
Stavely calls this 'lightweight literate programming'.  See
my
page for the tools and a few dozen examples ranging up to
4000+-line sources:

    http://www.
nmt.edu/~shipman/soft/litprog/

I don't know if this fits your application, but I thought
this
would be a good opportunity for me to promote one of my pet
techniques. 

+--
| I've tested filtering a xml file containing a
programlisting
| DocBook element through a custom stylesheet, but so far
I've
| been unable to avoid getting extra whitespace, when doing
it
| this way.
+--

I code mainly in Python, which is rather sensitive to
whitespace.
Here's how I format code fragments:

    <para>
      This next section...blah blah blah
    </para>
    <programlisting role='outFile:myscript.py'
>Line 1
Line 2
Line 3
</programlisting role='outFile:myscript.py'>
    <para>
      Etc. ....
    </para>
            
Line breaks are perfectly legal within XML tags just before
the closing '>' or '/>'.   So the above formatting
produces
three lines, with newline terminators, and nothing else.

This puts the work on you instead of the filter, but it
works for me.

Best regards,
John Shipman (johnnmt.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



------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-apps-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-apps-helplists.oasis-open.org

> Do anyone know of a library for generating DocBook
programlisting 
> fragments from
> source code listings marked up with special comments.
> The purpose is to generate the Docbook source and
program language 
> source,
> from a common specification. I've tested filtering a
xml file  containing 
> a programlisting
> DocBook element through a custom stylesheet, but so far
I've been  unable 
> to avoid
> getting extra whitespace, when doing it this way.

Hi, Tommy,

One of my clients is doing this against a code base that
consists of C, C++, 
Java, and Visual Basic (they program in C++ and Java but
expose APIs in all 
four languages). They have a program that scans their source
code 
directories, scoops up the specially marked code listings
(everything from 
one-line listings to entire executables), and dumps it all
into an XML 
(DocBook) file. Then the writers create references to the
file full of 
samples to scoop up the bits that go into about 40 different
books.

I can't share the code (they wrote their own proprietary
solution), but I 
could write such a program in an afternoon (including
testing). I helped 
them with the XML/XSLT part of setting up their DocBook
system, so I know 
the issue well and know that this solution works.

If you're generating source code listings with XSLT, by the
way, try setting 
the output mode to text and being very careful with the line
breaks and 
start-of-line spacing. You can still save the resulting
files as XML, but 
you'll get better control over the white space if you create
the output as 
text.

HTH

Jay Bryant
Bryant Communication Services


------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-apps-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-apps-helplists.oasis-open.org

>>>>> "TN" == Tommy Nordgren
writes:

    TN> Do anyone know of a library for generating
DocBook
    TN> programlisting fragments from source code
listings marked up
    TN> with special comments.

Well, they have been calling that kind of thing
"literate programming",
and at <http://www.google.co
m/Top/Computers/Programming/Methodologies/Literate_Programmi
ng/?il=1>
you can find a few interesting articles 
including one by Normal Walsh titled "Literate
Programming in XML"
at <http://nwalsh.com/docs/articles/xml2002/lp/paper.html&g
t; .
You might have come across Norman in the context of
DocBook,
and you will find, that his article is quite DocBook
related.

    TN> The purpose is to generate the Docbook source and
program
    TN> language source, from a common specification.
    TN> I've tested filtering a xml file containing a
programlisting
    TN> DocBook element through a custom stylesheet, but
so far I've
    TN> been unable to avoid getting extra whitespace,
when doing it
    TN> this way.

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-apps-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-apps-helplists.oasis-open.org