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