RFC_3

<<TableOfContents: execution failed [Argument "maxdepth" must be an integer value, not "[2]"] (see also the log)>>

About this document

This is an official Request for Comment (RFC) for migrating the user manual to the wiki.

For details on RFCs in general, check out the Wikipedia Entry: Request for Comments (RFCs)

Status

Open for public comment

How to Comment

To view/add comments, add them directly under the appropriate section. By adding your ideas to the Wiki directly, we can more easily organize everyone's ideas, and keep clear records. Be sure to include today's date and your name for each comment.

Try to keep your comments as concrete and constructive as possible. For example, if you find a part of the RFC makes no sense, please say so, but don't stop there. Take the extra step and propose alternatives.

Proposal

Currently the user manual is stored as a master Microsoft Word document in CVS. This is the main document edited and is converted automatically to PDF for the distribution and mostly manually to HTML to the online help (JavaHelp format) available from within Cytoscape. The problem with this is that it takes a long time to update the HTML and is not very flexible - for instance, we can't automate it as part of the build process.

The proposal is to move the master user manual document to the wiki and write some scripts to convert from the wiki initially only to PDF and JavaHelp HTML.

General Notes

• There is a word2wiki Word Macro available. It can easily be edited to write out MoinMoin wiki markup or any other with some visual basic editing. It only handles basic formatting and lists, so images will have to be manually imported into the wiki.

• If we convert from wiki to DocBook format, we can easily then convert to many other formats, including PDF and JavaHelp, automatically. The only issue then is converting from wiki to DocBook.

• Converting from wiki to DocBook

  • MikeSmoot set up a Docbook wiki instance, which might be an option, since it claims to do some of what we want, though it would be preferable to use MoinMoin wiki (avoid setting up and maintaining two different wikis)

  • wiki to docbook converters that we've been able to find so far - add more below:

    • http://tldp.org/wt2db/ docs; download

  • It might be easier to convert from the HTML output of the wiki to docbook

    • E.g. with http://wiki.docbook.org/topic/Html2DocBook (An XSLT!!!)

    • If we did this, we could use the wiki print view

    • Looks interesting for this process: http://sourceforge.net/projects/jtidy

• Converting from DocBook to JavaHelp

  • Uses XSL and is part of the DocBook distribution

  • http://www.sagehill.net/docbookxsl/JavaHelp.html

• Converting from DocBook to PDF

  • Uses XSL and is part of the DocBook distribution

• Ideally we could integrate the conversion process into our build process, as an Ant task

• More docbook tools: http://wiki.docbook.org/topic/DocBookTools

Open Issues

• How do we convert wiki to DocBook?

  • GaryBader - Dec.25.2005 - Looks like MoinMoin supports DocBook generation natively since v1.3.5. We need to upgrade.

• How well does DocBook handle images?

• How well does conversion work from DocBook to the formats we need - are there any lossy aspects?

• What is the best way to automate the conversion - Perl, Java? If we used Java, it would be cross platform, especially if XSLTs are mostly used.

Implementation Plan

• Status: Cytoscape 2.2 Word document converted to a wiki page using the Word2Wiki VBA script (modified to output rough MoinMoin markup) word2wiki.bas