@@ -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 `{<foo>}` 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 `{<foo>}` 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}
-* +{tilde}+
-* +{<tilde>}+
+* `{tilde}`
+* `{<tilde>}`
----
Renders as:
@@ -164,23 +164,21 @@ Renders as:
* \{<tilde>}
* {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].
+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:[~!@#$^&*(){}\;",<>?'`+]`.
@@ -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 =
Everyone has moved on but us. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/DocumentationGuideline.adoc | 26 +++++++++++------------ Documentation/Makefile | 2 +- 2 files changed, 13 insertions(+), 15 deletions(-)