Subject: Re: [xml2rfc] #311 (Version 2 cli): ability to suppress author org on first page

From: "xml2rfc issue tracker" <[email-masked]>
Date: Mon, 29 May 2017 17:41:02 -0000

#311: ability to suppress author org on first page

Comment (by [email-masked]):

 Fixed in [2307]:

 Merged in [2216] from [email-masked]:
 Use authorship PI with value 'IAB' to trigger IAB header
 formatting (show authors but not organizations on first page).
 Fixes issue #311.

-- 
------------------------------+----------------------------------
  Reporter:  [email-masked]  |      Owner:  [email-masked]
      Type:  enhancement      |     Status:  closed
  Priority:  medium           |  Milestone:
 Component:  Version 2 cli    |    Version:  2.4.x
Resolution:  fixed            |   Keywords:
------------------------------+----------------------------------

Ticket URL: </ticket/311#comment:2>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>

---

From: "xml2rfc issue tracker" <[email-masked]>
Date: Tue, 30 May 2017 13:42:49 -0000

Comment (by [email-masked]):

 I may sound like a broken record, but still...: we shouldn't add new
 functionality to PIs, in particular *not* when asked by the production
 center. If this is required functionality, it *has* to be added as a new
 v3 feature.

Ticket URL: <https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/311#comment:3>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>

---

From: "xml2rfc issue tracker" <[email-masked]>
Date: Tue, 30 May 2017 21:25:11 -0000

Fixed in [2317]:

 The implementation of PI 'authorship' in the original TCL tool could
 suppress the Author's Address section, while in the current implementation
 it removed some author information on the first page.  Changed to the
 original semantics.  Also changed to used the submissionType setting to
 trigger the behaviour described in issue #311. Fixes issue #311 without
 overlaying this on the 'authorship' PI.

Ticket URL: </ticket/311#comment:4>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>

---

From: "xml2rfc issue tracker" <[email-masked]>
Date: Tue, 30 May 2017 23:15:09 -0000

Changes (by [email-masked]):

 * status:  closed => reopened
 * resolution:  fixed =>

      Type:  enhancement      |     Status:  reopened
Resolution:                   |   Keywords:

Ticket URL: <https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/311#comment:5>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>

---

From: "xml2rfc issue tracker" <[email-masked]>
Date: Wed, 31 May 2017 10:30:43 -0000

See related V3 ticket: https://github.com/rfc-format/draft-iab-
 xml2rfc-v3-bis/issues/20

Ticket URL: <https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/311#comment:6>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 31 May 2017 16:08:43 +0200

Hi Julian,

>  center. If this is required functionality, it *has* to be added as a new

Changing the subject a bit, triggered by the comment above and recent
experience:

So, I don't see any consideration given in v3 to how to better control
orphans, widows, and page breaks.  That's an area where either better
PIs or vocabulary support would be needed.  With the current official
PIs there's no way to ask for a page break before the ToC, and the way
to ask for a page break before a section or paragraph is very obscure.

I don't personally really care whether it's done via PIs or vocabulary
options, but I do care about having it.  I suspect that there are people
who very much would like to get rid of the PIs -- well, in that case,
I think it's necessary to provide knobs in the vocabulary which does
what's needed.  Just ignoring page breaking isn't an option if we want
to produce PDFs and paginated text that looks good.

(When I was poking at the IAB no-author-org-names-on-front-page issue,
I used the draft xml for RFC 7754 as a test case, and wanted to see if
I could make the xml2rfc output look exactly as the published RFC.  In
order to do that, I had to insert <?rfc needLines="-1" ?> in a number
of places, and also introduce a new PI "tocpagebreak" to trigger the
needed page break before the Table of Contents.  Needing manual insertion
of page break points because there are no proper orphan and widow controls
is sad.  I don't see why we should not provide tools which will let the
RFC Production Center staff easily produce documents that actually look
the way they think they should look ...)

Best regards,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Wed, 31 May 2017 16:31:03 +0200

