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@xxxxxxxxx/ [5] https://lore.kernel.org/git/20230322000815.132128-1-felipe.contreras@xxxxxxxxx/ [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 -- 2.40.0+fc1
