[RFC,1/3] doc: add documentation guideline

Commit Message

Felipe Contreras April 5, 2023, 12:54 p.m. UTC

Most of the documentation is in asciidoc, and nowhere in our
documentation is described how best to use it.

Signed-off-by: Felipe Contreras <[e-mail]>
---
 Documentation/DocumentationGuideline.adoc | 195 ++++++++++++++++++++++
 Documentation/Makefile                    |   3 +
 2 files changed, 198 insertions(+)
 create mode 100644 Documentation/DocumentationGuideline.adoc

Patch

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/[e-mail]/[[PATCH\\] Documentation/git-reflog: remove unneeded \ from \{]
+:6: https://lore.kernel.org/git/[e-mail]/[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 `\&lt; \&gt; \&amp;`, 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 `{<foo>}` can't be attributes, so escaping would show the
+backspace.
+
+To avoid all these problems, one should use literals `pass:[+foo+]`.
+
+----
+* {<tilde>}
+* \{<tilde>}
+* {tilde}
+* \{tilde}
+* +{tilde}+
+* +{<tilde>}+
+----
+
+Renders as:
+
+====
+* {<tilde>}
+* \{<tilde>}
+* {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].
+
+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