Subject: [xml2rfc] Spacing between texttable cells

From: Robert Stepanek <[email-masked]>
Date: Wed, 06 Sep 2017 11:18:00 +0200

Hi,

I am new to xml2rfc and look for help on a how to format the spacing
between <texttable> cells.

All RFC documents, drafts and examples on the IETF site seem to insert
an empty line between two rows within a table. Yet, when I run the XML
source of these examples through my local xml2rfc installation (version
2.5.1) or the web version, there are *no* spaces inserted between
consecutive rows in the table.

I wouldn't fret about layout that much, but my tables are rather long
and have multi-line cells. Without spacing it would diminish legibility
up to a point that I might switch to using sections.

E.g. I tested it with this example of the IETF presentation on RFC
editing tools [1]. Note how the example in the PDF has empty lines
between rows. The same table in XML

<texttable anchor="table_ex" title="IETF Meetings in 2005">
  <ttcol align="center">IETF #</ttcol>
  <ttcol align="center">City</ttcol>
  <ttcol align="center"># of Attendees</ttcol>
  <c>62</c><c>Minneapolis</c><c>1133</c>
  <c>63</c><c>Paris</c><c>1450</c>
  <c>64</c><c>Vancouver</c><c>1240</c>
  <postamble>Data from http://www.ietf.org/meeting/past.html</postamble>
</texttable>

doesn't insert spaces in my xml2rfc installation. There's also an
example in section 2.3.1.4. in the RFC draft on RFC XML formatting [2].

I attached a complete XML draft document to this mail which includes
both examples and reproduces the missing spaces in the online xml2rfc
tool.

What am I missing?

Thanks,
Robert

[1] https://www.rfc-editor.org/materials/tools_ids_rfcs_94.pdf
[2]
https://xml2rfc.tools.ietf.org/authoring/xml2rfc-1.32/draft-mrose-writing-rfcs.txt

---

From: Julian Reschke <[email-masked]>
Date: Wed, 6 Sep 2017 11:36:55 +0200

> an empty line between two rows within a table. Yet, when I run the XML

Example?

> consecutive rows in the table.

The current version is 2.8, FWIW...

> ...

You should be able to get separator lines using 
<https://www.greenbytes.de/tech/webdav/rfc7749.html#element.texttable.attribute.style>.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 6 Sep 2017 11:42:20 +0200

Hi Robert,

> Yet, when I run the XML

To make our life easier answering questions, please upgrade, e.g.:

pip2 install —upgrade xml2rfc

(pip2 may be called pip on your machine.)

While we are talking about upgrades: The current XML2RFC v2 spec (soon to be superseded by v3) is in RFC 7749.  No need to consult Internet-Drafts from 2006 :-)

(Yes, we have to get better in hiding these historically interesting, but misleading documents.)

Now to the table spacing:

In XML2RFC v2, some presentation features are controlled by PIs (XML processing instructions).
Depending on whether the PI ‘compact’ is set to yes or no, a blank row is inserted between rows of table cells.

Example (in kramdown-rfc, because I don’t write XML any more):

<?rfc compact="yes"?>

| Length ll | uint    | sint   | float  *foo* |
|         0 | *uint8* | sint8  | binary16     |
|         1 | uint16  | sint16 | binary32     |
|         2 | uint32  | sint32 | binary64     |
|         3 | uint64  | sint64 | binary128    |
{: #lengths-compact title="Length values"}

<?rfc compact="no"?>

| Length ll | uint    | sint   | float  *foo* |
|         0 | *uint8* | sint8  | binary16     |
|         1 | uint16  | sint16 | binary32     |
|         2 | uint32  | sint32 | binary64     |
|         3 | uint64  | sint64 | binary128    |
{: #lengths-spacey title="Length values"}

generates:

               +-----------+---------+--------+-----------+
               | Length ll | uint    | sint   | float     |
               +-----------+---------+--------+-----------+
               | 0         | _uint8_ | sint8  | binary16  |
               | 1         | uint16  | sint16 | binary32  |
               | 2         | uint32  | sint32 | binary64  |
               | 3         | uint64  | sint64 | binary128 |
               +-----------+---------+--------+-----------+

                          Table 1: Length values

               +-----------+---------+--------+-----------+
               | Length ll | uint    | sint   | float     |
               +-----------+---------+--------+-----------+
               | 0         | _uint8_ | sint8  | binary16  |
               |           |         |        |           |
               | 1         | uint16  | sint16 | binary32  |
               |           |         |        |           |
               | 2         | uint32  | sint32 | binary64  |
               |           |         |        |           |
               | 3         | uint64  | sint64 | binary128 |
               +-----------+---------+--------+-----------+

                          Table 2: Length values

Right, this is not said anywhere in RFC 7749.
But of course we have the source of the xml2rfc formatter :-)

Grüße, Carsten

---

From: Robert Stepanek <[email-masked]>
Date: Wed, 06 Sep 2017 11:49:15 +0200

Thanks Carsten!

<?rfc compact="no"?> did the trick.

Cheers,
Robert

On Wed, Sep 6, 2017, at 11:42, Carsten Bormann wrote:
> While we are talking about upgrades: The current XML2RFC v2 spec (soon to
> be superseded by v3) is in RFC 7749.  No need to consult Internet-Drafts
> from 2006 :-)
>

---

From: Julian Reschke <[email-masked]>
Date: Wed, 6 Sep 2017 12:45:10 +0200

