Slashdot Mirror

You are trying to reinvent docbook. Not only is everything you want done, it is implemented in several tools (XMLMind and oXygen are two I know of), has a standard method of converting it to any form you want (XSL, XSLT, XSL-FO), and there are tools that are already written to take advantage of those standards (Apache FOP being a FLOSS one). The latest version of DocBook uses XML namespaces, so you can mix in other markup languages as well; the canonical example is DocBook + MathML + SVG, which covers 99.9% of the math/science based literature out there. BTW, if you DO plan on going down this path, I suggest picking up a copy of XSLT, 2nd edition by Doug Tidwell. The latest version of the DocBook book is supposed to be out in August; don't buy the version currently on sale, it is 10 years old, and does NOT cover the current version of DocBook.

XMLMind has a nice gui editor for DocBook xml: http://www.xmlmind.com/xmleditor/. There's a free version if used for open source projects.

XMLMind is not too bad

Writing my doctoral dissertation in Word back in 2003 was a repeated lesson in pain

Wow, I feel your pain. After Word couldn't reliably handle a small 100-page thesis I wrote, I switched to Mellel for the rest of my time as a student. Highly recommended. Does everthing a dissertation needs, is easy to use, looks nice, and is fast.

XMLMind + DocBook might also be a good option.

But please, whatever you do, avoid Word at all cost. It's just not suitable for this kind of writing.

There are actually quite a few Java apps that are important to many Mac users. Obviously, if you're running Mac OS X Server, you might want to run stuff like Apache Tomcat. User-level Java Mac apps include stuff like XML mind, which is widely used to write docbook documents. It's also kind of interesting that some Java apps running on Macs try to hide the fact that they're Java apps, because many Mac users have an irrational hatred of Java (probabbly due to the incredibly bad performance and looks of early Swing apps).

MacUpdate lists Java-based teaching apps, CAD Software, Microscope Image viewers, Magic card databases, iTunes helpers and a ton of games.

I'd say a huge number of Mac users have at least one or two Java apps on their Mac, probably without even realizing the apps are written in Java.

XMLMind ships a sorta wysiwyg DocBook editor: http://www.xmlmind.com/xmleditor/

If you like wrassling with the tags, jEdit is GPL and quite usable, IMO. If you're an Emacs-head, nxml-mode (http://thaiopensource.com/download) is probably what you want.

If you don't mind forking out a /little/ bit, like working with tags, and work for an educational institution, (http://www.oxygenxml.com) might
well be for you. Features up the wazoo, and connects to all sorts of different things.

The recent DocBook XSLT bundles do ship something that purports to almost round-trip simple "Word ML"; I don't suppose there's been enough interest in working on OpenOffice's DocBook filters, but they do exist.

