Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [asciidoc-lang-dev] Full and short markup for the same element

On Feb 19, 2021, at 2:14 AM, Dan Allen <dan@xxxxxxxxxxxxxx> wrote:

Hi 马旋,

I'm glad to hear that your relationship with AsciiDoc was love at first sight. We share that in common ;)

I do agree that inline shorthand should have an equivalent long-hand in the style of an inline macro (which AsciiDoc mostly has). We've learned over the years that each time we introduce shorthand, it makes the language more difficult to parse and less deterministic (so the costs of the shorthand can outweigh the benefits). The inline macros have proven to be very versatile and, whenever it makes sense, they should be preferred. (The main exception is text formatting, which would remain as is, though perhaps with full support for an attrlist). Inline macros are actually easier for writers to remember because they follow a common pattern. So your point about inline syntax is noted.

On the other hand, the generic block syntax that you proposed ("a block element can always be written as an open block") would fundamentally change the language, which doesn't fit the stated vision of this project. (It's also very reminiscent of XML, which is not what AsciiDoc is about). Therefore, it's not a proposal we are considering at this time.

> David Jencks wrote:
> such a syntax for sections would allow Section A to have content both before and after a nested Subsection B.

I don't agree this is the right approach. First, attaching content to a parent section is extremely rare and generally discouraged in publishing. If we do end up deciding to support it, we would use a different way of expressing it such as a return block (similar to how a page break is declared).

> I suspect that a ‘long notation’  for lists such as you propose, with explicit begin/end markers, would solve the problem for me.

Again, this would fundamentally alter the language, and that's not what we're doing. We can solve the underlying problem of attachment without requiring that all block elements have enclosures (yuk!). Those enclosures would make AsciiDoc far less appealing. I don't think we should investigate this further at this time.

I don’t understand why you characterize this proposal as “requiring all block elements have enclosures”.  My understanding of the proposal is that it acknowledges that the existing non-block syntax cannot deal with perhaps <1% of situations, and proposes an optional uniform block syntax for such cases.  What I like about it is that, whenever you get to the point of “hmmm, I’m stuck, there’s no way to do this” there’s a single way to resolve it.  99%+ of the time the current syntax will be more than adequate.

I suspect this explicit block syntax can be implemented as extensions, so perhaps, since these situations are likely to be rare, having extensions for them would be a better approach than changing the language spec.

David Jencks

Best Regards,


Dan Allen, Vice President | OpenDevise Inc.
Pronouns: he, him, his
Content ∙ Strategy ∙ Community
asciidoc-lang-dev mailing list
To change your delivery options, retrieve your password, or unsubscribe from this list, visit

Back to the top