Hi Karen,

2009/3/21 Karen Schneider kgs@esilibrary.com:

On Sat, Mar 21, 2009 at 8:04 AM, satya komaragiri satya.komaragiri@gmail.com wrote:

Speaking as a lurker on this list who in real life is trying to wrap her head around the complexity of formalizing  a docs project in an open source project... I personally think this feels a real need. Satya, there is also a docbook-apps list where you might get additional feedback on this idea. I'm working on a proof of concept for Docbook within our project, and there is a hurdle for Docbook production with respect to contributions from nontechnical volunteers (and even to some extent the more technical participants) that an editor "in the cloud" could significantly help address.

Thanks a lot for the feedback. Yes, Docbook can be daunting simply because of its richness of features. The main motive behind this project is to make life easier for the documentation team and attract new people to it by lowering the knowledge barrier.

Thanks for the pointer, I'll mail the Docbook Apps list too.

Regards Satya

2009/3/21 Matthew Daniels danielsmw@gmail.com:

Satya,

A docbook XML editor, especially web-based as you propose, could definitely be useful for the docs team. I don't think it would totally eliminate the need to know XML, but it doesn't need to. Just giving a way for contributers to write content without having to learn a rich markup language would probably mean we could recruit more people and get things done faster.

Keep us updated on your progress!

I've also found that for some people (myself included) that having WSYWIG and XML side by side can work as a good on the job learning aid. You could certainly market it as away for beginners to get used to working with XML.

-Yaakov

On Mar 21, 2009, at 8:04 AM, satya komaragiri satya.komaragiri@gmail.com 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/

-- fedora-docs-list mailing list fedora-docs-list@redhat.com To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list

-- fedora-docs-list mailing list fedora-docs-list@redhat.com To unsubscribe:https://www.redhat.com/mailman/listinfo/fedora-docs-list

On Sun, Mar 22, 2009 at 08:54:13AM -0400, Karen Schneider wrote:

If you need people to contribute comments about why this would be valuable, feel free to contact me.

Would you be willing to help mentor through the proposal process?

We need many hands to help work with the students on making the best proposal. That means reading it early, commenting often, and so forth. If you have good experience with documentation, content or knowledge management, herding cats, etc., then you can help mentor at this stage.

(For the person paired with Satya as a mentor, anyone willing could do it, but needs to be prepared to do a few hours of work every week in self-learning if not familiar with the Fedora Project the way an old timer is.)

- Karsten

Thanks  Karel, That will be very useful to build up my case.

Sorry Karen! My bad.

Regards Satya

Hi Betty,

On Sun, Mar 22, 2009 at 8:59 PM, Betty Harvey harvey@eccnet.com wrote:

Sorry Satya - I am late to the party (discussion).  A really good web based XML (docbook, DITA and generic) editor would be really nice. A few of the desktop XML editors (XMetal and Arbortext Editors) endeavored to create a web-based generic web-based editor with limited success.

Thanks for mailing :) You are not late and feedback is always welcome.

Just Systems is still marketing their product XMAX and it looks promising but unfortunately it only runs on a Windows-based server (not good).

There is another editor called XOpus that looks pretty promising as well.  I have played with this one a little and it looks pretty good but lacks some of the functionality that is needed for the non-XML savvy author/editor and it crashes  when using Mozilla which makes it a non-starter for most environments.

Also, unfortunately, neither of these editors is Open Sourced/Free.

I think that an editor that can used in a content management (I am using this loosely) system such as Drupal would be very appealing. There is an XML module for displaying XML in Drupal but nothing that provides a structured editing environment.

The Docbook editor will be just like TinyMCE or FCKEditor. This can be embedded anywhere in the webpage and a back-end can be hooked into it to perform XSLT operations. The target save points etc are fully customizable. Examples of this would be Wordpress which uses TinyMCE or Drupal itself where there is a TInyMCE add on.

Good luck and I look forward to hearing more about your project as it moves forward!

Betty

Thanks!

Satya

On Sun, Mar 22, 2009 at 07:50:41PM +0530, satya komaragiri wrote:

By integrate I meant we could host it on the Fedora Docs website and allow it to interact with the CVS. An approval module can also be implemented to ensure the quality of the documentation. Its just an editor that can be added anywhere in the page. So it could be added to the normal flow of any framework.

