Solved How to write html files compatible with Qt Assistant?
-
Hi,
The documentation is written in Qt's sources and in .qdoc files. You can take a look at Qt's sources to see how it's done.
-
Thank you for the response, @SGaist. I understand this was what @p3c0 suggested. I am sure that the generated html would be compatible with Assistant.
The proposed method is probably easier than writing and editing html source, but falls into the same category. I hoped to find a simple way that does not require using commands or tags, nor generation of a preview.
An editor that works in the preview mode (or what they call "What You See Is What You Get"), and saves the document as html, would be preferable.
-
-
Thank you for the response, @VRonin!
Both Doxygen and QDoc are excellent tools for documenting code and APIs, and for keeping documentation in sync with the code changes.
This is not the task I need to accomplish at this time though.
I need to write a manual for the users of my application, not for the developers. It will contain screen shots, links, tables. Rich text formatting basically. A WYSIWYG would be the tool of my choice, because one can update the documents quickly.
TinyMCE is the solution if the HTML it generates is compatible with QTextBrowser. I use Qt Assistant for preview, but the users will access it with "Help" window in my application. LibreOffice that I tried earlier was WYSIWYG too, but the resulting HTML was not fully compatible with Qt Assistant.
Have you used TinyMCE for generating Assistant-readable documentation?
-
I wouldn't classify libre office as WYSIWYG HTML editor but if you do not need to reference your code it's probably easier to build your documentation as it was a normal website (with full HTML support) and then use QWebEngineView to display it
-
I'd personally consider Latex for this with some sort of HTML output template.
-
Thank you, @kshegunov. Latex is a good tool for writing science papers with formulas and plots. Still it requires generation of the document. I am looking for a WYSIWYG editor.
Thank you @VRonin. I implemented help widget with QTextBrowser because it was recommended for Qt Help Framework. This is probably what Qt Assistant uses as well.
-
@VRonin I just tried TinyMCE online demo. I am sorry to say this, but HTML code it generated was not correct. For example, the text formatted as headings was not formatted correctly as such in the source...
-
The Qt help framework and Qt Assistant are designed to document code, not to build user manuals. I stick with my first post:
build your documentation as it was a normal website (with full HTML support) and then use QWebEngineView to display it
I just tried TinyMCE online demo. I am sorry to say this, but HTML code it generated was not correct.
TinyMCE features in every recent "Top 10 WYSIWYG Html editor" chart on the web so I find it hard to believe it's not good.
I myself still use BlueGriffon (aka Nvu, aka Composer) but it's buggy as hell and development has been basically discontinued -
Sounds like the issues with displaying HTML are related to QTextBrowser limitations, not the help framework. I try to replace it with QWebEngineView, as @VRonin suggested. This calls for implementation question, that I will post in a separate thread.
Thank you very much for the helpful insights and suggestions!