resolves #5 submit an initial outline for the AsciiDoc Language specification

Dan Allen requested to merge mojavelinux/asciidoc-lang:issue-5-spec-outline into main

Sarah and I have compiled an initial outline of the AsciiDoc Language specification. This merge request submits that outline for review (and likely revision). The outline is represented by the section structure in the document. That structure is accompanied by a lot of interspersed notes to give a better of idea of what information a section will cover.

Since AsciiDoc is a comprehensive markup language, we expect that some aspects may have been overlooked and that sections will need to be moved around. Once the group is satisfied that the outline fully represents the information that the spec must cover and convey, we'll take off the draft status and merge this outline into the repository. There, we expect it to serve as the roadmap for drafting the specification document. Keep in mind that outline will continue to evolve, both before and while the specification is being drafted. The outline is merely a guide.

One of the goals of this outline is not only to account for all the details of the AsciiDoc Language, but to also frame it in such a way that we can address as many of the pitfalls in the language as we reasonably can, especially as it pertains to the inline syntax. Any proposed syntax and rules cited in this outline will be split out into separate issues for consideration. Inclusion in the outline document does not equate to a decision that was made. There will be plenty of opportunity to discuss these matters.

Here's a brief manifest of what this document MR entails:

  • provides an initial outline for the AsciiDoc Language specification
  • organizes major aspects of the language and its facilities into parts
  • begins to establish a consistent terminology
  • identifies concepts and shared patterns
  • accounts for all unique syntax elements, ranging from blocks to inlines
  • incorporates a proposal to frame the inline syntax as a structured and parsable grammar
  • formalizes the referencing/addressing system that includes a proposal for a resource resolver
  • account for syntax extensions
  • dedicates a part to the TCK and how it will work

Merge request reports