AsciiDoc: Option to disable unintended content warning

[oturpe]

The AsciiDoc plugin produces this kind of warnings:

src/file.adoc:2: It seems that you are adding unindented content to an item. The standard allows this, but you may still want to change your document to use indented text to provide better visual clues to writers.

As said in the warning itself, such lines are allowed by the standard. The source content is not always modifiable. In such situations, warnings like this are not useful, because nothing can be done about them.

Could an option to disable such warnings be added to the AsciiDoc plugin?

See Fedora documentation issue fesco-docs #48 for background.

[jnavila]

I'm perfectly fine with removing this warning. Po4a is not a linter for asciidoc. Anyway, I think this is still a good writing practice for asciidoc to indent line continuations so that the reader understands the structure of the document. In the end, the document's structure is less prone to error cases in alternative parsers. Please remember that there is no real formal specification of asciidoc and that this parser tries to process and understand asciidoc by reverse-engineering and trials.

@oturpe Do you have any reason to not indent the paragraph continuations? (Asking in case I have overlooked a critical detail)

@mquinson ? What do you think?

[oturpe]

Oh, if there is no format specification at all, then what I referred to as "the standard" was actually a random help page in the internet. Perhaps the docs of one of the implementations, I do not even remember which page I was reading.

Anyhow, I have two cases where not emitting warnings would be preferable.

First is the case of the fesco-docs issue I linked to in the report. Fedora documentation uses Asciidoc as the main markup language. The primary, English documentation for each topic is written in one repository. Docs are generated from these repositories using Antora, which does not complain about unintended content in list items. Translators are a different group and run po4a on these repositories. Since po4a does complain about unintended content in list items, the end result is that translators have to either go back to original authors and ask to add the indents or just ignore the warnings. It would be better to not see those warnings at all, since the person running po4a did not write the input and does not deserve the nags.

The second use case is list items with complex content requiring the use of + continuation character:

Do one of these:

. Run this script
that will do it automatically:
+
----
./fix-it.sh --username USER
----
+
replacing USER with your username.

. Manually fix by editing `/some/file`

That example works just fine when indentation is not used. You can play around with it and try to apply indentation. The plus sign cannot be indented at all, it only works as the continuation character at the start of the line. The ---- block and paragraph text following a plus get interpreted wrong if indented. Because of this, to me at least, it is actually cleaner to avoid using indentation for list items. If you do use it, you have to keep thinking when you can, and when you must not, use it.

[mquinson]

I did not react to this issue earlier, mostly because I don't have any good opinion to propose. I tend to agree with @jnavila on this one (as usual): AsciiDoc is not a well specified format, and we should strive to remain compatible with all implementations. This idea of an optionnal linting seems very good to me. Thanks a lot!

[jnavila]

For the absence of indentation when using continuation paragraphs (with a + sign alone on a new line), I fully agree that this is the only option. To me, this breaks the initial deal of asciidoc with the reader that the source file can be easily read and its structure understood, without resorting to learning a particular markup grammar sorcery. Anyway, that's part of the "specification", and it will not change in near the future.

You can still apply indentation to the continuation lines of the same paragraph.

[ciampix]

I can agree with @jnavila but ... how can it be done in another way? If you come up with a better / more intuitive solution, please suggest it to the asciidoc standardization comittee https://www.eclipse.org/org/workinggroups/asciidoc-charter.php