On 2017-05-31 16:08, Henrik Levkowetz wrote:
> ...

We had epic discussions about this topic, and IMHO the general feeling 
was that paginated output really isn't that important. Even the 
attribute you're referring to didn't get a real consensus.

Why would we ever want to control whether the ToC starts on a new page 
or not? (yes, that's a serious question).

> the way they think they should look ...)

Apparently you're looking at this from a different angle than I do. My 
proposal is to entirely get rid of the "we control vertical whitespace" 
topic. It's - again IMHO - an entire waste of time.

Yes, the defaults should be sensible - thus, under normal conditions, we 
shouldn't see orphans or windows anyway.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 31 May 2017 16:56:26 +0200

> We had epic discussions about this topic, and IMHO the general feeling was that paginated output really isn't that important.

Well, if there ever was consensus on that, it was pretty rough...

> Even the attribute you're referring to didn't get a real consensus.

And it shouldn’t, because tweaking (which is what we are talking about here) is not semantic markup.
This should be a PI.

> Why would we ever want to control whether the ToC starts on a new page or not? (yes, that's a serious question).

Because there are some authors that care?
(I like to have at least one of those picky people as a co-author on an RFC; then I can at least be sure that things like DOIs are going to be right :-)

>> order to do that, I had to insert <?rfc needLines="-1" ?>

Whoa, there is such a thing?  I always used <vspace blankLines='999’/>, which looks strange in the HTML :-)

>> in a number
> Apparently you're looking at this from a different angle than I do. My proposal is to entirely get rid of the "we control vertical whitespace" topic. It's - again IMHO - an entire waste of time.

Discussing whether there is a need indeed is — we will always disagree on this question.
So why don’t we let Henrik fix this bug and go on with our lives?

> Yes, the defaults should be sensible - thus, under normal conditions, we shouldn't see orphans or windows anyway.

Very much so.

We need tweaks when the formatter cannot see something that is important to a human consumer of the text, such as an unfortunate page break.

(Oh, and we may need different tweaks for different kinds of paginated output, such as PDF and TXT; that may be something that still needs to be put into the PI processing.)

Grüße, Carsten

---

From: Fred Baker <[email-masked]>
Date: Wed, 31 May 2017 08:10:02 -0700

> On May 31, 2017, at 7:56 AM, Carsten Bormann <[email-masked]> wrote:
> 

Agreed. 

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

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 31 May 2017 17:53:20 +0200

Hi Julian,

On 2017-05-31 16:31, Julian Reschke wrote:
> was that paginated output really isn't that important.

I think the design group needs to accept that there are other people with
legitimate needs which ask for this.  It really doesn't matter if you as
a user don't see it as important, if there are users of the tool who does ...

> Even the 

Because the ToC might fit on one page, and doing a page break before it
would give a much nicer reader experience than getting a break in the
middle of the ToC, when that can be avoided.

> topic. It's - again IMHO - an entire waste of time.

But then, as a user you're perfectly free to not care, and not use it --
but you're blocking people who care from being able to write tooling which
treats this right, when you refuse to listen to the request to include
support for this.

The result will of course be that since there's no vocabulary support, there
will be PIs (which I think you want to avoid).

> shouldn't see orphans or windows anyway.

There are defaults, which are set for 2 lines on each side of the page break.
And for RFC 7754 the RFC-Editor staff seems to have done post-processing
which instead used a value of 3.  3 is a perfectly legitimate choice, which
cannot be provided by today's xml2rfc.

Best regards,

	Henrik

---

From: Nico Williams <[email-masked]>
Date: Wed, 31 May 2017 11:19:32 -0500

On Wed, May 31, 2017 at 04:31:03PM +0200, Julian Reschke wrote:
> We had epic discussions about this topic, [...]

We'll all agree to that!

>                                    [...], and IMHO the general feeling was
> that paginated output really isn't that important. Even the attribute you're
> referring to didn't get a real consensus.

It's easy to say we're divided on this so there's no consensus, but I
think that's just lame -- this isn't an Internet protocol we're
discussing, but a document format and tools.  The real question is
whether *implementors* are going to implement this, and so far the
answer is "no", leaving users who want this to submit a PR as they
(naturally) cannot force implementors to do it -- that seems fair
enough.

> not? (yes, that's a serious question).

When the abstract runs long and causes the ToC to be split weirdly
between two pages, it looks ugly.  Especially to the reader who reads a
printout.  Whenever the ToC fits on one page, it is very, very nice to
have it be on one page when you print the doc -- you can more easily
find it.

How often do you print I-Ds/RFCs?

Nico
--

---

From: Julian Reschke <[email-masked]>
Date: Wed, 31 May 2017 18:42:50 +0200

> a user don't see it as important, if there are users of the tool who does ...

Well, the audience in this context really was the RFC production center, 
FWIW.

> middle of the ToC, when that can be avoided.

Then a formatter should just do that automatically. Why does it need a 
hint for that?

> treats this right, when you refuse to listen to the request to include

If you feel strongly about this, raise tickets.

> will be PIs (which I think you want to avoid).

And per RFC, these PIs will have zero effect on the final RFC production 
as they get removed by the preptool.

> cannot be provided by today's xml2rfc.

Why do we need to support both? Seriously? Isn't it a goal to have a 
consistent look for all RFCs?

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Wed, 31 May 2017 18:45:06 +0200

On 2017-05-31 18:19, Nico Williams wrote:
> .. >

Yes. So why do weed a hint for that. Let's state the rule, and have the 
formatter do it without additional work by the author.

> How often do you print I-Ds/RFCs?

Occasionally before traveling so I can read on the airplane.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 31 May 2017 19:30:22 +0200

Hi Julian,

> Well, the audience in this context really was the RFC production center, 

Understood, but I think consideration for features not currently included
in v3 should be taken seriously when requested by future users of the format.

> Then a formatter should just do that automatically. Why does it need a 

Because there might be a judgement call here.  But certainly, if the RFC
Editor makes a request for such a feature, it can be added!

> If you feel strongly about this, raise tickets.

Mmm.  I'm not happy about that response.  I thought this was the IETF, and
a legitimate way to effect changes was to discuss things on the relevant
mailing list, and seek consensus.  Which is what I've been trying to do here;
saying 'raise tickets' after a reasonably sane discussion feels like a way
to avoid going where that discussion is heading.

> as they get removed by the preptool.

Aha.  So when one later processes the xml to paginated format, one is going
to end up without any of the refinements provided by the PIs.

This makes it essential to either seriously consider requests for page break
features in the vocabulary, or change stance on the preptool removing PIs.

> consistent look for all RFCs?

Hmm, right.  We should be consistent all across the range, from RFC 1 and
forever?   No, things may change, a document with a lot of text may need
different settings than a document with a lot of code; I can imagine that
an editor might choose different settings for different documents.  But
if the RFC editor is happy with one single setting, I'm willing to change
the current flavour of xml2rfc to use that value for minimum lines at start
and end of page.  However, the _next_ time there's a request for a setting
change, I'll definitely want it to be incorporated into the vocabulary, or
made available as a PI which won't be eradicated by the preptool.

Best regards :-)

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Wed, 31 May 2017 19:37:17 +0200

> Editor makes a request for such a feature, it can be added!

See? That's exactly what scares me. I don't want the production center 
to make judgement calls, if this can be avoided. I think right now way 
too much time is spent optimizing vertical whitespace with too little gain.

> to avoid going where that discussion is heading.

Sorry, I didn't want to make that impression. I was mentioning the issue 
tracker because - AFAIU - it realistically is the only way to get actual 
changes into the vocabulary. Note that the spec is *not* an IETF 
consensus work - it's "owned" by the IAB.

(And no, I'm not happy with that situation, either).

> features in the vocabulary, or change stance on the preptool removing PIs.

One of these, yes.

> made available as a PI which won't be eradicated by the preptool.

I could also imagine a command line setting or a config file :-).

Anyway, what's important to me is consistency.

Best regards, Julian

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Wed, 31 May 2017 18:01:12 +0000

On 5/31/17, 1:37 PM, "xml2rfc on behalf of Julian Reschke" <[email-masked] on behalf of [email-masked]> wrote:

    > Editor makes a request for such a feature, it can be added!

There are two different things that have been getting discussed here: 1) orphan+widow control, and 2) having some way to ensure that certain larger blocks are kept together.

