inline mode for rendering

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

inline mode for rendering

mojavelinux
Administrator
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.


wdyt? Is doctype=inline the way to go?

-Dan

--
Reply | Threaded
Open this post in threaded view
|

Re: inline mode for rendering

LightGuardjp
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.


wdyt? Is doctype=inline the way to go?

-Dan

--



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



--
Reply | Threaded
Open this post in threaded view
|

Re: inline mode for rendering

mojavelinux
Administrator
I was thinking about embedded too. But then I realized that embedded is complementary to the doctype. The embedded (or header_footer = false) means that you don't want a document container. (Although not implemented this way currently) we could even have an embedded and non-embedded outputs for doctype=inline.

The reason overriding paragraph doesn't work is because then you are fundamentally changing the backend for one type of use of that backend. You'd end up having to toggle templates around, which is just messy.

The more I think about it, the more it just fits in my mind.

-Dan



On Wed, May 15, 2013 at 1:43 PM, lightguard.jp [via Asciidoctor :: Discussion] <[hidden email]> wrote:
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.


wdyt? Is doctype=inline the way to go?

-Dan

--



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



--



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



--