New web based docbook editor project (was Re: Helping your documentation effort.)

[Jonathan Dill]

Hello Rob,

Funny you should mention it, I have been doing quite a bit of research 
in this area and have been planning to begin a DocBookWeb Wiki page with 
more information.  I am not a member of the Ubuntu Docteam (at least not 
yet ;) but have been doing this research for work.  I hang out here 
because I learn a lot from the Docteam members, and I hope that giving 
back some of what I have learned can be helpful to them, for example on 
the DocBookEditors Wiki page.

My goal is to develop a Wiki which could also generate an "Operations 
Manual" as a single file or hardcopy document for my use in supporting 
my network engineering clients--in a disaster scenario, getting to a 
server to retrieve this essential information may not be possible nor 
practical, which could put me in a Catch-22 situation with a regular Wiki.

At first, I had focused primarily on LAMP, but found there are a lot of 
bits and pieces missing that would have to be developed.  At first, I 
was avoiding Java, mainly because most of my experience is with LAMP and 
very little with Java, but I have discovered that most of the necessary 
bits and pieces already exist for Java.  So, now I am learning Java and 
Eclipse to see what I can do with that.

Here are a few links that you might want to take a look at:

DocBookWiki http://doc-book.sourceforge.net/homepage/

SilkPage http://silkpage.markupware.com/

IBM Whitepaper on authoring DocBook with Eclipse:
http://www.eclipse.org/articles/Article-Authoring-With-Eclipse/AuthoringWithEclipse.html

You may find more interesting links in my online bookmarks:

http://www.furl.net/members/jfdnerds

All of the tools that I have encountered so far have major shortcomings, 
for example most of the web-based tools do not handle XInclude.  Also, 
transforming XML can be a major resource hog, some kind of caching would 
be essential if you really want the Wiki to deal with DocBook XML 
internally.  Otherwise, it might not be practical to serve other formats 
to hundreds or even thousands of clients on the fly unless you want to 
put out the beaucoup bucks for commercial platforms that are designed 
for that purpose and the necessary hardware to support them.

For Open Source projects with little or no budget, it might be more 
efficient and practical to use something like WikiText or Textile 
internally and impose strict formatting conventions to ensure that it 
can be transformed to valid DocBook cleanly.  I am not an expert (yet), 
but I think presenting WikiText or Textile as HTML or even XHTML should 
be much more efficient than transforming XML.  Although this might be a 
good idea in general, it might not be a direction that the Ubuntu 
Docteam wants to go since the authoring itself would be done in a format 
other than DocBook using a different set of tools.

Robert Stoffers wrote:
> What about giving you the ability to actually fix using just a web 
> browser the section of a document you don't like, a little like a wiki?
Jonathan Dill