search

metanorma / metanorma.org

Official Metanorma website
https://www.metanorma.org
MIT License
7 stars 7 forks source link

Terminology page? #90

Open ronaldtse opened 5 years ago

ronaldtse commented 5 years ago

We have some inconsistencies in usage of terminology.

"RFC Asciidoctor" => AsciiRFC

Tons of references to AsciiDoc and Asciidoctor but conflates them. Asciidoctor is an AsciiDoc tool. It is not a syntax, and just happens that we use it as a parser.

The official terminology for Metanorma's AsciiDoc syntax is "Metanorma AsciiDoc".

We will be supporting LaTeX too, so it is important we differentiate them properly.

opoudjis commented 5 years ago

The cutesy abbreviations like AsciiCSD and AsciiISO need to go (if they haven't already): they are needlessly confusing. There is just Metanorma AsciiDoc.

I have never used AsciiDoc, I have always used Asciidoctor for both the Ruby variant of the language and the Ruby toolset. Someone other than me should be doing the cleanup...

ronaldtse commented 5 years ago

@opoudjis I agree about the abbreviations, but "AsciiRFC" too? We'll have to update the RFC.

AsciiDoc is the name of the syntax, Asciidoctor is the tool that reads in AsciiDoc. Asciidoctor's AsciiDoc syntax has been slightly modified from the original AsciiDoc.

There ought to be a "standardized AsciiDoc" ("SAD", duh) or "common AsciiDoc" ("CAD") or something of this sort. The name "Ascii" doesn't even work that well given that UTF-8 is supported...

opoudjis commented 5 years ago

AsciiRFC can stay for stability, since it's been there for two years; but I'm not convinced that RFC will ever be published.

I'm ignoring the last paragraph as I ignore all unnecessary scope creep. :-)