diff options
| author | Shulhan <ms@kilabit.info> | 2026-01-22 14:15:57 +0700 |
|---|---|---|
| committer | Shulhan <ms@kilabit.info> | 2026-01-22 14:16:22 +0700 |
| commit | b1b5b41d62c7e8fee012be72feec7a66e1bb83e7 (patch) | |
| tree | 5873da72362567c11c3e56862c55c28268f518fd /README.md | |
| parent | 050ae5215ba426a1f2a13dcc5555f9d1b21d9d56 (diff) | |
| download | asciidoctor-go-b1b5b41d62c7e8fee012be72feec7a66e1bb83e7.tar.xz | |
all: reformat README with prettier and simplify license
Instead of showing multiple paragraphs of license text, display it with
single line.
While at it, embed the SPDX license directly instead of using REUSE.toml.
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 348 |
1 files changed, 166 insertions, 182 deletions
@@ -1,3 +1,6 @@ +<!-- SPDX-FileCopyrightText: 2020 M. Shulhan <ms@kilabit.info> --> +<!-- SPDX-License-Identifier: GPL-3.0-or-later --> + # asciidoctor-go The asciidoctor-go is the Go module to parse the @@ -8,8 +11,7 @@ For the front-end tooling that use this library to build static website see [ciigo](https://sr.ht/~shulhan/ciigo). - -## Documentation +## Documentation See the [Go module documentation](https://pkg.go.dev/git.sr.ht/~shulhan/asciidoctor-go) @@ -20,170 +22,166 @@ During reverse engineering the AsciiDoc markup, we write the syntax, rules, and format in [specification file](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) -* [Document header](https://docs.asciidoctor.org/asciidoc/latest/document/header/) - * [Document title](https://docs.asciidoctor.org/asciidoc/latest/document/title/). +- [Document header](https://docs.asciidoctor.org/asciidoc/latest/document/header/) + - [Document title](https://docs.asciidoctor.org/asciidoc/latest/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/) -* Sections - * Titles as HTML headings - * Auto-generated IDs - * Custom IDs - * Multiple Anchors - * Links - * Anchors - * Numbering - * Discrete headings -* Blocks - * Title - * Metadata - * Delimited blocks -* Paragraph - * Alignment - * Line breaks (" +\n") - * Lead style -* Text formatting - * Bold and italic - * Quotation Marks and Apostrophes - * Subscript and Superscript - * Monospace -* Lists √ - * [Unordered Lists](https://docs.asciidoctor.org/asciidoc/latest/lists/unordered/) √ (see Notes below) - * Basic unordered list √ - * Nested unordered list √ - * Markers √ - * Default markers √ - * Custom markers √ - * [Ordered Lists](https://docs.asciidoctor.org/asciidoc/latest/lists/ordered/) √ - * Basic ordered list √ - * Nested ordered list √ - * Number styles √ - * [Checklists](https://docs.asciidoctor.org/asciidoc/latest/lists/checklist/) √ - * [Separating Lists](https://docs.asciidoctor.org/asciidoc/latest/lists/separating/) √ -* Description Lists - * [Description Lists](https://docs.asciidoctor.org/asciidoc/latest/lists/description/) - * Basic description list √ - * Mixing lists √ - * Nested description list √ - * Question and Answer Lists √ -* Tables - * Columns - * Column formatting - * Cell formatting - * Header row - * Footer row - * Table width - * Table borders - * Striping - * Orientation - * Table caption - * Escaping the Cell Separator -* Horizontal Rules - * Markdown-style horizontal rules -* Page Break -* URLs - * Link to Relative Files -* Cross References - * Automatic Anchors - * Defining an Anchor - * Internal Cross References - * Customizing the Cross Reference Text -* [Footnotes](https://docs.asciidoctor.org/asciidoc/latest/macros/footnote/) -* [Includes](https://docs.asciidoctor.org/asciidoc/latest/directives/include/) -* Images -* Video - * YouTube and Vimeo videos - * Supported Attributes -* Audio -* Admonition -* Sidebar -* Example -* Prose Excerpts, Quotes and Verses - * Quote - * Verse -* Comments -* Text Substitutions - * Special Characters - * Quotes - * Attributes (reference) - * Replacements - * Preventing Substitutions -* Listing Blocks -* Passthroughs - * Passthrough Blocks -* Open Blocks -* Predefined Attributes for Character Replacements + - [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/) +- Sections + - Titles as HTML headings + - Auto-generated IDs + - Custom IDs + - Multiple Anchors + - Links + - Anchors + - Numbering + - Discrete headings +- Blocks + - Title + - Metadata + - Delimited blocks +- Paragraph + - Alignment + - Line breaks (" +\n") + - Lead style +- Text formatting + - Bold and italic + - Quotation Marks and Apostrophes + - Subscript and Superscript + - Monospace +- Lists √ + - [Unordered Lists](https://docs.asciidoctor.org/asciidoc/latest/lists/unordered/) √ (see Notes below) + - Basic unordered list √ + - Nested unordered list √ + - Markers √ + - Default markers √ + - Custom markers √ + - [Ordered Lists](https://docs.asciidoctor.org/asciidoc/latest/lists/ordered/) √ + - Basic ordered list √ + - Nested ordered list √ + - Number styles √ + - [Checklists](https://docs.asciidoctor.org/asciidoc/latest/lists/checklist/) √ + - [Separating Lists](https://docs.asciidoctor.org/asciidoc/latest/lists/separating/) √ +- Description Lists + - [Description Lists](https://docs.asciidoctor.org/asciidoc/latest/lists/description/) + - Basic description list √ + - Mixing lists √ + - Nested description list √ + - Question and Answer Lists √ +- Tables + - Columns + - Column formatting + - Cell formatting + - Header row + - Footer row + - Table width + - Table borders + - Striping + - Orientation + - Table caption + - Escaping the Cell Separator +- Horizontal Rules + - Markdown-style horizontal rules +- Page Break +- URLs + - Link to Relative Files +- Cross References + - Automatic Anchors + - Defining an Anchor + - Internal Cross References + - Customizing the Cross Reference Text +- [Footnotes](https://docs.asciidoctor.org/asciidoc/latest/macros/footnote/) +- [Includes](https://docs.asciidoctor.org/asciidoc/latest/directives/include/) +- Images +- Video + - YouTube and Vimeo videos + - Supported Attributes +- Audio +- Admonition +- Sidebar +- Example +- Prose Excerpts, Quotes and Verses + - Quote + - Verse +- Comments +- Text Substitutions + - Special Characters + - Quotes + - Attributes (reference) + - Replacements + - Preventing Substitutions +- Listing Blocks +- Passthroughs + - Passthrough Blocks +- Open Blocks +- Predefined Attributes for Character Replacements Supported document attribute references, -* `author(_x)` -* `authorinitials(_x)` -* `docdir` -* `doctitle` -* `email(_x)` -* `firstname(_x)` -* `idprefix` -* `idseparator` -* `lastname(_x)` -* `last-update-label` -* [`leveloffset`](https://docs.asciidoctor.org/asciidoc/latest/directives/include-with-leveloffset/). -Only on document attributes, not on include directive. -* `middlename(_x)` -* `nofooter` -* `noheader` -* `revdate` -* `revnumber` -* `revremark` -* `sectids` -* `sectnumlevels` -* `sectnums` -* `showtitle` -* `stylesheet` -* `table-caption` -* `title-separator` -* `version-label` - +- `author(_x)` +- `authorinitials(_x)` +- `docdir` +- `doctitle` +- `email(_x)` +- `firstname(_x)` +- `idprefix` +- `idseparator` +- `lastname(_x)` +- `last-update-label` +- [`leveloffset`](https://docs.asciidoctor.org/asciidoc/latest/directives/include-with-leveloffset/). + Only on document attributes, not on include directive. +- `middlename(_x)` +- `nofooter` +- `noheader` +- `revdate` +- `revnumber` +- `revremark` +- `sectids` +- `sectnumlevels` +- `sectnums` +- `showtitle` +- `stylesheet` +- `table-caption` +- `title-separator` +- `version-label` Additional document attribute provides by this library, -* `author_names` - list of author full names separated by comma. +- `author_names` - list of author full names separated by comma. - -## Notes +## Notes ### Unsupported markup The following markup will not supported either because its functionality is duplicate, or inconsistent with others markup, or not secure, -* Header - * Subtitle partitioning. +- Header + - Subtitle partitioning. Rationale: duplicate with the "Main: sub" format -* Tables - * Nested tables. +- Tables + - Nested tables. Rationale: nested table is not a good way to present information, never should it be. - * Using different cell separator + - Using different cell separator -* Includes - * [Include Content by Tagged Regions](https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/) +- Includes + - [Include Content by Tagged Regions](https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/) Rationale: the parser would need to know the language to be included and parse the whole source code to check for comments and tags. - * [Include Content by URI](https://docs.asciidoctor.org/asciidoc/latest/directives/include-uri/) + - [Include Content by URI](https://docs.asciidoctor.org/asciidoc/latest/directives/include-uri/) Rationale: security and unreliable network connections. - -### Unordered list item with hyphen +### Unordered list item with hyphen The unordered list item with hyphen ('-') cause too much confusion and inconsistency. @@ -211,49 +209,45 @@ simple list item > because the hyphen marker (-) doesn’t work for nested lists. > -- <https://docs.asciidoctor.org/asciidoc/latest/lists/unordered/#basic-unordered-list> - -## TODO +## TODO List of features which may be implemented, -* Sections - * Section styles -* Paragraph - * Line breaks - * Per block "[%hardbreaks]" - * All document ":hardbreaks:" -* Text formatting - * Custom Styling With Attributes -* Tables - * Delimiter-Separated Values -* Cross References - * Inter-document Cross References -* Include Directive - * Offset Section Levels - * Indent Included Content - * Use an Include File Multiple Times - * Include List Item Content - * Include Content by Line Ranges -* Text Substitutions - * Macros - * Incremental Substitutions -* Passthroughs - * Passthrough Macros - +- Sections + - Section styles +- Paragraph + - Line breaks + - Per block "[%hardbreaks]" + - All document ":hardbreaks:" +- Text formatting + - Custom Styling With Attributes +- Tables + - Delimiter-Separated Values +- Cross References + - Inter-document Cross References +- Include Directive + - Offset Section Levels + - Indent Included Content + - Use an Include File Multiple Times + - Include List Item Content + - Include Content by Line Ranges +- Text Substitutions + - Macros + - Incremental Substitutions +- Passthroughs + - Passthrough Macros Future enhancements, -(1) Create tree that link Include directive. -Once the included files changes, the parent should be re-converted too. - +- Create tree that link Include directive. + Once the included files changes, the parent should be re-converted too. -## Bugs +## Bugs Unknown. If you found one, please report it [here](https://todo.sr.ht/~shulhan/asciidoctor-go). - ## Development [Changelog](https://kilabit.info/project/asciidoctor-go/CHANGELOG.html):: @@ -268,20 +262,10 @@ 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. - ## License -Copyright (C) 2021 Shulhan [<ms@kilabit.info>](mailto:ms@kilabit.info) - -This program is free software: you can redistribute it and/or modify it -under the terms of the GNU General Public License as published by the Free -Software Foundation, either version 3 of the License, or (at your option) -any later version. - -This program is distributed in the hope that it will be useful, but WITHOUT -ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for -more details. +Copyright 2021 M. Shulhan +[<ms@kilabit.info>](mailto:ms@kilabit.info). -You should have received a copy of the GNU General Public License along with -this program. If not, see <http://www.gnu.org/licenses/>. +This software is licensed under GNU General Public License version 3.0 or +later. |