The v3 PDF spec requires that the processor does proper orphan and widow control. This is a given, at least for PDF output.

The current v3 text spec removed all discussion of pagification. If you dislike that, be a squeaky wheel.

However, the v3 vocabulary does not have a way to say “keep this block together if at all possible”. If you want something along those lines, be a squeaky wheel.

	Tony

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 31 May 2017 20:02:26 +0200

Hi Julian,

> too much time is spent optimizing vertical whitespace with too little gain.

?? Do you have information on how much time is spent on that?

Trying to put myself in their place, it's just one detail out of a myriad
of details which each warrant attention, in order to produce a good document.

And there certainly is a difference in readability between a good document,
and some of the drafts that pass though IETF WGs.

I would not for pretty much anything try to take the editorial judgement
calls out of the loop -- our standards would end up being much harder to
read and make sense of.

Don't begrudge the RFC-Editor staff the tools needed to be able to produce
documents they are happy to publish, also in the case where this involves
a decision to break a page in one place, rather than another, where paginated
PDFs or .txt is concerned.

> consensus work - it's "owned" by the IAB.

Ok.  And hmm.  ... And the IAB has pronounced that mailing list discussions
on the topic are to be ignored, as long as there is no ticket?

> (And no, I'm not happy with that situation, either).

Ok, understood.

>> features in the vocabulary, or change stance on the preptool removing PIs.

Ok.

> Anyway, what's important to me is consistency.

Ok :-)

	Henrik

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 31 May 2017 20:19:15 +0200

