Different behaviour of literal blocks depending on definition way

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

Different behaviour of literal blocks depending on definition way

abelsromero
According to documentation a literal block can be defined in three ways

1. Indenting the first line of a paragraph by one or more spaces
2. Applying the literal attribute to a paragraph or block
3. Using the literal block delimiter (.... )

ref: http://asciidoctor.org/docs/user-manual/#literal-text-and-blocks
But I have seen that when using the second and third options the block does not continue the previous content (example below). This seems odd to me and forces me always to back-track and relate it with a `+`.

Let’s say I have something like this:

. Step 1

 $ nice magic command here

. Step 2

….
$ nice magic command also \
but this is a \
 multiline example
….
The first block is included as part of the numbered element and is properly indented. However in the second case the block is not, so I have to add a + before it.
I suspect this may have something to do with this sentence in the documentation “When you want an entire block of text to be literal and would prefer not to indent it, set the literal attribute on top of the element.”
But honestly I don’t get why the way of declaration should affect how the block relates to precedent elements.

Also I have seen that when adding a subs on top (e.g. [subs=”+attributes”]), it behaves as options 2 and 3 always.

So then, why is that? Is option 1 current behavior a bug or a hidden shortcut?

PS: I know I can use option 1 for multi-line also, but I find the delimited way much more expressive and easy to spot in longer and more complex documents.
Reply | Threaded
Open this post in threaded view
|

Re: Different behaviour of literal blocks depending on definition way

mojavelinux
Administrator
Option 1 is a shorthand in AsciiDoc that traces back to AsciiDoc Py. Technically, it's not a literal block, but rather a literal paragraph. It's gets a little bit of special treatment.

I agree that for anything more than a single line, the block form is preferred. I tend to use the literal paragraph for terminal commands only.

Cheers,

-Dan

On Fri, Sep 15, 2017 at 12:15 PM abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:
According to documentation a literal block can be defined in three ways

1. Indenting the first line of a paragraph by one or more spaces
2. Applying the literal attribute to a paragraph or block
3. Using the literal block delimiter (.... )

ref: http://asciidoctor.org/docs/user-manual/#literal-text-and-blocks
But I have seen that when using the second and third options the block does not continue the previous content (example below). This seems odd to me and forces me always to back-track and relate it with a `+`.

Let’s say I have something like this:

. Step 1

 $ nice magic command here

. Step 2

….
$ nice magic command also \
but this is a \
 multiline example
….
The first block is included as part of the numbered element and is properly indented. However in the second case the block is not, so I have to add a + before it.
I suspect this may have something to do with this sentence in the documentation “When you want an entire block of text to be literal and would prefer not to indent it, set the literal attribute on top of the element.”
But honestly I don’t get why the way of declaration should affect how the block relates to precedent elements.

Also I have seen that when adding a subs on top (e.g. [subs=”+attributes”]), it behaves as options 2 and 3 always.

So then, why is that? Is option 1 current behavior a bug or a hidden shortcut?

PS: I know I can use option 1 for multi-line also, but I find the delimited way much more expressive and easy to spot in longer and more complex documents.



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Different-behaviour-of-literal-blocks-depending-on-definition-way-tp5912.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux