AUG
26
2005

Using Quanta as a Docbook Editor

Quanta is widely recognized as the
most advanced free software web development environment. But a lot of people do
not know that Quanta is a friendly editor for all SGML and XML documents (and
therefore for docbook).

Writing documentation is a great way to start contributing to KDE. While the
KDE documentation team gladly accepts
contributions plain text, the format used for writing the applications
manuals is called
docbook.
Docbook is a format based on tags, which describe the format and specifications
of the document.

If you want to learn about docbook, or don't know how to start, the

KDE Documentation
Primer
was created to guide new writers, and offers information such as
what to write about,
English usage
guidelines
, how to get
the documentation sources
, a docbook
introduction
, a docbook reference
guide
and more. And if you need any assistence while getting up to speed as a new KDE contributor, don't hesitate to ask your questions in the kde-quality mailing list.

If you want get your documentation contribution inside the upcoming KDE 3.5 release, act now, as the Message Freeze starts on September 5th.

Comments

I forgot to add the link to the actual article...

http://quanta.kdewebdev.org/tutorials/quanta-docbook/quanta.html

Or better yet, add this link to the:

"Quanta is a friendly editor for all SGML and XML documents" part of the headline.

Sorry... :)


By Carlos Leonhard... at Thu, 2005/08/25 - 5:00am

done ..


By Fab at Thu, 2005/08/25 - 5:00am

I can't begin to express my appreciation for Carlos' work here, as well as his support of our project. It has been my dream for some time that Quanta would be a useful tool for documentation and he has almost single handedly advanced this.

It's also worth mentioning that custom dialogs for Docbook are constructed with Kommander. This means not only that they can be enhanced or modified by users, but that it's easy to extend Quanta with visual tools to enable it to do what you want, and easy to share those tools. Many people may not realize that almost all of what it took to develop this support was done visually within Quanta/Kommander or editing XML files.

Most of all I want to thank Carlos for his great contribution to KDE and our project. Many people feel it is too difficult to contribute either time or money to an open source project. Not Carlos! I know the demands Carlos has on his time and he is one of the people I admire most in KDE. Thanks Carlos!


By Eric Laffoon at Thu, 2005/08/25 - 5:00am

Quanta is a great tool. Thanks!

My problem with KDE documentation is the lack of unification in structure and style. Probably a docbook template for quanta would improve this.


By Bertram at Fri, 2005/08/26 - 5:00am

The KDE Documentation primer tries to address this in the "what to cover" section. But in the end, it is up to the documenter to follow it. I think that KDE documentation is picking up, really. So maybe, in the future, we would be able to review all the docs to check for some kind of guidelines conformance. But at the moment, if the doc is good, (independent of the structure), it is probably a big improvement.


By Carlos Leonhard... at Fri, 2005/08/26 - 5:00am

One of our goals for Quanta has been the visual creation of XML docs using CSS or XSLT. Initially we thought CSS might already work, but I haven't seen that yet. XSLT would be the coolest. There are XSL files to make HTML docs from KDE Docbook and they look pretty much like the final results in the help browser. So you could identify your XSL file and then create docs with templates and toolbars similar to a word processing feel.

This type of functionality will very likely be in Quanta 4.0. The enhancements with Webcore and the work Frans Englich is doing with KDOM will mean that we should be able to do this without having to write most of the code needed. In my opinion what has been needed is a visual document creation tool. Yes, programmers can easily understand C++ and XML is not too hard for the average user... But in both cases this is some effort required. In the visual creation mode it is possible not only to instantly see the result of an edit, but it will also rigidly enforce the DTD.

Not to diminish what Carlos has done, because I think his work means there will be more and better documentation in KDE now, but I think when KDE 4 arrives there will be no excuse not to have documentation being generated by someone invloved with a project. I hope this gets more users involved.


By Eric Laffoon at Fri, 2005/08/26 - 5:00am

