Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [asciidoc-lang-dev] Include expansion and block parsing [Was: Extension hooks in Asciidoc]

Thanks Lex, Sylvain for your replies.

On 26/3/21 11:10, Sylvain Leroux wrote:
On 26/03/2021 04:43, Lex Trotman wrote:

Yes the preprocessor has to keep track of this context, that does not
automatically rule out separate pre-processing.

Could you elaborate a little bit on that? Do you have some design ideas
to share?

I thought the same when I read Lex's comment. At least some parsing needs to be be mixed with preprocessing, doesn't it?

So I would propose that the current behaviour be modified, or at least
be deprecated with a warning.

Given the goal for v1 is to formalize the de facto standard established
by the ruby implementation, we indeed have to live with the actual
behavior. But I support adding a deprecation warning before removing it
entirely from the v2 specs.

Agree. This suggests that in parallel with the actual specification, we need to discuss and agree upon many details of the release process, like defining a standard deprecation cycle (how many major releases before a features is completely removed, etc).

I also call attention to the fact that in many cases this effort seems
to be turning into standardising Asciidoctor the implementation, not
AsciiDoc the markup.  There seems to be no real thought being given to
if current behaviour is useful and intended or if it is merely a side
effect of the current implementation method, and if it would be better
to change the behaviour for the good of the AsciiDoc ecosystem.

See my above remark. This is a consequence of the WG intentions: the
"asciidoctor" ruby implementation *is* the current language
specification. It was clearly stated in the "AsciiDoc Language Kickoff"
message (


There is room to "make a few long-overdue decisions to cut or clarify
some of the syntax," but I'm not sure stricter requirements for included
documents will fall in that category.

My original message was only intended to clarify what the status quo is w.r.t. parsing/preprocessing.

I suspect many people in this list share the idea that current implementations (and the language they accept and process) can be improved, and have good ideas on how to do it. But even the workflow for contributions to the spec has not been defined and agreed upon, yet.

Also, I think the plan to build on what we currently have is a sensible one to not lose or contribute to fragment the current AsciiDoc user base. It's not ideal having to specify an implementation-defined artifact. It's a difficult and probably not very rewarding task, often closer to reverse engineering than it is to design (I'm trying to contribute to this task, I expect to share my findings soon). But we need to complete this task before we can have a meaningful discussion about potential improvements. IMO, we can start the debate about our long term vision for the language before Spec 1.0 is released, but I think it would be premature to discuss concrete proposals before having even a draft of the spec.

On the particular case of how includes work, I consider they have many shortcomings in current implementations, but it's probably an area that needs a lot of debate and prototyping (and a deprecation policy, etc) before we can even aspire to agree on a path for progress. I personally agree with the idea, already expressed at least once in this list, that any modern inclusion/import/reuse mechanism should depart from the obsolete C-preprocessor paradigm, and will happily join any effort to design such a mechanism when the time arrives, and if this is a generalized opinion in the community.

No doubt, for the v2, we will have to clean up the syntax and semantic
of the language to a broader extend to remove unintended or legacy
behaviors. I'll strongly support that effort. As an implementor, I don't
see much point in emulating all the current implementation quirks and
side effects. So, I won't bother much with v1 compatibility and, if any,
I will directly target v2 compatibility.

It's an interesting idea I hadn't contemplated to target v2 directly, given that at least the Java implementation will be fully v1-compatible and will secure the transition. At the moment I'm still committed to v1, as I think that having a diversity of implementations is the best way to come up with a good spec.


Back to the top