diff options
| -rw-r--r-- | .reuse/dep5 | 8 | ||||
| -rw-r--r-- | README | 240 | ||||
| l--------- | README.adoc | 1 | ||||
| -rw-r--r-- | README.md | 236 | ||||
| l--------- | _doc/index.adoc | 1 | ||||
| l--------- | _doc/index.md | 1 |
6 files changed, 243 insertions, 244 deletions
diff --git a/.reuse/dep5 b/.reuse/dep5 index 1f269e1..7c8da4b 100644 --- a/.reuse/dep5 +++ b/.reuse/dep5 @@ -1,7 +1,7 @@ Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ -Upstream-Name: ciigo +Upstream-Name: asciidoctor-go Upstream-Contact: Shulhan <ms@kilabit.info> -Source: https://git.sr.ht/~shulhan/ciigo +Source: https://git.sr.ht/~shulhan/asciidoctor-go Files: testdata/* Copyright: 2022 Shulhan <ms@kilabit.info> @@ -10,3 +10,7 @@ License: GPL-3.0-or-later Files: go.sum Copyright: 2020 Shulhan <ms@kilabit.info> License: GPL-3.0-or-later + +Files: README.md +Copyright: 2020 Shulhan <ms@kilabit.info> +License: GPL-3.0-or-later @@ -1,240 +0,0 @@ -// SPDX-FileCopyrightText: 2020 M. Shulhan <ms@kilabit.info> -// SPDX-License-Identifier: GPL-3.0-or-later -= asciidoctor-go -Shulhan <ms@kilabit.info> -:toc: -:sectanchors: -:sectlinks: -:url_ref: https://docs.asciidoctor.org/asciidoc/latest - -The asciidoctor-go is the Go module to parse the -https://asciidoctor.org/docs/what-is-asciidoc[AsciiDoc markup^] -and convert it into HTML5. - -== Documentation - -https://pkg.go.dev/git.sr.ht/~shulhan/asciidoctor-go[Go documentation^]. - -=== Specifications - -During reverse engineering the AsciiDoc markup, we write the syntax, rules, -and format in -link:SPECS.html[this document^]. - -=== Features - -List of available formatting that are supported on current implementation. -Each supported feature is linked to official -{url_ref}[AsciiDoc Language Documentation^]. -The numbered one is based on the old documentation. - -* {url_ref}/document/header/[Document header^] -** {url_ref}/document/header/document/title/[Document title^]. This including - meta `doctitle`, `showtitle!` and subtitle. -** {url_ref}/document/author-information/[Author information^] -** {url_ref}/document/revision-information/[Revision information^] -** {url_ref}/document/metadata/[Metadata^] -* {url_ref}/blocks/preamble-and-lead/[Preamble^] -* 16. Sections -** 16.1. Titles as HTML headings -** 16.2. Auto-generated IDs -** 16.3. Custom IDs -** 16.4. Multiple Anchors -** 16.5. Links -** 16.6. Anchors -** 16.7. Numbering -** 16.8. Discrete headings -* 17. Blocks -** 17.1. Title -** 17.2. Metadata -** 17.3. Delimited blocks -* 18. Paragraph -** 18.1. Alignment -** 18.2. Line breaks (" +\n") -** 18.3. Lead style -* 19. Text formatting -** 19.1. Bold and italic -** 19.2. Quotation Marks and Apostrophes -** 19.3. Subscript and Superscript -** 19.4. Monospace -* 20. Unordered Lists -** 20.1. Nested -** 20.2. Complex List Content -** 20.3. Custom Markers -** 20.4. Checklist -* 21. Ordered Lists -** 21.1. Nested -** 21.2. Numbering Styles -* 22. Description List -** 22.1. Question and Answer Style List -* 23. Tables -** 23.1. Columns -** 23.2. Column formatting -** 23.3. Cell formatting -** 23.4. Header row -** 23.5. Footer row -** 23.6. Table width -** 23.7. Table borders -** 24.8. Striping -** 24.9. Orientation -** ~~24.10. Nested tables~~ -** 24.11. Table caption -** 24.12. Escaping the Cell Separator -* 24. Horizontal Rules -** 24.1. Markdown-style horizontal rules -* 25. Page Break -* 26. URLs -** 26.1. Link to Relative Files -* 27. Cross References -** 27.1. Automatic Anchors -** 27.2. Defining an Anchor -** 27.3. Internal Cross References -** 27.5. Customizing the Cross Reference Text -* https://docs.asciidoctor.org/asciidoc/latest/macros/footnote/[Footnotes] -* 28. Include Directive -** 28.1. Anatomy -** 28.2. Processing -** 28.3. File resolution -* 29. Images -* 30. Video -** 30.1. YouTube and Vimeo videos -** 30.2. Supported Attributes -* 31. Audio -* 32. Admonition -* 33. Sidebar -* 34. Example -* 35. Prose Excerpts, Quotes and Verses -** 35.1. Quote -** 35.2. Verse -* 36. Comments -* 37. Text Substitutions -** 37.1. Special Characters -** 37.2. Quotes -** 37.3. Attributes (reference) -** 37.4. Replacements -** 37.9. Preventing Substitutions -* 39. Listing Blocks -* 40. Passthroughs -** 40.2. Passthrough Blocks -* 41. Open Blocks -* A.3. Predefined Attributes for Character Replacements - -Supported metadata or attribute references, - -* `author(_x)` -* `authorinitials(_x)` -* `doctitle` -* `email(_x)` -* `firstname(_x)` -* `idprefix` -* `idseparator` -* `lastname(_x)` -* `last-update-label` -* `middlename(_x)` -* `nofooter` -* `noheader` -* `revdate` -* `revnumber` -* `revremark` -* `sectids` -* `sectnumlevels` -* `sectnums` -* `showtitle` -* `table-caption` -* `title-separator` -* `version-label` - - -Additional metadata provides by this library, - -* `author_names` - list of author full names separated by comma. - - -The following markup will not supported because its functionality is duplicate -with others markup or not secure, - -* 14. Header -** 14.4. Subtitle partitioning. - Rationale: duplicate with 14.1.2 the "Main: sub" format - -* 23. Tables -** 23.10. Nested tables. - Rationale: nested table is not a good way to present information. - Never should it be. -** Using different cell separator - -* 28. Include Directive -** 28.6. Select Portions of a Document to Include. - Rationale: the parser would need to know the language to be included and - parse the whole source code to check for comments and tags. -** 28.8. Include Content from a URI. - Rationale: security and unreliable network connections. -** 28.9. Caching URI Content - - -=== TODO - -List of features which may be implemented, - -* 16. Sections -** 16.9. Section styles -* 18. Paragraph -** 18.2. Line breaks -*** Per block "[%hardbreaks]" -*** All document ":hardbreaks:" -* 19. Text formatting -** 19.5. Custom Styling With Attributes -* 23. Tables -** 23.13. Delimiter-Separated Values -* 27. Cross References -** 27.6. Inter-document Cross References -* 28. Include Directive -** 28.4. Partitioning large documents and using leveloffset -** 28.5. AsciiDoc vs non-AsciiDoc files -** 28.7. Normalize Block Indentation -** 28.10. Include a File Multiple Times in the Same Document -** 28.11. Using an Include in a List Item -* 37. Text Substitutions -** 37.5. Macros -** 37.8. Incremental Substitutions -* 40. Passthroughs -** 40.1. Passthrough Macros - - -==== BUGS - -Unknown. - - -==== ENHANCEMENTS - -* Create tree that link Include directive. - Once the included files changes, the parent should be rendered too. -+ --- - Include Node - parent -> Parent Node. --- - - -=== Miscellaneous - -link:CHANGELOG.html[Changelog]. - -The following files compare the HTML generated by asciidoctor and this -library: - -* link:testdata/test.exp.html[HTML file generated using asciidoctor^] -* link:testdata/test.got.html[HTML file using this library^] - - -== Development - -https://git.sr.ht/~shulhan/asciidoctor-go[Repository^]:: -Link to the source code. - -https://lists.sr.ht/~shulhan/asciidoctor-go[Mailing list^]:: -Link to discussion or where to send the patches. - -https://todo.sr.ht/~shulhan/asciidoctor-go[Issues^]:: -Link to open an issue or request for new feature. diff --git a/README.adoc b/README.adoc deleted file mode 120000 index 100b938..0000000 --- a/README.adoc +++ /dev/null @@ -1 +0,0 @@ -README
\ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..90faadb --- /dev/null +++ b/README.md @@ -0,0 +1,236 @@ +# asciidoctor-go + +Author: [Shulhan](mailto:ms@kilabit.info) + +The asciidoctor-go is the Go module to parse the +[AsciiDoc markup](https://asciidoctor.org/docs/what-is-asciidoc) +and convert it into HTML5. + +## Documentation + +[Go documentation](https://pkg.go.dev/git.sr.ht/~shulhan/asciidoctor-go). + +### Specifications + +During reverse engineering the AsciiDoc markup, we write the syntax, rules, +and format in +[SPECS](SPECS.html). + +### Features + +List of available formatting that are supported on current implementation. +Each supported feature is linked to official +[AsciiDoc Language Documentation](https://docs.asciidoctor.org/asciidoc/latest) +The numbered one is based on the old documentation. + +* [Document header](https://docs.asciidoctor.org/asciidoc/latest/document/header/) + * [Document title](https://docs.asciidoctor.org/asciidoc/latest/document/header/document/title/). + This including meta `doctitle`, `showtitle!` and subtitle. + * [Author information](https://docs.asciidoctor.org/asciidoc/latest/document/author-information/) + * [Revision information](https://docs.asciidoctor.org/asciidoc/latest/document/revision-information/) + * [Metadata](https://docs.asciidoctor.org/asciidoc/latest/document/metadata/) +* [Preamble](https://docs.asciidoctor.org/asciidoc/latest/blocks/preamble-and-lead/) +* 16. Sections + * 16.1. Titles as HTML headings + * 16.2. Auto-generated IDs + * 16.3. Custom IDs + * 16.4. Multiple Anchors + * 16.5. Links + * 16.6. Anchors + * 16.7. Numbering + * 16.8. Discrete headings +* 17. Blocks + * 17.1. Title + * 17.2. Metadata + * 17.3. Delimited blocks +* 18. Paragraph + * 18.1. Alignment + * 18.2. Line breaks (" +\n") + * 18.3. Lead style +* 19. Text formatting + * 19.1. Bold and italic + * 19.2. Quotation Marks and Apostrophes + * 19.3. Subscript and Superscript + * 19.4. Monospace +* 20. Unordered Lists + * 20.1. Nested + * 20.2. Complex List Content + * 20.3. Custom Markers + * 20.4. Checklist +* 21. Ordered Lists + * 21.1. Nested + * 21.2. Numbering Styles +* 22. Description List + * 22.1. Question and Answer Style List +* 23. Tables + * 23.1. Columns + * 23.2. Column formatting + * 23.3. Cell formatting + * 23.4. Header row + * 23.5. Footer row + * 23.6. Table width + * 23.7. Table borders + * 24.8. Striping + * 24.9. Orientation + * ~~24.10. Nested tables~~ + * 24.11. Table caption + * 24.12. Escaping the Cell Separator +* 24. Horizontal Rules + * 24.1. Markdown-style horizontal rules +* 25. Page Break +* 26. URLs + * 26.1. Link to Relative Files +* 27. Cross References + * 27.1. Automatic Anchors + * 27.2. Defining an Anchor + * 27.3. Internal Cross References + * 27.5. Customizing the Cross Reference Text +* [Footnotes](https://docs.asciidoctor.org/asciidoc/latest/macros/footnote/) +* 28. Include Directive + * 28.1. Anatomy + * 28.2. Processing + * 28.3. File resolution +* 29. Images +* 30. Video + * 30.1. YouTube and Vimeo videos + * 30.2. Supported Attributes +* 31. Audio +* 32. Admonition +* 33. Sidebar +* 34. Example +* 35. Prose Excerpts, Quotes and Verses + * 35.1. Quote + * 35.2. Verse +* 36. Comments +* 37. Text Substitutions + * 37.1. Special Characters + * 37.2. Quotes + * 37.3. Attributes (reference) + * 37.4. Replacements + * 37.9. Preventing Substitutions +* 39. Listing Blocks +* 40. Passthroughs + * 40.2. Passthrough Blocks +* 41. Open Blocks +* A.3. Predefined Attributes for Character Replacements + +Supported metadata or attribute references, + +* `author(_x)` +* `authorinitials(_x)` +* `doctitle` +* `email(_x)` +* `firstname(_x)` +* `idprefix` +* `idseparator` +* `lastname(_x)` +* `last-update-label` +* `middlename(_x)` +* `nofooter` +* `noheader` +* `revdate` +* `revnumber` +* `revremark` +* `sectids` +* `sectnumlevels` +* `sectnums` +* `showtitle` +* `table-caption` +* `title-separator` +* `version-label` + + +Additional metadata provides by this library, + +* `author_names` - list of author full names separated by comma. + + +The following markup will not supported because its functionality is duplicate +with others markup or not secure, + +* 14. Header + * 14.4. Subtitle partitioning. + Rationale: duplicate with 14.1.2 the "Main: sub" format + +* 23. Tables + * 23.10. Nested tables. + Rationale: nested table is not a good way to present information. + Never should it be. + * Using different cell separator + +* 28. Include Directive + * 28.6. Select Portions of a Document to Include. + Rationale: the parser would need to know the language to be included and + parse the whole source code to check for comments and tags. + * 28.8. Include Content from a URI. + Rationale: security and unreliable network connections. + * 28.9. Caching URI Content + + +### TODO + +List of features which may be implemented, + +* 16. Sections + * 16.9. Section styles +* 18. Paragraph + * 18.2. Line breaks + * Per block "[%hardbreaks]" + * All document ":hardbreaks:" +* 19. Text formatting + * 19.5. Custom Styling With Attributes +* 23. Tables + * 23.13. Delimiter-Separated Values +* 27. Cross References + * 27.6. Inter-document Cross References +* 28. Include Directive + * 28.4. Partitioning large documents and using leveloffset + * 28.5. AsciiDoc vs non-AsciiDoc files + * 28.7. Normalize Block Indentation + * 28.10. Include a File Multiple Times in the Same Document + * 28.11. Using an Include in a List Item +* 37. Text Substitutions + * 37.5. Macros + * 37.8. Incremental Substitutions +* 40. Passthroughs + * 40.1. Passthrough Macros + + +#### Bugs + +Unknown. +If you found one, please report it +[here](https://todo.sr.ht/~shulhan/asciidoctor-go). + + +#### Enhancements + +Create tree that link Include directive. +Once the included files changes, the parent should be re-converted too. + +``` +Include Node +parent -> Parent Node. +``` + +### Miscellaneous + +[Changelog](CHANGELOG.html). + +The following files compare the HTML generated by asciidoctor and this +library: + +* [HTML file generated using asciidoctor](testdata/test.exp.html) +* [HTML file using this library](testdata/test.got.html) + + +## Development + +[Repository](https://git.sr.ht/~shulhan/asciidoctor-go):: +Link to the source code. + +[Mailing list](https://lists.sr.ht/~shulhan/asciidoctor-go):: +Link to discussion or where to send the patches. + +[Issues](https://todo.sr.ht/~shulhan/asciidoctor-go):: +Link to open an issue or request for new feature. diff --git a/_doc/index.adoc b/_doc/index.adoc deleted file mode 120000 index 59a23c4..0000000 --- a/_doc/index.adoc +++ /dev/null @@ -1 +0,0 @@ -../README
\ No newline at end of file diff --git a/_doc/index.md b/_doc/index.md new file mode 120000 index 0000000..32d46ee --- /dev/null +++ b/_doc/index.md @@ -0,0 +1 @@ +../README.md
\ No newline at end of file |