I like your simplicity of design so far, building on known components and making something lightweight that can fit in other web apps.

BTW, the source for documents is no longer a single CVS repository. We use multiple repositories on fedorahosted.org, such as git and Subversion.

I wonder if there are some lessons that can be learned from Transifex and how it can submit to multiple upstream repositories from the single web application?

/me pokes Glezos ...

- Karsten

On Wed, Mar 25, 2009 at 02:14:30AM +0530, satya komaragiri wrote:

documentation process in Fedora and the Documentation guide [1] pointed me to CVS.

[1] Documentation Guide: http://docs.fedoraproject.org/documentation-guide/en_US/

That document is unmaintained and almost criminally out of date.

Anyone interested in taking it over and updating it? We could start a new project on fedorahosted.org for it.

For other orphaned content of interest:

http://cvs.fedoraproject.org/viewvc/?root=docs

- Karsten

----- Original Message ----- From: "Karsten Wade" kwade@redhat.com To: fedora-docs-list@redhat.com Sent: Wednesday, March 25, 2009 7:01 PM Subject: Re: Proposal for Implementing a Docbook Editor

...

http://docs.fedoraproject.org/documentation-guide/en_US/

That document is unmaintained and almost criminally out of date.

Does it make sense to let it stay out of date until we sort how we are actually going to move forward with Publican (if that is possible) and Zikula?

--McD

On Wed, Mar 25, 2009 at 04:01:09PM -0700, Karsten Wade wrote:

On Wed, Mar 25, 2009 at 02:14:30AM +0530, satya komaragiri wrote:

...

documentation process in Fedora and the Documentation guide [1] pointed me to CVS.

...

[1] Documentation Guide: http://docs.fedoraproject.org/documentation-guide/en_US/

That document is unmaintained and almost criminally out of date.

Anyone interested in taking it over and updating it? We could start a new project on fedorahosted.org for it.

I've been meaning to make a git repo out of this for a while. I'm doing that now, and will request it as a hosted project.

Hello,

On Wed, Mar 25, 2009 at 10:31 AM, Sankarshan Mukhopadhyay sankarshan.mukhopadhyay@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.

The functionality is very limited as yet, but it will serve to provide an idea of what to expect.

Regards, Satya

Hello,

I have narrowed down to the following set of tags as the minimum that Docbook editor will need to support for the initial stages of the project. It would be great if the list could review them once and suggest any additions/deletions.

tags:

Top Level: <article id="ID"> </article>

Section: <section id="ID"> <title></title> </section>

Block Tags: <para></para> <screen></screen>

<itemizedlist> <listitem> <para></para> </listitem> </itemizedlist>

<orderedlist> <listitem> <para></para> </listitem> <orderedlist>

<procedure> <step> <para> </para> </step> </procedure>

<important>

<title></title> <para></para> </important>

<tip> <title></title> <para></para> </tip>

<note> <title></title> <para></para> </note>

<warning> <title></title> <para></para> </warning>

<caution> <title></title> <para></para>

</caution>

Inline:

<firstterm></firstterm> <application></application>

<command> <option></option>

</command>

<package></package> <filename></filename> <systemitem></systemitem> <computeroutput></computeroutput> <userinput></userinput>

<prompt></prompt>

<menuchoice> <guimenu></guimenu> <guisubmenu></guisubmenu> <guimenuitem></guimenuitem> </menuchoice>

<guibutton></guibutton> <guiicon></guiicon> <guilabel></guilabel>

<mousebutton></mousebutton>

<keycombo> <keycap></keycap> </keycombo>

<abbrev></abbrev> <acronym></acronym> <emphasis></emphasis>

<quote></quote>

<link></link>

<subscript></subscript> <superscript></superscript>

<action>

<classname> <constant>

<errorcode></errorcode> <errorname></errorname> <errortype></errortype>

<function></function> <interface></interface> <parameter></parameter> <property></property> <replaceable></replaceable> <returnvalue></returnvalue> <structfield><structfield> <structname></structname> <symbol></symbol> <token></token> <type></type> <varname></varname>

Regards, Satya

Hi,

On Wed, May 20, 2009 at 10:26 PM, Paul W. Frields stickster@gmail.com wrote:

