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

I think this is a very interesting proposal and deserves careful consideration.
As you say, such a syntax for sections would allow Section A to have content both before and after a nested Subsection B.
I’ve written an extension that appends list items and sublists to existing lists, and there’s a problem I haven’t been able to solve that the “explicit list” ends after the generated items.
I suspect that a ‘long notation’  for lists such as you propose, with explicit begin/end markers, would solve the problem for me.
While I don’t think most sections will ever be written in ‘long notation’ I think it can open up a range of otherwise inaccessible possibilities, while making the syntax logically more coherent.

I look forward to investigating this further!
David Jencks

On Feb 17, 2021, at 2:49 PM, 马旋(MA Xuan) <supermmx@xxxxxxxxx> wrote:

Hi everyone,

Since day one I met AsciiDoc, I am in love with it.

I suggest a full markup and a short markup for many (if not all) of the elements, it is kind of like the Java 1.4 syntax, and many syntax sugar added in later versions.

The benefit is that the concepts are very easy, just block element and inline element with different styles, and could support complex structures that are hard to support, like the last paragraph belongs to the parent section instead of the last child section.

== Examples

Actually AsciiDoc (AsciiDoctor) is already like this now.  Here are some examples:

=== Blocks:

This is a tip.


TIP: This is a tip.

=== Inline Macros and Inline Elements:

"xref:document-b.adoc#section-b[Section B]" vs "<<document-b.adoc#section-b, Section B>>"

== New Thoughts

I think we could formalize the idea to make it consistent all the way, like a block element can always be written as an open block, and an inline element can always be written as an inline macro.

The full markup could express everything clearly and comprehensively, while the short markup is easy to write but could have some limitations.  In extreme cases, everything could like that:

[document,type="book",title="Full Markup Example"]

This is the preamble paragraph.

[section,level=2,title="Section 1"]

This is bold:bold and italic:italic[] text[].

Another paragraph shows up here.

-- // sidebar

-- // section

-- // document

And the one with the short markup:

= Full Markup Example
:doctype: book

This is the preamble paragraph.

== Section 1

This is *bold and _italic_ text*.

Another paragraph shows up here.

So we could have a very verbose document and a very concise document that are exactly the same semantically, and both are rendered exactly the same.

Does this make sense?

asciidoc-lang-dev mailing list
To change your delivery options, retrieve your password, or unsubscribe from this list, visit

Back to the top