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

[Soulliere, Robert]

Hi Dan,

You might be onto something and it is always important to review our tool set for better solutions.

Looking at the AsciiDoc website, it looks very promising and versatile as a base option for the documentation.
http://www.methods.co.nz/asciidoc/

I remember converting some AsciiDocs you had to DocBook for the Developer chapters using tools to automate the process. It went very smoothly.

I am not sure about the process to select DocBook as the format for DIG or if other options were looked at since I wasn't involved in the DIG at that time, but perhaps this could be opened up for discussion/review?

Maybe we could give DIG folks a chance to download and play with AsciiDoc tools and provide feedback on the list or have an official discussion on switching base formats/tools at a future DIG meeting?


Thanks,
Robert

Robert Soulliere, BA (Hons), MLIS
Systems Librarian
Mohawk College Library
robert.soulliere at mohawkcollege.ca
Telephone: 905 575 1212 x3936
Fax: 905 575 2011
________________________________________
From: open-ils-documentation-bounces at list.georgialibraries.org [open-ils-documentation-bounces at list.georgialibraries.org] On Behalf Of Dan Scott [dan at coffeecode.net]
Sent: March 4, 2011 11:51 AM
To: Documentation discussion for Evergreen software
Cc: Mike Rylander
Subject: [OPEN-ILS-DOCUMENTATION] Converting to Docbook - or AsciiDoc? was: Acquisitions and Serials Documentation Drafts Now Available

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.

This E-mail contains privileged and confidential information intended
only for the individual or entity named in the message.  If the reader
of this message is not the intended recipient, or the agent responsible
to deliver it to the intended recipient, you are hereby notified that
any review, dissemination, distribution or copying of this communication
is prohibited.  If this communication was received in error, please
notify the sender by reply E-mail immediately, and delete and destroy
the original message.