Mention that converters can also log
MODIFY
asciidoctorj-documentation/src/test/java/org/asciidoctor/integrationguide/converter/TextConverter.java
asciidoctorj-documentation/src/test/java/org/asciidoctor/integrationguide/converter/TextConverter.java
@@ -7,6 +7,8 @@ import org.asciidoctor.ast.Section;
import org.asciidoctor.ast.StructuralNode;
import org.asciidoctor.converter.ConverterFor;
import org.asciidoctor.converter.StringConverter;
+import org.asciidoctor.log.LogRecord;
+import org.asciidoctor.log.Severity;
import java.util.Map;
@@ -41,6 +43,8 @@ public class TextConverter extends StringConverter {
String content = (String) block.getContent();
return new StringBuilder(content.replaceAll(LINE_SEPARATOR, " "))
.append(LINE_SEPARATOR).toString(); // <5>
+ } else {
+ log(new LogRecord(Severity.WARN, "Unexpected node")); // <6>
}
return null;
}

MODIFY
docs/modules/ROOT/examples/org/asciidoctor/integrationguide/converter/TextConverter.java
docs/modules/ROOT/examples/org/asciidoctor/integrationguide/converter/TextConverter.java
@@ -7,6 +7,8 @@ import org.asciidoctor.ast.Section;
import org.asciidoctor.ast.StructuralNode;
import org.asciidoctor.converter.ConverterFor;
import org.asciidoctor.converter.StringConverter;
+import org.asciidoctor.log.LogRecord;
+import org.asciidoctor.log.Severity;
import java.util.Map;
@@ -41,6 +43,8 @@ public class TextConverter extends StringConverter {
String content = (String) block.getContent();
return new StringBuilder(content.replaceAll(LINE_SEPARATOR, " "))
.append(LINE_SEPARATOR).toString(); // <5>
+ } else {
+ log(new LogRecord(Severity.WARN, "Unexpected node")); // <6>
}
return null;
}

MODIFY
docs/modules/ROOT/pages/write-converter.adoc
docs/modules/ROOT/pages/write-converter.adoc
@@ -25,6 +25,9 @@ This could be for example the value `embedded` to indicate that the resulting do
If it is `null` the transformation usually is defined by the node type and name.
<5> Calls to the method `getContent()` of a node will recursively call the method `convert()` with the child nodes again.
Thereby the converter can collect the rendered child nodes, merge them appropriately and return the rendering of the whole node.
+<6> Converters can log messages in the same way as xref:extensions:logging.adoc[extensions].
+These messages will also be forwarded to build tools like the Asciidoctor Maven plugin and allow xref:maven-tools:plugin:goals/process-asciidoc.adoc#configuration-logHandler[failing the build] on certain messages.
+
Finally, the converter can be registered and used for conversion of AsciiDoc documents:

Mention that converters can also log