> Depending on whether the PI ‘compact’ is set to yes or no, a blank row is inserted between rows of table cells.

I wasn't aware that PIs affect table formatting; interesting.

> {: #lengths-spacey title="Length values"}

RFC 7749 describes the vocabulary, not processor-specific processing 
instructions... Also note that V3 deprecates <texttable> in favor of 
<table>, removing *all* styling options. Feedback on that should be sent 
before it's too late :-)

> But of course we have the source of the xml2rfc formatter :-)

Yup.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 6 Sep 2017 13:01:31 +0200

On Sep 6, 2017, at 12:45, Julian Reschke <[email-masked]> wrote:
> 
> RFC 7749 describes the vocabulary, not processor-specific processing instructions…

Well, it is more or less random what went into the element/attribute structure (including “styles”) and what went into PIs.  I don’t think XML2RFC is particularly usable without what is now in the PIs.

> Also note that V3 deprecates <texttable> in favor of <table>, removing *all* styling options. Feedback on that should be sent before it's too late :-)

Hmm, feedback will come once people are trying to get their documents done with the new toys.
By definition, it cannot be “too late” then — any feedback before that is speculative.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Wed, 6 Sep 2017 13:33:36 +0200

> Well, it is more or less random what went into the element/attribute structure (including “styles”) and what went into PIs.  I don’t think XML2RFC is particularly usable without what is now in the…

What went into PIs were usually "ad hoc" changes that never got any 
review, and most of these got too little documentation.

> By definition, it cannot be “too late” then — any feedback before that is speculative.

Of course it's a bit of speculation; but we do have a corpus of existing 
documents, no?

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 6 Sep 2017 14:17:35 +0200

> review, and most of these got too little documentation.

True, but in many cases things went into the PIs because there was a need.

I'm convinced that there are more than one case where the first issue
of the v3 vocabulary does not provide for the needs that drove the PIs.

Best regards,

	Henrik

> _______________________________________________
> xml2rfc mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc
>

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 6 Sep 2017 14:21:22 +0200

> Hmm, feedback will come once people are trying to get their documents

Right.  I hope to make the first release of the preptool during September,
and then the v3 xml2rfc text converter next.  At that point, real feedback
should be possible not only on the tool implementation, but on the vocabulary.

> By definition, it cannot be “too late” then — any feedback before

I agree.

	Henrik

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 6 Sep 2017 16:34:03 +0200

> On Sep 6, 2017, at 13:33, Julian Reschke <[email-masked]> wrote:
> 
> What went into PIs were usually "ad hoc" changes that never got any review, and most of these got too little documentation.

It got a lot of review from the people using it…

> Of course it's a bit of speculation; but we do have a corpus of existing documents, no?

Well, yes, but that doesn’t help much here.

(The fact that we are discussing the ‘compact' PI here as if its use were unusual — although it occurs about 3000 times in the corpus of ~ 2000 documents I have — should be ample demonstration.)

Where v3 just uses established techniques from v2 or there is a straightforward translation, the corpus helps.

But nobody has gone ahead and translated all the texttables in the corpus from v2 into v3 tables.  Nobody knows whether the results of applying v3 tables will look good (as opposed to confusing readers).  I’d say each new design in v3 is speculative and needs to be subject to an iterative improvement process based on real usage experience.

Grüße, Carsten

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Wed, 6 Sep 2017 14:46:23 +0000

The v3 design is oriented away from paper presentation and towards newer formats: html and, in the future, things like ePub. So features that are very specific to how the layout works on paper have been downplayed. The “compact” PI is an example of that: it affects the layout on paper and nothing else.

	Tony Hansen

---

From: Julian Reschke <[email-masked]>
Date: Wed, 6 Sep 2017 17:00:23 +0200

> (The fact that we are discussing the ‘compact' PI here as if its use were unusual — although it occurs about 3000 times in the corpus of ~ 2000 documents I have — should be ample demonstration.)

The problem with "compact" (and "subcompact") is that it does many 
things at once, and has little documentation at all.

> But nobody has gone ahead and translated all the texttables in the corpus from v2 into v3 tables.  Nobody knows whether the results of applying v3 tables will look good (as opposed to confusing rea…

Well, we know that it'll be ugly.

What complicates things is that the primary target of the V3 vocab is 
HTML output, while for V2 it was plain text (where micro-managing 
whitespace is way more popular).

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Wed, 6 Sep 2017 18:07:52 +0200

> The v3 design is oriented away from paper presentation and towards newer formats: html and, in the future, things like ePub. So features that are very specific to how the layout works on paper have…

Hm, when you say "on paper" you mean in plain text, I assume?

It certainly affects the HTML output of rfc2629.xslt (for lists), and I 
*believe* it does that in xml2rfc's HTML output as well (maybe not in 
V2, though).

Best regards, Julian

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Wed, 6 Sep 2017 13:37:01 +0000

On 9/6/17, 8:17 AM, "xml2rfc on behalf of Henrik Levkowetz" <[email-masked] on behalf of [email-masked]> wrote:

    

Yeah, I’ve been long convinced of that too.

	Tony

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Wed, 6 Sep 2017 17:38:36 +0000

On 9/6/17, 12:07 PM, "Julian Reschke" <[email-masked]> wrote:

[TH] yes

[TH] I didn’t think the PI affected v2 xml2rfc’s HTML output, but I may be mistaken.

The point is: in v1 and v2, paper/plain text ruled. In v2, it doesn’t.

	Tony Hansen