Processor doesn't fail when it should

[john-cj]

Probably a bug.

If you want the processor to fail when the document contains a missing attribute, set the attribute-missing attribute to warn and pass the --failure-level=WARN option to the processor.

$ asciidoctor -a attribute-missing=warn --failure-level=WARN doc.adoc

As I understand, at least one of these examples should fail:

Hello {Name}!

:attribute-missing: warn

Hello {Name}!

However, in both cases, HTML file was "successfully" created:

<div class="paragraph">
<p>Hello {Name}!</p>
</div>

I haven't tested on Linux, but it occurs at least on Windows. asciidoctor -v:

Asciidoctor 1.5.8 [https://asciidoctor.org]
Runtime Environment (ruby 2.5.3p105 (2018-10-18 revision 65156) [i386-mingw32])
(lc:IBM437 fs:Windows-1252 in:IBM437 ex:IBM437)

[mojavelinux]

Your observation is correct. Your understanding of the --failure-level, however, is not. The --failure-level option controls the CLI exit status of the program. It does not stop Asciidoctor from generating a document. That's because the failure level setting is computed once the processing is complete and is based on what log messages were written during processing.

You can see how it works by chaining a command to Asciidoctor.

asciidoctor -a attribute-missing=warn --failure-level=WARN document.adoc && echo success

In your case, the echo success command will not be executed because the exit status of the program is 1 instead of 0.

[mojavelinux]

So it fails (exit status), just not in the way you were anticipating.

[john-cj]

Understood, thanks.

[john-cj]

Here is simple script to automatically remove "error prone" HTML file:

@echo off
cls
asciidoctor -v -a attribute-missing=warn --failure-level=WARN test.adoc || (timeout 2 >nul & del /f test.html & echo *** File was deleted ***)

It's just another illustration of what Dan said. Of course, it's not suitable for real work: e.g., it's not a good idea to use timeout.

Test file:

Non-existing {variable}

Non-existing <<cross-reference>>

include::non-existing-file.ext[]

[mojavelinux]

That's a nice tip, though I'm no sure why the timeout is necessary. The call to asciidoctor is synchronous, so the or condition will only run once asciidoctor has finished executing.

The feature you were probably anticipating is "fail fast". That's possible using a custom logger (as the logger will receive the log event). It's also proposed as a built-in feature in #803, but it still needs some design work.

Asciidoctor tries not to be overly pedantic to avoid disrupting the writer's work. That's why it will produce a document even with warnings, but gives the tools you need to make that behavior more strict.

[john-cj]

I'm no sure why the timeout is necessary <...>

Yes, exactly, it's not necessary. It was my mistake during testing.

[mojavelinux]

👍