Re: [docbook-apps] documenting code

[Dave Pawson <davep@dpawson.co.uk>]

Rowland, Larry wrote:
> +--
> | 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?
> +--
> 
> We face this problem in our current documentation for UNIX variants.
> Our customers tend to copy sample commands from our documents and
> then paste them into a shell interpreter.  The solution has been
> fairly simple.  We wrap our command line samples by hand (the
> programlisting is a verbatim element in DocBook) and include the
> continuation character (a backslash) in our samples. 

Is it the same problem? A command line for Windows wouldn't work
since (AFAIK) there is no continuation character?
I've faced that problem, making documentation look good (not
over wide).
Extracting the code into distinct files gives a slightly different
problem, where all 'single' lines must remain single (excepting
the use of continuation lines, only available in some languages.)


  As long as the
> extracting code respects white space (which it should for code, anyway)
> the command lines work as stored, even when they are long and complex
> (which happens with distressing frequency regardless of efforts to
> simplify our user's tasks).  I have seen discussions of wrapping code
> that automatically inserts the continuation character, but we find that
> humans are usually better at making intelligent decisions about the
> best place to break a long line into chunks that make it easier for the
> user to understand the long code than a wrap algorithm is.

Agreed, but I'm looking at an automated process rather than a user
copying code snippets out?
Perhaps your option might be to provide the documented code,
then also extract the full code, and save to a separate file
alongside the documentation?

Either way
<line>
<linebreak/>
</line>
could just as easily be transformed into a continuation
character, if the language supported it, though that would
make it a little brittle.




regards


regards

-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk