Add documentation for logging from extensions

[robertpanzer]

Thank you for opening a pull request and contributing to AsciidoctorJ!

Please take a bit of time giving some details about your pull request:

Kind of change

• Bug fix
• New non-breaking feature
• New breaking feature
• Documentation update
• Build improvement

Description

Add documentation for how an extension can log messages that are also captured by build tools like the maven or gradle plugin.

[abelsromero]

I think the parenthesis are a leftover?

[robertpanzer]

I copied this sentence as is from the Asciidoctor.js module to make sure that we don't provide deviating definitions. :D
But yeah, I'll remove the parens.

[mojavelinux]

I tested this and it works great. This is exactly what I had in mind for being able to log from an extension.

log(new org.asciidoctor.log.LogRecord(org.asciidoctor.log.Severity.WARN, "Hello, World!"));

[mojavelinux]

Something I think we should add to the docs is how to configure JUL so that it matches the default log output of Asciidoctor Ruby. This is more of demonstration, but it gives the user a launching off point.

logging.properties

handlers = java.util.logging.ConsoleHandler
.level = WARNING
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format = %3$

Calling asciidoctorj:

JAVA_OPTS="-Djava.util.logging.config.file=$PWD/logging.properties" asciidoctorj document.adoc

Let me know if you'd like a separate issue for that and I'll file it.

[mojavelinux]

Keep in mind that if the default level is INFO instead of WARNING, users will see provisional messages about possible invalid xrefs...which could be valid xrefs that Asciidoctor just can't resolve.

[robertpanzer]

Thanks for the feedback!
I added some notes on this to the description of the log handling API, since this is also the place that mentions that log messages are automatically forwarded to JUL.

[robertpanzer]

Added a comment to the converter docs that they can also log by calling log().
The current docs "just" show how to implement a string based converter that extends the abstract class StringConverter.
For arbitrary, binary formats there is also an approach based exclusively on interfaces.
We might want to document this in the future.