OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [docbook] Is DocBook the right tool for this (source code examples with interspersed output and embedded links)?


Hi Stephan,
One key question: Can the code samples in the documentation be marked up with inline XML elements? I ask this because DocBook's tools can import working source code files as part of the content, and can automatically apply highlighting like colors to certain languages.

However, the highlighting feature uses configuration files specific to each programming language, and currently there are no config files for fortran, pascal, or basic. And the links to the reference pages would not be automatically formed.

But if you are copying the code samples into DocBook XML and applying markup, then the language support for automatic highlighting is not needed, and you can add element markup to form the links.

I infer from your statement that "whatever documentation tool I use doesn't need to touch this code" that the code samples are copied into the XML, and therefore could be marked up manually to form the highlighting and the links.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net

On 5/28/2014 4:11 AM, Stephan Petersen wrote:

Hi everyone,

I'm new to DocBook and I'm currently trying to figure out whether it's
the right authoring tool for the job.

In short, I'm looking for a tool that allows me to do things like these
when writing the documentation for a library:

http://gtt.mch.rwth-aachen.de/gtt-web/Software/ChemApp/CAL-DOC/cal62.html#l100

I.e. adding syntax-highlighted source code examples in various languages
with (semi-)automatically interspersed chunks of output and links to the
function descriptions in other parts of the docs.

The "long" story :-):

The "job" is the manual for a code library (from the area of
thermochemistry, if anyone cares to know :-) ), and it does NOT involve
documenting the source code of the library itself. Actually, it doesn't
even matter in which language the library is coded (it's Fortran), since
whatever documentation tool I use doesn't need to touch this code.

I've already given doxygen and Sphinx a test drive, but the tricky
things are really the code examples mentioned above, which are currently
in Fortran and C, with Pascal and Python likely to be added later.

I've looked at DocBook and tried to understand the necessary tool chain,
but I don't feel confident in already deciding whether its the right
tool for my job, and how much tweaking I would potentially need to do go
get it to work. In fact, I find it quite difficult to judge which
particular tools for DocBook I should actually give a try (my platform
of choice would be Debian).

The above example and link btw. is an older version of the documentation
which I started in the late 90s, I used "Yodl" for this, plus a number
of custom Perl scripts run via Makefiles for pre- and post-processing.
But I'd like to move away from Yodl to a more "active" tool with a
larger user base...)

You can see that I splice chunks of output of the very sample programs
into the documented code. In fact, the output is generated from the
current version of the library automatically right before the
documentation is made.

Does anybody out there use DocBook in such a way? Is that possible? If
so, do I best use DocBook 5.x or an older version? Which other tools do
I need?

Thanks in advance for any pointers,

Stephan


---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org






[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]