I'm just going to toss this grenade and run - http://maven.apache.org/doxia/
Doxia is framework developed by Maven folks which is able to parse documentation in various flavors and then output it to various flavors. For example, it supports parsing *simplified* docbook (http://www.docbook.org/schemas/simplified ) and outputting confluence wiki text. I've not used Doxia ever, so I don't know how robust its parsing or output generation is, but I think it is worth a look. Here is how easy it is supposed to be to use (from http://maven.apache.org/doxia/modules/index.html#Using_A_Doxia_Module) : File userDir = new File( System.getProperty ( "user.dir" ) ); File inputFile = new File( userDir, "test.apt" ); File outputFile = new File( userDir, "test.html" ); SinkFactory sinkFactory = (SinkFactory) lookup( SinkFactory.ROLE, "html" ); // Plexus lookup Sink sink = sinkFactory.createSink( outputFile.getParentFile(), outputFile.getName() ) ); Parser parser = (AptParser) lookup( Parser.ROLE, "apt" ); // Plexus lookup Reader reader = ReaderFactory.newReader( inputFile, "UTF-8" ); parser.parse( reader, sink ); You would use the Confluence sink and the Docbook parser instead of HTML and APT. So Doxia gives one the option of maintaining the canonical documentation in Docbook, but transforming it to Confluence wiki text for users to consume. /me runs away On Jan 6, 2010, at 10:26 AM, Jeffrey Trimble wrote: > I thought I should write something since I've been the person > working on the DSpace 1.6 > documentation. I've written documentation before for other software > products, albeit > commercial library ILS, but still documentation. > > Upon volunteering as the "Document Gardener" for DSpace 1.6 release, > I took it upon > myself to evaluate what was there and what needed to be done and > what should be done. > I also needed to acclimatize myself to the tools used for generating > the documentation. > > Here's some salient observations concerning the manual: > > 1. It needed to be updated to reflect the changes since version > 1.3.2. There were some > remaining text that pointed to 1.3.2 version and how the system > behaved and or operated. > > 2. Nomenclature. Some of the nomenclature used was foreign to > users, but not to a programmer. > That was addressed as well. > > 3. Re-organization. There was major re-organization performed for > this next release. > > 4 Enhancement. Our current documentation has been enhanced a wee > bit. What is still > missing, and was missing was the end user documentation. I'm > currently working on that. > (Any help is welcomed!) > > 5. Docbook xml knowledge. This is the area that seems to be the hot > topic of discussion. > While docbook.xml **was** foreign to me, I made it my job to find > everything I could about it. > It was enlightening to say the least. > > This is not some fly-by-night standard. Docbook has been around > since 1991 and in 1998 > moved to SGML Open consortium which is now OASIS. It is formally > defined by a RELAX NG > schema and integrated with SChematron rules. Supporting this is W3C > XML Schema and > DTD. > > Marking up documentation in Docbook XML is able to produce HTML, > XHMLT EPUB, PDF, man pages, > HTML Help and now Eclipse Help Center documentation. > > Editing can be done in <Oxygen/> XML Editor's Author mode (GUI), > Altova Spy, and other GUI > editors, one can use XML editors too. > > Compiling of the docbook into PDF and HTML can be accomplished using > FOP (free), DSSSL (Free), > WEP (Commercial) and other commercial software. I've used FOP and > WEP. > > What I didn't know and many people do not know is that this is now > the publishing standard used > by most Commercial publishing houses. So when you go to Safari.com > or O'Reilly, or Que those > documents are produced from a docbook. That said, you may pay > $50.00 or more to buy it. But > if contact the publisher they'll let you have the docbook for free > and you can produce your own. > (I do that all the time). > > Now, as for Confluence. I believe we should always be evaluating > our tools and migrating tools > when appropriate. We need to be testing the tools and using people > to test the tools to see how > people interface with it. Do they like it? Does it do what the > software engineers thing it should? > In other words, is the User's needs being fulfilled? Make no > assumption as if you are all-knowing. > > That said, it is good that we are experimenting with Confluence. > What I notice now is that there > is a dialog of philosophies of how documentation should be created, > maintained and enhanced. > Points to consider for migrating documentation: > > -- Is this a consistent pathway that the end user (Administrator, > Programmer, End User) will not > have to navigate to find an item in the new documentation compared > with the old? That could be > as simple as a title, index or page number. Or, is it so different > the user walks away frustrated > and says "forget it today, I don't have time for this"? > > -- How is the documentation written in its context, language and > style. Mark Wood wrote a > few emails back about the bottleneck. This is subjective to a > point, but there is nothing worse > than reading documentation written by a bit-diddler and the end user > says "what did > this mean "use Ant to compile in the usual way" or "Pack your zoned > decimals". When the > real instructions should have been kindly written "Use the Ant > Update command to compile > your software in the usual way. Refer to ____ for further > instructions". The bottleneck can > come from variety of sources. In the current DSpace 1.6 manual, > most all committers have > been gracious in sending plain text in the jira ticket for me or > someone else to insert into the > docbook.xml. Larry Stone and Stuart Lewis have just gone in and > made the edits for sections and just > alerted me in the event I was editing the same chapter. Thank you > for that. They did a fine > job. > > -- Documentation IMHO should never be independent of a release, > except for glaring errors, > and patches. (Okay, this is my philosophical rant and rave). > > -- Programmers and users need to work together on this and make > strides in getting it done in > the first place. > > -- Convention. I've created a document that contains information > about the editing I've done > with the current DSpace documentation. It has information about the > print.xsl (fo) and html.xsl > styles used, the dictionaries for spell check, the internal linking > and other pieces of information > used for publication. It is based on the Que and O'Reilly "house > rules" for publication. I haven't > included it in the manual, but perhaps another appendix is now > warranted. > > So, where does leave us? Well, it really leaves us with things to > think about. Confluence > may eventually produce a product for us, but to throw the baby out > with the bath water doesn't > really help the situation. > > I'd like us to think about using the Confluence project to "Shadow" > the current documentation > for the next release OR so.... and we can certainly "play" with > it. The larger community > could give us feed back on this and we can make wiser decisions and > have more in depth > discussions regarding individual philosophies. > > Wiki's, IMHO are not academically rigorous for publication. (At > least for tenure at my institution > because Wiki's are not considered peer-reviewed). > > A final note. Please look at the Apache.org site. The projects > there are managed documentation > via HTML. Postgresql is managing it's documentation via HTML and PDF. > > Disruption Change is not something I enjoy these days. Maybe I'm > getting old. > > But again, sometimes we need heresies to educate us. Without Martin > Luther, were would we > be today? > > > Jeffrey Trimble > System LIbrarian > William F. Maag Library > Youngstown State University > 330.941.2483 (Office) > [email protected] > http://www.maag.ysu.edu > http://digital.maag.ysu.edu > "I must not fear. Fear is the mind-killer. > I will permit it to pass over me and through me..." > --Litany against fear.... > > <ATT00001.txt><ATT00002.txt> ------------------------------------------------------------------------------ This SF.Net email is sponsored by the Verizon Developer Community Take advantage of Verizon's best-in-class app development support A streamlined, 14 day to market process makes app distribution fast and easy Join now and get one step closer to millions of Verizon customers http://p.sf.net/sfu/verizon-dev2dev _______________________________________________ Dspace-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/dspace-devel
