Help authoring tools and output for Linux applications

In September 2003, I asked the technical writers' list and the help authors' list if there is any help authoring tool (HAT) that runs on Linux, to produce HTML-based help for a Linux or Web application. I said the help should be displayed in a browser, and the tool needs to have capabilities for ToC and index production and some project-management features.

Some suggestions involved Linux tools for creating Web pages, including Emacs, NEdit, asWedit, StarOffice, and OpenOffice. These tools didn't sound like quite what I'm looking for, because I don't think a help author could easily use them to create a ToC and index for the help.

Keith Borman of Qarbon.com, http://www.qarbon.com/, wrote: "We have a Linux tool that creates animated demos of how software works. The tool is called ViewletBuilder..." The website has links to a free trial download and numerous examples. Unfortunately, these examples took too long to download over my modem link, but if the viewlets were on a CD or available over a fast link, they might be very useful for tutorials and "show me" type help.

Someone pointed out some tools that can port CHM and HLP files to Linux. This doesn't meet the requirement for Linux-based authoring, but could be very helpful for someone authoring on Windows for multi-platform applications:
xCHM, http://xchm.sourceforge.net/
HelpExplorer, http://www.kamasoftware.com/helpexplorer.php

Eric Ray mentioned Helen, from http://www.software7.biz/, for creating JavaHelp for Linux.

Sean Wheller wrote a detailed response to my questions, in which he said, "There is no HAT for Linux, there is however XML... Most Open Source projects use DocBook XML as the standard document type for creating product and project support materials. This can be transformed into any format, including the Windows formats.

"Linux Desktops like KDE and GNOME have widgets that are used to provide access to help documents. For example if I am running SuSE with a KDE Desktop I will have the SuSE HelpCenter (on GNOME this tool is called ScrollKeeper). This is essentially a customized Konqueror Browser. Two panes, left Contents, Search and Glossary. Right, the text or pages selected.

"The outline includes a bunch of help documents arranged in a tree view. Project developers can choose to integrate their help with the Help Center or not. Some do and some don't. Mostly you will find Linux Documents and the Desktop (Application) Documents. Some may be HTML, others INFO, others MAN and yet others PDF...

"The reason why you do not see any HAT for Linux is primarily because of DocBook. While it may seem formidable, it is the standard for most OO projects.

"So on Linux, the HAT is actually an XML publishing tool chain. ... The model is simple. Store your content in DocBook XML or Simplified DocBook. Validate it. Input the XML document with an XSL style sheet to the processor and it compiles your help in the format supported by the XSL. So if you want chm, just input an xsl designed to output chm. If you want HTML,...

"For developers and writers, standards based Docbook is the best option. Remember that open source projects are developed by 100's sometimes 1000's of individuals... all these people may use different tools to author. So there must be a standard format that has no lock-in to a specific tool. ... Each [author] can use the XML Editor of their choice, without impacting me or you.

"I am happy to say that DocBook does go the whole round trip. The DTD is now very mature and is even moving to RelaxNG. An XSD has been around for some time. The DocBook XSLs are also strong, supporting JavaHelp, HTML, XHTML, HTML Help, MAN pages and FO for formats such as PS, RTF and PDF.

"The tool chain is actually very strong. Already we are seeing the implementation of standards such as XInclude. It does not however address the need for a RoboHelp equivalent that will reduce the learning curve that Windows based authors will have if they wish to use Linux as their development platform.

"If you're on Windows and a Word user you may try http://www.yawcpro.com/. It's not the ideal way to create DocBook, but it certainly will help you with the learning curve. Also look at the wiki for other free tools. http://docbook.org/wiki/moin.cgi/DocBookAuthoringTools "

Sean's comments, and the followup research I did on some of the tools he mentioned, tell me that while no easy-to-use, Linux-compatible, off-the-shelf help authoring tool exists, the tools for putting together an XML publishing chain are becoming available at reasonable prices; but it still sounds like anyone contemplating using them needs to spend a fair amount of time learning how and then setting up the system.

I'll be concentrating on using OpenOffice.org to create DocBook files, because the latest version (1.1) of OOo has an option to save as Simplified DocBook, which uses a limited set of DocBook tags, making it easier to use.

Typically the people I work with are small to medium sized businesses looking for "good, fast, cheap" solutions. Usually they settle for "fast and cheap" and plan to maintain their documentation in-house, no matter what anyone says. On Windows, I can point these people to various HATs and they can cope. On Linux? I don't know. I'm trying to find out.

Sean mentioned GNOME. More on the GNOME Help Browser is here: http://developer.gnome.org/doc/tutorials/helpsys.html

The other main GUI for Linux is KDE. For more on KDE in general, see http://www.kde.org/. While wandering around that site, I ran across this link, which looks to be worth some closer study: The KDE DocBook Authors Guide, http://opensource.bureau-cornavin.com/crash-course/

More links:
Emacs, http://www.gnu.org/software/emacs/emacs.html
NEdit, http://www.nedit.org/
OpenOffice.org, http://www.openoffice.org/
StarOffice, http://wwws.sun.com/software/star/staroffice/

There was a lot more to this discussion that I've summarised here. If you want to read the whole thread, go to http://www.raycomm.com/techwhirl/ and search the archives for the subject lines "Any HAT that runs on Linux?" and "Linux users' expectations of online help".

The discussion on Linux help-authoring tools spawned a related discussion on Linux users' expectations of online help, which I have summarised here: http://www.jeanweber.com/howto/linux-users.htm

---