Proposal for Implementing a Docbook Editor

[Christopher Curran]

satya komaragiri wrote:
> Hello,
>
> I am a final year undergraduate student from India and I plan to apply
> for Google Summer of Code. I would like to implement a Docbook editor.
> I discussed this idea with Mr. Yaakov Nemoy (cc'ed in this mail) who
> has agreed and is guiding me through the process.
>
> The Docbook editor will make it easy to write documentation through a
> wysiwyg interface. Since Docbook has a great collection of XSLs[1] it
> will be easy to convert it to HTML and write a web based editor.
>
> My research has pointed me to Beacon[2], which is a similar editor for
> GuideXML (Gentoo's documentation format). It uses an XSLT engine to
> transform XML to HTML and vice versa. I contacted the developer of
> this project and it seems like this project has been in hibernation
> for couple of months or so. But the codebase is quite developed and
> should be easy to work with. The developers were also making it a
> generic plug-able framework for easy integration of other doc types.
>
> Since it is a web-based editor, we can integrate this into the Fedora
> documentation site for easy editing and creation.
>
> It would be very nice if the Docs team could provide some feedback on
> what they feel about  a web-based GUI editor which would eliminate the
> need for knowing the Docbook XML format. If I am given a go ahead, I
> would like to put this up as a Feature.
>
> Regards,
> Satya Komaragiri
>
>
> [1]  Existing XSL for Docbook:
> http://wiki.docbook.org/topic/DocBookXslStylesheets
> [2]  Beacon: http://beacon.kix.in/
>
>   
I say good luck to you, Satya.

No, seriously, I hope you are successful.

Just some tips I've gleaned from similar projects that have failed:
* Don't extend the spec. It is the downfall of most XML 
editor/interpreter projects that the developers involved decide to add 
substantial amounts of metadata or additional tags into the XML.
* Avoid directional and positional data. If you include lots of 
positional data (like openoffice does) other interpreters will struggle 
and it will undermine a core tenet of DocBook, single sourcing. The 
easiest way to avoid this is to use a html/CSS approach. We all know 
tables are bad because too much of the positional data is hard coded at 
the wrong level. When display data is stored separately your code is 
more portable and easier to single source.
* Use existing tools. I don't know how many times I have seen someone 
rewrite an XML parser or similar but it is quite a few. I like your 
approach of using XLTS, stick with it :)

Good luck,
Chris

-- 
Chris Curran 
Technical Writer for Virtualization and Emerging Technologies
Phone: +61735148302 (UTC+10)
Brisbane, Australia. Red Hat, Inc.