| Re: [asciidoc-lang-dev] Include expansion and block parsing [Was: Extension hooks in Asciidoc] |
On 26/03/2021 04:43, Lex Trotman wrote: > > > On 24/03/2021 12:24, Guillem Marpons via asciidoc-lang-dev wrote: > [...] > > > > > > To elaborate on what David says: there is a circular dependency between > include expansion, attribute resolution and block parsing: > > * A line with contents > > :key: value > > is considered an attribute entry only in some places (e.g., not > inside a > passthrough or verbatim delimited block), so parsing affects attribute > setting and resolution. > > > 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? > > * Include expansion affects both attribute resolution and parsing. An > include file can left open any number of delimited blocks or other > constructions, thus affecting subsequent parsing, or the context in > which a potential attribute entry is parsed. And attributes can be > defined in and set in included files. > > > This is something that needs to be addressed, it is a hangover from > the AsciiDoc Python streaming implementation which Asciidoctor > replicated (presumably in the name of backward compatibility). > Considerable thought needs to be given to if it is more dangerous than > useful. Leaving delimited blocks open in an include file looks like an anti-pattern to me. To my mind, included files SHOULD match the production for the "block" element. I rephrased that idea from the XML "parsed entity" definition (https://www.w3.org/TR/xml11/#wf-entities). To quote the same source: > A consequence of well-formedness in general entities is that the > logical and physical structures in an XML document are properly nested Admittedly, I have limited experience in that area. So I may have missed valid use cases that have to be addressed by leaving blocks open in an included file. > > 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. > > 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 (https://www.eclipse.org/lists/asciidoc-lang-dev/msg00001.html): > Goal 1:: > Clearly define the AsciiDoc syntax as it is recognized and used today. > [...] > Goal 2:: > The first version of the AsciiDoc specification will be as compatible > as possible with documents that are currently being processed by > Asciidoctor. > > [...] > > Until the first version of the AsciiDoc Language Specification is > ratified, AsciiDoc is defined by the Asciidoctor implementation. 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. 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. Regards, - Sylvain
Attachment:
signature.asc
Description: OpenPGP digital signature