Hi Tony,

On 2017-05-31 20:01, HANSEN, TONY L wrote:
> There are two different things that have been getting discussed here:
> 1) orphan+widow control, and 2) having some way to ensure that
> certain larger blocks are kept together.
> 
> The v3 PDF spec requires that the processor does proper orphan and
> widow control. This is a given, at least for PDF output.

But it doesn't provide for any settings related to that.  And as I just
discovered for one RFC, the desired number of lines kept together on
each side of the break may differ between what a human finds optimal,
and what's encoded in a tool.

> you dislike that, be a squeaky wheel.

I'm definitely objecting.  And I thought it was and expressed desire to
get feedback on the specifications, as work on implementation got done?

Was I wrong in that?  If so, and if the IAB is willing to say that the
deficiencies I observe should be ignored, then, I won't feel there's
much sense in saying anything, of course.

> However, the v3 vocabulary does not have a way to say “keep this
> block together if at all possible”. If you want something along those
> lines, be a squeaky wheel.

I think that whoever is supposed to be in control of this specification
(and Julian's comment about 'raise tickets' makes me feel that exactly
who that is, is somewhat obscure) should care when deficiencies are
pointed out.  Even if in some ears it sounds as a squeaky wheel.

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Wed, 31 May 2017 20:30:23 +0200

> on the topic are to be ignored, as long as there is no ticket?

No. I just don't think that the authors of the v3bis spec actually are 
reading this.

Best regards, Julian

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Wed, 31 May 2017 18:34:24 +0000

On 5/31/17, 2:19 PM, "Henrik Levkowetz" <[email-masked]> wrote:

    Hi Tony,

    

    

You are correct: feedback is absolutely desired.

I think the proper place to “raise tickets” is against the bis specs as issues within github, with supporting discussion on the rfc-interest mailing list.

https://github.com/rfc-format

there’s a repo for each of the v3 specs.

	Tony