chore: update readme and add TASKS.TODO.md

2024-03-22 13:30:55 +08:00 · 2018-09-16 03:45:07 +01:00 · 2018-09-16 03:45:07 +01:00 · f46479b4ee
commit f46479b4ee
parent f24e314a70
4 changed files with 388 additions and 21 deletions
--- a/README.md
+++ b/README.md
@ -224,14 +224,6 @@ var defaultOptions = showdown.getDefaultOptions();
 * **rawHeaderId**: (boolean) [default false] Remove only spaces, ' and " from generated header ids (including prefixes),
    replacing them with dashes (-). WARNING: This might result in malformed ids **(since v1.7.3)**
 
- * **parseImgDimensions**: (boolean) [default false] Enable support for setting image dimensions from within markdown syntax.
-   Examples:
-   ```
-   ![foo](foo.jpg =100x80)     simple, assumes units are in px
-   ![bar](bar.jpg =100x*)      sets the height to "auto"
-   ![baz](baz.jpg =80%x5em)  Image with width of 80% and height of 5em
-   ```
- 
 * **headerLevelStart**: (integer) [default 1] Set the header starting level. For instance, setting this to 3 means that

    ```md
@ -243,6 +235,14 @@ var defaultOptions = showdown.getDefaultOptions();
    <h3>foo</h3>
    ```

+ * **parseImgDimensions**: (boolean) [default false] Enable support for setting image dimensions from within markdown syntax.
+   Examples:
+   ```
+   ![foo](foo.jpg =100x80)     simple, assumes units are in px
+   ![bar](bar.jpg =100x*)      sets the height to "auto"
+   ![baz](baz.jpg =80%x5em)  Image with width of 80% and height of 5em
+   ```
+
 * **simplifiedAutoLink**: (boolean) [default false] Turning this option on will enable automatic linking to urls.
   This means that:

@ -278,18 +278,8 @@ var defaultOptions = showdown.getDefaultOptions();
   <p>some text with__underscores__in middle</p>
   ```

- * **literalMidWordAsterisks**: (boolean) [default false] Turning this on will stop showdown from interpreting asterisks
-   in the middle of words as `<em>` and `<strong>` and instead treat them as literal asterisks.
-
-   Example:
-
-   ```md
-   some text with**underscores**in middle
-   ```
-   will be parsed as
-   ```html
-   <p>some text with**underscores**in middle</p>
-   ```
+ * ~~**literalMidWordAsterisks**: (boolean) [default false] Turning this on will stop showdown from interpreting asterisks
+   in the middle of words as `<em>` and `<strong>` and instead treat them as literal asterisks.~~
   
 * **strikethrough**: (boolean) [default false] Enable support for strikethrough syntax.
   `~~strikethrough~~` as `<del>strikethrough</del>`
@ -324,7 +314,7 @@ var defaultOptions = showdown.getDefaultOptions();
   by 4 spaces for them to be nested, effectively reverting to the old behavior where 2 or 3 spaces were enough.
   **(since v1.5.0)**
 
- * **simpleLineBreaks**: (boolean) [default false] Parses line breaks as <br> like GitHub does, without
+ * **simpleLineBreaks**: (boolean) [default false] Parses line breaks as <br>, without
   needing 2 spaces at the end of the line **(since v1.5.1)**
 
   ```md