I have been trying to get my team to use XmlMind Editor ( http://www.xmlmind.com/xmleditor/ ). It is a JAVA app, and they have a Mac DMG file for installation.

XML was never built to be written by hand, or to be read with the human eye.

What we do need is a good (ideally open source) XML editor that's as natural and intuitive to use as Notepad (or more ideally Textpad) is to edit text files.

Then again I'm an old bastard (30) who wants to edit everything by hand no matter what.

I'm using XMLMind's XML Editor. I just took over the tldp.org's Enterprise Java on Linux Howto and I didn't have any experience with docbook and it's been fairly easy with XMLMind. It's sort of a WYSIWYG editor for docbook and it will do transformation to html. There is a free version but if you buy it then you get webdav support. I was going to buy it since I like the free version so much but it's a little pricey for me but since we're comparing it to Office here...Oh, and it's Java based so it'll run anywhere.

XMLMind works with WebDAV and is great for DocBook. We use it for all of our documentation.

The problem with docbook isn't the complexity of the markup, but the lack of decent editors. I hate markup languages. They always manage to grow larger than the set of markups you can store in your memory for occasional use.

If I'm concentrated on developing in language X and architecture Y using technologies Q,R and T. I don't want to also have to juggle around markup language Z in order to properly document the project.

My advice would be to use XMLMind to write Docbook. It's much like Lyx in that it's a WYSIWYM editor, but it was written from the ground up to do Docbook XML. It's also not Open Source, but the basic version that handles Docbook well is freely available from the author's site.

It helps to have some knowledge of Docbook to use XMLMind, but it takes most of the work away. You can save and convert the output using the standard docbook tools that come with most Linux distros. It's not a silver bullet to this particular problem, but it sure does help a lot.

Forrest and XMLMind

from XMLMind (free/beer). They also have a very nice FOP->RTF converter (works ten times better than JFOR). Then again, I speak from document writing poitn of view, hence YMMV...

• Arbortext Epic Editor
• SoftQuad XMetal or Corel XMetal
• EpcEdit XML/SGML Editor
• Altova Authentic
• XmlMind XML Editor (Standard version is free)
• Morphon XML Editor
• TimeLux XPress
• GenDoc (open source, could be nice if someone wrote a docbook plugin)
• Conglomerate (open source project which seems to be resurrected, nothing available now though)
• ExcoSoft XML Client (as far as I can tell from the website...)
• SoftMagic SendStory
• 
  Anyone has experience with these? (or others that are missing from the list).

I also looked at ArborText and FrameMaker. They claimed to support DocBook, but they supply config files only for (much) older DocBook versions. I found the out-of-the-box support for docBook to be sorely lacking. It looked like it was possible to configure them for better support, but it would have taken many hours to do so.

XML Spy and XMetaL looked pretty good. I don't remember how well they did with DocBook, but they are geared more for data-oriented XML, whereas Morphon and XXE are more suited for document-oriented XML, such as DocBook.

Essentially your choices are Adobe Framemaker (~$800), Lyx (Open Source) and XMLmind (Freeware). There may be some others, but these are the ones I've looked at. These are the ones you can use like a WYSIWYG, but are more WYSIWYM (What you see is what you mean). For more info on WYSIWYM, look at Lyx's site.

DocBook is a great spec, but the editors suck for the most part. Lyx can't import DocBook in reliably, and your Docbook is stored as a lyx file (latex I think). Lyx's Docbook stuff can be a bear to set up, even on a system like RedHat where most of the software comes installed. I only recommend Lyx to people who have experience with Lyx, to someone who just wants to write docs, it tends to be more trouble than it's worth.

Framemaker will probably do everything you want and be a godsend with lots of nice features, but you'll pay for it, $800 for Win/Mac and ~$1300 for Unix.

XMLmind is pretty cool, it does Docbook well but is a little slow, it has a little bit of a learning curve, but is prolly the best Docbook editor I've found for free. It's not Open Source though. It is written in Java, so you might have some speed issues, depending on the platform you run it on. I've been recommending XMLmind to everyone I know that asks about Docbook, it has a tree view of the DOM as well as a WYSIWYM view with stylesheets applied on the fly. It has property editors and a pretty smart insert tool that follows the DTD, only allowing you to insert allowed tags into other tags. It feels like more of a programmer's tool than Framemaker, but it should be fairly easy for most WYSIWYG users to adjust.

<rant>
I don't understand why on God's green earth OpenOffice or Abiword or KOffice, or anyone else in the OpenSource world has neglected this area. It's been three years since the LDP went to DocBook, GNOME uses DocBook as their doc format. Why in the hell don't we have decent document writing tools when everyone is always screaming about the lack of documentation in the OpenSource world?

If we want more docs written, it needs to be easier to write them and shouldn't involve learning all about SGML or XML engines as well as a markup language to do it. DocBook is too big to keep in my head and I shouldn't have to think hard about how to write docs when my focus is the content I want to write for. Organizing technical info on a difficult subject is hard enough, stopping every five minutes to look up a DocBook tag or trying to better understand the structure is a huge barrier to getting the work done.
</rant>

But that's just my $.02

Forget about how do you build the repository -- that's easy. (Well, okay, non-trivial, but with databases, cvs, and even just simple shared folders, storing the docs is the least of your worries).

I still maintain that the biggest hurdle in any standardized document system (especially if you include multiple concurrent authors) is the front-end editor. I wrote a simple (and highly buggy, I'll admidt, so you who know me keep your traps shut!) VB application that provided a multi-user front end to a database. The back-end (PHP) pulled all the appropriate rows for any given doc together and mashed it into a nice, navigable HTML document. I even had PDF support at one time (but it was even flakier than the GUI).

However, it was not XML, so it was REALLY limited in how easy it was to create new views on the data. The biggest problem I ran into was trying to find a good GUI editor -- this thing was written for security engineers, not HTML experts, and I wanted them to concentrate on content, not tags. I eventually settled (and settled is the right word) on the Microsoft DHTML control. Worked well enough for the time (two years ago at this point), but I still think half my problems stemmed from that widget, or bad interface programming to it. The advantage? WYSIWYG (more or less) editing. Seamless multi-user editing of the same document (well, okay, we had some record locking issues. :) ) But again, the long pole of the tent was the editor widget.

Since then, I've wanted very much to rewrite the thing to handle full XML, and I understand there's an effort underway to do just that (I've since moved to different pastures), but it's slow going. I've looked at current technology (ABIword, for example), and i'm just not convinced that it's going to be easy to get a good semi-WYSIWYG XML editor going. At least not on the cheap.

Some time ago was posted here an app called Conglomorate, which I still think has about the best approach to visually representing an XML document. But it hasn't been updated in forever, and was slow/buggy the one time I played with it. More recently, the XMLmind XML Editor (XXE) has shown a lot of promise, even including CSS files for editing DocBook XML. They even have source available. Again, goes a long way to letting you edit diverse XML files in a logical way -- not by forcing you to look at ugly tree-views of an XML file, like so many first-generation editors. Finally, the latest XML Spy editor beta goes a bit father even than XXE, using a full XSLT transform to provide a WYSIWYG format for XML files. Theoretically, with this, you should be able to display any of your documents in whichever approach you like -- full WYSIWYG, tables, trees, block labels, whatever.

Of course, neither of these latter tools work in a concurrent editing fashion. But that's a "minor" enhancement -- put together a robust DB back end, allow for good record locking, editor-to-editor communications for lock management, transaction log to allow back-out of changes, etc. Lots of possibilities. Take XXE, put this kind of capability on the back-end, an integrated login and document management system, and you've got a kick-ass document solution. Work the backend to allow for multi-stage review and publishing, and provide output engines for HTML, PDF, WAP, whatever, serve different subtrees of the system to, say, internal project web servers, external web servers, sales and marketing (for glossies), etc., and everyone can manage everything, real-time, GUI, with one tool.

But I dream.

(seriously -- if anyone's really working this, I'd love to help. I just wanna use it at home for my own web pages.)