[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: Proposal for Implementing a Docbook Editor



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.


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]