How to write html files compatible with Qt Assistant?

SGaist

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.

roni219

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.

VRonin

The de-facto standard in C++ documentation is Doxygen which was built on qdoc but, again, it uses tags in the code.

If you want a WYSIWYG documentation and you want to build it manually then just get an HTML editor like TinyMCE, write your documentation and save it in html.

roni219

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?

VRonin

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

kshegunov

I'd personally consider Latex for this with some sort of HTML output template.

roni219

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.

roni219

@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...

VRonin

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

roni219

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!