[ADD] review fixes commit 1

.gitignore

@@ -15,7 +15,6 @@ build/
 develop-eggs/
 dist/
 eggs/
-lib/
 lib64/
 parts/
 sdist/
@@ -72,4 +71,3 @@ docs/_build/
 *.swp
 
 # OCA rules
-!static/lib/

web_widget_html_markdown/__manifest__.py

@@ -13,7 +13,7 @@
     "category": "Web",
     "license": "AGPL-3",
     "website": "https://github.com/OCA/web",
-    "summary": "Widget to text fields that adds markdown Html bidirectional editor",
+    "summary": "Widget for Html fields that adds markdown Html bidirectional editor",
     "depends": [
         "web", "web_editor", 
         ],

web_widget_html_markdown/readme/DESCRIPTION.rst

@@ -1,7 +1,15 @@
-This module adds a new widget for Html field in form view on Odoo:
+Behaviour of the module and best practices
+==========================================
 
-- In readonly mode, it renders normal Html
-- In write mode, use markdown or normal Html editor, with switcher to 
-  allow to convert/switch bidirectionally between Html and Markdown. Data will always 
-  be saved in Html.
+- In readonly mode, the widget renders as Html
+- In editable mode, there is a switcher to choose if the source should be HTML or Markdown. If HTML, it shows the HTML edit widget. If Markdown, it shows a markdown widget. When done editing, it will save in the field as Html, no matter which widget is chosen.
+- In markdown mode, the markdown is saved embedded within the HTML so that it can be shown again on subsequent edits of the field and there is no loss from backconversion of Html to Markdown.
+- When switching the widget from Markdown to HTML, the Markdown source is lost.
+- When switching the widget from HTML back to Markdown, the Showdown.JS backconversion is used to generate a reasonable representation of the HTML in markdown. This is where some information loss can occur, so the user should not needlessly switch from HTML to Markdown and back - in general, choose one way to edit your field content, and stick to it.
+- In edit mode, the widget provides some feedback about potential loss of information when switching from HTML to markdown or when editing in HTML text that was edited in markdown.
 
+
+Utility of this module vs web_widget_text_markdown
+==================================================
+
+Why this module when web_widget_text_markdown already exists? Mainly because it is designed to work on Text fields, and most fields within Odoo are HTML fields for example: mail content, project.task description etc. Although you could develop a custom module that overrides these fields to be Text fields and render them on-screen as HTML, this rendering would not be done when the field is for example used in sending out a mail or fetching the field content through Odoo API. In these cases this widget comes in handy because it is plug-and-play: the field type and content remains as HTML, but you can choose to edit it with a markdown widget.

web_widget_html_markdown/readme/ROADMAP.rst

@@ -1,2 +1,3 @@
 * Images Will be lost when passing from Html to markdown
+* Other information may be lost when switching from Html to markdown
 

web_widget_html_markdown/readme/USAGE.rst

@@ -1,8 +1,10 @@
-Your XML form view definition should contain::
+Your XML form view definition should contain:
 
     ...
-    <field name="field_name" widget="html_markdown"/
+    <field name="field_name" widget="html_markdown"/>
     ...
 
 
-This will render the Html field as typical html and edit as markdown or HTML.
+This will replace the default Html widget by the new Markdown/HTML widget and
+allow the field to be edited as Markdown or HTML, depending on the user's choice.
+

web_widget_html_markdown/static/src/js/web_widget_html_markdown.js

@@ -186,7 +186,7 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
          * @private
          * @returns {$.Promise}
          */
-        _createWysiwygIntance: function () {
+        _createWysiwygInstance: function () {
             var self = this;
             this.wysiwyg = new Wysiwyg(this, this._getWysiwygOptions());
             // Coming from markdown we need to inject in new wysiwyg new value.
@@ -375,9 +375,9 @@ odoo.define("web_widget_html_markdown.FieldHtmlMarkDown", function(require) {
 
             if (this.nodeOptions.cssEdit) {
                 // Must be async because the target must be append in the DOM
-                this._createWysiwygIntance();
+                this._createWysiwygInstance();
             } else {
-                return this._createWysiwygIntance();
+                return this._createWysiwygInstance();
             }
         },
         /**