GSoC Proposal for Implementing a Web-Based Docbook Editor

35 views
Skip to first unread message

satya komaragiri

unread,
Mar 21, 2009, 4:18:53 PM3/21/09
to redhat-summer, loupgar...@gmail.com, n9986...@gmail.com
Hello,

I plan to apply for Google Summer of Code this year and would like to
implement a Docbook editor for the Fedora Documentation team to make
it easier to author/edit documentation even for those who are not very
comfortable with Docbook XML.

I discussed this idea with Mr. Yaakov Nemoy (cc'ed in this mail) who
has agreed and is guiding me through the process. I proposed this
idea on the fedora-docs list and have received some positive response
from them.[1]

The Docbook editor will make it easy to write documentation through a
wysiwyg interface. Since Docbook has a great collection of XSLs[2] it
will be easy to convert it to HTML and write a web based editor.

I have come upon an existing editor Beacon[3], which is a similar
editor for GuideXML (Gentoo's documentation format). It uses an XSLT
to transform XML to HTML and vice versa. I contacted the developer of
this project (cc'ed in mail too) 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 are
also working towards making it a generic plug-able framework for easy
integration of other doc types.

Since it is a web-based editor, we can also integrate this into the
Fedora documentation site for easy editing and creation.

It would be great to have some feedback from the community. :)


Thanks and Regards,
Satya Komaragiri


[1] Proposal thread on Fedora-docs ML:
https://www.redhat.com/archives/fedora-docs-list/2009-March/msg00077.html
[3] Existing XSL for Docbook:
http://wiki.docbook.org/topic/DocBookXslStylesheets
[3] Beacon: http://beacon.kix.in/

Sankarshan Mukhopadhyay

unread,
Mar 21, 2009, 10:02:23 PM3/21/09
to redhat...@googlegroups.com, loupgar...@gmail.com, n9986...@gmail.com
On the face of it, this is a good idea. However, there are certain
elements that would come up once you task it out:

- how does this fit into the Publican driven flow within Fedora Docs

- where does this add value to Transifex

- do projects like Bespin attempt to solve similar issues

- can this be a hosted 'cloud based' service

etc. I find the idea interesting. More so because it does add an
interesting twist to the variety of projects you handle ;)

~s
--
Sent from my mobile device

You see things; and you say 'Why?';
But I dream things that never were;
and I say 'Why not?' - George Bernard Shaw

satya komaragiri

unread,
Mar 22, 2009, 11:15:42 AM3/22/09
to redhat...@googlegroups.com, loupgar...@gmail.com, n9986...@gmail.com
Hello,

I apologize for the delay in replying.


On Sun, Mar 22, 2009 at 7:32 AM, Sankarshan Mukhopadhyay
<sankarshan....@gmail.com> wrote:
>
> On the face of it, this is a good idea. However, there are certain
> elements that would come up once you task it out:
>
> - how does this fit into the Publican driven flow within Fedora Docs

This does not modify the flow within Fedora Docs, just provides an
easy parallel path for writing Docbook XML format documentation. The
editor can be seen as analogous to a wiki system where you have icons
on top which people not comfortable with wiki mark ups can use. Beacon
is a similar online GUI tool which understands GuideXML and is
intelligent enough to prevent users from destroying the format of the
documentation.

Rich text editors like TinyMCE or FCKEditor are similar. We can say
our tool will be a rich text editor for Docbook format.

WYSIWYG Editors have the reputation of being very notorious. I plan to
make this better by making it more of a 'What you see is what you
mean' by using inline editors so that a user can't mess around with
the sanity of the XML document by inserting content where's it not
supposed to be. The markup will remain clean.

> - where does this add value to Transifex

This is a language independent editor which only helps create 'Docbook
XML following' documentation. Once that is created, Transifex can be
used as always to translate the documentation.

> - do projects like Bespin attempt to solve similar issues

Bespin is mainly intended for code editing and is not browser
independent as it uses canvas.

> - can this be a hosted 'cloud based' service

It can be used either as a wiki-like (with an optional approval module
to ensure the quality) web-based editor which can interact with the
docs CVS to push in changes.

It can also be bundled as an application which the documentation team
can use as an easy alternative to PSGML with emacs or vi. and then
follow the normal procedure to commit it.

> etc. I find the idea interesting. More so because it does add an
> interesting twist to the variety of projects you handle ;)

:)

Regards,
Satya Komaragiri

