RE: 'WebHelp' from from DocBook: Browsers and operating systems;translation of UI; performance; authoring of DocBook files

["Cramer, David W (David)" <dcramer@motive.com>]

Hi Christian,

I’m posting this to the docbook-apps mailing list so we can continue the thread there since your questions pertain to DocBook generally. Also, other members of the community might have things to contribute.

 

Yes,  you can produce WebHelp from simplified DocBook. WebHelp is based on the DocBook xslts which handle the full DocBook DTD/schema. Simplified DocBook is limited to a subset of the DocBook elements but has all the constructs you would need to write a document you wish to transform into WebHelp.

 

Currently, the DocBook xslts can handle most versions of DocBook certainly back to 4.4. I don’t know how far back though. If you’re starting a new project, then go with 5.0 and find an editor that understands RelaxNG schemas. If you end up needing to customize the schema, RelaxNG is a joy to work with compared to DTDs. There’s a transition guide [1] with some information about DocBook 4.x v. 5.x

 

I’ve worked some with MoinMoin’s DocBook support and gotten it to  work. Mostly we did small pages (e.g. release notes) without much hyperlinking. I believe it worked if you included several other pages into a wrapper page and converted the wrapper to DocBook. MoinMoin is written in Python so if that’s a language you like, you can probably make it do what you want. In general I think a wiki2docbook solution is an ok idea for light documentation needs, such as release notes, whitepapers, and such, but if you plan to do anything sophisticated, then a wiki as authoring tool may not be the right choice. Wikis are good at making easy things easy. DocBook/XML has the semantic richness to make hard things possible. The lightweight markup of a wiki inherently limits what you can do on the DocBook/XML side.

 

David

 

[1] http://www.docbook.org/docs/howto/

 

 

Simplified DocBook

I have found out that tools which generate DocBook files out of other formats (e.g. OpenOffice, moinmoin wiki, mediaWiki) often use "Simplified DocBook" instead of DocBook. One of its biggest limitations seems to be: "This subset for single documents (articles, white papers, etc.), so there's no need for books or sets, just 'articles'."

Would DocBook still be a usable input for WebHelp, i.e. would all the features of WebHelp be available?

 

DocBook Versions

I have also found out that tools which generate DocBook files out of other formats generate DocBook files in a variety of versions, e.g. 4.4, 4.5, 5.0. Are documents in all of those versions a usable input for WebHelp, i.e. would all the features of WebHelp be available when using any of those versions?

 

moinmoin wiki (or other wikis)

Have you got any experience with exporting several linked wiki pages (starting from one 'landing' page, then all other pages by traversing all links from that page recursively) from moinmoin wiki (or other wiki) into DocBook and using that as an input for WebHelp?

If so, were the page nesting/traversing structure, links and images preserved? We are currently using mediaWiki and in my experiments with tools for creating DocBook files out of it those were the things that didn't work!