[...]
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.
* Attribute value affects include expansion, as David pointed out:
include::{key}.adoc[]
Correct, preprocessing needs to handle attribute definitions and their substitution into preprocessor contexts like this.
* 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.
It is dangerous, if include files can alter the parsing of surrounding constructs it is not possible to read an adoc file in isolation and know what it means (for both humans and machines). And an included file has to be read in the context of where it is included, which can make reuse difficult since it can only be re-used in the same context.
This makes writing documents by more than one person difficult to manage, and in the era of github/lab many people can be expected to contribute to document development. If it is not possible to divide a document reliably into parts it means any contributor has to know the construction of the _whole_ document, and that limits contributions.
Similarly capturing attributes means that an attribute used in an including file could be accidently modified by the included file, so again writers of included files need to know where they are used and/or writers including other document parts need to be aware of attributes and constructs used in the files they include.
It is standard computer programming language practice to scope variable names for these reasons and the mechanisms of scoped variables are well known and inexpensive.
So I would propose that the current behaviour be modified, or at least be deprecated with a warning.
By some tests I've done, even comment strip-out cannot easily being done
as an actual preprocess: an include can left open a comment block,
affecting lines external to the included file.
Another example of its dangers.
All that means that in current AsciiDoc it's not possible to have an
actual preprocessing as a separate step. Include expansion needs to be
performed at the same time of (block) parsing (as David says). Or am I
missing something?
How are the so called "preprocessor directives" implemented in
Asciidoctor and other tools?
I don't know about Asciidoctor, but the original AsciiDoc Python was a stream processor, that is it did one pass through the input and generated the output as it went. It never created an explicit parse tree (although it was implicit in the stack contents).
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.
Cheers
Lex
--
Guillem
_______________________________________________
asciidoc-lang-dev mailing list
asciidoc-lang-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/asciidoc-lang-dev
