# [RFC PATCH 0/3] doc: document for our use of legacy asciidoc.py 4 messages from 2023-04-05 to 2023-04-05. Participants: Felipe Contreras. Thread: https://gitlist.dev/t/59551 ## Felipe Contreras, 2023-04-05 12:54 Subject: [RFC PATCH 0/3] doc: document for our use of legacy asciidoc.py Message-ID: <20230405125453.49674-1-felipe.contreras@gmail.com> URL: https://gitlist.dev/e/20230405125453.49674-1-felipe.contreras%40gmail.com ``` I see many people confused about the AsciiDoc syntax in the mailing list. The fact that we are using a deprecated syntax [1] of a legacy processor [2] (in fact, considered legacy more than two years ago [3]) that is not maintained anymore, does not help. AsciiDoc.py is a legacy processor for this syntax, handling an older rendition of AsciiDoc. As such, this will not properly handle the current AsciiDoc specification. It is suggested that unless you specifically require the AsciiDoc.py toolchain, you should find a processor that handles the modern AsciiDoc syntax. But we refuse to move on and keep on carrying patches that were needed only 15 years ago [4] and not today, or worse: patches that were considered ancient in 2009 [5], never mind now. Because we don't use the modern syntax, the canonical documentation [6] is only partially useful. Therefore we need documentation specific to us. This patch series attempts to start that documentation. [1] https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/ [2] https://asciidoc-py.github.io/ [3] https://github.com/asciidoc-py/asciidoc-py/pull/175/files [4] https://lore.kernel.org/git/20230323221523.52472-1-felipe.contreras@gmail.com/ [5] https://lore.kernel.org/git/20230322000815.132128-1-felipe.contreras@gmail.com/ [6] https://docs.asciidoctor.org/asciidoc/latest Felipe Contreras (3): doc: add documentation guideline doc: use deprecated syntax in doc guideline doc: asciidoc.py workarounds for doc guideline Documentation/DocumentationGuideline.adoc | 194 ++++++++++++++++++++++ Documentation/Makefile | 3 + 2 files changed, 197 insertions(+) create mode 100644 Documentation/DocumentationGuideline.adoc -- 2.40.0+fc1 ``` ## Felipe Contreras, 2023-04-05 12:54 Subject: [RFC PATCH 1/3] doc: add documentation guideline Message-ID: <20230405125453.49674-2-felipe.contreras@gmail.com> URL: https://gitlist.dev/e/20230405125453.49674-2-felipe.contreras%40gmail.com In-Reply-To: <20230405125453.49674-1-felipe.contreras@gmail.com> ``` Most of the documentation is in asciidoc, and nowhere in our documentation is described how best to use it. Signed-off-by: Felipe Contreras --- Documentation/DocumentationGuideline.adoc | 195 ++++++++++++++++++++++ Documentation/Makefile | 3 + 2 files changed, 198 insertions(+) create mode 100644 Documentation/DocumentationGuideline.adoc diff --git a/Documentation/DocumentationGuideline.adoc b/Documentation/DocumentationGuideline.adoc new file mode 100644 index 0000000000..940c09c905 --- /dev/null +++ b/Documentation/DocumentationGuideline.adoc @@ -0,0 +1,195 @@ += Documentation Guideline +:1: https://docs.asciidoctor.org/asciidoc/latest/ +:2: https://docs.asciidoctor.org/asciidoc/latest/subs/special-characters/ +:3: https://docs.asciidoctor.org/asciidoc/latest/text/troubleshoot-unconstrained-formatting/ +:4: https://docs.asciidoctor.org/asciidoc/latest/text/literal-monospace/ +:5: https://lore.kernel.org/git/pull.1304.git.git.1659387885711.gitgitgadget@gmail.com/[[PATCH\\] Documentation/git-reflog: remove unneeded \ from \{] +:6: https://lore.kernel.org/git/CABPp-BEEDS%3Dv7ouOKts83OFMxDq%3DF0TKO1XvHEbnmXJ+Z1WELA@mail.gmail.com/[Re: [PATCH\\] git-merge-tree.txt: replace spurious HTML entity] + +Documents shall follow the AsciiDoc format, a simple markup language specified in the {1}[AsciiDoc Language +Documentation]. + +---- +This is a basic document. +---- + +Documents simply contain normal text, except this text will be interpreted using various rules. + +---- +This is a line which contains special characters: < > & +---- + +The tools used to generate the documentation will convert these special characters when appropriate, for example for +HTML they will be converted to `\< \> \&`, so you don't have to worry about that (for reference check +{2}[Special Character Substitutions]). + +Formatting can be easily added: + +---- +When all else fails, do `git reset --hard`. +---- + +This will render as: + +==== +When all else fails, do `git reset --hard`. +==== + +Therefore one must be careful when using certain characters as they may be interpreted as formatting marks. All of these +are special characters: `pass:[_ * ` ^ ~ ']`. For a detailed explanation and examples of troubleshooting edge cases see +{3}[Troubleshoot Unconstrained Formatting Pairs]. + +== Titles + +Titles is how you organize your document, you can have as many sections as you like, but only one document title (level +0 title). + +---- += Document Title (level 0) + +This is a document introduction. + +== Section Title (level 1) + +This is a section introduction. +---- + +== Description Lists + +Description list are used to describe a list of things, for example options: + +---- +-v:: verbose +-h:: help +-q:: quiet +-f:: force +---- + +Renders as: + +==== +-v:: verbose +-h:: help +-q:: quiet +-f:: force +==== + +== Listing Blocks + +Often you'll want to include example code, for that you can use listing blocks: + +----- +---- +__attribute__((format (printf, 2, 3))) +void fprintf_or_die(FILE *, const char *fmt, ...); +---- +----- + +Renders as: + +==== +---- +__attribute__((format (printf, 2, 3))) +void fprintf_or_die(FILE *, const char *fmt, ...); +---- +==== + +Anything inside them is literal, so you don't need to escape it. + +If the code is a single line, you can use a single or more spaces of indentation: + + {space}$ cat .git/HEAD >&2 + +==== + $ cat .git/HEAD >&2 +==== + +== Links + +To link to other parts of the documentation, use the `link` macro: + +---- +For more information see link:CodingGuidelines.html[Coding Guidelines]. +---- + +==== +For more information see link:CodingGuidelines.html[Coding Guidelines]. +==== + +To link to a manpage, use the `linkgit` macro: + +---- +linkgit:git-config[1] +---- + +==== +linkgit:git-config[1] +==== + +External links don't use a macro: + +---- +https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation] +---- + +==== +https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation] +==== + +== Caveats + +Because the format is so straightforward, one might be tempted to forget that we are using a markup language, but it is +a language, and certain strings have certain interpretations, for example `+{tilde}+` is going to be substituted with the +`tilde` attribute (`~`). + +So one can't just use `+{foo}+` haphazardly, these texts have to be escaped. For example with `+\{foo}+`. So one should +write `+master@\{upstream}+`. However, other texts, such as `{}` can't be attributes, so escaping would show the +backspace. + +To avoid all these problems, one should use literals `pass:[+foo+]`. + +---- +* {} +* \{} +* {tilde} +* \{tilde} +* +{tilde}+ +* +{}+ +---- + +Renders as: + +==== +* {} +* \{} +* {tilde} +* \{tilde} +* +{tilde}+ +* +{}+ +==== + +However, more often than not what we want to show is `+{tilde}+`, not +{tilde}+, so in those cases what we want is +literal monospace text, so we have to add backticks: `pass:[`+{tilde}+`]`. For more information see {4}[Literal +Monospace]. + +This isn't theoretical, developers have been confused by this.footnote:[{5}] + +There are other replacements, such as `+<=+` replaced with `<=`. Which again: has confused people.footnote:[{6}] + +So when in doubt just use literal monospace. + +=== There's more + +But what happens if the literal text contains `{backtick}` or `{plus}`? In those cases you can use the inline `pass` macro: + +---- +The following characters must be encoded: `pass:[~!@#$^&*(){}\;",<>?'`+]`. +---- + +==== +The following characters must be encoded: `pass:[~!@#$^&*(){}\;",<>?'`+]`. +==== + +--- + +This should cover the basics, but there's no substitute to {1}[RTFM]. diff --git a/Documentation/Makefile b/Documentation/Makefile index a6ba5bd460..59b64a6d5e 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -372,6 +372,9 @@ $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.tx SubmittingPatches.txt: SubmittingPatches $(QUIET_GEN) cp $< $@ +%.html : %.adoc + asciidoctor -I . -r asciidoctor-extensions.rb -o $@ $< + XSLT = docbook.xsl XSLTOPTS = XSLTOPTS += --xinclude -- 2.40.0+fc1 ``` ## Felipe Contreras, 2023-04-05 12:54 Subject: [RFC PATCH 2/3] doc: use deprecated syntax in doc guideline Message-ID: <20230405125453.49674-3-felipe.contreras@gmail.com> URL: https://gitlist.dev/e/20230405125453.49674-3-felipe.contreras%40gmail.com In-Reply-To: <20230405125453.49674-1-felipe.contreras@gmail.com> ``` Everyone has moved on but us. Signed-off-by: Felipe Contreras --- Documentation/DocumentationGuideline.adoc | 26 +++++++++++------------ Documentation/Makefile | 2 +- 2 files changed, 13 insertions(+), 15 deletions(-) diff --git a/Documentation/DocumentationGuideline.adoc b/Documentation/DocumentationGuideline.adoc index 940c09c905..8f1300f898 100644 --- a/Documentation/DocumentationGuideline.adoc +++ b/Documentation/DocumentationGuideline.adoc @@ -20,7 +20,7 @@ This is a line which contains special characters: < > & ---- The tools used to generate the documentation will convert these special characters when appropriate, for example for -HTML they will be converted to `\< \> \&`, so you don't have to worry about that (for reference check +HTML they will be converted to `< > &`, so you don't have to worry about that (for reference check {2}[Special Character Substitutions]). Formatting can be easily added: @@ -139,22 +139,22 @@ https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation] == Caveats Because the format is so straightforward, one might be tempted to forget that we are using a markup language, but it is -a language, and certain strings have certain interpretations, for example `+{tilde}+` is going to be substituted with the +a language, and certain strings have certain interpretations, for example `{tilde}` is going to be substituted with the `tilde` attribute (`~`). -So one can't just use `+{foo}+` haphazardly, these texts have to be escaped. For example with `+\{foo}+`. So one should -write `+master@\{upstream}+`. However, other texts, such as `{}` can't be attributes, so escaping would show the +So one can't just use `{foo}` haphazardly, these texts have to be escaped. For example with `\{foo}`. So one should +write `master@\{upstream}`. However, other texts such as `{}` can't be attributes, so escaping would show the backspace. -To avoid all these problems, one should use literals `pass:[+foo+]`. +To avoid all these problems, one should use literals `pass:[`foo`]`. ---- * {} * \{} * {tilde} * \{tilde} -* +{tilde}+ -* +{}+ +* `{tilde}` +* `{}` ---- Renders as: @@ -164,23 +164,21 @@ Renders as: * \{} * {tilde} * \{tilde} -* +{tilde}+ -* +{}+ +* `{tilde}` +* `{}` ==== -However, more often than not what we want to show is `+{tilde}+`, not +{tilde}+, so in those cases what we want is -literal monospace text, so we have to add backticks: `pass:[`+{tilde}+`]`. For more information see {4}[Literal -Monospace]. +For more information see {4}[Literal Monospace]. This isn't theoretical, developers have been confused by this.footnote:[{5}] -There are other replacements, such as `+<=+` replaced with `<=`. Which again: has confused people.footnote:[{6}] +There are other replacements, such as `<=` replaced with `⇐`. Which again: has confused people.footnote:[{6}] So when in doubt just use literal monospace. === There's more -But what happens if the literal text contains `{backtick}` or `{plus}`? In those cases you can use the inline `pass` macro: +But what happens if the literal text contains `pass:[`]`? In those cases you can use the inline `pass` macro: ---- The following characters must be encoded: `pass:[~!@#$^&*(){}\;",<>?'`+]`. diff --git a/Documentation/Makefile b/Documentation/Makefile index 59b64a6d5e..bb29a0c87f 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -373,7 +373,7 @@ SubmittingPatches.txt: SubmittingPatches $(QUIET_GEN) cp $< $@ %.html : %.adoc - asciidoctor -I . -r asciidoctor-extensions.rb -o $@ $< + asciidoctor -I . -r asciidoctor-extensions.rb -a compat-mode -o $@ $< XSLT = docbook.xsl XSLTOPTS = -- 2.40.0+fc1 ``` ## Felipe Contreras, 2023-04-05 12:54 Subject: [RFC PATCH 3/3] doc: asciidoc.py workarounds for doc guideline Message-ID: <20230405125453.49674-4-felipe.contreras@gmail.com> URL: https://gitlist.dev/e/20230405125453.49674-4-felipe.contreras%40gmail.com In-Reply-To: <20230405125453.49674-1-felipe.contreras@gmail.com> ``` asciidoc.py for some reason can't handle one URL, and doesn't understand listings inside listings (of obvious different levels). Signed-off-by: Felipe Contreras --- Documentation/DocumentationGuideline.adoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Documentation/DocumentationGuideline.adoc b/Documentation/DocumentationGuideline.adoc index 8f1300f898..a581c47f05 100644 --- a/Documentation/DocumentationGuideline.adoc +++ b/Documentation/DocumentationGuideline.adoc @@ -4,7 +4,7 @@ :3: https://docs.asciidoctor.org/asciidoc/latest/text/troubleshoot-unconstrained-formatting/ :4: https://docs.asciidoctor.org/asciidoc/latest/text/literal-monospace/ :5: https://lore.kernel.org/git/pull.1304.git.git.1659387885711.gitgitgadget@gmail.com/[[PATCH\\] Documentation/git-reflog: remove unneeded \ from \{] -:6: https://lore.kernel.org/git/CABPp-BEEDS%3Dv7ouOKts83OFMxDq%3DF0TKO1XvHEbnmXJ+Z1WELA@mail.gmail.com/[Re: [PATCH\\] git-merge-tree.txt: replace spurious HTML entity] +:6: https://lore.kernel.org/git/CAMP44s3Kqyrdavp1OiozNbA7k4EHCj0KiQq4d2Dyg_KZSEAUuQ@mail.gmail.com/[Re: [PATCH\\] git-merge-tree.txt: replace spurious HTML entity] Documents shall follow the AsciiDoc format, a simple markup language specified in the {1}[AsciiDoc Language Documentation]. @@ -78,12 +78,13 @@ Renders as: Often you'll want to include example code, for that you can use listing blocks: ------ +[listing] +.... ---- __attribute__((format (printf, 2, 3))) void fprintf_or_die(FILE *, const char *fmt, ...); ---- ------ +.... Renders as: -- 2.40.0+fc1 ```