Asciidoctor :: Discussion

Is a blank line mandatory between a section title and its content?

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

4 messages Options

Sylvain Leroux

Is a blank line mandatory between a section title and its content?

Sorry to bother you again, but the more I dig into sections, the more I have questions.

So, is a blank line mandatory between a section title and its content?

I noticed this is the case for level 0 sections (otherwise the text is taken as the author name--something which is explained in the docs).
But for levels >0, the empty line seems optional. And all text is taken as content. Is this the desired behavior?

Regards,
- Sylvain

= My section
Some text

More content

== My section
Some text

More content

Produces:

<?xml version="1.0" encoding="UTF-8"?>
<?asciidoc-toc?>
<?asciidoc-numbered?>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info>
<title>My section</title>
<date>2021-01-28</date>
<author>
<personname>
<firstname>Some</firstname>
<surname>text</surname>
</personname>
</author>
<authorinitials>St</authorinitials>
</info>
<simpara>More content</simpara>
<section xml:id="_my_section">
<title>My section</title>
<simpara>Some text</simpara>
<simpara>More content</simpara>
</section>
</article>

my asciidoctor-based website: https://yesik.it

mojavelinux

Re: Is a blank line mandatory between a section title and its content?

Administrator

> So, is a blank line mandatory between a section title and the content?

No, it is not. A section title is self-terminating, just like a block macro.

That said, we consider it a best practice to include a blank line in this location to make the document easier to read. So it's enforced by the recommended style, but not by the parser.

> I noticed this is the case for level 0 sections (otherwise the text is taken as the author name--something which is explained in the docs).

You are confusing a level-0 section title with a document header (document title + metadata). The document header contains a level-0 section that is the doctitle. (https://docs.asciidoctor.org/asciidoc/latest/document/header/) But all other level-0 section titles in a multipart book are parsed just like all the other section titles.

Best Regards,

-Dan

On Thu, Jan 28, 2021 at 2:38 AM Sylvain Leroux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Sorry to bother you again, but the more I dig into sections, the more I have questions.

So, is a blank line mandatory between a section title and the content?

I noticed this is the case for level 0 sections (otherwise the text is taken as the author name--something which is explained in the docs).
But for levels >0, the empty line seems optional. And all text is taken as content. Is this the desired behavior?

Regards,
- Sylvain
= My section
Some text

More content

== My section
Some text

More content
Produces:
<?xml version="1.0" encoding="UTF-8"?>
<?asciidoc-toc?>
<?asciidoc-numbered?>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info>
<title>My section</title>
<date>2021-01-28</date>
<author>
<personname>
<firstname>Some</firstname>
<surname>text</surname>
</personname>
</author>
<authorinitials>St</authorinitials>
</info>
<simpara>More content</simpara>
<section xml:id="_my_section">
<title>My section</title>
<simpara>Some text</simpara>
<simpara>More content</simpara>
</section>
</article>
my asciidoctor-based website: https://yesik.it

If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/Is-a-blank-line-mandatory-between-a-section-title-and-its-content-tp8471.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux

Sylvain Leroux

Re: Is a blank line mandatory between a section title and its content?

mojavelinux wrote

A section title is self-terminating [...]

That also explains why a section's title can't have a continuation (`+`) and MUST be on the same line as the `==` token.

> I noticed this is the case for level 0 sections (otherwise, the text is
taken as the author name--something which is explained in the docs).

You are confusing a level-0 section title with a document header (document
title + metadata). The document header contains a level-0 section that is
the doctitle. (https://docs.asciidoctor.org/asciidoc/latest/document/header/)
But all other level-0 section titles in a multipart book are parsed just
like all the other section titles.

Indeed, this was not clear in my mind. As far as I remember, I never used level-0 sections in my own documents. So, to check my understanding here:

= Some title

The above document fragment could be parsed:

* either as a document header, if it's at the start of the document
* or, as a level-0 section if it's found anywhere else.

Is that correct?

my asciidoctor-based website: https://yesik.it

mojavelinux

Re: Is a blank line mandatory between a section title and its content?

Administrator

On Thu, Jan 28, 2021 at 3:28 AM Sylvain Leroux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

mojavelinux wrote

A section title is self-terminating [...]

That also explains why a section's title can't have a continuation (`+`) and MUST be on the same line as the `==` token.

Section titles have never supported a continuation, so it's more than it just being restricted to a single line. That's suggesting something that just isn't AsciiDoc.

> I noticed this is the case for level 0 sections (otherwise, the text is
taken as the author name--something which is explained in the docs).

You are confusing a level-0 section title with a document header (document
title + metadata). The document header contains a level-0 section that is
the doctitle. (https://docs.asciidoctor.org/asciidoc/latest/document/header/)
But all other level-0 section titles in a multipart book are parsed just
like all the other section titles.

Indeed, this was not clear in my mind. As far as I remember, I never used level-0 sections in my own documents.

level-0 sections are parts in a multi-part book. I agree it's a lesser used feature because not many documents have this structure.

So, to check my understanding here:
= Some title
The above document fragment could be parsed:

* either as a document header, if it's at the start of the document
* or, as a level-0 section if it's found anywhere else.

Again, you're framing this incorrectly. A document has an optional document header. A document header may contain a doctitle, which looks exactly like a level-0 section title. And it doesn't have to be on the first line of the document. It can be anywhere in the document header. See https://docs.asciidoctor.org/asciidoc/latest/document/header/

Once you have passed the document header, any level-0 section is a part. But that is only permitted if the doctype is book. You cannot have a level-0 section title in an article. By adding at least one level-0 section to a book, it implicitly becomes a multi-part book.

Best Regards,

-Dan

Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux