Skip to content

Commit

Permalink
refactor(parser): simplified grammar rules for attributes (#804)
Browse files Browse the repository at this point in the history
Process the attributes in a more generic way: positional values
are retained until the block is initialized, in which case they
are process accordingly, by mapping the position to an expected
attribute name.

Overall, the grammar for block and inline attributes is much simpler,
which means that adding support for new elements will require
less effort.

Also:
- no need to the `AdmonitionKind` and `BlockKind` types, whose
constant values are all `string` now and stored in the `style` key.
- for inline attributes, spaces after the opening square bracket (`[`)
are not tolerated (this was already the case for block attributes). This
allows for a better consistency and simpler grammar rules.

BREAKING CHANGE: for images and links, positional attributes are delimited
with commas, so if a link text should contain such a comma, it is necessary
that the text be wrapped in single or double quotes. This makes the syntax
(and thus, the parsing) consistent between block attributes and inline
attributes.
Eg: `link:http://example.com["a description, with comma"]`

BREAKING CHANGE: inline attributes content must not start with spaces, as
it is the case with block attributes.
Eg: `image::cookie.png[ cookie ]` is not valid.

Fixes #750

Signed-off-by: Xavier Coulon <[email protected]>
  • Loading branch information
xcoulon authored Dec 16, 2020
1 parent af509d0 commit 1a08657
Show file tree
Hide file tree
Showing 67 changed files with 9,836 additions and 10,836 deletions.
14 changes: 13 additions & 1 deletion LIMITATIONS.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -124,9 +124,21 @@ See https://github.com/bytesparadise/libasciidoc/issues/677[Issue #677].

== File Inclusions

File inclusions are performed before the full parsing takes place. During this phase, the main file is parsed to look for `include::` directives and then replace them with the content of the file to include.
File inclusions are performed before the full parsing takes place. During this phase, the parser looks for `include::` directives and replace them with the content of the file(s) to include.
If the file to include has an empty last line, it will be ignored, so it's always a good practice to include a blank line after the `include::` directive in the main document, to avoid side-effects during
the "full" parsing.
Also, the `lines` and `tags` attribute values must use semicolon (`;`) to join multiple ranges when they are not wrapped in quotes, and they can use both colon (`,`) and semicolon within quotes.

For example:

[source]
====
pass:[include::chapter-a.adoc[lines=1;3..4;6..10]]
pass:[include::chapter-a.adoc[lines="1,3..4,6..10"]]
pass:[include::chapter-a.adoc[lines="1;3..4;6..10"]]
====

== Substitutions

Expand Down
Loading

0 comments on commit 1a08657

Please sign in to comment.