[...snip...]

...

<systemitem></systemitem>

Are you planning on implementing support for the @class attribute?  I use that a lot, and it appears in Fedora Doc

Also, I think we tend to use <indexterm> and its indexing-specific children too.  But if those significantly increase the difficulty, they could be pushed off.  These are just suggestions and not requirements. :-)

I saw the class attribute being used in quite a few places. But i haven't yet figured how to implement it and <indexitem> in a wysiwyg interface. How will they be specified, written, edited, etc.

Indexitem can be implemented with a button (say Add to Index) which will index some word/phrase which is selected/highlighted.

Class has a lot of variations for different tags so I need to think of a 'user-friendly' way to implement it. Perhaps when the user clicks the button for filename, I could give the user some kind of a drop down menu which enumerates the type (devicefile, directory, etc, as listed at http://docbook.org/tdg/en/html/filename.html). I'll try to figure out these details soon and get these two in.

Thanks for the feedback. I'll try and implement all the important bits suggested here. :)

Regards, Satya

On Wed, May 20, 2009 at 9:47 PM, satya komaragiri satya.komaragiri@gmail.com wrote:

I have narrowed down to the following set of tags as the minimum that Docbook editor will need to support for the initial stages of the project. It would be great if the list could review them once and suggest any additions/deletions.

Might I suggest putting up the proposed list on the wiki (allowing more additions by those who use DocBook often) or, as a file on your fedorapeople.org $home (and, accepting additions as patches).

Concur on the wiki and on the additions, and kudos for your work on this. What is your deadline for feedback on tags? A number of us in the Evergreen project just committed to moving forward with DocBook but we're all at a user conference this week.

2009/5/21 Karen Schneider kgs@esilibrary.com:

Concur on the wiki and on the additions, and kudos for your work on this. What is your deadline for feedback on tags? A number of us in the Evergreen project just committed to moving forward with DocBook but we're all at a user conference this week.

It's not a deadline that Satya is under. Rather, GSoC starts coding this weekend, and the more information she has upfront, the better she can focus her priorities. This means, the better her priorities are set up, the more useful Beacon will be to us right away.

-Yaakov

Hi Jeff,

On Mon, Mar 23, 2009 at 5:53 AM, Jeff Fearn jfearn@redhat.com wrote:

Have you considered?

Web based access to eclipse editor:

http://www.alphaworks.ibm.com/tech/eclifox

Visual DocBook editor for eclipse:

http://in.relation.to/Bloggers/HowToCreateAVisualDocBookEditorIn10Minutes

Combine the two:

<insert summer of code project here>

Ew java, I feel dirty ... but someone had to ask :(

Cheers, Jeff.

Thanks for the links. I did not see them before. But I still feel using PHP or python will be better and will ensure portability. Moreover, Beacon can be integrated more easily in any page and no extra setup is required. And also, some people won't feel dirty while using it ;)

Regards, Satya

Hello Chris,

On Mon, Mar 23, 2009 at 11:37 AM, Christopher Curran ccurran@redhat.com wrote:

I say good luck to you, Satya.

No, seriously, I hope you are successful.

Thanks a lot :)

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.

Yes, we'll keep that in mind. All we are doing is transforming the XML to HTML using XSLT and the HTML format will just be suiting our needs so we can use it in the editor. The output XML will be standard without any unwanted changes.

• 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.

That is the agenda. We do plan to go the HTML/CSS way (Beacon already does that). Tables will be included only if the content writer himself/herself wants the Docbook XML to contain a table.

• 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 :)

Thanks, we might need to modify the XSLs a bit to suit our requirements but we won't be re-inventing the wheels.

Good luck, Chris

Regards, Satya

On Mon, Mar 23, 2009 at 04:07:43PM +1000, Christopher Curran wrote:

• 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.

It would be reasonable to start with a specific subset of tags, right? We could even do a minimized DTD, if that helps.

A few minutes work on the current set of documentation will tell us which tags are currently used. For example, I've never seen any of the OO programming tags (<methodname>, etc.) used in Fedora Docs.

We don't have to limit the tagset forever, but it would give a smaller scope for the early/first iterations, and it would follow the rule suggested above about spec extension.

- Karsten