[OPEN-ILS-DOCUMENTATION] Converting to Docbook - or AsciiDoc? was: Acquisitions and Serials Documentation Drafts Now Available

[Dan Scott]

On 4 March 2011 11:22, Mike Rylander <mrylander at gmail.com> wrote:
> On Fri, Mar 4, 2011 at 11:12 AM, Soulliere, Robert
> <robert.soulliere at mohawkcollege.ca> wrote:
>>  I think having the discussion on the Documentation list is important as well.
>>
>> The hope is that the Acquisitions. documentation would be included as part of the official documentation for 2.0:
>> http://docs.evergreen-ils.org/2.0/draft/html/
>>
>> I think it would be best to get the documentation into DocBook XML format which could then be processed in both HTML and PDF as part of the official documentation.
>>
>
> For ruby-ites out there:
> http://juretta.com/log/2006/08/10/convert_microsoft_word_to_docbook_xml_using_ruby_and_openoffice/
>
> So, we could automate the conversion.
>
> There are companies that will convert from Word to DocBook as well,
> one of which (says google) is:
> http://www.whiplashtech.com/technologies.html

Once upon a time, OpenOffice.org offered Docbook read/write filters as
well: http://xml.openoffice.org/xmerge/docbook/

Tangent: I wonder now, five years after I initially proposed
all-Docbook all the time for the docs, whether something more
approachable like AsciiDoc might be worth considering as a source
format for the docs. I find it easy to dump something to plain text
and mark up as AsciiDoc, with a low WTF factor. From AsciiDoc, you can
directly generate HTML, PDF, slide shows, etc, as well as transform to
DocBook. And most importantly, you can read the source, and read diffs
between revisions, and feel like it's possible to add a sentence or
new section - and if that helps increase the community of potential
writers and the speed at which docs go from "submitted format X" to
"part of the official documentation" by replacing the "translate to
Docbook" step with the much easer "translate to AsciiDoc" part of the
documentation chain (or skipping it entirely because the barrier to
entry is lower), that has to be a good thing, right?

http://svn.open-ils.org/trac/ILS-Contrib/browser/governance provides
an example AsciiDoc document - I've attached the HTML and PDF default
output as well. The [loweralpha] / [lowerroman] bits are only there
because I was matching the formatting of the source document;
generally, AsciiDoc provides reasonable output for readable input. I
could even see individual AsciiDoc documents being distributed as part
of the Evergreen source (for example, the README, release notes,
documentation for particular tools) and then being combined to
generate corresponding parts of The Book of Evergreen.

If nothing else, using AsciiDoc as an intermediate format to generate
Docbook for submissions to the official doc source is a possibility
for those who don't want to learn or write Docbook directly.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20110304/4804899b/attachment-0001.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: governance.pdf
Type: application/pdf
Size: 85985 bytes
Desc: not available
Url : http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20110304/4804899b/attachment-0001.pdf