A philosophical document articulating the fundamental principles, values, and worldview of the AsciiDoc language.
|
Note
|
Transparency: AI-assisted prototype, not an official document
This document was written by Claude (Anthropic’s AI), under my direction and editorial review. The information is accurate and grounded in the AsciiDoc Working Group charter, community discussions, and project history — this is not AI-generated filler content. However, it carries no official standing. Only the AsciiDoc Working Group has the authority to issue official documents. The intent is explicitly prototypal: to synthesize existing knowledge, surface insights, and provide a concrete foundation that the community and Working Group can evaluate, critique, and draw from when writing a future official document. I see no methodological problem in using AI as a drafting tool for this purpose, provided the content is accurate and communicates clearly — much as we delegate lexical and syntactic analysis to a compiler rather than writing Assembly by hand. The tool does not determine the validity of the result; the rigor of the process and the accuracy of the content do. If you disagree with specific claims, the right place to raise them is the AsciiDoc Zulip chat. |
The AsciiDoc Manifesto — The main document. Read this first.
Ecosystem Guide — Understand the distinction between the AsciiDoc language (specification) and processors (implementations).
Resources & Links — References for specification, TCK, documentation, community.
This manifesto is a community initiative aimed at articulating the philosophical foundations of AsciiDoc. While it reflects extensive research into the AsciiDoc Working Group charter, community discussions, and the project’s history, it is not yet an official document.
The goal is to provide a foundation that the AsciiDoc community and Working Group can review, refine, and potentially adopt as a standardized reference for understanding AsciiDoc’s principles and identity.
|
Important
|
Want to discuss or contribute to this manifesto? The primary channel for AsciiDoc language discussions is the AsciiDoc Zulip chat. This is where the community and Working Group coordinate on standardization efforts, language specification questions, and foundational discussions. Whether you want to propose changes, ask questions, or discuss the manifesto’s ideas, please join the conversation on Zulip. The future of this document depends on community engagement through official channels. |
If you’re new to AsciiDoc:
-
Read the Manifesto to understand the philosophy
-
Consult Asciidoctor Docs to learn syntax
-
Join the Zulip chat for questions
If you’re a Working Group member:
-
Review the Manifesto to evaluate its alignment with community values
-
Discuss potential adoption or refinements on Zulip
-
Reference the Language Specification for technical details
If you’re implementing a processor:
-
Study the Language Specification
-
Test against the TCK
-
Engage with the community on Zulip
While this repository accepts pull requests, the preferred way to discuss substantial changes or philosophical questions is through the AsciiDoc Zulip chat.
This ensures that:
-
Discussions happen in the official community space
-
Working Group members can participate
-
Ideas are vetted by the broader community
-
The manifesto reflects collective understanding, not individual perspective
For small corrections or clarifications:
-
Fork this repository
-
Make your changes
-
Submit a pull request with clear description
For philosophical or substantial changes:
-
Start a discussion on Zulip
-
Gather community feedback
-
Submit a pull request reflecting the consensus
Guidelines:
-
Maintain the manifesto’s philosophical coherence
-
Cite community discussions or Working Group references for significant claims
-
Preserve the tone: welcoming but realistic, philosophical but practical
All content under CC0 1.0 Universal.
You are free to copy, modify, distribute, and use this work for any purpose without attribution (though acknowledgment is appreciated).
Documentation is not decoration. It is the preservation and transmission of knowledge across time and people.