Opened 8 years ago
Closed 7 years ago
#4067 closed enhancement (fixed)
Add a Documentation Editor to OMEdit.
| Reported by: | anonymous | Owned by: | Adeel Asghar |
|---|---|---|---|
| Priority: | high | Milestone: | 1.12.0 |
| Component: | OMEdit | Version: | |
| Keywords: | Cc: |
Description
Now that OpenModelica is fast getting mature, I think it is time to substitute, in OMEdit, the "Documentation Browser" with a "Documentation Editor" allowing writing rich text (with bold, underline, font size choice, etc.) to write model documentation effectively.
Directly writing in html is lengthy and requires some html knowledge.
Qt offers several options to create reliable WYSIWYG text interactively and to convert it into html.
Attachments (1)
Change History (18)
follow-up: 13 comment:1 by , 8 years ago
follow-up: 14 comment:2 by , 8 years ago
I made some tests in the meanwhile.
If the Qt Widget QTextEdit, if the function toHtml() is called, html code is produced that, once the stuff before the "<html>" tag is removed, is cluttered but well interpreted by Dymola.
I mean, using the QTextEdit to add documentation editing capabilities to OMEdit although not perfect in terms of readability of the html output, allows OMEdit to ease user's model documentation writing with a very small programming effort.
And the resulting html can be read and edited by other tools, at least by Dymola.
Just as a helper I add a very simple test program (attached GenerateHTML.exe), that in Qt Creator requires writing just a few rows of code.
Procedure to see html output and check compatibility with Dymola:
1) write some rich text in the left box
2) create the html using the "Show html" button
3) copy-paste the html in notepad, then copy-paste it into a Dymola's documentation page in "Info Source" mode
3) switch the Dymola's documentation mode into "Formatted Documentation".
At this point you can also modify the information in the Dymola's "Info Editor" mode, and everything continues to work. BTW, Dymola simplifies the html, which is not bad. I've not checked, but I've no doubt that the resulting html can be read back into OM, if QTextEditor capabilities are used again.
Naturally, the produced html can be pasted in any documentation annotation of a modelica model, and read well by OM (the only trick is to substitute any double quote \", because, obviously, all that html must be a unique modelica string).
by , 8 years ago
| Attachment: | GenerateHTML.exe added |
|---|
comment:3 by , 8 years ago
A documentation editor is really missing for serious use of OMEdit.
In the simplest case the documentation browser might allow to switch to HTML source view, maybe with some markup. This editor should preserve the text formatting to not mess up repositories.
Starting from this, more convenient WYSIWYG approaches could be investigated in a second step.
comment:4 by , 8 years ago
Also I would like to have a documentation editor in OMEdit. Is it possible to add a very basic approach in the short term?
comment:5 by , 8 years ago
I just added a simple HTMLEditor in 820fa36/OMEdit which allow users to edit documentation.
comment:7 by , 8 years ago
hm, I wanted to give this a try, but Hudson seems to have stopped generating Win64 nightly builds 5 days ago.
comment:8 by , 8 years ago
The builds will be back on in a couple of hours. I forgot to enable the 64bit build back after I build the 1.9.7 release. Anyhow we need to fix a build issue before you will get any build, I'm looking at that now.
comment:9 by , 8 years ago
Thanks! I'll just try to grab a new nightly on Monday.
(Btw, it seems that the win_release build runs once per day? I don't know what it's supposed to do, but from the name alone I would expect it to run once per released version, as the released version does not change from day to day. :-P)
comment:10 by , 8 years ago
@Christoph: it runs but does nothing because it knows that is already built. I will disable the automatic build as it should be ran manually anyway. I copied the 64bit build job and inherited the settings.
comment:11 by , 8 years ago
Some minor issues:
See the following example, where "Some docu" was added with OMEdit:
model ModelWithDocu annotation(Documentation(info = "<html> Some docu. See <a href=\"http://www.openmodelica.org\">OpenModelica homepage</a>. </html>", revisions = "", __OpenModelica_infoHeader = "")); end ModelWithDocu;
Clicking on the "info" button will show the nested double quotes without backslash character \. Attempts to change something in the docu will be ignored, I think due to the missing backslashes.
Assuming that OMEdit intentionally removes backslashes when showing the html text, it should also add them again upon save.
Generally the changes should not silently be thrown away, but some notification would be preferred in case of save errors.
Last but not least: it might be considered unconvenient if OMEdit always adds revisions and __OpenModelica_infoHeader. Many people would have to remove these things manually afterwards.
comment:12 by , 8 years ago
Fixed in ffae961/OMEdit.
I also added support for editing __OpenModelica_infoHeader.
comment:13 by , 8 years ago
Replying to anonymous:
Maybe I must add that I could not find in the documentation what subset of HTML is supported by OM.
Is it somewhere and I could not find it?
If it is not, why not to add a paragraph with this piece of information?
Most of the controls used like QLabel, QTextBrowser etc. use a limited subset of static HTML 4 / CSS 2.1. However, for displaying documentation QtWebkit is used which is based on the Open Source WebKit engine. You can read more here https://wiki.qt.io/Handling_HTML.
comment:14 by , 8 years ago
Replying to ceraolo:
I made some tests in the meanwhile.
If the Qt Widget QTextEdit, if the function toHtml() is called, html code is produced that, once the stuff before the "<html>" tag is removed, is cluttered but well interpreted by Dymola.
I mean, using the QTextEdit to add documentation editing capabilities to OMEdit although not perfect in terms of readability of the html output, allows OMEdit to ease user's model documentation writing with a very small programming effort.
And the resulting html can be read and edited by other tools, at least by Dymola.
Just as a helper I add a very simple test program (attached GenerateHTML.exe), that in Qt Creator requires writing just a few rows of code.
Procedure to see html output and check compatibility with Dymola:
1) write some rich text in the left box
2) create the html using the "Show html" button
3) copy-paste the html in notepad, then copy-paste it into a Dymola's documentation page in "Info Source" mode
3) switch the Dymola's documentation mode into "Formatted Documentation".
At this point you can also modify the information in the Dymola's "Info Editor" mode, and everything continues to work. BTW, Dymola simplifies the html, which is not bad. I've not checked, but I've no doubt that the resulting html can be read back into OM, if QTextEditor capabilities are used again.
Naturally, the produced html can be pasted in any documentation annotation of a modelica model, and read well by OM (the only trick is to substitute any double quote \", because, obviously, all that html must be a unique modelica string).
Do you really want to use QTextEdit? It produces way too much crap html. For example using your demo, I just wrote Test, made it bold and it produces this,
<html><head><meta name="qrichtext" content="1" /><style type="text/css">
p, li { white-space: pre-wrap; }
</style></head><body style=" font-family:'MS Shell Dlg 2'; font-size:8.25pt; font-weight:400; font-style:normal;">
<p style=" margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px;"><span style=" font-family:'Times New Roman'; font-size:10pt; font-weight:600;">Test</span></p></body></html>
We should use QWebView together with DOM API. In particular Document.execCommand API. QWebView provides ways of executing JavaScript so we can manipulate the underlying DOM. I will try to implement it next week. I am pretty sure Dymola is doing something similar. This is the best option I believe.
Another option is to use QtWebkit bridge. It allows JavaScript and QObject to communicate. So we can use any JavaScript based WYSIWYG (e.g., TinyMCE) and connect it to the GUI. It is not a best option since it adds another 3rd party tool, is difficult to implement and we have to accept what 3rd party WYSIWYG provides.
comment:15 by , 8 years ago
I agree with you, and I wrote, indeed:
"QTextEdit [...] although not perfect in terms of readability of the html output, allows OMEdit to ease user's model documentation writing with a very small programming effort."
So if with a reasonable effort a different solution is found that creates a more compact code, I will be happy.
I also agree with you that depending on a 3rd party tool is not the best options. I would not choose it, since since better ones are available (those discussed before).
Thank you for considering this ticket. I consider it very important to have good documentation of models, and thus having html editing capability in OMEdit is a boon.
comment:17 by , 7 years ago
| Milestone: | 2.0.0 → 1.12.0 |
|---|---|
| Resolution: | → fixed |
| Status: | new → closed |
This is already done for 1.12.0
Maybe I must add that I could not find in the documentation what subset of HTML is supported by OM.
Is it somewhere and I could not find it?
If it is not, why not to add a paragraph with this piece of information?