[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]