Welcome to the development mailing list for the AsciiDoc Language project (
https://projects.eclipse.org/projects/technology.asciidoc)! This list hosts the technical discussions pertaining to the development of the AsciiDoc Language specification and TCK.
About this Project
The AsciiDoc Language Specification describes the syntax and grammar, Abstract Semantic Graph (ASG), Document Object Model (DOM), referencing system, and APIs for processing, converting, and extending the AsciiDoc Language. The Technology Compatibility Kit (TCK) for the AsciiDoc Language Specification verifies that an AsciiDoc processor implementation is compatible with the specification.
This project adheres to the Eclipse Foundation Specification Process (
https://www.eclipse.org/projects/efsp/) (EFSP) and is affiliated with the AsciiDoc Working Group (AsciiDoc WG). The Steering Committee for the AsciiDoc WG also serves as the Specification Committee for the AsciiDoc Language project.
Vision
The overarching vision of this project is to create an official, verifiable grammar for the AsciiDoc syntax and nomenclature. Our purpose is to standardize AsciiDoc so it can be implemented across multiple language platforms and tools without it splintering into multiple flavors.
Keep in mind that AsciiDoc is designed and intended to be extended (i.e., extensible). Thus, the specification will primarily focus on the repeatable building blocks of the language. It should be careful not to overreach or over-specify. For example, the specification should not mandate that all implementations produce exactly the same output from the AsciiDoc source (though it should certainly set expectations about how to interpret elements). It's the interpretation of the syntax and the semantics of that syntax that we want to be consistent. You should be able to move a document from one processor to another and have it still be able to recognize and comprehend the content and produce sensible output.
While the AsciiDoc syntax will evolve, it should always retain these characteristics:
* Plain text, relying only on ASCII characters for markup
* Human readable
* Parsable
* Concise / DRY
* Consistent
* Comprehensive and semantic
* Extensible
The AsciiDoc specification must always strive to achieve a balance between authorship (technical writers) and development (developers), between novices and experts in both fields, and between small and large publishable works. It's that balance and flexibility that makes AsciiDoc so appealing.
The syntax should not be changed for the sole purpose of making development of the parser easier at the detriment of syntax's usability. On the other side of the coin, the syntax should not be so free-form or elaborate that parsing it becomes prohibitively time and resource intensive.
With that in mind, we aim to make AsciiDoc as useful and accessible to as many people and use cases as possible. We want AsciiDoc to be the writing format of choice for both writers and developers alike, and we want them to enjoy working with it.
Goals
Goal 1::
Clearly define the AsciiDoc syntax as it is recognized and used today. We will need to explore how best to describe this grammar using something like EBNF. However, since AsciiDoc is often contextual, we may end up using a hybrid approach.
Goal 2::
The first version of the AsciiDoc specification will be as compatible as possible with documents that are currently being processed by Asciidoctor. We plan to make a few long-overdue decisions to cut or clarify some of the syntax* and refine the terminology*. When those changes are made, we will clearly document what modifications people will have to make to their own documents in order to give them ample opportunity to migrate.
* Examples may include: dropping the setext (two-line) syntax for section titles / discrete headings; eliminating support for mismatched delimited block boundaries; allowing the open block to be nested; repurposing the use of the word "caption"; allowing a space before the footnote macro, etc.
Goal 3::
Where we expect more substantial changes are in the APIs. We want to specify a well-defined, well thought out API for the DOM and processor. We have to be mindful of the fact that AsciiDoc will be parsed by many different languages, so these APIs will need to be specified in pseudo-code with at least one concrete example for reference (e.g., Java, _javascript_, etc).
Goal 4::
The initial specification will focus on parsing the AsciiDoc source and providing a framework for processing (converter, extensions, etc). We don't envision defining mandatory standard output formats (such as HTML) in the first version (or maybe we will). Instead, these outputs may be defined by an implementation and later standardized. Or, we may simply make them a recommendation. That position may change as we get deeper into the process.
Goal 5::
A possible candidate for inclusion in the first version is an inline parser. Currently, the inline syntax is parsed and converted (during the conversion phase) using multiple passes of a regular _expression_-based substitutor. This parsing strategy has been a significant weak spot in AsciiDoc. While we may need to keep the substitutor in the first version, we may also introduce a separate parsing mode that will parse the inline syntax during the parsing phase using a recursive descent parser. (This should also open the door to universal backslash escaping). We anticipate that this new mode will interpret most documents in the same way, but will prove more accurate for content that contains complex markup permutations. We will draw on the implementations for this research. The goal would be to transition to this new parsing mode by default in future versions of the specification.
Project Repository
As announced on the AsciiDoc WG list, the initial contribution from Asciidoctor was reviewed and approved by Eclipse legal. This initated the creation of the project's repository located at
https://gitlab.eclipse.org/eclipse/asciidoc/asciidoc-lang. This repository is hosted on the Eclipse Foundation's instance of GitLab and is administered by the Eclipse Foundation. The material in the repository is maintained by the committers.
The initial contribution was imported into the repository earlier today. The repository also hosts the issue tracker, milestones/releases, and merge requests for the project. All the AsciiDoc-related repositories at Eclipse will be organized under the AsciiDoc group on that instance at
https://gitlab.eclipse.org/eclipse/asciidoc.
(The TCK may end up being hosted in a separate repository under this group, though it will obviously remain as part of this project).
About the Initial Contribution
The initial contribution for the AsciiDoc Language project comes from the AsciiDoc user-facing documentation authored by the Asciidoctor project. While this documentation is not itself the specification, it's deemed the best description we have of the language to date. The project should use this documentation as the basis for drafting the initial specification. When there's ambiguity in that documentation about a language feature, the implementation in Asciidoctor should be consulted (since the document structure, syntax, and nomenclature that Asciidoctor understands is what defined modern AsciiDoc).
Until the first version of the AsciiDoc Language Specification is ratified, AsciiDoc is defined by the Asciidoctor implementation. There is no other official definition of the language. The official documentation for the AsciiDoc Language will remain on the
https://docs.asciidoctor.org site until the AsciiDoc Language project starts publishing its own documentation for the AsciiDoc Language. It's important that we keep this continuity while the specification is being developed for the benefit of the AsciiDoc community.
Contributing
The AsciiDoc Language project has an initial set of committers (
https://gitlab.eclipse.org/eclipse/asciidoc/asciidoc-lang/-/project_members) that were brought in by way of the Initial Contribution. That list of committers will certainly grow as time goes on.
Being a specification project at the Eclipse Foundation, the AsciiDoc Language project follows the Eclipse Foundation Specification Process (EFSP) (
https://www.eclipse.org/projects/efsp/). The EFSP extends the Eclipse Development Process (EDP) (
https://www.eclipse.org/projects/dev_process/), so it's important to understand how that process works to contribute to this project successfully. Recall that an Eclipse Specification is code-driven, so ideas must be tested in the crucible of an implementation before being considered for the specification.
We'll go into more detail about how this process works in forthcoming threads.
Next Immediate Steps
* Collaborate with the Java implementation team (as well as other implementation teams) to refine initial goals, draft milestones, etc.
* Set up our contributing workflow.
* Fix errors/inconsistencies/omissions in the user-facing documentation to ensure we're starting from the strongest position possible.
(We could use help on this last item, and it's a good way to review the files that have been imported).
Thanks for being a part of this project. We look forward to a busy, yet exciting year of collaboration ahead!
Best Regards,
-Dan
--
Dan Allen, Vice President | OpenDevise Inc.
Pronouns: he, him, his
