From f3bc802f3978192ad25176a0f9e2c24ac855c23a Mon Sep 17 00:00:00 2001 From: Shulhan Date: Sat, 27 May 2023 23:47:51 +0700 Subject: all: convert README from Asciidoc to Markdown I use two remote repositories: GitHub and SourceHut. GitHub support rendering README using asciidoc while SourceHut not. This cause the repository that use README.adoc rendered as text in SourceHut which make the repository page less readable. Also, the pkg.go.dev now render README but only support Markdown. Since we cannot control the SourceHut and go.dev, the only option is to support converting Markdown in ciigo so I can write README using Markdown and the rest of documentation using Asciidoc. How did Markdown become defactor standard? Its lack comment, creating table of content, macro, and many more. --- .reuse/dep5 | 8 +- README | 240 -------------------------------------------------------- README.adoc | 1 - README.md | 236 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ _doc/index.adoc | 1 - _doc/index.md | 1 + 6 files changed, 243 insertions(+), 244 deletions(-) delete mode 100644 README delete mode 120000 README.adoc create mode 100644 README.md delete mode 120000 _doc/index.adoc create mode 120000 _doc/index.md 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 -Source: https://git.sr.ht/~shulhan/ciigo +Source: https://git.sr.ht/~shulhan/asciidoctor-go Files: testdata/* Copyright: 2022 Shulhan @@ -10,3 +10,7 @@ License: GPL-3.0-or-later Files: go.sum Copyright: 2020 Shulhan License: GPL-3.0-or-later + +Files: README.md +Copyright: 2020 Shulhan +License: GPL-3.0-or-later diff --git a/README b/README deleted file mode 100644 index a4688a7..0000000 --- a/README +++ /dev/null @@ -1,240 +0,0 @@ -// SPDX-FileCopyrightText: 2020 M. Shulhan -// SPDX-License-Identifier: GPL-3.0-or-later -= asciidoctor-go -Shulhan -: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 -- cgit v1.3