Comment-Based Disabling of Value Rules Breaks Asciidoctor PDF Generation

[p0fi]

Check for existing issues

• Completed

Environment

• OS: macOS
• Install Method: Homebrew
• Vale Version: 3.11.2

Describe the bug / provide steps to reproduce it

When trying to disable a specific rule (or vale entirely) via the method described here: https://vale.sh/docs/formats/asciidoc

The generation of a PDF from that source fails. This is the error generated:

asciidoctor: ERROR: failed to parse formatted text: <!-- vale off --> (reason: Expected one of 'br', 'img', 'a', 'strong', 'em', 'code', 'font', 'span', 'button', 'kbd', 'sup', 'sub', 'mark', 'menu', 'del' after < at byte 2)

This is most likely due to the fact that Asciidoctor with backend PDF does only have limited support for passthrough syntax. As described here: https://docs.asciidoctor.org/pdf-converter/latest/passthrough-content/

[p0fi]

This appears to be an upstream issue because asciidoctor-pdf does not support HTML comments. I have also raised an issue in that repository: see asciidoctor/asciidoctor-pdf#2571.

[p0fi]

The maintainer of asciidoctor-pdf thinks that handling comments by ignoring and not rendering them isn't within the project's scope. I find it hard to grasp this perspective, but it does make disabling Vale in AsciiDoc files, which are converted to PDF using asciidoctor-pdf, quite complicated. The author of asciidoctor-pdf recommended wrapping the passthrough comment in backend-specific preprocessor directives like this:

ifndef::backend-pdf[]
pass:[<!-- vale off -->]
endif::[]

Although this method works, it feels a bit too wordy to me. Could there be a simpler way to disable Vale in AsciiDoc files that doesn't depend on HTML comments?

[jdkato]

It depends what you’re trying to ignore. You can ignore based on classes or regex.

In any case, I don’t think this is a bug with Vale.

[p0fi]

The thing is that it is a weird section of the document and I just need to disable spellcheck for some lines. So neither ignore mechanisms work well here.

If I simply put // vale off in the asciidoc file this will not be rendered anywhere but unfortunately this does not disable vale 😥

[jdkato]

The work in #900 is very close to what would be needed to support // comments. The PR is such that it expects opening- and closing-delimiters, but it could be expanded to support only one set.