New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Remove legacy from title #262
Comments
This is indeed confusing for me, as a newcomer to the AsciiDoc ecosystem. The official AsciiDoc and AsciiDoctor websites both mention that "AsciiDoc.py" is outdated and unmaintained. However this repo looks to very actively developed, and the docs have been updated recently. Which one is it? Furthermore, who maintains this implementation? Is it "community-maintained", or is it somehow official and/or blessed by the Eclipse Software Foundation? Edit: I also came across this https://www.asciidoc3.org/. Is that an unrelated project? |
The legacy refers to the fact that this implementation currently parses a legacy version of asciidoc. Asciidoctor, since it's creation in 2014, became the defacto implementation of asciidoc, and has made a number of changes to the "asciidoc spec" that asciidoc.py currently odes not implement. Additionally, the formal specification of asciidoc will incorporate the informal doc as laid out by asciidoctor. I would like to get asciidoc.py to parse the "modern asciidoc" syntax, at which point I'll drop the legacy bit from the title. I do agree that any other sites that say that asciidoc.py is "unmaintained" should be changed to drop that, but "outdated" is unfortunately probably correct when referenced with what asciidoc syntax features are supported.
It's unrelated. It was a fork of asciidoc.py that was accounted in April 2018 (see asciidoc-py/asciidoc-py2#83 (comment)), where there was no yet a working python3 port of the original asciidoc.py codebase, and no one had yet finished up the work there. There's been some slight communications about merging the projects in the past (e.g. comments in asciidoc-py/asciidoc-py2#83 and asciidoc3/asciidoc3#3, https://gitlab.com/asciidoc3/asciidoc3/-/issues/1), but nothing has come of it. At this current juncture, it's also possible that @asciidoc3 and I have a widening difference in opinion of where we want to take the original codebase. |
While Asciidoctor fans have unilaterally declared it as the defacto implementation of asciidoc, those long-standing users of Asciidoc do not recognize any other reimplementation as such. Those involved with Asciidoctor, or any other reimplementation, are free to make whatever changes they like. But there is no requirement for Asciidoc to adopt them. The use of the term 'legacy' some like an attempt to put people off what is a very usable application. |
Hi all friends of AsciiDoc out there, |
Be that as it may, the AsciiDoc working group is starting their specification process of AsciiDoc language using the Asciidoctor documentation. From my perspective, this doesn't mean that what's there is set in stone for what'll be in the final formal spec, but that's what will be the starting point, which will happen at some point this quarter. The best way to affect change there would be to join the WG mailing list or zulip server and voice your concerns.
Except that to claim a library parses "AsciiDoc", there is a requirement to match the spec that is put out by the AsciiDoc working group, who own the trademark to the name "AsciiDoc". This project cannot make claims contrary to that without running afoul of that, and I have no interest in dealing with the Eclipse Foundation's lawyers who would defend the trademark. As such, from my perspective, the choices for this library are:
As the current maintainer of this library, my choice is to work towards (1) and attempt to make this implementation "spec compliant", with a hope to offer ways to retain BC with older syntax (via flags or other mechanisms). I would add here that the addition of the "legacy" wording was done at the behest of @mojavelinux who was chair of the AsciiDoc WG at the time, and he can certainly provide additional info here as he is currently leading the specification process as laid out by the WG.
@asciidoc3 Yes, and also Asciidoc.py is a living python3 implementation of the same legacy asciidoc-language variant. This repo also runs seamlessly on the same platforms. If you're going to advertise your fork, please do so in a way that highlights the ideological differences of direction, and not try to imply that this repository is in some way dead or is not compatible with python 3, or that it's not 100% compatible with the syntax. |
Just to be clear, what was submitted as the initial contribution to the AsciiDoc Language Specification project hosted at the Eclipse Foundation is the description of the AsciiDoc language as defined by Asciidoctor (which evolved from AsciiDoc.py over the course of a decade). The Eclipse Foundation now owns the trademark for AsciiDoc and therefore what is defined by the AsciiDoc Language Specification project is the only definition and permitted use of AsciiDoc. (The language will continue to be evolved by that project, so it's not static). This transfer was done in good faith to the community primary to avoid forks/flavors like with Markdown. Once the first version of the specification is complete (which is still ongoing, but underway), any implementation will have to pass the TCK in order to claim to be AsciiDoc compliant. Any implementation that does not pass the TCK cannot claim to be compliant AsciiDoc. (There is no other living definition of the AsciiDoc language). As such, the implementation must specify that it's not AsciiDoc compliant or use another name when referring to the language (adding a number to the name doesn't count as different). It's correct to label this repository as "legacy AsciiDoc" because that's what it is (and the AsciiDoc WG is well aware of that). Therefore, I assert that this issue can be closed. I'm not going to comment further on it here. If you have objections, you can bring them to the AsciiDoc Working Group, which governs the AsciiDoc trademark and specification. |
Yeah, I'm going to close this issue for the time being. Ideally we can get this codebase to pass the TCK, at which point can re-evaluate removing the "legacy" adjective. I will also let the Eclipse WG handle communication with asciidoc3 project about the trademark via a channel that's not this repo's issue tracker. |
This is not the 'Legacy' python implementation.
It is the ongoing python implementation.
Remove 'Legacy' from the repos short description.
The text was updated successfully, but these errors were encountered: