mbox series

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

Message ID 20230405125453.49674-1-felipe.contreras@gmail.com (mailing list archive)
Headers show
Series doc: document for our use of legacy asciidoc.py | expand

Message

Felipe Contreras April 5, 2023, 12:54 p.m. UTC 
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