Spacing of definition lists

[opoudjis]

I do not agree with mandating a <vspace/> (<br/> in v3) after the definition text in a definition list: the user should have the option of leaving the definition text inline. This can already be left as a choice in Asciidoc markup, and in fact I've used the option to align definition lists to their text RFC counterparts:

Inline definition list

definition:: Hello

RFC XML 2:

  <list style="hanging">
    <t hangText="SRO Param">Hello</t>
  </list>

RFC XML 3:

<dl>
  <dt>SRO Param</dt>
  <dd>Hello</dd>
</dl>

Next line definition list:

definition::
+
Text

RFC XML 2:

  <list style="hanging">
    <t hangText="SRO Param"><vspace/>Hello</t>
  </list>

RFC XML3:

<dl>
  <dt>SRO Param</dt>
  <dd>
    <t>Hello</t>
  </dd>
</dl>

Increasingly, this looks like we need a style guide to Asciidoc. At any rate, I will add the separate line definition list to rspec.

[ronaldtse]

Aha, the reason the “vspace” is needed is that idnits complains about the white spacing of the resulting definition lists. It is not a stated requirement but will fail IETF validation.

[opoudjis]

Oh. God. Yuck.

[opoudjis]

sigh OK. Putting it back in. I am not touching v3 yet.

The vspace for breaking up multi paragraph lists is still required independently.

[ronaldtse]

Actually I’m a bit torn on this one because you are technically right. Maybe we could use some “option” that acts as a hack in this case... up to you. However if we return the behavior we’d better explain in some style guide how to actually create a RFC that passes idnits validation.

[opoudjis]

Hm.

Yet again, document option. By default in v2, we insert the vspace; if the document option is off, we don't.

[ronaldtse]

Or just enforce the vspace in v2 and forget it.

The option could be called something like definition-vspace or something better...

[opoudjis]

Option is :inline-definition-lists:, defaults to false.

Checked in, refer to spec/asciidoctor/rfc/v2/dlist_spec.rb

[ronaldtse]

Nice stuff. Thanks @opoudjis !