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 [email protected] Telephone: 905 575 1212 x3936 Fax: 905 575 2011 ________________________________________ From: [email protected] [[email protected]] On Behalf Of Dan Scott [[email protected]] 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 <[email protected]> wrote: > On Fri, Mar 4, 2011 at 11:12 AM, Soulliere, Robert > <[email protected]> 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. _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
