As part of the discussions on this list and elsewhere there are proposals for improvements to Asciidoc that are not fully backward compatible and suggestions that some of those changes be delayed to later evolutions of the specification.
To facilitate that I propose that the Asciidoc specifications adopt semantic versioning to identify versions and a means be added to Asciidoc to allow documents to specify which version they use so processors can detect if they don't support that version.
Semantic versioning of the major.minor.micro form seems to fit fairly well.
Major versions are the only ones where backwards compatibility that breaks valid documents is allowed.
Minor versions allow new features and fixes and definitions of previously undefined items that break invalid documents but should not break valid documents.
Micro versions are only fixes with full backward compatibility, eg fixes to bad examples or better explanations if something is confusing.
The document could specify the version with an attribute in the heading such as:
:asciidoc-version: 2.0
A processor that does not support that major version would error, and if not that specific minor version would warn.
Cheers
Lex
