Skip to content
GitLab
Projects Groups Snippets
  • /
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
  • Sign in
  • AsciiDoc Language AsciiDoc Language
  • Project information
    • Project information
    • Activity
    • Labels
    • Members
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
    • Locked Files
  • Issues 21
    • Issues 21
    • List
    • Boards
    • Service Desk
    • Milestones
    • Iterations
    • Requirements
  • Merge requests 2
    • Merge requests 2
  • Deployments
    • Deployments
    • Releases
  • Monitor
    • Monitor
    • Incidents
  • Analytics
    • Analytics
    • Value stream
    • Code review
    • Insights
    • Issue
    • Repository
  • Activity
  • Graph
  • Create a new issue
  • Commits
  • Issue Boards
Collapse sidebar
  • Eclipse ProjectsEclipse Projects
  • AsciiDoc Language
  • AsciiDoc LanguageAsciiDoc Language
  • Issues
  • #11
Closed
Open
Issue created Oct 16, 2022 by Dan Allen@mojavelinuxMaintainer

Tighten the scope of the project

The dearth of progress on this project is due, in part, to the fact that the scope is too broad. I'd like to propose narrowing the scope so it's razor-focused on parsing the AsciiDoc Language (syntax, grammar, terminology, parsing strategy). The only time the spec should expand beyond the syntax is to stipulate required behaviors in the converter and/or output format that support the content. Once the first version of the specification is released, we can revisit the scope for future versions.

You can find the existing scope in the creation review: https://projects.eclipse.org/projects/technology.asciidoc/reviews/creation-review

Here's the revised scope:

<p>The AsciiDoc language project defines and maintains the AsciiDoc Language Specification and Technology Compatibility Kit (TCK), its artifacts, and a writer-oriented language guide.
The AsciiDoc Language Specification describes the syntax and grammar, Abstract Semantic Graph (ASG), Document Object Model (DOM) interfaces, referencing system, designated extension points, processing phases, and required integrations and behaviors.
The TCK is used to verify and self-certify that an AsciiDoc processor implementation is compatible with this specification.</p>

<p>Specifically, the project scope includes the following matters:</p>

<ul>
  <li>AsciiDoc language syntax / grammar (i.e., EBNF, ANTLR4, or similar)
  <ul>
    <li>Lexicon</li>
    <li>Preliminaries / primitives (e.g., line-oriented, block, phrase, macro, preprocessor directive, etc.)</li>
    <li>Doctype-specific structures and required elements</li>
    <li>Built-in attributes and reserved attribute namespaces</li>
    <li>Designated file extension (.adoc)</li>
    <li>Escaping mechanism</li>
  </ul>
  </li>
  <li>TCK: Technology Compatibility Kit for verifying and self-certifying compliance of an AsciiDoc language processor</li>
  <li>ASG: an encoded form of the parsed document for use in developing a language-agnostic TCK (e.g., JSON)</li>
  <li>DOM API (interfaces only): language-agnostic, semantic representation of the structure, metadata, and content in the AsciiDoc document</li>
  <li>Parsing strategy / processing phases (preprocess, parse, convert)</li>
  <li>Extension Facility
  <ul>
    <li>Syntax extension points (e.g., custom block or macro)</li>
    <li>Resolvers (e.g., path and attribute resolvers, ID generator)</li>
    <li>Lifecycle interceptors (e.g., preprocessor, output processor, tree processor)</li>
  </ul>
  </li>
  <li>Internal and external referencing system: (e.g., xrefs, includes, images)</li>
  <li>Mandatory integration adapters: syntax highlighter, STEM, docinfo, icons</li>
  <li>Expected converter behaviors (e.g., toc, ID generation, caption numbering, collapsible blocks)</li>
</ul>

<p>In addition to the specification document and TCK, the project also provides the following:</p>

<ul>
  <li>AsciiDoc Language guide for writers</li>
  <li>ASG schema for the TCK</li>
  <li>API documentation for the DOM</li>
</ul>

I am going to bring this proposal to the AsciiDoc WG Steering / Specification committee for approval. Once it's approved, I will update the scope on the project page and proceed accordingly.

Edited Oct 24, 2022 by Dan Allen
Assignee
Assign to
Time tracking

Copyright © Eclipse Foundation, Inc. All Rights Reserved.     Privacy Policy | Terms of Use | Copyright Agent