Most of the documentation is in asciidoc, and nowhere in our documentation is described how best to use it. Signed-off-by: Felipe Contreras <felipe.contreras@xxxxxxxxx> --- 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@xxxxxxxxx/[[PATCH\\] Documentation/git-reflog: remove unneeded \ from \{] +:6: https://lore.kernel.org/git/CABPp-BEEDS%3Dv7ouOKts83OFMxDq%3DF0TKO1XvHEbnmXJ+Z1WELA@xxxxxxxxxxxxxx/[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 `{<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 -- 2.40.0+fc1
