inline mode for rendering

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:

1. Only a single paragraph is rendered from the parsed document

2. Inline formatting & normal (paragraph) substitutions are applied

3. The content is output as-is, not wrapped in the normal paragraph tags

You apply the rules as follows:

puts Asciidoctor.render("http://asciidoc.org[AsciiDoc] is...", :doctype => :inline)

I've sent a pull request that implements this behavior.

https://github.com/asciidoctor/asciidoctor/pull/329

wdyt? Is doctype=inline the way to go?

-Dan

--

Dan Allen | http://google.com/profiles/dan.j.allen

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/inline-mode-for-rendering-tp199.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

My first knee-jerk reaction was "No, inline doesn't really do it." however, after thinking about it I can't come up with anything else. Embedded isn't really it, paragraph doesn't work either. inline may just be the correct one.

On Wed, May 15, 2013 at 1:34 PM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

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:

1. Only a single paragraph is rendered from the parsed document

2. Inline formatting & normal (paragraph) substitutions are applied

3. The content is output as-is, not wrapped in the normal paragraph tags

You apply the rules as follows:

puts Asciidoctor.render("http://asciidoc.org[AsciiDoc] is...", :doctype => :inline)

I've sent a pull request that implements this behavior.

https://github.com/asciidoctor/asciidoctor/pull/329

wdyt? Is doctype=inline the way to go?

-Dan

--

Dan Allen | http://google.com/profiles/dan.j.allen

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/inline-mode-for-rendering-tp199.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

--

Jason Porter
http://en.gravatar.com/lightguardjp

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/inline-mode-for-rendering-tp199p201.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML