Subject: [xml2rfc] #194: handling of leading space in figure artwork

From: "xml2rfc issue tracker" <[email-masked]>
Date: Thu, 01 Aug 2013 10:25:24 -0000

#194: handling of leading space in figure artwork

 Regarding the left-hand space on a figure:

 - v2 is literal: it outputs only the space that's actually shown in the
 <figure><artwork> in the XML file *unless* there is zero space,  in which
 case it outputs the normal 3-space margin.
 Figure 1 in the attached file: v2 output has 6 spaces on the left b/c
 that's how many are in the XML file.

 - v1 is not literal: it adds 3 spaces, always.
 Figure 1 in attached v1 output has 9 spaces.

 What is the best thing for v2 to do?
 a) match v1 behavior
 b) remain as it is
 c) do something different

 RFC Editor preference is (a).

-- 
-----------------------------+----------------------------------
 Reporter:  [email-masked]  |      Owner:  [email-masked]
     Type:  defect           |     Status:  new
 Priority:  medium           |  Milestone:
Component:  Version 2 cli    |    Version:  2.4.x
 Keywords:                   |
-----------------------------+----------------------------------

Ticket URL: <http://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/194>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>

---

From: "xml2rfc issue tracker" <[email-masked]>
Date: Thu, 01 Aug 2013 10:57:48 -0000

Comment (by [email-masked]):

 Umm.  When I count the spaces in test_v1.txt (version 1 output) I get 7
 spaces...

 From what I remember of v1 (without now going digging into the code) I
 have a vague idea
 that what it did was more complex -- it would start out with one
 assumption (probably
 adding 3 spaces) but if the figure overran the 72 character margin, it
 would try to
 change the placement to stay within 72 characters ... ?

 I don't have strong feelings about what's right here, but whatever we do,
 consistency
 and predictability is good.

-- 
------------------------------+----------------------------------
Resolution:                   |   Keywords:
------------------------------+----------------------------------

Ticket URL: <http://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/194#comment:1>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>

---

From: Nico Williams <[email-masked]>
Date: Thu, 1 Aug 2013 12:34:34 -0500

> [...]

Exactly: xml2rfc's handling of this must be consistent and
predictable.  And that means: it must be utterly simple.  Either
always add three spaces, or never do (or allow the author to specify
how much space to add).

If artwork overruns the margins, well, for an I-D it's a warning one
might choose to ignore.  Or the author could adjust the artwork.  But
having unpredictable auto-adjustments will complicate the author's
efforts to fit the artwork.

Nico
--

---

From: Julian Reschke <[email-masked]>
Date: Fri, 02 Aug 2013 09:00:12 +0200

> efforts to fit the artwork.

It may make sense to define an indent parameter that defaults to 3 and 
can be adjusted once space runs out.

That being said: allowing wider artwork of course would be an option as 
well...

Best regards, Julian

---

From: Tony Hansen <[email-masked]>
Date: Fri, 02 Aug 2013 04:56:18 -0400

Version 1 is consistent and predictable. Its rules were:
    If length <= 69, indent = 3
    else if length == 70, indent = 2, warn about outdent
    else if length == 71, indent = 1, warn about outdent
    else if length == 72, indent = 0, warn about outdent
    else if length > 72, indent = 0, warn about excess characters
    output line

Version 2 is consistent and predictable. Currently its rules are:
    indent = 3
    if length > 69, warn about excess characters
    output line

The problem is that version 1 and version 2 are different. Consequently,
documents that are acceptable with v1 are not acceptable with v2.

I'm told that this is particularly an issue with MIBs, which I'm also
told tend to use very LONG artwork and often hit that 70-72 range.

The question is which is "proper and correct" and should be the rule
going forward.

    Tony Hansen

---

From: Paul Hoffman <[email-masked]>
Date: Fri, 2 Aug 2013 12:32:16 +0200

On Aug 2, 2013, at 10:56 AM, Tony Hansen <[email-masked]> wrote:

> The problem is that version 1 and version 2 are different. Consequently, documents that are acceptable with v1 are not acceptable with v2.
> 
> I'm told that this is particularly an issue with MIBs, which I'm also told tend to use very LONG artwork and often hit that 70-72 range.
> 
> The question is which is "proper and correct" and should be the rule going forward.

The way version 1 did it is much better than version 2 because it causes more understandable documents to be able to be published.

--Paul Hoffman