Isn't there also a K-XML-Tool?

Why do it with Quanta?


By Masert at Sat, 2005/08/27 - 5:00am

Why not?


By Andras Mantia at Sat, 2005/08/27 - 5:00am

There is KMXL editor, which can also operate as a plugin within Quanta. It breaks everything into nodes you can view, but it doesn't seem to particulary flow. Last I checked it also didn't do structural DTD based validation, custom editing toolbars, templates, entities and auto completion among other things. For working with relatively static files it is a nice tool with a tree mode, although Quanta does have a structure tree too. There is also Syntext Serena which can visually work with XSLT, but it's a commercial tool with a license cost to use it for any purpose. Kate can also be used with much of the functionality of Quanta but Quanta adds the toolbars and dialogs and can also use Kate's custom plugins.

So the answer to your question is that Quanta, with the docbook editing tools, is the most specialized tool to ease development on KDE, unless of course you want to buy a commercial visual tool. BTW Quanta will be competitive with that tool in KDE 4.

I would also like to say that if you're saying "Quanta is an HTML editor so why use it for Docbook" then I would say that is flat wrong. Quanta is not an HTML editor. It's an SGML/XML editor. It just has the most support packages for HTML, but even HTML isn't HTML any more. It's XHTML, XML, PHP and a lot of other things. Because people may think of Quanta as an HTML editor, like for instance NVU, we need to bring to their attention that it is designed with a broader scope. If we had made an HTML editor in the 3x series we would have been engineering future obsolescence.

So there is a reason to use Quanta for Docbook as well as a reason to make people aware that it has advantages.


By Eric Laffoon at Sun, 2005/08/28 - 5:00am

> and he has almost single handedly advanced this.

This is not true. Andras did most of the work. I just tested it, create the docbooks toobars, the doc primer package, and bugged him a lot :)


By Carlos Leonhard... at Mon, 2005/08/29 - 5:00am

> This is not true. Andras did most of the work. I just tested it, create the docbooks toobars, the doc primer package, and bugged him a lot :)

Just like I said... Andras is so awesome a coder you just get him music with a faster beat for more code... But you came along and aimed the steamroller of code and then did a nice job of putting the finishing touches on the work. In my experience it is the finishing touches that take disproportionally more attention for the amount of work. I'm pretty happy both of you took something we were close to and made it real.


By Eric Laffoon at Mon, 2005/08/29 - 5:00am

Carlos, can you point out translation/localization resources in this respect? AFAIK Docbook has issue with RTL languages (Hebrew, Arabic, etc.)..., though I never really used it.


By Uri Sharf at Fri, 2005/08/26 - 5:00am

I have been using Quanta for years. The entire contents of my Linux Tutorial (www.linux-tutorial.info) is written using Quanta. All the articles I write are done using Quanta. The two applications that are *always* open are Kmail and Quanta. Eric, we all owe you a debt of thanks.


By Jim Mohr at Sat, 2005/08/27 - 5:00am

> Eric, we all owe you a debt of thanks.

Speaking of which... You were the first person to send me a check. I had recently sponsored Andras and discontinued *every* personal expense that wasn't absolutely essential at the time. I mean how many people in the US have to fiddle with rabbit ears to watch 5 channels of TV? I didn't know what to do with people wanting to send money. Thankfully I got myself satellite TV and Tivo for Christmas last year after 3 years, but I owe Andras money again. So thanks are welcome and the most cherished expression, but thanks with pictures of dead presidents keep Andras' electricity in his computer. ;-)

Anyone who wants to buy us dinner in Malaga I have a Paypal debit card...
http://kdewebdev.org/donate.php

BTW Jim also came all the way to the US from Germany, supposedly on vacation, but I suspect it was just to come harass me at the Portland Saturday Market. ;-) "Oh, you don't have a cat?" ... Uh-huh.


By Eric Laffoon at Sat, 2005/08/27 - 5:00am