RE: [docbook-apps] documenting code

["Rowland, Larry" <larry.rowland@hp.com>]

+--
| 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.  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.

Regards,

LRR

=======================================================================
[ Larry Rowland             | If you want to build a ship, don't drum ]
[ ESS/ATG                   | up the men to gather the wood, divide   ]
[ Hewlett-Packard           | the work, and give orders. Instead,     ]
[ 3404 East Harmony Road    | teach them to yearn for the vast and    ]
[ Fort Collins, CO  80528   | endless sea. - Antoine de Saint Exupery ]
[ Phone: 970/898-2280       +-----------------------------------------]
[ E-Mail:larry.rowland@.hp.com                                        ]
=======================================================================