Documentation without Qt Assistant
-
Hi
I've been reading about the documentation API that Qt provides, but it seems that it does not meet my needs.
We have an existing external documentation in html that is written by a person who does not have access to the source code.
We have introduced a documentation system where the user can rightclick on any widget and jump to the corresponding html page in the documentation.If I understand it correctly, this feature would be part of the Qt Documentation API if the documentation was in a qch format.
Extract from http://doc.qt.nokia.com/4.7-snapshot/qthelpproject.html:
"To enable the QHelpEngine to retrieve the proper documentation to a given link, every documentation set has to have a unique identifier."It is not clear to me, why the target of these links can only be in qch files. Is there a possibility to use the QHelpEngine with normal html files?
Are compiled help files not quite an old concept and nowadays, most documentation is simply a normal html file/folder?
Regards
Sacha
-
Qt provides lots of different tools for producing help systems:
If you like to keep your files as HTML files, you can use webkit to build your custom viewer. Obviously you have a need for a customized version. Otherwise you would be using firefox. The requirment you mentioned, clicking on an image to jump to another page is a standard browser feature however.
Assistant is a very powerful documentation viewer. You can compile html sources and the result is one file for easy distribution. You get an index and full text search. There are still companies running around selling tools like this for a fortune.
-
[quote author="Volker" date="1310376872"]
I don't know for sure, but I'm pretty sure the reason for the compiled format is a more than noticeable speedup.[/quote]I can imagine this is the case for larger projects, but for our documentation, the index and search functionality provided by the documentation tool we use is sufficient.
As our customers are not computer scientists, I think they would be confused that they have to use an additional piece of software.
The presentation of the help files in Qt Assistant is not so nice. When I need to read the Qt class reference, I rather use the browser than with Qt assistant.
[quote author="dialingo" date="1310378530"]
If you like to keep your files as HTML files, you can use webkit to build your custom viewer. Obviously you have a need for a customized version. Otherwise you would be using firefox. The requirment you mentioned, clicking on an image to jump to another page is a standard browser feature however.
[/quote]I don't quite understand what you mean by "build a custom viewer". Are you refering to displaying help directly in the UserInterface of the application? This is something I might want to do at a later stage, but for now I would like to automate the display of help upon rightclicks.
I'm fine with using firefox, but the functionality I use is right click on a UI element in my software (not on a website), I get a "Get Help" Context menu and upon clicking in that menu, Firefox opens with the apropriate documentation.
-
That seems to be a good feature. I will put a short description in this box and also provide a "read more" link that then jumps to the full documentation in the browser:
"If the text is rich text and the user clicks on a link, the widget also receives a QWhatsThisClickedEvent with the link's reference as QWhatsThisClickedEvent::href()." (from http://doc.qt.nokia.com/4.7-snapshot/qwhatsthis.html)
Thanks for your help
-
[quote author="sbaebler" date="1310380365"]
I'm fine with using firefox, but the functionality I use is right click on a UI element in my software (not on a website), I get a "Get Help" Context menu and upon clicking in that menu, Firefox opens with the apropriate documentation.
[/quote]Alternatively you could just open a modeless dialog containing a QWebView and load the HTML into that.
-
I'm currently working on the implementation of the documentation links. It is possible using the whatsThis or modal dialog, but I think the programming and documenting workflow could be improved much.
Rather than having to enable context help and write the text for every UI element that is added, context help should be available by default.
Developers tend to forget to add context help support and it can only be added by modifying the code. It would be better to have the context text and links externalized (I have read into localization, but there a first text is always required, from which is then translated).
Our old implementation was:
@
class SomeUIElement {Q_OBJECT
// context help action is added in constructor
SomeUIElement() {
QString vHelpText = ...;
QAction* vContextHelpAction = new QAction(QIcon(""), tr(vHelpText), this);
connect(vContextHelpAction, SIGNAL(triggered()), this, SLOT(OnContextHelp()));
addAction(vContextHelpAction);
setContextMenuPolicy(Qt::ActionsContextMenu);
}void OnContextHelp() {
QString vLink = GetContextLinkFor("myClassIdentifier");
OpenHtmlFile(vLink);
}}
@A first improvement is that I could replace "myClassIdentifier" by QString vClassName = metaObject()→className(); and use this as the identifier. Like that, the OnContextHelp method is the same for every class.
In a second step, I thought I could create my own version of QWidget
@
class MyContextHelpEnabledWidget
{
void OnContextHelp() {
...
}
}
@
and make all my user interface elements inherit from MyContextHelpEnabledWidget instead of QWidget. But this works only for the dialogs I create. I would prefer to have this on a "core UI element" level, i.e. for every button, dropdown, table, etc. but then I do not know how I could have QButton inherit from MyContextHelpEnabledWidget instead of QWidget. (I guess this is too much hacking anyway).In short again, how can I implement a default context help for every button in my application?