Andre posted a mail on the hackers list about the state of Evolution docs. The doc team here at Novell uses FrameMaker to manage documentation. So the master copy that we use is frame files which can only be exported to XML and no way to import/sync from xml. So any commits that happen for the XML file on the svn needs to be manually synced. At times, some patches are XML fixes which are auto-generated by FrameMaker. In which cases, the commit from Frame files to svn would overwrite them. This is a big issue. One solution that came our is hand editing XML files for documentation. Definitely hand editing the files isn’t going to be easy (it is 8K lines file with almost 1K modification every release). It can be more prone to errors than now. I really want to know how other projects over come this?. Are there any other tools or process other projects use? Or just hand edit XML files? Any better suggestions to me? I would be happy to hear any suggestions/processes that already other projects use.
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?
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.
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)
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.
č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. 🙂