Wording of CommonMark definition


#1

On the front page of commonmark.org, CommonMark is defined as follows:

A strongly specified, highly compatible implementation of Markdown

I think it would be clearer as:

A strongly specified, highly compatible specification of Markdown

There are many implementations of the CommonMark specification, so it’s misleading to call CommonMark a (single) implementation.

But perhaps with a different word instead of “specified” to avoid duplication, e.g.

A strongly defined, highly compatible specification of Markdown


#2

Agreed. @codinghorror - let’s think about how this could be rewritten. “Implementation” isn’t really right. “Strongly specified specification” wouldn’t make much sense. I’m also not sure about “highly compatible.” Compatible with what, exactly?


#3

I think this definition is great. :+1:


#4

Compatible with existing (vanilla) Markdown documents based on the Daring Fireball syntax guide, I thought?


#5

Compatible with a large corpus of Markdown from large, popular websites that currently use Markdown?


#6

Ok I changed it to

A strongly defined, highly compatible specification of Markdown

I also changed

With your help, we plan to announce a finalized 1.0 spec and test suite in early 2016, along with implementations in many different languages.

So be careful what you ask for, eh? :wink:

http://commonmark.org/


#7

I’m not sure what “strongly defined” is supposed to mean – but I guess “precise specification” or “unambiguous specification” would express a very similar intent.

And does a “strongly defined specification” implies “strict syntax rules set down in a strongly defined specification”? :wink: Kidding aside: a specification could be clear, or unambiguous, or precise, or loose, or simple, or formal, or inconsistent, but I see no point in postulating a specification to be “strongly defined”.

Furthermore, the thing that is supposed to be “compatible” is probably not the specification, but what the specification does specify: in our case, a syntax (or a language) and its semantics (or interpretation).

Since every input text is supposed to be accepted by a “traditional” Markdown implementation as well as a “modern” Commonmark implementation (there are no “invalid” input texts, or “syntax errors”): it is obviously not the specified language itself which is or is not “compatible”, but the interpretation of the input document.

So my “mission statement” proposal would be something like this:


  • A clear, precise specification of
    1. the input syntax rules (by which the “structure” of the input text is recognized),
    2. the content model of the “output document” (equivalent to @jgm’s “AST”),
    3. the transformation rules by which the “output document” (ie, an instance of the content model) is derived from the “structured” (or “parsed”) input text,
  • which together produce the same (or very similar) output as would a “traditional” Markdown processor according to the “official” (ie: Gruber’s) syntax description – at least in “most practical cases” …

I would leave implicit the goals that the specification

  • should be abstract in the sense “free of unnecessary details and constraints”: for example, the content model should not be simply a subset of the HTML content model (for example given as the XML Information Set of XHTML document instances) – while it certainly and easily can be mapped into it and into a variety of other document types (like LaTeX or DocBook articles or reports etc).

  • should be loose in the sense “allowing implementation choices”: for example, the character set and encoding scheme (like “UTF-16LE”, or “ISO 646 IRV”) and the “line breaking convention” (DOS-like “CR,LF” , or UNIX-like “LF”, or Unicode Standard Annex #14 etc) supported and usable in the input text should be the choice of an implementation.


#8

I believe the discourse description should be updated as well.


#9

Good point, changed it here in the site desc and the pinned topic.


#10

Strongly defined as opposed to vaguely/weakly defined.