enh(asciidoc) follow-up, support emphasis unconstrained syntax #2914
Conversation
test/markup/asciidoc/default.txt
Outdated
| using an explicit link:http://example.com[link prefix]. | ||
|
|
||
| * single quotes around a phrase place 'emphasis' | ||
| * single quotes around a phrase does not place 'emphasis' |
There was a problem hiding this comment.
This syntax is obsolete and unsupported in Asciidoctor.
Since the Asciidoctor project now maintains the official definition of the AsciiDoc syntax I think we should drop it.
There was a problem hiding this comment.
This could all be my fault for not bring up sooner but you do realize AsciiDoc and AsciiDoctor are two DIFFERENT things?
https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/
I think we may have made a misstep here. Our existing grammar is named and described as:
Language: AsciiDoc
Website: http://asciidoc.org
Does this change everything?
There was a problem hiding this comment.
AsciiDoc Python and Asciidoctor are both implementations of the AsciiDoc syntax.
Historically, http://asciidoc.org was managed by the AsciiDoc Python project but AsciiDoc is now a registered "trademark" by Eclipse on the behalf of the AsciiDoc WG.
As a result, http://asciidoc.org will be updated to clarify the situation.
AsciiDoc Python is now deprecated, you can read on http://asciidoc.org:
Asciidoctor provides a modern, compliant, and substantially faster implementation of the AsciiDoc processor written in Ruby. This implementation can also be run on the JVM (with AsciidoctorJ) or using JavaScript (with Asciidoctor.js). The Asciidoctor project now maintains the official definition of the AsciiDoc syntax.
I think this is confusing because AsciiDoc (Python) is named AsciiDoc but AsciiDoc is a syntax not a specific processor.
Likewise, Asciidoctor is not a syntax, it's a processor. Having said that, and until the AsciiDoc WG produces a specification, it's where the official definition of the AsciiDoc syntax is maintained.
Does this change everything?
No, we are all good!
We are implementing a syntax highlighter for AsciiDoc (the syntax).
There was a problem hiding this comment.
As the lead of the Asciidoctor implementation and the chair of the AsciiDoc Working Group, I back up this statement by @Mogztter. The language is AsciiDoc and the asciidoc.org website is currently in the process of being transitioned to reflect that fact. The content that currently lives there is being phased out (and moved).
There was a problem hiding this comment.
@mojavelinux So you're the lead on the Ruby implementation and an asciidoc Python maintainer also? :)
There was a problem hiding this comment.
@joshgoebel That's correct. For AsciiDoc.py, I'm really more than just a maintainer. I'm also the co-administrator with Lex, a duty we took on when Stuart left the project.
There was a problem hiding this comment.
Cool. I'm not familiar with the term "co-administator", but I think I get the gist. Here I typically say I'm the current "maintainer" (historically maintainers change every few years, churn) and that we have other core team members. We have no co-administrators I don't think. :)
There was a problem hiding this comment.
I think you understood my point.
test/markup/asciidoc/default.txt
Outdated
|
|
||
| - escape characters are supported | ||
| - you can escape a quote inside emphasized text like 'here\'s johnny!' | ||
| - you can escape underscores like \_surrounded by underscores!_ |
|
I guess the part that concerned me was the intro (emphasis mine):
So it seems we need to decide if we're supporting the "AsciiDoc syntax" referred to here or the Asciidoctor "new syntax" plus "differences". The intro and list makes it clear there are behavioral differences, no? Perhaps none of the differences matter for our uses, but when you start talking about "obsolete" syntax I wonder if you're talking about some of these differences... and if so that means we're forced to decide which version of asciidoc we intend to support. |
Simply put, Asciidoctor is the current version of the AsciiDoc language and AsciiDoc Python is the "previous version". I believe that Highlight.js supports the latest syntax available for a given language? For instance, the syntax highlighting should recognize Java 15 new language features, right?
I was referring to the single quote character to emphasize text.
Asciidoctor has a |
|
This is helpful perhaps:
Is that what all the Python people think? IE, is this the universal agreement? Is the Python version is dead and no longer maintained and literally being replaced by the AsciiDoctor Ruby project? Their GitHub seems to say the opposite. I'm not trying to be difficult at all, just make sure we understand the bigger picture fully.
Generally. We have typically been "slow" to drop old keywords and such things as languages develop in order to continue to well highlight "older" code. I'm not sure that's what is happening here though. To me (at a glance from the sidelines) this feels perhaps more like a sorta fork... Perl 6 vs Perl 5, etc... if some people continue to use the "old" AsciiDoc and there is even a "compat" mode (for AsciiDoctor) then we definitely have to stop and ask the question of how that impacts us and whether we're "breaking" anything with these changes. (such as when you suggest removing "obsolete" things) If we supported "compat" mode before and now (lets say) we're choosing to drop it (which might even be the right call) - that's a change we need to be fully aware of - and making very intentionally. If there are incompatibilities (and both versions plan to co-existing in the world) I could see someone arguing we need both an
I think it would be optimal if we just supported ALL the syntax (old and new) if that was not too hard to do. Optimally if someone throws either AsciiDoc OR AsciiDoctor (ie, compat vs new) code at us we should do a "nice" job of highlighting it with our singular "asciidoc" grammar. If possible the grammar should probably be renamed to AsciiDoctor or AsciiDoc / AsciiDoctor. |
To be clear this shouldn't mean detecting a I think given the hopeful goal of a single grammar that "adding new features" is a reasonable to do just so long as we aren't "breaking old/obsolete features"... I'm not yet as convinced as you are that AsciiDoctor (Ruby) is the v2 and Asciidoc (Python) is the v1. @Mogztter Do you have any idea of the actual politics and interplay between the Python and Ruby projects (which both seem to be in active development) - and how they think of the format? I feel like your prior explanation was perhaps over-simplifying? The Python project refers to AsciiDoc plenty yet doesn't mention AsciiDoctor a single time. I will circle back to this in the next few days and try to review this more thoroughly (and the original PR) and see if it feels like we're still on an "ok" path... @Mogztter I recognize the effort you've put into this... so don't worry about us throwing it away or anything (that would be rude), but I think we're just asking if perhaps we really might need @allejo @egor-rogov Any thoughts here or knowledge of the AsciiDoc(tor) community? |
I think the "universal agreement" is that the Working Group will drive the standardization of the AsciiDoc language.
I won't say that the Python implementation is being replaced by Asciidoctor. Currently, the Asciidoctor project maintains the official definition of the AsciiDoc syntax but ultimately it's the Working Group job to define what is AsciiDoc and establish a language specification. Once the specification is established, both AsciiDoc Python and Asciidoctor will have to comply with the specification and pass the technology compatibility kit (TCK).
No worries, I think it's beneficial and it emphasizes the importance of the AsciiDoc Working Group.
Fair enough.
It's definitely not a fork but I agree we should not get ahead of the AsciiDoc specification. Today, AsciiDoc and Asciidoctor (with "compat" mode) support single quote to emphasize text so I think we should keep it.
No, I think it was a mistake, we should keep it.
Asciidoctor is not a language, we only need a syntax highlighter for the AsciiDoc language.
Yes 👍
From a syntax highlighter point of view, I think it's doable.
No, the grammar is AsciiDoc and should be named AsciiDoc. |
Agreed and in any case it's not even possible to do so 😃
Yes 💯
Yes, it was overly-simplified. I think the common agreement is that Asciidoctor project now maintains the official definition of the AsciiDoc syntax (as stated on https://asciidoc.org). To be honest, I don't think there's a huge gap (if any) between AsciiDoc Python and Asciidoctor with "compat" mode.
Again, AsciiDoc is the name of the language and Asciidoctor is the name of an other implementation so it's not really a surprise.
No worries, it's a good thing to be thorough and dropping this syntax was a mistake (or at the very least overzealous).
|
This is correct and has been verified and approved by the AsciiDoc Working Group. There are no outstanding objections (legal or otherwise), even from the maintainers of the AsciiDoc.py project (of which I am one). It is Asciidoctor from which the initial contribution for the AsciiDoc language specification at Eclipse has been submitted (https://github.com/asciidoctor/asciidoc-docs/). That further confirms that it is Asciidoctor that is currently maintaining the definition of AsciiDoc (until the specification is drafted and ratified). Some of the statements found on asciidoctor.org are very outdated and make statements that predate the current situation. We are working on getting these lingering statements removed / revised. |
Yes, I'm pretty sure I got it now. It's a bit confusing when the website talks about ~"syntax differences between AsciiDoc and AsciiDoctor"... and my two choices to install with Homebrew are But if the goal is for the working group to define the blessed spec and then everyone catches up then it seems clear our AsciiDoc grammar should try and maintain pace with the "official spec". The problems will come if we run into conflicts between the "compat" mode and the newer spec. At that point we might need to make a choice to only support the newer syntax or to split into But hopefully we won't come to that bridge for a bit. So would referring to the two as "AsciiDoc" and "AsciiDoc (compat mode)" be an improvement? If not, what wording should I use? So given this understanding I don't think we removed anything in the first PR, so we should be good and I'll try to find time in the next few days to review this. If this "deprecated" any compat syntax obviously we should put that back in if at all possible and if not look at the issues.
I don't think you'd removed anything yet, had you? |
Yes, looks like we did. So we'd need to revert those changes - to still allow the compat syntax. |
I reverted this change. |
- Remove obsolete syntax 'emphasis' - Support unconstrained emphasis: That's fan__freakin__tastic! - Improve constrained and unconstrained syntax highlighting
ggrossetie
force-pushed
the
issue-2869-followup-emphasis-mono
branch
from
233f6fb to
9ef1cc8
Compare
This ☝️
At this point, I would just forget about the compat mode. It was a transitional that we added as a way to help people transition when we updated the syntax in 2014 and hardly any documents remain that use it. It's behind us.
Just use AsciiDoc. I think you are reading way too much into this. highlight.js shouldn't be the one determining what AsciiDoc is. |
Perhaps. But I was only doing due diligence. :) If Your showing up and clarifying the history is certainly helpful. Thanks again.
Well, not in the "working group official AsciiDoc standard" sense no - and that's not what I was doing; but so long as the grammar is first-party we are forced to decide when we will adopt new things, deprecate old things, etc... or whether we might adapt things that seem likely but that the working group hasn't fully signed off on yet (I'd think not), etc... and we of course have certain "library wide" ideas of how we handle certain things - though that's probably less of an issue with markup languages (which tend to have a lot more semantic consistency) than other programming languages. It's also easy to publish a 3rd party grammar and bypass our thinking entirely on such matters. :) IE, the AsciiDoc working group could publish their own 3rd party grammar module and do anything they wanted with it. :-) I'm not sure that'll be necessary here, but it's always an option.
Well that is certainly very helpful knowledge. 🙂 I don't think I realized this was all "so long ago in a galaxy far far away" I think I might agree with you now that we can just ignore "compat" it if it dates back to 2014 and "hardly any documents remain that use it". @Mogztter Thoughts? I wouldn't have made such a big deal about it if I had known how long ago all this had transpired (and that such documents are super rare today). Sound like you could/should just |
Off the top of my head I would presume we should be willing to add things as they are approved (not proposed). How we might handle removals from the spec that happen in 2021 (vs 2014) might have to be decided on a case-by-case basis. I assume though (for everyones sanity) that the spec will be semi-stable over time. :) @mojavelinux One other consideration: we often are used highlight a lot of static/historic content... someone blogs about XYZLang v4 code on their blog and we highlight it nicely. When XYZLang v5 comes out (even if XYZLang v4 is deprecated, no longer maintained, etc.) we are still somewhat cognizant of the fact that that XYZLang v4 code might exist on that blog forever and we are still being trusted to highlight it properly. (StackOverflow being a great example of this) In some ways it's an impossible problem and certainly (for everyones sanity) we often have to break the highlighting of XYZLang v4 at some point, but we try not to be in a hurry to do so - and when doing so we try to understand the context fully so we can know who we are breaking things for (if anyone). |
I don't mind keeping this syntax around. As you mentioned, Highlight.js is conservative and as long as it does not significantly increase complexity or induce side effects I think we can keep it. In any case, if we decide to remove it, I think we should do it in a dedicated pull request. |
I have a feeling eventually someone will say "hey this shouldn't be highlighted", but I'm ok waiting for that day.
I can live with that, even if it's only because you're just tired of going back and forth on this LOL. |
|
Just need that changlog entry then this will ship in 10.5. :) |
|
@Mogztter Thanks much! |
resolves #2869
Changes
Checklist
CHANGES.mdAUTHORS.txt, under Contributors