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
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
