-
Notifications
You must be signed in to change notification settings - Fork 24
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(parser): support double punctuation in quoted text (#39)
add a `LIMITATIONS.adoc` file to report limitations or differences with Asciidoc/Asciidoctor when using nested quotes or unbalanced quotes. Signed-off-by: Xavier Coulon <xcoulon@redhat.com>
- Loading branch information
Showing
12 changed files
with
1,610 additions
and
460 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| <div id="preamble"> | ||
| <div class="sectionbody"> | ||
| <div class="paragraph"> | ||
| <p>This is the contribute.md of our project. Great to have you here. Here are a few ways you can help make this project better!</p> | ||
| </div> | ||
| </div> | ||
| </div> | ||
| <div class="sect1"> | ||
| <h2 id="_adding_new_features">Adding new features</h2> | ||
| <div class="sectionbody"> | ||
| <div class="paragraph"> | ||
| <p>Please open an issue <a href="https://github.com/bytesparadise/libasciidoc/issues">here</a> to discuss about the feature you would like to see in Libasciidoc, | ||
| If you’re in the mood to implement it (that’s awesome!), then submit a pull-request along with enough tests (both at the parser level and at the renderer level) to validate the behaviour of your code.</p> | ||
| </div> | ||
| <div class="paragraph"> | ||
| <p>Don’t get discouraged if you don’t get an immediate response, this is a side-project.</p> | ||
| </div> | ||
| </div> | ||
| </div> | ||
| <div class="sect1"> | ||
| <h2 id="_bug_triage">Bug triage</h2> | ||
| <div class="sectionbody"> | ||
| <div class="ulist"> | ||
| <ul> | ||
| <li> | ||
| <p>You can help report bugs by filling them <a href="https://github.com/bytesparadise/libasciidoc/issues">here</a>.</p> | ||
| </li> | ||
| <li> | ||
| <p>You can help us diagnose and fix existing bugs by asking and providing answers for the following:</p> | ||
| <div class="ulist"> | ||
| <ul> | ||
| <li> | ||
| <p>Is the bug reproducible as explained?</p> | ||
| </li> | ||
| <li> | ||
| <p>Are the steps to reproduce the bug clear? If not, can you describe how you might reproduce it?</p> | ||
| </li> | ||
| <li> | ||
| <p>What tags should the bug have?</p> | ||
| </li> | ||
| <li> | ||
| <p>Is this bug something you have run into? Would you appreciate it being looked into faster?</p> | ||
| </li> | ||
| </ul> | ||
| </div> | ||
| </li> | ||
| <li> | ||
| <p>You can close fixed bugs by testing old tickets to see if they are still happening.</p> | ||
| </li> | ||
| <li> | ||
| <p>You can update our changelog here:</p> | ||
| </li> | ||
| <li> | ||
| <p>You can remove duplicate bug reports by:</p> | ||
| </li> | ||
| </ul> | ||
| </div> | ||
| </div> | ||
| </div> | ||
| <div class="sect1"> | ||
| <h2 id="_beta_testing">Beta testing</h2> | ||
| <div class="sectionbody"> | ||
| <div class="paragraph"> | ||
| <p>Testing existing features is a good way to contribute to the project, too!</p> | ||
| </div> | ||
| </div> | ||
| </div> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| = Known limitations and differences with Asciidoc/Asciidoctor | ||
|
|
||
| This document reports the known limitations and differences with Asciidoc/Asciidoctor. | ||
| In any case, feel free to https://github.com/bytesparadise/libasciidoc/issues[open an issue] | ||
| if you want to discuss about an actual limitation of Libasciidoc or if you want to report a new one. | ||
|
|
||
| == Quoted Text | ||
|
|
||
| Quoted text rendering can differ in the following cases: | ||
|
|
||
| - when the punctuation is unbalanced. Eg: | ||
| ``` | ||
| some **bold content*. | ||
| ``` | ||
| will be rendered as the raw input: | ||
| ``` | ||
| some **bold content*. | ||
| ``` | ||
| instead of : | ||
| ``` | ||
| <p>some <strong>*bold content</strong></p> | ||
| ``` | ||
|
|
||
| - when quoted text uses the same punctuation. Eg: | ||
| ``` | ||
| *some *nested bold* content*. | ||
| ``` | ||
| Libasciidoc will detect the nested bold quote and renderer accordingly: | ||
| ``` | ||
| <strong>some <strong>nested bold</strong> content</strong>. | ||
| ``` | ||
| whereas Asciidoc/Asciidoctor will produce : | ||
| ``` | ||
| <p><strong>some *nested bold</strong> content*.</p> | ||
| ``` | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| <div id="preamble"> | ||
| <div class="sectionbody"> | ||
| <div class="paragraph"> | ||
| <p>This document reports the known limitations and differences with Asciidoc/Asciidoctor. | ||
| In any case, feel free to <a href="https://github.com/bytesparadise/libasciidoc/issues">open an issue</a> | ||
| if you want to discuss about an actual limitation of Libasciidoc or if you want to report a new one.</p> | ||
| </div> | ||
| </div> | ||
| </div> | ||
| <div class="sect1"> | ||
| <h2 id="_quoted_text">Quoted Text</h2> | ||
| <div class="sectionbody"> | ||
| <div class="paragraph"> | ||
| <p>Quoted text rendering can differ in the following cases:</p> | ||
| </div> | ||
| <div class="ulist"> | ||
| <ul> | ||
| <li> | ||
| <p>when the punctuation is unbalanced. Eg:</p> | ||
| </li> | ||
| </ul> | ||
| </div> | ||
| <div class="listingblock"> | ||
| <div class="content"> | ||
| <pre class="highlight"><code>some **bold content*.</code></pre> | ||
| </div> | ||
| </div> | ||
| <div class="paragraph"> | ||
| <p>will be rendered as the raw input:</p> | ||
| </div> | ||
| <div class="listingblock"> | ||
| <div class="content"> | ||
| <pre class="highlight"><code>some **bold content*.</code></pre> | ||
| </div> | ||
| </div> | ||
| <div class="paragraph"> | ||
| <p>instead of :</p> | ||
| </div> | ||
| <div class="listingblock"> | ||
| <div class="content"> | ||
| <pre class="highlight"><code><p>some <strong>*bold content</strong></p></code></pre> | ||
| </div> | ||
| </div> | ||
| <div class="ulist"> | ||
| <ul> | ||
| <li> | ||
| <p>when quoted text uses the same punctuation. Eg:</p> | ||
| </li> | ||
| </ul> | ||
| </div> | ||
| <div class="listingblock"> | ||
| <div class="content"> | ||
| <pre class="highlight"><code>*some *nested bold* content*.</code></pre> | ||
| </div> | ||
| </div> | ||
| <div class="paragraph"> | ||
| <p>Libasciidoc will detect the nested bold quote and renderer accordingly:</p> | ||
| </div> | ||
| <div class="listingblock"> | ||
| <div class="content"> | ||
| <pre class="highlight"><code><strong>some <strong>nested bold</strong> content</strong>.</code></pre> | ||
| </div> | ||
| </div> | ||
| <div class="paragraph"> | ||
| <p>whereas Asciidoc/Asciidoctor will produce :</p> | ||
| </div> | ||
| <div class="listingblock"> | ||
| <div class="content"> | ||
| <pre class="highlight"><code><p><strong>some *nested bold</strong> content*.</p></code></pre> | ||
| </div> | ||
| </div> | ||
| </div> | ||
| </div> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,110 @@ | ||
| <div id="preamble"> | ||
| <div class="sectionbody"> | ||
| <div class="paragraph"> | ||
| <p><span class="image"><a class="image" href="https://travis-ci.org/bytesparadise/libasciidoc"><img src="https://travis-ci.org/bytesparadise/libasciidoc.svg?branch=master" alt="Build Status"></a></span> | ||
| <span class="image"><a class="image" href="https://codecov.io/gh/bytesparadise/libasciidoc"><img src="https://codecov.io/gh/bytesparadise/libasciidoc/branch/master/graph/badge.svg" alt="Codecov"></a></span> | ||
| <span class="image"><a class="image" href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a></span></p> | ||
| </div> | ||
| <div class="paragraph"> | ||
| <p>Libasciidoc is an open source Go library that converts Asciidoc content into HTML (other output formats may be supported in the future). | ||
| It is is available under the terms of the <a href="https://raw.githubusercontent.com/bytesparadise/libasciidoc/LICENSE">Apache License 2.0</a>.</p> | ||
| </div> | ||
| </div> | ||
| </div> | ||
| <div class="sect1"> | ||
| <h2 id="_supported_syntax">Supported syntax</h2> | ||
| <div class="sectionbody"> | ||
| <div class="ulist"> | ||
| <ul> | ||
| <li> | ||
| <p>Title and Sections (level 1 to 6)</p> | ||
| </li> | ||
| <li> | ||
| <p>Document attribute declaration (after the title and within the rest of the document) and substitution</p> | ||
| </li> | ||
| <li> | ||
| <p>Paragraphs</p> | ||
| </li> | ||
| <li> | ||
| <p>Delimited Source Blocks (using the ``` delimiter, a.k.a "fences")</p> | ||
| </li> | ||
| <li> | ||
| <p>Literal blocks (paragraph starting with a space, with the "…​." delimiter or with the <code>[literal]</code> attribute)</p> | ||
| </li> | ||
| <li> | ||
| <p>Quoted text (bold, <em>italic</em> and <code>monospace</code>)</p> | ||
| </li> | ||
| <li> | ||
| <p>Unordered lists, using the <code>-</code> marker for simple lists, or the <code>*</code> marker for nested lists (and <code>**</code>, <code>***</code>, etc. for the sublists) .</p> | ||
| </li> | ||
| <li> | ||
| <p>External links in paragraphs (<code>https://</code>, <code>http://</code>, <code>ftp://</code>, <code>irc://</code>, <code>mailto:</code>)</p> | ||
| </li> | ||
| <li> | ||
| <p>Inline images in paragraphs (<code>image://</code>)</p> | ||
| </li> | ||
| <li> | ||
| <p>Block images (<code>image:://</code>)</p> | ||
| </li> | ||
| <li> | ||
| <p>Element attributes (ID, link and title, when applicable) on block images, paragraphs, lists and sections</p> | ||
| </li> | ||
| </ul> | ||
| </div> | ||
| <div class="paragraph"> | ||
| <p>See the <a href="http://LIMITATIONS.adoc">known limitations</a> document for differences between Asciidoc/Asciidoctor and Libasciidoc.</p> | ||
| </div> | ||
| <div class="paragraph"> | ||
| <p>Further elements will be supported in the future. Feel free to open issues <a href="https://github.com/bytesparadise/libasciidoc/issues">here</a> to help prioritizing the upcoming work.</p> | ||
| </div> | ||
| </div> | ||
| </div> | ||
| <div class="sect1"> | ||
| <h2 id="_installation">Installation</h2> | ||
| <div class="sectionbody"> | ||
| <div class="literalblock"> | ||
| <div class="content"> | ||
| <pre>$ go get -u github.com/bytesparadise/libasciidoc</pre> | ||
| </div> | ||
| </div> | ||
| </div> | ||
| </div> | ||
| <div class="sect1"> | ||
| <h2 id="_usage">Usage</h2> | ||
| <div class="sectionbody"> | ||
| <div class="paragraph"> | ||
| <p>Libasciidoc provides 2 functions to convert an Asciidoc content into HTML:</p> | ||
| </div> | ||
| <div class="olist arabic"> | ||
| <ol class="arabic"> | ||
| <li> | ||
| <p>Converting to a complete HTML document:</p> | ||
| <div class="literalblock"> | ||
| <div class="content"> | ||
| <pre>func ConvertToHTML(context.Context, io.Reader, io.Writer, renderer.Options) error</pre> | ||
| </div> | ||
| </div> | ||
| </li> | ||
| <li> | ||
| <p>Converting to a <code>body</code> element only:</p> | ||
| <div class="literalblock"> | ||
| <div class="content"> | ||
| <pre>func ConvertToHTMLBody(context.Context, io.Reader, io.Writer) (*types.DocumentAttributes, error)</pre> | ||
| </div> | ||
| </div> | ||
| </li> | ||
| </ol> | ||
| </div> | ||
| <div class="paragraph"> | ||
| <p>where the returned <code>types.DocumentAttributes</code> object contains the document’s title (which is not rendered in the HTML’s body) and its other attributes.</p> | ||
| </div> | ||
| </div> | ||
| </div> | ||
| <div class="sect1"> | ||
| <h2 id="_how_to_contribute">How to contribute</h2> | ||
| <div class="sectionbody"> | ||
| <div class="paragraph"> | ||
| <p>Please refer to the <a href="http://CONTRIBUTE.adoc">Contribute</a> file.</p> | ||
| </div> | ||
| </div> | ||
| </div> |
Oops, something went wrong.