all: reformat the README back to asciidoc

This change use file name "README" for serving it in sr.ht, since the
site does not support rendering asciidoc.

The index.adoc is provided as symlink to README.

While at it, add list of BUGS and ENHANCEMENTS under TODO sections;
link to CHANGELOG, and other files.

5 files changed, 229 insertions, 187 deletions

diff --git a/.gitignore b/.gitignore
index 412ef07..561d23f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,5 @@
 // SPDX-FileCopyrightText: 2020 M. Shulhan <ms@kilabit.info>
 // SPDX-License-Identifier: GPL-3.0-or-later
+*.html
 cover.html
 cover.out
diff --git a/Makefile b/Makefile
index 29948b1..fff4d50 100644
--- a/Makefile
+++ b/Makefile
@@ -1,7 +1,7 @@
 ## SPDX-FileCopyrightText: 2020 M. Shulhan <ms@kilabit.info>
 ## SPDX-License-Identifier: GPL-3.0-or-later
 
-.PHONY: all lint
+.PHONY: all lint test-parser serve-doc
 
 all: lint test
 
@@ -16,3 +16,6 @@ test:
 test-parser:
 	asciidoctor --attribute stylesheet=empty.css testdata/test.adoc
 	go test -v -run=Open .
+
+serve-doc:
+	ciigo serve .
diff --git a/README b/README
new file mode 100644
index 0000000..56a5279
--- /dev/null
+++ b/README
@@ -0,0 +1,223 @@
+// 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:
+
+The asciidoctor-go is the Go module to parse the
+https://asciidoctor.org/docs/what-is-asciidoc[AsciiDoc markup^]
+and convert it into HTML5.
+
+== 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,
+numbered based on
+https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation^].
+
+* 14. Header
+** 14.1. Document title
+*** 14.1.1. doctitle attribute
+*** 14.1.2. Document subtitle
+*** 14.1.3. Document title visibility
+** 14.2. Author and email
+** 14.3. Revision number, date
+** 14.5. Metadata
+*** 14.5.1. Description
+*** 14.5.2. Keywords
+* 15. 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
+* 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)`
+* `middlename(_x)`
+* `nofooter`
+* `noheader`
+* `revdate`
+* `revnumber`
+* `revremark`
+* `sectids`
+* `sectnumlevels`
+* `sectnums`
+* `showtitle`
+* `table-caption`
+* `title-separator`
+* `version-label`
+
+
+==  TODO
+
+List of features which will 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
+
+* Comment above heading 1 with space cause the heading not parsed.
+
+* Comment start with white spaces is not parsed correctly.
+
+=== ENHANCEMENTS
+
+* Create tree that link Include directive.
+  Once the included files changes, the parent should be rendered too.
++
+--
+	Include Node
+	parent -> Parent Node.
+--
+
+
+==  Not supported
+
+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
+
+
+==  Miscellaneous
+
+link:CHANGELOG.html[Changelog].
+
+The following files compare the HTML generated by asciidoctor and this
+library:
+
+* link:testdata/test.html[HTML file generated using asciidoctor^]
+* link:testdata/got.test.html[HTML file using this library^]
diff --git a/README.md b/README.md
deleted file mode 100644
index 3d5c1ef..0000000
--- a/README.md
+++ /dev/null
@@ -1,186 +0,0 @@
-// SPDX-FileCopyrightText: 2020 M. Shulhan <ms@kilabit.info>
-// SPDX-License-Identifier: GPL-3.0-or-later
-# asciidoctor-go
-
-Shulhan <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.
-
-## Features
-
-List of available formatting that are supported on current implementation,
-numbered based on
-[AsciiDoc user manual](https://asciidoctor.org/docs/user-manual/),
-
-* 14. Header
-  * 14.1. Document title
-    * 14.1.1. doctitle attribute
-    * 14.1.2. Document subtitle
-    * 14.1.3. Document title visibility
-  * 14.2. Author and email
-  * 14.3. Revision number, date
-  * 14.5. Metadata
-    * 14.5.1. Description
-    * 14.5.2. Keywords
-* 15. 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
-* 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)`
-* `middlename(_x)`
-* `nofooter`
-* `noheader`
-* `revdate`
-* `revnumber`
-* `revremark`
-* `sectids`
-* `sectnumlevels`
-* `sectnums`
-* `showtitle`
-* `table-caption`
-* `title-separator`
-* `version-label`
-
-
-##  TODO
-
-List of features which will 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
-
-
-## Not supported
-
-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
diff --git a/index.adoc b/index.adoc
new file mode 120000
index 0000000..100b938
--- /dev/null
+++ b/index.adoc
@@ -0,0 +1 @@
+README
\ No newline at end of file