2008-09-17T21:23:23Z

Project overview 254 Home 47

3926

= RuDI: Ruby Utilities for DITA processing = This project is aimed at improving collaboration and production processes for DITA-based web documents, by providing high-end CMS features using inexpensive open-source tools. The project has several aspects: * '''[http://kenai.com/projects/rudi/sources/subversion/content/lib/rudi/xml_transform.rb Ruby-based XML Styles and Transforms (RXSLT)]:''' A Ruby-based XML transformation engine that lets you write transforms in a Ruby-ized version of XSLT, but which puts the power of Ruby at your disposal to do conditional processing, use subroutines, store values for later use, and do anything else that Ruby lets you do (a lot!). * '''[[Flexible, Template-Based Production System|DITA Publishing using DreamWeaver Templates]]:''' A set of tools that uses the Ruby transformation engine to merge DITA content into DreamWeaver templates. The templates let designers focus on the results they want to produce, and minimizes the amount of code the production team has to write to generate it. Pipeline processing lets the production team specify transforms in more flexible and more powerful ways. This system doesn't replace the DITA toolkit, but rather augments it by adding add post-processing steps--which also means that the DITA toolkit can be upgraded at will, without having to retrofit dozens of customizations. * '''[[Man Page Processing]]:''' [''in progress''] A utility and suite of processing scripts that uses Ruby processing to generate nroff/troff man pages from HTML generated by the DITA Open Toolkit (OT). Solves some problems that prevents OT-generated troff output from working as a man page. And, because it exists as a separate utility, both it and the OT can be updated separately, so there is no need to re-integrate the utility when you update the OT. * '''Link-Management, Topic Search, and Version Control:''' [''future''] One of the really important features of any content management system is the ability to keep links intact in the face of renames, moves, and deletes of files and directories. The goal here is to provide those features in the context of one or more open source version control systems like [http://subversion.tigris.org/ Subversion]. (At this point, the [[link management algorithms]] have been defined, but not implemented.) When sophisticated search-and-replace functionality is added to that, the result will be a low-cost solution for topic storage that rivals a high-end CMS. * '''End-To-End Solution:''' [''future''] When the DITA publishing solution and link management capabilities are integrated with Claude Vedovini's [http://www.dita-op.org/ DITA open platform] for web-based editing, the result will be a complete, end-to-end solution for DITA authoring, storage, and production. * '''Collaboration:''' [''future''] The goal here is to effectively author DITA documents online. Since others are currently working in that space, the idea will be to integrate these tools and support those systems. (Some worth keeping an eye on are [http://www.inmediusdita.com/ DITAStorm ], [http://xopus.com XOpus], and David Green's [http://greensopinion.blogspot.com/2008/11/mylyn-wikitext-targets-oasis-dita.html Wiki->DITA] tool.) Then--given the ability to collaborate on DITA documents--it becomes possible to enable [http://blogs.sun.com/coolstuff/entry/enabling_collaborative_design_and_decision collaborative design-and-decision-making online] using DITA specializations. * '''Localization Support:''' [''future''] A version control system accumulates many changes to a document, but localization teams typically translate only a few of a those versions. To be of maximum benefit to translators, the system must be able to interact with localization systems. Translators need to be able to store identification information for the last version number they worked with (either in the DITA system or in their own system), and get differences between that version and the current version, for translation. ['''Note:''' Such tools can also benefit collaborators, who need an option to get a display that highlights changes from the last version they read.] The result, ideally, will be a fully integrated system that users can easily set up to produce well-styled, highly readable HTML pages. Those pages will include links to editing tools that use Wiki-text, an online editor like DITAStorm, or a desktop editor like oXygen or XMetaL. At the end of the day, changes made to those topics will ripple through the PDFs and other documents that depend on them, and go out through a variety of delivery channels. == A Note on Licensing == I've avoided the whole discussion of licenses for years. Just not something I wanted to spend my time on. (I know it's important. But I have limited brain cycles.) To set up this project, however, I needed to make a selection from the 18 or 20 "recommended" license models. Google is your friend. I typed in the names of several promising candidates, to find a page that compared them. I came across this one, and relied on it to make a decision: [http://weblogs.java.net/blog/evanx/archive/2006/05/cddling_up_with_1.html this page]. To summarize the points made in that page: * GPL licenses are "viral", so they're not friendly to a company that wants to use your stuff to make money. But they do ensure that all improvements and extensions go back to the community. * BSD licenses (and derivatives like the Apache license) are "use at your own risk" licenses. They're business friendly, but do not ensure the growth of the code in the "software commons". * The Mozilla license was really good, but had a couple of bugs. * The CDDL license claims to fix those bugs. In the process, it distinguishes between "derived works" (new files) and "modifications" (changes to existing files). You're not required to contribute derived works back to the community (although you can--and should, whenever possible), but you are required to submit modifications back to the community for approval and adoption. The CDDL seemed like the right idea, so that's the license I chose. (I haven't spent the time reading the license and consulting with lawyers to be sure that it actually does all that, but it sounds like it is trying to do the right thing, at least. So it looked like the best choice available at the time.)

<h1><a name='RuDI:_Ruby_Utilities_for_DITA_processing'></a> RuDI: Ruby Utilities for DITA processing </h1> This project is aimed at improving collaboration and production processes for DITA-based web documents, by providing high-end CMS features using inexpensive open-source tools. The project has several aspects: <ul><li> <a class='external' href="http://kenai.com/projects/rudi/sources/subversion/content/lib/rudi/xml_transform.rb">Ruby-based XML Styles and Transforms (RXSLT)</a>: A Ruby-based XML transformation engine that lets you write transforms in a Ruby-ized version of XSLT, but which puts the power of Ruby at your disposal to do conditional processing, use subroutines, store values for later use, and do anything else that Ruby lets you do (a lot!). </li></ul><ul><li> <a href='<?url_for_page Flexible, Template-Based Production System?>' class='<?class_for_page_link Flexible, Template-Based Production System?>'>DITA Publishing using DreamWeaver Templates</a>: A set of tools that uses the Ruby transformation engine to merge DITA content into DreamWeaver templates. The templates let designers focus on the results they want to produce, and minimizes the amount of code the production team has to write to generate it. Pipeline processing lets the production team specify transforms in more flexible and more powerful ways. This system doesn't replace the DITA toolkit, but rather augments it by adding add post-processing steps--which also means that the DITA toolkit can be upgraded at will, without having to retrofit dozens of customizations. </li></ul><ul><li> <a href='<?url_for_page Man Page Processing?>' class='<?class_for_page_link Man Page Processing?>'>Man Page Processing</a>: [in progress] A utility and suite of processing scripts that uses Ruby processing to generate nroff/troff man pages from HTML generated by the DITA Open Toolkit (OT). Solves some problems that prevents OT-generated troff output from working as a man page. And, because it exists as a separate utility, both it and the OT can be updated separately, so there is no need to re-integrate the utility when you update the OT. </li></ul><ul><li> Link-Management, Topic Search, and Version Control: [future] One of the really important features of any content management system is the ability to keep links intact in the face of renames, moves, and deletes of files and directories. The goal here is to provide those features in the context of one or more open source version control systems like <a class='external' href="http://subversion.tigris.org/">Subversion</a>. (At this point, the <a href='<?url_for_page link management algorithms?>' class='<?class_for_page_link link management algorithms?>'>link management algorithms</a> have been defined, but not implemented.) When sophisticated search-and-replace functionality is added to that, the result will be a low-cost solution for topic storage that rivals a high-end CMS. </li></ul><ul><li> End-To-End Solution: [future] When the DITA publishing solution and link management capabilities are integrated with Claude Vedovini's <a class='external' href="http://www.dita-op.org/">DITA open platform</a> for web-based editing, the result will be a complete, end-to-end solution for DITA authoring, storage, and production. </li></ul><ul><li> Collaboration: [future] The goal here is to effectively author DITA documents online. Since others are currently working in that space, the idea will be to integrate these tools and support those systems. (Some worth keeping an eye on are <a class='external' href="http://www.inmediusdita.com/">DITAStorm </a>, <a class='external' href="http://xopus.com">XOpus</a>, and David Green's <a class='external' href="http://greensopinion.blogspot.com/2008/11/mylyn-wikitext-targets-oasis-dita.html">Wiki->DITA</a> tool.) Then--given the ability to collaborate on DITA documents--it becomes possible to enable <a class='external' href="http://blogs.sun.com/coolstuff/entry/enabling_collaborative_design_and_decision">collaborative design-and-decision-making online</a> using DITA specializations. </li></ul><ul><li> Localization Support: [future] A version control system accumulates many changes to a document, but localization teams typically translate only a few of a those versions. To be of maximum benefit to translators, the system must be able to interact with localization systems. Translators need to be able to store identification information for the last version number they worked with (either in the DITA system or in their own system), and get differences between that version and the current version, for translation. [Note: Such tools can also benefit collaborators, who need an option to get a display that highlights changes from the last version they read.] </li></ul> The result, ideally, will be a fully integrated system that users can easily set up to produce well-styled, highly readable HTML pages. Those pages will include links to editing tools that use Wiki-text, an online editor like DITAStorm, or a desktop editor like oXygen or XMetaL. At the end of the day, changes made to those topics will ripple through the PDFs and other documents that depend on them, and go out through a variety of delivery channels. <h2><a name='A_Note_on_Licensing'></a> A Note on Licensing </h2> I've avoided the whole discussion of licenses for years. Just not something I wanted to spend my time on. (I know it's important. But I have limited brain cycles.) To set up this project, however, I needed to make a selection from the 18 or 20 "recommended" license models. Google is your friend. I typed in the names of several promising candidates, to find a page that compared them. I came across this one, and relied on it to make a decision: <a class='external' href="http://weblogs.java.net/blog/evanx/archive/2006/05/cddling_up_with_1.html">this page</a>. To summarize the points made in that page: <ul><li> GPL licenses are "viral", so they're not friendly to a company that wants to use your stuff to make money. But they do ensure that all improvements and extensions go back to the community. </li></ul><ul><li> BSD licenses (and derivatives like the Apache license) are "use at your own risk" licenses. They're business friendly, but do not ensure the growth of the code in the "software commons". </li></ul><ul><li> The Mozilla license was really good, but had a couple of bugs. </li></ul><ul><li> The CDDL license claims to fix those bugs. In the process, it distinguishes between "derived works" (new files) and "modifications" (changes to existing files). You're not required to contribute derived works back to the community (although you can--and should, whenever possible), but you are required to submit modifications back to the community for approval and adoption. </li></ul> The CDDL seemed like the right idea, so that's the license I chose. (I haven't spent the time reading the license and consulting with lawyers to be sure that it actually does all that, but it sounds like it is trying to do the right thing, at least. So it looked like the best choice available at the time.)

2010-01-16T21:26:26Z

949