Asciidoctor :: Discussion

Adding Words to Title Causes Errors

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

7 messages Options

Jon Forrest

Dec 04, 2018; 4:47am

Adding Words to Title Causes Errors

Ubuntu 18.10
asciidoctor --version = Asciidoctor 1.5.6.1 [http://asciidoctor.org]
Runtime Environment (ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-linux-gnu]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)

I have the following in a file called jon.asc

Pro Git
=======
[preface]
A B C

Running

bundle exec asciidoctor jon.asc

produces no errors, as expected. However, changing the first line to

Pro Git Jon

and running the same command produces

asciidoctor: WARNING: jon.asc: line 6: invalid style for paragraph: preface

Of course, there's no line 6 in jon.asc.

This is obviously a contrived example. However, when I run the same command on a full book, which includes
a bunch of chapters, I get an error message, e.g. "asciidoctor: ERROR: book/03-git-branching/sections/basic-branching-and-merging.asc: line 335: only book doctypes can contain level 0 sections"

Why does adding words to the first line cause errors when nothing else changes?

Thanks,
Jon Forrest

abelsromero

Dec 04, 2018; 7:15am

Re: Adding Words to Title Causes Errors

Not sure about the line 6 error, but while the original example does no produce errors, it does not produce a correct output neither.
In v 1.5.6.1 and 1.5.8 the preface section is processed as part of the author and revision data.
Adding more text makes the confuses de parser in a bad manner.

This is an issue to me, but it points to an error in the source format. I am no expect, but I don't think that preface format is 100% correct, have you checked with https://asciidoctor.org/docs/user-manual/#user-preface?

About the issue in the book it would seem the doktype is not being correctly passed as a parameter to the asciidoctor command, and it is running in article mode.

Jon Forrest

Dec 04, 2018; 10:11pm

Re: Adding Words to Title Causes Errors

On 12/3/2018 11:15 PM, abelsromero [via Asciidoctor :: Discussion] wrote:

> About the issue in the book it would seem the doktype is not being
> correctly passed as a parameter to the asciidoctor command, and it is
> running in article mode.

I'm no expert either, but I do know that running asciidoctor on
https://github.com/progit/progit2 works fine until you change the
line I showed. This problem is preventing me from (slightly) changing
the title of that book.

Jon

abelsromero

Dec 05, 2018; 8:16am

Re: Adding Words to Title Causes Errors

The issue comes from title underline that uses Markdown syntax.
It should be the same length as the title text.

Most of the book already uses normal Asciidoctor syntax for titles (= prefix), I'd recommend replacing it to avoid this kind of issues.

Btw, I run the book with v 1.5.6.1 and 1.5.8 successfully, I also recommend to update to the last version, just change the Gemfile.

Jon Forrest

Dec 05, 2018; 2:45pm

Re: Adding Words to Title Causes Errors

On 12/5/2018 12:16 AM, abelsromero [via Asciidoctor :: Discussion] wrote:
> The issue comes from title underline that uses Markdown syntax.
> It should be the same length as the title text.

That was the cause of the problem!! Thanks for pointing this
out.

> Most of the book already uses normal Asciidoctor syntax for titles (=
> prefix), I'd recommend replacing it to avoid this kind of issues.

I'm taking the existing book and making changes to the text. I'm
not planning on making any changes to the Asciidoc constructs since
I don't really know what I'm doing.

> Btw, I run the book with v 1.5.6.1 and 1.5.8 successfully, I also
> recommend to update to the last version, just change the Gemfile.

That's probably a good idea but I want to track the original book
as closely as possible so I'm not going to do that. If I were
starting from scratch though, I'd definitely do that.

Thanks again for solving my problem.

Jon Forrest

mojavelinux

Dec 05, 2018; 7:48pm

Re: Adding Words to Title Causes Errors

Administrator

Abel correctly pointed out that the title text and the underline must be the same length.

Usually, I would advocate for changing it to an ATX (single-line) section heading as Abel suggested. But I think there is a good reason why this book uses the underline style. That's an implicit way to enable compatibility mode. If that's the case, then you don't want to change anyway it as it could break other syntax.

Just make sure the two lines are the same length and you'll be all good!

Cheers,

-Dan

On Wed, Dec 5, 2018 at 7:45 AM Jon Forrest [via Asciidoctor :: Discussion] <[hidden email]> wrote:

On 12/5/2018 12:16 AM, abelsromero [via Asciidoctor :: Discussion] wrote:
> The issue comes from title underline that uses Markdown syntax.
> It should be the same length as the title text.

That was the cause of the problem!! Thanks for pointing this
out.

> Most of the book already uses normal Asciidoctor syntax for titles (=
> prefix), I'd recommend replacing it to avoid this kind of issues.

I'm taking the existing book and making changes to the text. I'm
not planning on making any changes to the Asciidoc constructs since
I don't really know what I'm doing.

> Btw, I run the book with v 1.5.6.1 and 1.5.8 successfully, I also
> recommend to update to the last version, just change the Gemfile.

That's probably a good idea but I want to track the original book
as closely as possible so I'm not going to do that. If I were
starting from scratch though, I'd definitely do that.

Thanks again for solving my problem.

Jon Forrest

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Adding-Words-to-Title-Causes-Errors-tp6627p6634.html

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

... [show rest of quote]

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

Jon Forrest

Dec 05, 2018; 7:59pm

Re: Adding Words to Title Causes Errors

On 12/5/2018 11:48 AM, mojavelinux [via Asciidoctor :: Discussion] wrote:
> Abel correctly pointed out that the title text and the underline must be
> the same length.

Yep. I never would have guessed. I made the change and everything
is working fine now.

> Usually, I would advocate for changing it to an ATX (single-line)
> section heading as Abel suggested. But I think there is a good reason
> why this book uses the underline style. That's an implicit way to enable
> compatibility mode. If that's the case, then you don't want to change
> anyway it as it could break other syntax.

Absolutely, and the last thing I wanted to do was to get involved with
asciidoc syntax.

> Just make sure the two lines are the same length and you'll be all good!

Yep again. All is well.

Thanks for your help.

Jon