satya komaragiri

unread,
Mar 23, 2009, 3:31:06 PM3/23/09
to redhat...@googlegroups.com, loupgar...@gmail.com, n9986...@gmail.com
Hello,

I think I'll apply for this project now the application phase for
summer of code has started. :) The proposal is in a more concrete form
thanks to the great feedback have been receiving from the docs
team.[1]

Yaakov has discussed this project with me and has been advising me so
far. But this project will need a mentor who is familiar with the
functioning of docs team to guide me better. Is anyone available to
mentor this project? Can anyone guide me to someone who is available?

Regards,
Satya

[1] Discussion thread:
https://www.redhat.com/archives/fedora-docs-list/2009-March/msg00077.html

Terrance Hutchinson

unread,
Mar 23, 2009, 4:09:16 PM3/23/09
to redhat...@googlegroups.com, loupgar...@gmail.com, n9986...@gmail.com
I would have someone proof-read your proposal. I did that last year and it did wonders for me in terms of getting accepted.

Best Regards,

Hutchint

satya komaragiri

unread,
Mar 23, 2009, 4:20:54 PM3/23/09
to redhat...@googlegroups.com
On Tue, Mar 24, 2009 at 1:39 AM, Terrance Hutchinson
<terrance....@gmail.com> wrote:
> I would have someone proof-read your proposal. I did that last year and it
> did wonders for me in terms of getting accepted.
> Best Regards,
> Hutchint

Thanks, yeah I'll do that.

Regards,
Satya

Sankarshan Mukhopadhyay

unread,
Mar 25, 2009, 1:01:56 AM3/25/09
to redhat...@googlegroups.com, satya komaragiri
Hi,

On Sun, Mar 22, 2009 at 1:48 AM, satya komaragiri
<satya.ko...@gmail.com> wrote:

> I plan to apply for Google Summer of Code this year and would like to
> implement a Docbook editor for the Fedora Documentation team to make
> it easier to author/edit documentation even for those who are not very
> comfortable with Docbook XML.

So, aside from the discussions that seem to be happening on the lists,
here are a few points that I'd like to put out:

- right now, this is just a project idea and, is on mail. I'd like to
see this in a proposal format with the following aspects covered:

* Tasks and Milestones
* Proposed list of features to be completed within the GSoC time-frame
(should this be accepted)
* Thoughts about whether this tool/application can fit into the
Transifex and Publican based workflow that is currently part of the
infrastructure

Since you've been a GSoC candidate in the previous years, I don't
think it is necessary to stress the need for a well thought out and
reasonably pragmatic proposal.

With a proposal available, I would say the search for a possible
mentor would begin :) I haven't seen a mentor lining up for the idea
yet.

> The Docbook editor will make it easy to write documentation through a
> wysiwyg interface. Since Docbook has a great collection of XSLs[2] it
> will be easy to convert it to HTML and write a web based editor.

DocBook does not lend itself to WYSIWYG paradigm very naturally. Would
it be possible for you to take time for a small mockup ?

> It would be great to have some feedback from the community. :)

I'd say, now would be a good time to start working on a proposal.

~s


--

You see things; and you say 'Why?';
But I dream things that never were;
and I say 'Why not?' - George Bernard Shaw

Sent from: Calcutta WB India.

satya komaragiri

unread,
Mar 26, 2009, 1:55:12 PM3/26/09
to Sankarshan Mukhopadhyay, redhat...@googlegroups.com, Yaakov Nemoy
Hello,

On Wed, Mar 25, 2009 at 10:31 AM, Sankarshan Mukhopadhyay
<sankarshan....@gmail.com> wrote:


> So, aside from the discussions that seem to be happening on the lists,
> here are a few points that I'd like to put out:
>
> - right now, this is just a project idea and, is on mail. I'd like to
> see this in a proposal format with the following aspects covered:

[...]

The proposal draft can be found at
http://92.243.3.101/DocBookEditorProposal.txt . Feedback is welcome :)

> DocBook does not lend itself to WYSIWYG paradigm very naturally. Would
> it be possible for you to take time for a small mockup ?
>

Sure, I'll try and put up a mock-up by weekend.


Regards,
Satya

Sankarshan Mukhopadhyay

unread,
Mar 27, 2009, 9:54:05 AM3/27/09
to satya komaragiri, redhat...@googlegroups.com, Yaakov Nemoy
On Thu, Mar 26, 2009 at 11:25 PM, satya komaragiri
<satya.ko...@gmail.com> wrote:

> The proposal draft can be found at
> http://92.243.3.101/DocBookEditorProposal.txt . Feedback is welcome :)

Ahh ! That was quick. Here are a few immediate observations:

- the method to arrive at the subset of the schema to be supported as
part of this phase of the project needs more inputs

- the first timeline is fairly large, would it be possible for you to
chunk it down to more granularity ? Personally, I'd like to see time
durations of a maximum of around 10 days (ie. 2 working weeks) which
leave enough room and headspace to think things through, adapt ideas
and produce test-ready code.

- it would perhaps be more useful to have the first run of the
application as an RPM (for say, F11) which would enable more folks to
give it a spin.

Having said all of the above, best of luck in finding a mentor and,
should your proposal get through, r0ck the world :)

~sankarshan

satya komaragiri

unread,
Mar 27, 2009, 10:48:16 AM3/27/09
to Sankarshan Mukhopadhyay, redhat...@googlegroups.com, Yaakov Nemoy
Hello,

On Fri, Mar 27, 2009 at 7:24 PM, Sankarshan Mukhopadhyay
<sankarshan....@gmail.com> wrote:
> On Thu, Mar 26, 2009 at 11:25 PM, satya komaragiri
> <satya.ko...@gmail.com> wrote:
>
>> The proposal draft can be found at
>> http://92.243.3.101/DocBookEditorProposal.txt . Feedback is welcome :)
>
> Ahh ! That was quick. Here are a few immediate observations:

[...]

Thank you for the feedback :) Will make the changes and put it up.

> Having said all of the above, best of luck in finding a mentor and,
> should your proposal get through, r0ck the world :)
>
> ~sankarshan

Thank you :)

Regards,
Satya

Sankarshan Mukhopadhyay

unread,
Mar 28, 2009, 12:28:08 AM3/28/09
to redhat...@googlegroups.com
It just struck me that discussing about proposals etc via this list
may be contrary to the aims of the list. If that is the case, then I'd
like to say sorry. I'll use the GSoC app to point out the comments to
Satya.

~sankarshan

On Fri, Mar 27, 2009 at 7:24 PM, Sankarshan Mukhopadhyay
<sankarshan....@gmail.com> wrote:

Patrick W. Barnes

unread,
Mar 28, 2009, 3:38:33 AM3/28/09
to redhat...@googlegroups.com
On Friday 27 March 2009 23:28:08 Sankarshan Mukhopadhyay wrote:
> It just struck me that discussing about proposals etc via this list
> may be contrary to the aims of the list. If that is the case, then I'd
> like to say sorry. I'll use the GSoC app to point out the comments to
> Satya.
>

Actually, such discussion is welcome here. Much of the advice that applies
for one student will also help others.

--
Patrick "The N-Man" Barnes
The Fedora Project
nma...@fedoraproject.org

http://fedoraproject.org/wiki/PatrickBarnes

Have I been helpful? Rate my assistance!
http://rate.affero.net/nman64/

All messages cryptographically signed:
http://en.wikipedia.org/wiki/OpenPGP
--


signature.asc

satya komaragiri

unread,
Apr 1, 2009, 11:14:30 AM4/1/09
to Sankarshan Mukhopadhyay, redhat...@googlegroups.com
Hello,

On Wed, Mar 25, 2009 at 10:31 AM, Sankarshan Mukhopadhyay
<sankarshan....@gmail.com> wrote:

> DocBook does not lend itself to WYSIWYG paradigm very naturally. Would

> it be possible for you to take time for a small mock-up ?

I have uploaded a small mock-up on http://92.243.3.101/editor/test.php
(It would be best if you could open that link in Firefox) .

1. I have modified beacon to show DocBook as an option for document type.
2. I have added support to edit DocBook sections, paragraphs and list.
As can be seen in the demo, when we click on any portion of that
document, an inline editor for that portion opens up (paragraphs
cannot handle <enter key> as yet).
3. For styling tags, I have implemented a Boldface formatter. Once you
click on any paragraph or list to edit it, any portion of that text
can be selected and made bold (clicking twice does not unbold it as
yet).
4. The sidebar is meant to show the document tree.

As can be seen above, the functionality is very limited as yet, but it
will serve to provide an idea of what to expect.


Regards,
Satya

Reply all
Reply to author
Forward
0 new messages