Subject: [xml2rfc] Hangtext spacing

From: Brian E Carpenter <[email-masked]>
Date: Wed, 25 Oct 2017 11:39:02 +1300

Hi,

I just hit a case where xml2rfc outputs text that idnits doesn't like:

<t>There are 3 properties applicable to the installation of ASAs:
 <list style="hanging">
  <t hangText="The dynamic installation property">allows installing an ASA on demand, on any	hosts compatible with the ASA.</t>
  <t hangText="The decoupling property">allows controlling resources of a NE from a remote ASA, i.e. an ASA installed on a host machine different from the resources' NE.</t>
  <t hangText="The multiplicity property">allows controlling multiple sets of resources from a single ASA.</t>
 </list>
</t>

The output looks like this:
   The dynamic installation property  allows installing an ASA on
      demand, on any hosts compatible with the ASA.

   The decoupling property  allows controlling resources of a NE from a
      remote ASA, i.e. an ASA installed on a host machine different from
      the resources' NE.

   The multiplicity property  allows controlling multiple sets of
      resources from a single ASA.

Note the two spaces after the hangtext in each case. Idnits issues
warnings:

  == Line 361 has weird spacing: '...roperty  allow...'

  == Line 364 has weird spacing: '...roperty  allow...'

  == Line 368 has weird spacing: '...roperty  allow...'

Why two spaces?

     Brian

-- 
Regards
   Brian Carpenter

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 25 Oct 2017 13:54:06 +0200

Hi Brian,

>   == Line 368 has weird spacing: '...roperty  allow...'

That's the convention xml2rfc uses to separate the list item identifier
from the item text in a list with hanging indentation.  In your use case,
you don't have a very clear item identifier; I'm not sure how to best
approach this.  Maybe:

 <t>There are 3 properties applicable to the installation of ASAs:
  <list style="hanging">
   <t hangText="The dynamic installation property:"><vspace blankLines="0"/>
    allows installing an ASA on demand, on any hosts compatible with the
    ASA.</t>
   <t hangText="The decoupling property:"><vspace blankLines="0"/>
    allows controlling resources of a NE from a remote ASA, i.e. an ASA
    installed on a host machine different from the resources' NE.</t>
   <t hangText="The multiplicity property:"><vspace blankLines="0"/>
    allows controlling multiple sets of resources from a single ASA.</t>
  </list>
 </t>

which produces:

   There are 3 properties applicable to the installation of ASAs:

   The dynamic installation property:
      allows installing an ASA on demand, on any hosts compatible with
      the ASA.

   The decoupling property:
      allows controlling resources of a NE from a remote ASA, i.e. an
      ASA installed on a host machine different from the resources' NE.

   The multiplicity property:
      allows controlling multiple sets of resources from a single ASA.

Best regards,

	Henrik

---

From: [email-masked] (Dale R. Worley)
Date: Wed, 25 Oct 2017 20:47:31 -0400

> Note the two spaces after the hangtext in each case. Idnits issues

Might the problem be that the hangtext doesn't end in a punctuation
mark?

Dale

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 26 Oct 2017 14:39:22 +1300

> Might the problem be that the hangtext doesn't end in a punctuation

Well, yes and no. As Henrik pointed out (thanks!) the hangtext is
a bit unusual by being purely alphanumeric. Of course the workaround
is obvious. However, shortly afterwards in the document we have

   Inputs are:

   [ASA class of type_x]  that specifies which classes ASAs to install,

Another hangtext that doesn't end in a punctuation mark, does generate
a double space, but *doesn't* upset idnits.

So what upset me is one tool producing output that upset another tool.
If there's a rule that hangtext must not end in an alphanumeric, fine,
but that doesn't seem to be in the DTD.

    Brian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 26 Oct 2017 09:14:37 +0200

On 2017-10-26 03:39, Brian E Carpenter wrote:
> ...
> ...

By definition of what DTDs can do and can not.

That said: hangText doesn't need to end with punctuation.

Given that we're approaching V3, it would make sense to think about how 
your text would actually be written using the new V3 list elements, and 
how it would display then.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Thu, 26 Oct 2017 10:31:58 +0200

> Might the problem be that the hangtext doesn't end in a punctuation

idnits would probably not complain if there was a punctuation mark.  But
the idnits warning is just a warning, to be disregard it if the spacing
is intentional.

	Henrik

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 27 Oct 2017 08:50:16 +1300

> the idnits warning is just a warning, to be disregard it if the spacing

Correct. The visual effect is a bit  ugly though. Clearly we will work
around it for this particular draft; and I agree with Julian that
if anything should change, it should be in the context of v3.

    Brian

---

From: Fred Baker <[email-masked]>
Date: Fri, 27 Oct 2017 08:19:24 +0400

> On Oct 26, 2017, at 12:31 PM, Henrik Levkowetz <[email-masked]> wrote:
> 

Except that reviewers request that drafts be "idnits clean" (produce no idnits comments), in which case an error that the author ignored becomes mandatory to fix.

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 27 Oct 2017 07:38:46 +0200

> Except that reviewers request that drafts be "idnits clean" (produce no idnits comments), in which case an error that the author ignored becomes mandatory to fix.

Well, then it might be time to explain the purpose of this tool to them.
(Is there a convenient place to link to that explains this?)

Grüße, Carsten

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 27 Oct 2017 08:26:16 +0200

> (Is there a convenient place to link to that explains this?)

I added some text to the idnits about page.  I'll also include this in
the help text and manpage when I do the idnits rewrite for the RFC format
tools at the beginning of next year.

See https://tools.ietf.org/tools/idnits/about

Best regards,

	Henrik

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 27 Oct 2017 13:15:20 +0200

Nice!  Thank you. 

Sent from mobile

> On 27. Oct 2017, at 08:26, Henrik Levkowetz <[email-masked]> wrote:
> 
>