[RFC PATCH 0/3] doc: document for our use of legacy asciidoc.py

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