The Asciidoctor Javadoc integration (Asciidoclet) brought to light an important use case that is missing in Asciidoctor (and AsciiDoc). While Javadoc comments can be output as partial HTML documents (and hence block elements), tag content can only be marked up with inline HTML (or else it breaks Javadoc).

The way AsciiDoc and Asciidoctor work today, if you pass a string such as:

http://asciidoc.org[AsciiDoc] is a _lightweight_ markup language.

You get:

<div class="paragraph">

<p>

<a href="http://asciidoc.org">AsciiDoc</a> is a <em>lightweight</em> markup language.

</p>

</div>

That's because a single line of text is a paragraph block, and that paragraph block is passed through the paragraph template. The result is that the text is wrapped in paragraph markup.

For the tag content in Javadoc, the output we need is just the paragraph content. In other words, the inline formatted text:

<a href="http://asciidoc.org">AsciiDoc</a> is a <em>lightweight</em> markup language.

The solution is simple, just get the first block in the document, validate that it's a paragraph block and print the result of the #content() method. You'll get exactly the output in the previous listing.

The question is, How do we specify this behavior? When I look around the AsciiDoc "spec", I see that this could be a good use for the doctype property. Currently, Asciidoctor supports two values, "book" and "article". The value of the proper determines the container that is used around the document...and some rendering rules as well (such as what level headings are allowed). AsciiDoc supports additional doctypes, such as "manpage". Again, that determines how the output is wrapped.

Thus, it makes sense to me to add the value "inline" that enforces these rendering rules:

-Dan