search

asciidoctor / asciidoctor.org

:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
https://asciidoctor.org
Other
322 stars 807 forks source link

Syntax quick reference page still calls itself "AsciiDoc" #968

Closed oddhack closed 3 years ago

oddhack commented 3 years ago

https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ still is titled, and internally mostly refers to itself, as an AsciiDoc reference. This caused me to need to check the document revision history to make sure it was actually talking about the current asciidoctor and not the old AsciiDoc implementation. Can this be changed? (presumably with a redirect from the old URL).

mojavelinux commented 3 years ago

This is the quick reference for AsciiDoc. Asciidoctor is the modern and current implementation of AsciiDoc (and this document is part of what is being submitted as the initial contribution for the AsciiDoc language specification project). So no, this cannot be changed.

The relationship between Asciidoctor and AsciiDoc Python is explained in the user manual. https://asciidoctor.org/docs/user-manual/#migrating-from-asciidoc-python and https://asciidoctor.org/docs/user-manual/#changed-syntax. For all intents and purposes, AsciiDoc Python is legacy software, maintained primarily for those who still rely on it. Ultimately, these differences will be recognized by the AsciiDoc language specification project.

oddhack commented 3 years ago

OK, in that case it should not say "to learn more about Asciidoctor and its capabilities" at the end of the document. If it's obsolete then OK, but the document is internally inconsistent about what it claims to be describing. As someone who's been using Asciidoc(tor) for 6 years, if I'm still confused by this, I guarantee other people are as well. A prominent "This is NOT accurate information for the currently supported asciidoctor implementation" at the top would suffice.

oddhack commented 3 years ago

Similarly the latest revision in git has a desciption of "remove mentions of air quotes since they have been removed from Asciidoctor". If they haven't been removed from AsciiDoc then why were they removed from this document two weeks ago? Basically this document and its metainformation are just not clear about what they claim to describe.

mojavelinux commented 3 years ago

Similarly the latest revision in git has a desciption of "remove mentions of air quotes since they have been removed from Asciidoctor". If they haven't been removed from AsciiDoc then why were they removed from this document two weeks ago?

They were introduced into AsciiDoc by the Asciidoctor project as an experiment. It turned out to not be useful (and not consistent), so we removed it, thus removing it from AsciiDoc.

mojavelinux commented 3 years ago

Basically this document and its metainformation are just not clear about what they claim to describe.

If you want to propose a revision to the document, I'm happy to consider it. This is the Asciidoctor project, so it's fair that the reference can be both for the language and mention the Asciidoctor project itself.

mojavelinux commented 3 years ago

A prominent "This is NOT accurate information for the currently supported asciidoctor implementation" at the top would suffice.

Why do you think this is not accurate information? This is the quick reference for AsciiDoc as it exists today (and parsed by Asciidoctor).

mojavelinux commented 3 years ago

As someone who's been using Asciidoc(tor) for 6 years, if I'm still confused by this, I guarantee other people are as well.

That's why we're going through this whole exercise of creating a specification for the language (see https://projects.eclipse.org/projects/technology.asciidoc). Then we can have a specification for the language, with it's own technical reference, user-oriented guide, and syntax quick reference. Implementations (like Asciidoctor) will no longer have the burden of documenting the language and can just worry about documenting their own user interfaces / APIs. But this is not a simple endeavor and will take time.

Currently, Asciidoctor has the responsibility of documenting both the language and the program that processes it. That's why the documentation site has both information about the language and the processor. AsciiDoc is the language. Asciidoctor is the processor. This is mentioned many times in the documentation.