--- a/TASKS.TODO.md
+++ b/TASKS.TODO.md
@ -0,0 +1,140 @@
+# ROADMAP TO VERSION 2.0
+
+
+## Options
+
+- [ ] **ghCompatibleHeaderId** (removal)
+
+    Will be removed and **will become the default behavior**.
+    
+- [ ] **customizedHeaderId** (removal)
+
+    This option introduced non compliant syntax so it really belongs in an extension.
+    The new **listener extension system** allows users to directly modify and customize
+    the HTML and add any attributes they wish. 
+
+- [ ] **rawPrefixHeaderId** (removal)
+
+    This option will be superseeded by the option `rawHeaderId`. So basically activating `rawHeaderId` will make
+    showdown only to replace spaces, ', ", > and < with dashes (-) from generated header ids, including prefixes.
+
+- [X] **literalMidWordAsterisks** (removal)
+
+    This option is weird, hard to maintain and really... makes little sense.
+
+- [ ] **excludeTrailingPunctuationFromURLs** (removal)
+
+    This option will be removed and will be the default behavior from now on.
+
+- [ ] **strikethrough** (change)
+
+    Will be enabled by default
+
+- [ ] **disableForced4SpacesIndentedSublists** (to think/postpone)
+
+    This was only a temporary option for backwards compatibility reason. However, most flavours support lists indented
+    with 2 spaces, so it puts us in a tight spot, specially since some markdown beautifiers out there insist in
+    indenting lists with 2 spaces, probably in a misguided try to follow the CommonMark spec.
+    
+    The CommonMark spec is, IMHO, a bit confusing for users regarding this, since list sub-blocks (and lists) 
+    are determined by the spaces from the start of the line and the first character after the list mark. And the proof
+    are the MD beautifiers out there, which misinterpreted the spec and made a mess 
+    
+    Showdown syntax is actually easier (and fully compliant with the original spec): if you indent something 4 spaces,
+    it becomes a sub-block. Since lists are blocks, you must indent it 4 spaces for it to become a sub-block.
+    
+    Regardless, we kinda have 2 solutions:
+    
+    - Drop support for 2 space indentation (and make a lot of users confused since GFM, CommonMark and others allow this)
+    - Create a new list subparser that can be turned on with an option, like gfmListStyle
+      (but postpones even more the alpha 2.0 release since the list subparser is probably the hardest thing to rewrite)
+    
+    Tough choices...
+
+- [ ] **simpleLineBreaks** (change)
+
+    Will be removed from Github Flavor since github only does this in comments (which is weird...)
+
+- [ ] **openLinksInNewWindow** (removal)
+
+    Will be removed in favor of the new listener extension, which will allow users to manipulate HTML tags attributes
+    directly.
+    
+- [ ] Revamp the option system
+
+    Revamp the option system so that it becomes more simple. Right now, it's really confusing. And option names are weird
+    too. The idea is to pass options to the constructor under an option object, that can have hierarchical structure.
+    Ex:
+    
+    ```js
+    var conv = new showdown.Converter({ 
+      options: { 
+        links: {
+          autoLinks: true
+        },
+        headings: {
+          startLevel: 2
+        }
+      }
+    });
+    ``` 
+
+## Legacy Code Removal
+- [ ] Legacy extension support
+        
+    Old extensions that inject directly into extensions object property will no longer be supported
+    
+- [ ] HTML and OUTPUT extensions
+    
+    HTML and OTP extensions will be dropped in favor of Listener Extensions. We might even give them a new name
+    
+## Subparsers
+- [ ] **Anchors**: Revamp the anchors subparser so it calls strikethrough, bold, italic and underline directly
+- [ ] **autoLinks**: Fix some lingering bugs and issues with autolinks
+
+
+## Priority Bugs
+- [ ] **#355**: *simplifiedAutoLink URLs inside parenthesis followed by another character are not parsed correctly*
+- [ ] **#367**: *sublists rendering with 2 spaces* - related to disableForced4SpacesIndentedSublists option...
+- [ ] **#537**: *master branch doesn't work in a web worker*
+
+
+## CLI
+- [ ] Refactor the CLI
+- [ ] **#381**: *Support for src and dst directories in showdown cli*
+- [ ] **#584**: *Fails to read from stdin*
+- [ ] **#554**: *CLI not working with jsdom v10*
+
+## Other stuff
+- [X] Regexp rewrite for more performance oompf
+- [ ] Full unit testing
+- [ ] Better error reporting
+
+## Stuff that probably won't make it to v2.0
+- [ ] **#486**: *A backslash at the end of the line is a hard line break*
+- [ ] **#548**: *anchors and images of subParser are errors when they are specific strings*
+- [ ] **#549**: *Strange parsing issue with `<pre><code>`*
+
+## NEW Features
+
+### Event system
+- [X] Listener system revamp
+- [ ] Standardize events for all event types
+- [ ] Unit testing
+- [ ] Functional testing
+
+This should address:
+- **#567**: Allow not making header ids lowercase
+- **#540**: Add complete class to the tasklist list element
+
+### MD to HTML conversion
+- [X] Basic support
+- [X] Basic functional testcase
+- [ ] Advanced support for all showdown MD features
+- [ ] Advanced functional testcase
+- [ ] Unit testing
+
+## Documentation (for v2.0)
+- [ ] Options
+- [ ] Extensions (and the new event system)
+- [ ] Cookbook (with stuff for backwards compatibility, specially regarding removed options)
--- a/test/functional/makehtml/cases/features/simplifiedAutoLink/complete-test-case.html
+++ b/test/functional/makehtml/cases/features/simplifiedAutoLink/complete-test-case.html
@ -0,0 +1,79 @@
+<!-- SHOULD PASS -->
+<p><a href="http://foo.com/blah_blah">http://foo.com/blah_blah</a></p>
+<p><a href="http://foo.com/blah_blah/">http://foo.com/blah_blah/</a></p>
+<p><a href="http://foo.com/blah_blah_(wikipedia)">http://foo.com/blah_blah_(wikipedia)</a></p>
+<p><a href="http://foo.com/blah_blah_(wikipedia)_(again)">http://foo.com/blah_blah_(wikipedia)_(again)</a></p>
+<p><a href="http://www.example.com/wpstyle/?p=364">http://www.example.com/wpstyle/?p=364</a></p>
+<p><a href="https://www.example.com/foo/?bar=baz&inga=42&quux">https://www.example.com/foo/?bar=baz&inga=42&quux</a></p>
+<p><a href="http://✪df.ws/123">http://✪df.ws/123</a></p>
+<p><a href="http://userid:password@example.com:8080">http://userid:password@example.com:8080</a></p>
+<p><a href="http://userid:password@example.com:8080/">http://userid:password@example.com:8080/</a></p>
+<p><a href="http://userid@example.com">http://userid@example.com</a></p>
+<p><a href="http://userid@example.com/">http://userid@example.com/</a></p>
+<p><a href="http://userid@example.com:8080">http://userid@example.com:8080</a></p>
+<p><a href="http://userid@example.com:8080/">http://userid@example.com:8080/</a></p>
+<p><a href="http://userid:password@example.com">http://userid:password@example.com</a></p>
+<p><a href="http://userid:password@example.com/">http://userid:password@example.com/</a></p>
+<p><a href="http://142.42.1.1/">http://142.42.1.1/</a></p>
+<p><a href="http://142.42.1.1:8080/">http://142.42.1.1:8080/</a></p>
+<p><a href="http://➡.ws/䨹">http://➡.ws/䨹</a></p>
+<p><a href="http://⌘.ws">http://⌘.ws</a></p>
+<p><a href="http://⌘.ws/">http://⌘.ws/</a></p>
+<p><a href="http://foo.com/blah_(wikipedia)#cite-1">http://foo.com/blah_(wikipedia)#cite-1</a></p>
+<p><a href="http://foo.com/blah_(wikipedia)_blah#cite-1">http://foo.com/blah_(wikipedia)_blah#cite-1</a></p>
+<p><a href="http://foo.com/unicode_(✪)_in_parens">http://foo.com/unicode_(✪)_in_parens</a></p>
+<p><a href="http://foo.com/(something)?after=parens">http://foo.com/(something)?after=parens</a></p>
+<p><a href="http://☺.damowmow.com/">http://☺.damowmow.com/</a></p>
+<p><a href="http://code.google.com/events/#&product=browser">http://code.google.com/events/#&product=browser</a></p>
+<p><a href="http://j.mp">http://j.mp</a></p>
+<p><a href="ftp://foo.bar/baz">ftp://foo.bar/baz</a></p>
+<p><a href="http://foo.bar/?q=Test%20URL-encoded%20stuff">http://foo.bar/?q=Test%20URL-encoded%20stuff</a></p>
+<p><a href="http://مثال.إختبار">http://مثال.إختبار</a></p>
+<p><a href="http://例子.测试">http://例子.测试</a></p>
+<p><a href="http://उदाहरण.परीक्षा">http://उदाहरण.परीक्षा</a></p>
+<p><a href="http://1337.net">http://1337.net</a></p>
+<p><a href="http://a.b-c.de">http://a.b-c.de</a></p>
+<p><a href="http://223.255.255.254">http://223.255.255.254</a></p>
+<p><a href="https://foo_bar.example.com/">https://foo_bar.example.com/</a></p>
+<!-- WEIRD BUT SHOULD ALSO PASS -->
+<p><a href="http://www.foo.bar./">http://www.foo.bar./</a></p>
+<p><a href="http://a.b--c.de/">http://a.b--c.de/</a></p>
+<!-- SHOULD PARTIALLY PASS -->
+<p><a href="http://foo.bar/foo(bar)baz">http://foo.bar/foo(bar)baz</a> quux</p>
+<p><a href="http://foo.bar?q=Spaces">http://foo.bar?q=Spaces</a> should be encoded</p>
+<!-- THESE ARE INVALID IPS BUT WE WILL LET THEM PASS -->
+<p><a href="http://10.1.1.1">http://10.1.1.1</a></p>
+<p><a href="http://10.1.1.254">http://10.1.1.254</a></p>
+<p><a href="http://0.0.0.0">http://0.0.0.0</a></p>
+<p><a href="http://10.1.1.0">http://10.1.1.0</a></p>
+<p><a href="http://10.1.1.255">http://10.1.1.255</a></p>
+<p><a href="http://224.1.1.1">http://224.1.1.1</a></p>
+<p><a href="http://1.1.1.1.1">http://1.1.1.1.1</a></p>
+<p><a href="http://123.123.123">http://123.123.123</a></p>
+<!-- SHOULD FAIL -->
+<p>http://</p>
+<p>http://.</p>
+<p>http://..</p>
+<p>http://../</p>
+<p>http://?</p>
+<p>http://??</p>
+<p>http://??/</p>
+<p>http://#</p>
+<p>http://##</p>
+<p>http://##/</p>
+<p>//</p>
+<p>//a</p>
+<p>///a</p>
+<p>///</p>
+<p>http:///a</p>
+<p>foo.com</p>
+<p>rdar://1234</p>
+<p>h://test</p>
+<p>http:// shouldfail.com</p>
+<p>:// should fail</p>
+<p>http://-error-.invalid/</p>
+<p>http://-a.b.co</p>
+<p>http://a.b-.co</p>
+<p>http://3628126748</p>
+<p>http://.www.foo.bar/</p>
+<p>http://.www.foo.bar./</p>
--- a/test/functional/makehtml/cases/features/simplifiedAutoLink/complete-test-case.md
+++ b/test/functional/makehtml/cases/features/simplifiedAutoLink/complete-test-case.md
@ -0,0 +1,158 @@
+<!-- SHOULD PASS -->
+
+http://foo.com/blah_blah
+
+http://foo.com/blah_blah/
+
+http://foo.com/blah_blah_(wikipedia)
+
+http://foo.com/blah_blah_(wikipedia)_(again)
+
+http://www.example.com/wpstyle/?p=364
+
+https://www.example.com/foo/?bar=baz&inga=42&quux
+
+http://✪df.ws/123
+
+http://userid:password@example.com:8080
+
+http://userid:password@example.com:8080/
+
+http://userid@example.com
+
+http://userid@example.com/
+
+http://userid@example.com:8080
+
+http://userid@example.com:8080/
+
+http://userid:password@example.com
+
+http://userid:password@example.com/
+
+http://142.42.1.1/
+
+http://142.42.1.1:8080/
+
+http://➡.ws/䨹
+
+http://⌘.ws
+
+http://⌘.ws/
+
+http://foo.com/blah_(wikipedia)#cite-1
+
+http://foo.com/blah_(wikipedia)_blah#cite-1
+
+http://foo.com/unicode_(✪)_in_parens
+
+http://foo.com/(something)?after=parens
+
+http://☺.damowmow.com/
+
+http://code.google.com/events/#&product=browser
+
+http://j.mp
+
+ftp://foo.bar/baz
+
+http://foo.bar/?q=Test%20URL-encoded%20stuff
+
+http://مثال.إختبار
+
+http://例子.测试
+
+http://उदाहरण.परीक्षा
+
+http://1337.net
+
+http://a.b-c.de
+
+http://223.255.255.254
+
+https://foo_bar.example.com/
+
+
+<!-- WEIRD BUT SHOULD ALSO PASS -->
+
+http://www.foo.bar./
+
+http://a.b--c.de/
+
+<!-- SHOULD PARTIALLY PASS -->
+
+http://foo.bar/foo(bar)baz quux
+
+http://foo.bar?q=Spaces should be encoded
+
+<!-- THESE ARE INVALID IPS BUT WE WILL LET THEM PASS -->
+http://10.1.1.1
+
+http://10.1.1.254
+
+http://0.0.0.0
+
+http://10.1.1.0
+
+http://10.1.1.255
+
+http://224.1.1.1
+
+http://1.1.1.1.1
+
+http://123.123.123
+
+
+<!-- SHOULD FAIL -->
+
+http://
+
+http://.
+
+http://..
+
+http://../
+
+http://?
+
+http://??
+
+http://??/
+
+http://#
+
+http://##
+
+http://##/
+
+//
+
+//a
+
+///a
+
+///
+
+http:///a
+
+foo.com
+
+rdar://1234
+
+h://test
+
+http:// shouldfail.com
+
+:// should fail
+
+http://-error-.invalid/
+
+http://-a.b.co
+
+http://a.b-.co
+
+http://3628126748
+
+http://.www.foo.bar/
+
+http://.www.foo.bar./