We need to compile to QtHelp (.qch and .qhc). I'm wondering what tool/toolchain would be easiest for this? We'd like a WYSIWYG help authoring tool as our starting point, then run the output from that through whatever we have to to get QtHelp.
We have used Help & Manual in the past, and that's the kind of WYSIWYG interface we're looking for in a help authoring tool. But we need the toolchain to produce simple html pages (one per help topic) that we can use with qhelpgenerator or qcollectiongenerator, as well as create the .qhp's (at least the table of contents and the keywords sections) and .qhcp to generate the .qch's and .qhc. I'm not seeing how Help & Manual can fit into this.
We've looked briefly at Sphynx, but it seems it has extremely limited options for text formatting. For example, it doesn't look like there's any way to change the font, font size, font color, etc. for a section of text. It appears to be actually impossible to have text that is both bold and italic. Looks great for developer documentation, but seems to be missing basic stuff for authoring a user help file. Please correct me if I somehow missed the basic text formatting features!
So, what WYSIWYG help authoring tool do you recommend, and what is the path from that tool to .qch's and a .qhc?
Looks like Help and Manual will work after all! Here's the sequence we're looking at now. If please comment if you see any problems or improvements that can be made.
In Help & Manual (tested with version 5.5.1 Build 1296 professional license), in the Project Explorer, in the Configuration section:
Go HTML Page Templates\Default. In the HTML Source Code tab, comment out the section.
Go to Publishing Options\Web Help.
In Layout, select No frames, no scripts.
In Navigation, we don't need anything checked - although if there is a way to control the format of the value of KEYWORD_INDEX so we could copy and paste directly into our .qhp, that would be great! I haven't found a way to do that, so we plan to maintain keywords directly in the .qhp.
Similarly, Table of Contents is also irrelevant, unless we can control the format we'll have to maintain the toc directly in the .qhp.
In Popup Topics, we are set to HTML encoded topics. Not sure if this is necessary.
That's all the settings we have to change. Create help content in H&M as normal, then to publish Webhelp. This creates a separate .htm file for each topic.
In the same folder as the .htm's, we create our .qhp and .qhcp files, and run qcollectiongenerator to produce our .qhc, which we then display with Qt Assistant. See http://doc.qt.nokia.com/4.7/qthelp-framework.html for help with the Qt side of this toolchain.
Again, it would be great if we could find a way to set up H&M to create the toc and the keywords in the format required for the .qhp and we could just paste them into the .qhp (or for that matter, maintain the .qhp in that template also). Another option would be to write a script to convert from what H&M creates for toc and keywords to what the .qhp requires. If you do that and don't mind sharing, please post the code!
Some benefits we find using H&M to solve this problem:
Again, if anyone has a better solution or improvements to this one, please post!