Comments on: Evolution doc issues

By: Andre Klapper

Andre Klapper — Thu, 13 Dec 2007 18:46:43 +0000

čau matĕj,
there seems to be will to move away from framemaker, but emacs is just not an option for these writers. so the question is “what to use instead of framemaker?”, and that is what this blog entry is about imo.

By: Jeff

Jeff — Thu, 13 Dec 2007 18:00:17 +0000

Matej: Lets keep it civil.

It’s obvious to anyone that Srini is genuinely trying to find a solution that makes everyone happy. He clearly does not want Evolution doc contributors to have to spend $900 for doc-editing tools, that accusation is just rediculous.

As far as hand-editing large xml files, you have to be kidding. Anyone who has tried such a thing can tell you that such a suggestions is insane for a number of reasons, of which these are just a few:

1. xml, while “humanly readable”, does not offer itself well to WYSIWYG and so is not efficient for writing docs. If it were, we wouldn’t have word processors.

2. You need to remember the rules for encoding xml CDATA/property values and know the conversions by memory. This is just too much effort and very prone to error.

3. No spell-checking facility which is quite handy

As far as Olafur’s suggestion of Conglomerate – I have no experience with the tool, but from the website (http://www.conglomerate.org), it seems a far better solution than hand-editing.

I might start using it for my own projects

Thanks, Olafur.

By: sragavan

sragavan — Thu, 13 Dec 2007 14:41:31 +0000

Matěj,
Btw, I did’t complain of any thing. I know of docbook/xml. Frame also generates it. Which is what the doc team here uses and I was discussing the workflow issue that we are facing and asking for suggestion . May be you need to read my tone to know if I’m open for a solution or not. I understand the size of doc is smaller than the source code itself. I was wondering if a tool (Be it Open sourced or proprietary) can do it, why would one hand write everything. I’m asking for suggestions on how other projects do it. If hand-editing seems to be the best/easy solution, I think then we have to do that. (Note: I’m just a coder and I’m speaking on behalf my doc person)

By: Olafur Arason

Olafur Arason — Thu, 13 Dec 2007 10:42:43 +0000

Conglomerate works pretty well, at least on gedit help documents. But it crashes on the evolution ones.
It’s open source so it’s possible to fix it.
it’s integrated with gnome so that’s a plus.
And it does everything one needs from that kind of editor.

By: Matěj

Matěj — Thu, 13 Dec 2007 10:18:02 +0000

Let me try to recapitulate what you said — you are maintaining your documentation in the obsolete (on Linux — http://www.adobe.com/products/framemaker/systemreqs.html) proprietary and pretty expensive system (the current non-Linux version is for almost $900) and you complain that nobody is willing to help you with the maintenance?

And to your question how other projects are doing this — let me see: KDE uses Docbook (http://developer.kde.org/documentation/), Gnome uses Docbook (http://live.gnome.org/DocumentationProject/Join), Linux kernel uses Docbook, Eclipse uses Docbook (their website is so messy, that I cannot find the proper URL. Are you so ignorant that you have to ask, or you just don’t want to hear the answer?

Emacs nxml-mode is pretty good for writing XML and every other tool on the planet (free or non-free — both in terms of license and money) can edit Docbook XML.

And concerning the size of documentation and its maintenance by hand. Could you compare the size of Evolution documentation with the size of its source code? Do you need some proprietary non-sense for genrating that? Or do you really still “just hand edit” the source files? Is “just” text editor and svn enough? OK, so why it shouldn’t be enough for your documentation?