How to write html files compatible with Qt Assistant?

roni219 · wrote on 27 Sept 2016, 03:28

Hello,

I am looking for a simple way to create html files compatible with Qt Assistant.

I created and saved the html files using LibreOffice 4.2.8.2, generated the help collection with qcollectiongenerator, and opened it with Qt Assistant 5.7.0. Some of the formatting did not show in the Assistant's browser.

For example the html file contains a table with borders and inner lines. These lines are seen in the LibreOffice:

https://drive.google.com/open?id=0B3VIzaAFexv9UUltaFprUU5rMTQ

but not in Qt Assistant:

https://drive.google.com/open?id=0B3VIzaAFexv9QWg2RGRfSV9GZ0U

Is a special setting required to make html compatible with Qt Assistant? Or perhaps, another editor is needed? Ideally it would be an editor available on Linux, and such that works in a preview mode (i.e. showing what the file would look like in a browser.

Thank you in advance!

Roni.

p3c0 · wrote on 27 Sept 2016, 06:12

@roni219
AFAIK the documentation is usually generated by the qdoc tool. The qdoc tool when run against its target checks for QDoc comments and generates appropriate documentation. The stylesheets used are I think in-built or perhaps configurable too.
For eg. to add a table QDoc provides \table command.

So to make your external HTML compatible with QtAssistant you will need to find out how qdoc generates and stylizes the HTML doc.
You can try to explore the installed HTML docs on your system.
For eg. <QTDIR>/Docs/Qt-5.7/qtqml/qtqml-cppintegration-data.html document contains a table.

roni219 · wrote on 27 Sept 2016, 16:58

Thank you very much, @p3c0, both for the info and for the prompt response! I did not know about qdoc. Let me look it up today. (I will mark the topic solved after that).

roni219 · wrote on 27 Sept 2016, 19:19

Thanks again, @p3c0. I looked up qdoc manual. I understand it will generate a compatible html, but it is rather a low-level tool. It is designed to extract comments from the source files. Does everybody use it when they write help manuals for their Qt applications?

Any suggestions for an WYSIWYG (What You See Is What You Get) editor?

SGaist · wrote on 27 Sept 2016, 22:08

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 · wrote on 28 Sept 2016, 01:21

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 · wrote on 28 Sept 2016, 08:22

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 · 28 Sept 2016, 18:14

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 · wrote on 28 Sept 2016, 18:10

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 · wrote on 28 Sept 2016, 18:14

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

roni219 · wrote on 28 Sept 2016, 19:13

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 · wrote on 28 Sept 2016, 19:55

@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 · 4 Oct 2016, 22:21

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 · 10 Jun 2016, 05:22

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!