5

On windows CHM is a very good option.

Is there anything other then delivering a static set of HTML pages and using a primitive call to a webbrowser (which is even a problem itself on linux). And it would not offer any kind of fulltext searching, separated bookmarks and even the simple fact of not opening a new tab for each help call.

gpoo
  • 8,408
  • 3
  • 38
  • 53
Lothar
  • 12,537
  • 6
  • 72
  • 121

4 Answers4

3

I'd still recommend static HTML as the best option (and of course man pages!). For example you can use Sphinx to write beautiful documentation with a full-text search support!

Zaur Nasibov
  • 22,280
  • 12
  • 56
  • 83
  • 1
    Such documentation tools are a dime a dozen. Most of them are more suitable to SDK docs than application help though. I prefer latex with a tex4ht and some minor DOM based postprocessing. But for me PDF is the main target format. – Marco van de Voort Dec 28 '12 at 21:37
  • 1
    That's true. But I find Sphinx very convenient for writing application documentation as well, thanks to the reStructured Text format. Moreover Sphinx has LaTeX, PDF, Man pages, CHM, ePub and many more builders beside the HTML document builder. – Zaur Nasibov Dec 28 '12 at 21:47
  • I'm looking for a solution for an application manual. While I like reStructed Text i have a lot more requirements. Like conditional compilation. we produce documentation for different products from one 80% common source base. We have our home made XML processor, so the question is just about delivery. – Lothar Dec 29 '12 at 20:48
3

The Gnome yelp program is what is used for GTK/Gnome applications. It supports a number of formats, but not CHM directly. They have started to define their own markup, named Mallard. But I don't know what is the status of that.

Keith
  • 42,110
  • 11
  • 57
  • 76
1

There are CHM viewers available on Linux though frankly as a Linux user I'd prefer to get static HTML pages.

Some examples are chmsee and kchmviewer.

Benny Hill
  • 6,191
  • 4
  • 39
  • 59
1

Afaik there is no universal system. Depending on your desktop system (gnome/kde) there might be helpsystems, but they are usually based on loose files and use full-blown browsers. (usually webkit based)

For Lazarus a CHM based helpsystem and embedded browser was created, including CHM write support.

The reasons to avoid loose static html were mostly:

  1. the 60000 lemma static documentation took too long to install on lighter systems or systems with specialist filesystems.
  2. CHM removes slack and adds compression.
  3. we also support non posix and OS X systems, and little filesystem related problems (charsets/encoding, separators, path depth etc) and case insenstive filesystems on *nix caused a lot of grief. The CHM based help solved that, allowing for one set of routines to access helpdata on all systems.
  4. indexing and toc are Btree based, and can be easily merged runtime from independently produced help sets. In general integrating independently produced helpfiles is a underappreciated aspect of helpfiles in general, while key to open platforms.
  5. native fulltext search.

An own viewer also has the ability to take advantage of extra features on top of the base system.

I'm not mentioning the Lazarus system in the hope you adapt it, since it is at the moment too much a development system (SDK) oriented system, the viewer is not even available as a separate package. I mainly mention it to illustrate the problems of loose html.

I haven't investigate KDE/Gnome/Eclipse what they use as helpsystem for a while though. If I would have to restart from scratch, that's where I would look first.

If I had to create something myself quickly, I would use zipped static html, and a single gziped file with metadata/indexes and the lightest browser (Konquerer?) I could find. Not ideal, not like Windows, but apparently the best Linux can offer.

Marco van de Voort
  • 25,628
  • 5
  • 56
  • 89