On Wed, Jan 6, 2010 at 7:44 AM, Elliot Metsger <[email protected]> wrote: > > 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.
Doxia is designed primarily to manage Maven Site Generated Content, that is wrapped in a Maven Site like the following... http://maven.apache.org/ It is maintained in an SVN repository... http://svn.apache.org/viewvc/maven/site/trunk/src/site/ and allows for that Site content to be in various formats. > > 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. True it can be utilized for other types of documentation conversion. The challenge is where the canonical documentation is maintained and what direction the pipeline is moving in... Confluence + Scroll "produces" both PDF and a package of docBook content. It allow you edit the manual as a hierarchy of Confluence pages and maps confluence syntax into docBook and PDF. The point of using Confluence is to introduce a mechanism of collaboration on managing the documentation, thus the challenge with using it as a sink and docBook as the canonical source is that you don't get to use Confluence for what it is good for... an Editor. I will add that there is possibly the alternative of "roundtripping" that may be plausible here. 1.) svn/docBook --> doxia --> confluence 2.) svn/docBook <-- Scroll <-- confluence Albiet I expect there to be a mismatch in what is output. Thus I'd rather recommend choosing one canonical source and have all others be derivative... For instance confluence --> scroll --> pdf confluence --> scroll --> svn/docBook confluence --> scroll --> svn/docBook --> svn/html confluence --> scroll --> svn/docBook --> svn/pdf confluence --> scroll --> svn/docBook --> eclipse help confluence --> scroll --> svn/docBook --> maven sites thus maintaining the documentation in an editorial tool and exporting a version to the svn repository once the release is ready... next... ;-) Jeff, a most excellent overview of your experience... I will precede to comment below... > > On Jan 6, 2010, at 10:26 AM, Jeffrey Trimble wrote: > > > > 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!) All points that we need a "technical editor" pool here that are not "programmers". > > > > > 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... True, my point isn't that its fly by night, but that only "programmers" are the ones sitting here editing it like its code... Publishing houses use expensive inhouse WYSIWYG editors to maintain docBook content. > > 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. Ok, personal opinion here... all these "suck" (well maybe except for XMLSpy, which unfortunately costs a lot and only runs on Windows)... all too heavy as tools for a common lightweight and immediate editorial review workflow. Ideal maybe for publishing houses where this is what one does all day long. None accomplish what integrating on Confluence will allow us to do. Which is hand our community an online tool for providing feedback and editing support directly on the documentation. Again, one less bottleneck and one more way to actively participate. For instance, if we utilize the following plugin, an editorial review process can be captured directly within confluence itself. https://plugins.atlassian.com/plugin/details/131 These guys have a commercial plugin that allow you to produce editorial workflows that has a free community license. http://confluence.comalatech.com/display/AWP/Home http://confluence.comalatech.com/display/WWW/Knowledge+base+approval+process http://confluence.comalatech.com/display/AWP/Creating+an+FAQ+workflow+tutorial > > > > 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. I expect that this is exactly what confluence is doing "for us" under the hood with Scroll... Scroll uses FOP for the Open Source license and uses a Commercial rendering engine on the paid licenses. I highly expect the intermediary format is either docBook or more directly using Confluences own xml format to accomplish the FOP transform. Likewise, Scroll allows you to manipulate the templates used in this processing so you can produce exactly what you want to. > > 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). Wow, that is a seriously cool tip, I will have to try it :-) > > > > 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. I agree, it is all I am asking for, not to be shot down without first testing out what I have done. > > > > 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"? I think that a consistent and more fine grained documentation outline (splitting some of the larger pages into smaller ones) would allow us to accomplish two things: Establish fixed locations for specific topics. http://fedora-commons.org/confluence/display/DSTEST/Introduction which is a temporary URL, I would suggest something more like http://docs.dspace.org/DSpace1.5/Introduction http://docs.dspace.org/DSpace1.6/Introduction http://docs.dspace.org/DSpace1.7/Introduction I would say that much like supporting backward compatibility in the code base, retaining backward compatibility in the documentation outline would be critical, pages could be added, but not removed or renamed during a maintenance release branch (1.6.0, 1.6.1, 1.6.2) > > > > -- How is the documentation written in its context, language and > > style. Mark Wood wrote a > > few emails back about the bottleneck. I think this was my comment about bottlenecks... > >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. The past bottleneck was a lack of resources and participation of non-coders on the canonical documentation. That their work tests to be "one off" in WIKI, Blog and even the static DSpace website. Rather than on the core resources themselves, thus my suggestion, either move the management of the docs out of the svn or add more people to manage it. This was one of the original discussions that lead to the benefit of your addition to the team :-) > > 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. And I know they will continue to do so no matter where this documentation is managed, its the possibility of new participation that I am interested in seeing come to fruition. > > > > -- Documentation IMHO should never be independent of a release, > > except for glaring errors, > > and patches. (Okay, this is my philosophical rant and rave). This topic got a little out of context, I suggested that the online documentation would be better serviced if it could be improved asynchronously from the release, such that bug fixes and improvements would be reflected immediately online (or after a brief editorial review) rather than waiting another 6 months to a year of it to be released. > > > > -- Programmers and users need to work together on this and make > > strides in getting it done in > > the first place. An developers are the responsible party here, they need to be soliciting help from the user base, because users will not participate unless they are somehow engaged. > > > > -- 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. And I think such conventions would also be able to be applied to the confluence based Manual as well. > > > > 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. But that won't give you the full effect of confluence as the canonical source and the content in the svn repository being a derivative. Without a pipeline to get the changes in the confluence site into the Manual that is published with the release the benefit to the community and the participation by the community will create more work for someone merging the content back to the svn repository. > > Wiki's, IMHO are not academically rigorous for publication. (At > > least for tenure at my institution > > because Wiki's are not considered peer-reviewed). However, this is organizational, and will be a concern whether we are talking docBook in SVN or a WIKI or an MS Word document. It will take proper moderation and editorial review processes in place to create the best product possible. I agree, without it, the Manual would end up looking like the current wiki does. > > 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. In much of the Apache site, this is Maven driven (as my above example points out). But you will notice there is the same issue of sparsness in much of the generated documentation, especially in the Maven based projects... often a criticism. Also why I shy away from recommending it as a solution. > > 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? Excellent dialog, Mark -- Mark R. Diggory Head of U.S. Operations - @mire http://www.atmire.com - Institutional Repository Solutions http://www.togather.eu - Before getting together, get t...@ther ------------------------------------------------------------------------------ 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
