Thursday, July 2, 2009

DocBook Editor 2

Just completed a tiny DTD for DocBook corresponding to the small set of tags for which I had written the XSLs. I am so glad it works! ( works best with firefox)

Now on it is just a matter of adding more elements to get a richer tag-set for DocBook till the mid-term evals. The basic infra is all set up (will try to keep improving usability though).

Also added a brand new and better CSS.

On the other side I think I should try and get more community involvement into developing the editor as the number of DocBook elements is *huge*.

I'll start by explaining what beacon is and how it works.

Beacon is a What you see is what you mean editor which relies heavily on XSL for XML to HTML conversions and vice-versa.

Most of the work involved in making a plugin is writing the two XSLs. One is required for converting the XML to HTML so that it can be displayed in the browser. And the other for converting the HTML back to XML. All these operations are done on the server side using PHP (or Python).

One may wonder, why rewrite XSLs if they already exists, like for Docbook for example. The reason is that Beacon needs some 'hooks' in the generated HTML so it can pick up the nodes using Javascript. This is required to do multitude of tasks like rendering inline editors, maintaining structural sanity, addition/deletion of new nodes, etc. Since HTML and Docbook XML tags are very different, there needs to be some way to map the XML tags over to HTML. These hooks are done using title attribute on tags. So for example, the tag will be rendered in HTML as:

< p title = "docbookPara"> Somethings are best with a title < /p >

Title tags tend to be most unobtrusive here and works well for DOM manipulation which is made even easier thanks to jQuery.

Once the HTML has been rendered, some Javascript magic makes it editable via inline editors of various types. We are still working on the node adding/deleting feature. Once that is done we will have a more or less a complete editor.

The validation of the generated HTML is kept in check via a Javascript based DTD.

So the user cycle of Beacon is:

new document -> XML -> HTML -> XML

All ajax-y communication is handled by JSON (except for file upload which uses an iframe of course).

Since its a web based it relies completely on Ajax for any post first page load. The UI is pretty much like a desktop Application with Tabs, sidebar etc.

To sum it up, a plugin now requires:
  1. Couple of XSLs
  2. Javascript based DTD
  3. Some trivial PHP code
  4. CSS + some template XMLs

I will write a tutorial on how to make a plugin for docbook next. Will be nice if folks chip in to get in as many tags supported as possible.


John said...

Just a quick word of encouragement...

Having been involved in the Fedora Docs Project off-and-on since 2006, I clearly see the need for this editor. You can poke around the Fedora wiki and see my attempts to point people to WYSIWYG editors for DocBook XML.

I especially like the fact that your GSOC project for Fedora is building upon a previous GSOC project for Gentoo.

My personal motto is "FOSS Docs the FOSS Way!" - this project is a good example of "FOSS Projects the FOSS Way!"

Finally, if you need any help on editing your wiki pages, let me know. My personal "long hot summer" project is to learn Publican to assess its strengths and weaknesses. I definitely will be using one of your wiki pages as a DocBook cheat sheet.

John Babich
Volunteer, Fedora Project

satya said...

Thank you John! It is always very nice to find acceptance of one's project idea.

I will be working on integrating Beacon with Publican in my 2nd half of GSoC timeline. I could definitely use some help in that.

It would be nice if you could give me your contact id so I can contact you when I am working on that.

Once again, thanks a lot :)

quaid said...

Just a couple of quick thoughts; sorry it's not more! But you are doing great, so not much needed. :)

You posted earlier about needing a test server for working on, which is why you are using There isn't a problem with you using that, esp. if it's helping you collaborate with other people. In the end, though, you are going to need this deployed on Fedora Infrastructure, and you can get full access to a public test server for doing that. It also can be used for collaboration, with anyone who has a FAS (Fedora) account.

You can make a request for resources using this procedure:

In addition, there is a public test server for the Zikula instance. You could begin working with the Zikula team on getting this Beacon working there; you might just want to skip the step of running your own public test server and start using the Zikula one. YMMV.

skleinei said...

Hi Satya, this looks awesome. I just wanted to let you know about a wiki-based alternative. The Scroll Wiki Exporter lets you export trees of pages from your Confluence wiki to DocBook and PDF.

(Confluence and Scroll provide free community licenses.)


satya said...

@quaid: Thank you for your suggestion :) Will contact the Zikula team in Fedora now and work on integrating Beacon.

satya said...

@stefan: Thank you :) Scroll works with only Confluence wiki. But AFAIK, Fedora does not use Confluence. Please correct me if I am wrong.