Subject: [xml2rfc] Keeping some authors off the front page ?

From: Thomas Morin <[email-masked]>
Date: Tue, 10 May 2011 16:54:08 +0200

Hello folks,

This is about an issue that has already been discussed

While reviewing a draft I edit, the AD in charge pointed out the usual 
"too many authors on the front page" issue:
> Would it be possible to consider moving everyone except for the editor
> off the front page? [all authors] will still all be listed as authors at the end
> of the document.

After reading again the xml2rfc ML archives, in particular the thread in 
October 2008, the understanding I have is that:
- some people would like to do this, but the toolchain does not allow this
- it's been explained that the initial idea is that the "Authors' 
addresses" section should list only the people appearing on the front page
- however, it does not seem there is a strict rule imposing this, and it 
seems there are drafts that list only editors on the front page and more 
people in the "Authors' addresses" section
- the RFC Editor encourages a limitation of the number of authors (for 
both the front page and the "Authors' addresses" contact information 
section): this is motivated at 
http://www.rfc-editor.org/policy.html#policy.authlist
- the AUTH48 process contact people listed on the front page and it is 
thus also encouraged to limit the number of authors on the front page
- the resulting recommendation is to do only declare as authors the 
people who have to appear on the front page, and put others in an 
additional section

It seems to me that restricting what the xml2rfc tool can do based on 
this recommendation is not satisfying at all:
- it seems at the opposite of the path taken for other issues: the 
general thinking seems to be that the tool could be use for other 
purpose than IETF or RFCs, and should not enforce a policy upon users
- it makes users of xml2rfc unable to do what users of other toolchains 
(a) can technically do, and (b) can submit to the IETF with good chances 
of success

So, with the above in mind, why not add a "frontage" attribute to the 
"author" element, which would default to "yes", and if set to "no" would 
just result in the said author to not appear on the front page ... ?

Moreover, implementing the recommended approach with xml2rfc is not great:
- the section with the additional authors has to be written manually 
(cannot use authors elements, even though it can be appropriate to give 
contact information for them too)
- it is not easy to have the same formatting for the two sections, 
especially across all types of output (TXT, HTML, ...)
- this section cannot be put in a close location to the "Authors' 
addresses" section

So, for people wanting to implement the recommended approach in a nicer 
way, could we introduce a special rfc/back/contributors, which could 
include text and "author" elements, and which would be rendered in the 
output right after the "Authors' addresses" section (after References) ?

Thank you,

-Thomas

---

From: Julian Reschke <[email-masked]>
Date: Tue, 10 May 2011 17:06:34 +0200

On 10.05.2011 16:54, Thomas Morin wrote:
> ...

Hi Thomas,

you clearly have done your homework :-).

This has been an issue for a long time. The main blocking issue IMHO 
was/is the lack of direction from the IETF and the RFC Editor. Maybe 
this will be fixed once we have a new RFC Editor.

The issues that I see are:

- the "only 5 authors" rule doesn't make sense if there are indeed more 
authors; yes, this complicates AUTH48, but such is life

- we could add a "contributors" section, but it's not entirely clear how 
it would be different from an Acknowledgments section.

So we really need to come to *stable* (*) consensus about the terms 
"editor", "author", and "contributor".

Best regards, Julian

(*) So we don't need to change the tools all the time...

---

From: Thomas Morin <[email-masked]>
Date: Tue, 10 May 2011 17:35:44 +0200

Hi Julian,

> you clearly have done your homework :-).

I hit the issue several times in the past, and I've been following the 
list... so I know its not trivial.

I wrote this email because, after doing my homework, I got convinced 
that strongly coupling document structure, document rendering and 
process is going to be a dead end.

> this will be fixed once we have a new RFC Editor.

I understand, but the point I'm trying to make is that until IETF/RFC Ed 
gives us better directions, the tool should be flexible.
And in fact, for other uses (personal memo, etc.) the tool should be 
kept flexible, even after the RFC Ed eventually give better directions.

Hence my insistance on having a frontline=yes/no attribute to the author 
element .

> - the "only 5 authors" rule doesn't make sense if there are indeed 
> more authors; yes, this complicates AUTH48, but such is life

I agree, and the solution I would think reasonable is to change the 
process so that in the case where the RFC Editor thinks there are too 
many authors for smooth AUTH48, then it could ask authors to agree on a 
subset of them from which approval would be asked. How this set of 
"AUTH48 authors" is tracked could then become a purely technical matter: 
it could be tracked by tweaking "who is on the front page", but it could 
be handled through another channel independent of document content as well.

> - we could add a "contributors" section, but it's not entirely clear 
> how it would be different from an Acknowledgments section.

In practice, people seem to want to be able to distinguish between 
significant contributors involved from day one, and people who were 
useful but whose participation or support was restricted to a few 
specific points, but defining a strict rule to distinguish the two roles 
may not be doable...

> (*) So we don't need to change the tools all the time...

It might be *very* hard to find working precise definitions for these roles.

Another path which I think might be more reasonable would be to design 
the toolchain independently of any attempt at a consensus on what these 
roles would be, and let this interpretation/policy/process stuff happen 
independently of the toolchain. If the name of the section containing 
the additional people is not constrained (e.g. a title attribute like a 
normal section), then you don't have to define what "contributor" means, 
and tool users can choose to name that section "Contributors", 
"Co-authors" or "Additional authors", or even "Usual suspects", and it 
just will be up to AD's, IESG, RFC Editor to eventually encourage or 
impose a different naming...

-Thomas

---

From: Julian Reschke <[email-masked]>
Date: Tue, 10 May 2011 17:47:34 +0200

> Hence my insistance on having a frontline=yes/no attribute to the author

Well, I'm usually happy to tune *my* xml2rfc processor (rfc2629.xslt). 
However, changing things in xml2rfc.tcl is really really hard, and 
that's why it's currently being rewritten.

But of course designing the vocabulary should be separate from that (and 
happen here!).

> be handled through another channel independent of document content as well.

Another issue is what to do with previous authors when a spec is being 
revised (like what we do in HTTPbis). Just because a few people 
volunteer to work on a revision doesn't change the fact the authorship 
of previous authors (unless all is rewritten from scratch).

> impose a different naming...

Yes and no.

At the end of the day, the XML markup should answer the question: "who 
is author of this document?". We can't just add more <author> elements 
in the same place, when those people really are not authors.

For historical documents, rfc2629.xslt contains an extension that 
provides some flexibility, but of course this doesn't help when you want 
to produce output with xml2rfc.tcl.

See, for instance:

   http://greenbytes.de/tech/webdav/rfc2046.xml

and

   http://greenbytes.de/tech/webdav/rfc2046.html

Best regards, Julian

---

From: Dave CROCKER <[email-masked]>
Date: Tue, 10 May 2011 08:54:56 -0700

On 5/10/2011 8:06 AM, Julian Reschke wrote:
> - we could add a "contributors" section, but it's not entirely clear how it
> would be different from an Acknowledgments section.

If this added section contained entries in the same style as 'authors', then it 
well might resolve the problem of having long lists of authors.

That is, it could permit distinguishing among:

    * folks who produced the document

    * folks who added significantly to the content

    * folks who participated in discussion

and it could provide contact information for the second set.

But as you note, this really is something for the RFC Editor to decide officially.

That said, xml2rfc could add the construct on its own, since there are no rules 
against something like the second bullet construct...

d/
-- 

   Dave Crocker
   Brandenburg InternetWorking
   bbiw.net

---

From: Nico Williams <[email-masked]>
Date: Tue, 10 May 2011 11:23:14 -0500

On Tue, May 10, 2011 at 10:35 AM, Thomas Morin
<[email-masked]> wrote:
> I agree, and the solution I would think reasonable is to change the process
> so that in the case where the RFC Editor thinks there are too many authors
> for smooth AUTH48, then it could ask authors to agree on a subset of them
> from which approval would be asked. How this set of "AUTH48 authors" is
> tracked could then become a purely technical matter: it could be tracked by
> tweaking "who is on the front page", but it could be handled through another
> channel independent of document content as well.

ETOOCOMPLICATED :)  I think the RFC-Editor should send AUTH48 e-mail
to the I-D authors list address (every I-D gets one), and the
RFC-Editor should warn the authors of the need to negotiate a sub-set
of representative authors.  How the authors do that is up to them --
no mechanism need be offered.

That said, there's a different unrelated issue: only so many authors
can fit on the front page, and xml2rfc supports a private (non-IETF)
mode.  Therefore it could provide an option for listing "Joe Sixpack
et. al." on the front page.  It'd also be nice to have a guarantee
that <author> element order matches up with order int he author
section, and, perhaps, a way to add text to the author section, so
that one could list editors, core authors, and contributors without
requiring <author> metadata (though that would be nice too!).

> significant contributors involved from day one, and people who were useful
> but whose participation or support was restricted to a few specific points,
> but defining a strict rule to distinguish the two roles may not be doable...

Why a whole new section when additional text in the Authors section will do?

> Another path which I think might be more reasonable would be to design the
> toolchain independently of any attempt at a consensus on what these roles
> would be, and let this interpretation/policy/process stuff happen
> independently of the toolchain. If the name of the section containing the
> additional people is not constrained (e.g. a title attribute like a normal
> section), then you don't have to define what "contributor" means, and tool
> users can choose to name that section "Contributors", "Co-authors" or
> "Additional authors", or even "Usual suspects", and it just will be up to
> AD's, IESG, RFC Editor to eventually encourage or impose a different
> naming...

+1.

Moreover, the options provided by the toolchain might influence any
policy decisions.

Nico
--

---

From: Julian Reschke <[email-masked]>
Date: Tue, 10 May 2011 18:32:11 +0200

On 10.05.2011 18:23, Nico Williams wrote:
> that<author>  element order matches up with order int he author
> requiring<author>  metadata (though that would be nice too!).
> ....

Like that? <http://greenbytes.de/tech/webdav/rfc2046.html#rfc.section.9>?

Best regards, Julian

---

From: Nico Williams <[email-masked]>
Date: Tue, 10 May 2011 12:33:15 -0500

> Like that? <http://greenbytes.de/tech/webdav/rfc2046.html#rfc.section.9>?

Yes.  That's there now?  If so is the issue just whom to list on the
front page?  Can you add a directive to list only the first author
follow by "et. al."?

---

From: Julian Reschke <[email-masked]>
Date: Tue, 10 May 2011 20:16:41 +0200

On 10.05.2011 19:33, Nico Williams wrote:
> On Tue, May 10, 2011 at 11:32 AM, Julian Reschke<[email-masked]>  wrote:
>> Like that?<http://greenbytes.de/tech/webdav/rfc2046.html#rfc.section.9>?
>

No. Just in rfc2629.xslt.

> front page?  Can you add a directive to list only the first author

On the front page? Is this an accepted format?

---

From: "Dan Wing" <[email-masked]>
Date: Tue, 10 May 2011 17:46:25 -0700

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On
> Behalf Of Julian Reschke
> Sent: Tuesday, May 10, 2011 8:07 AM
> To: Thomas Morin
> Cc: [email-masked]
> Subject: Re: [xml2rfc] Keeping some authors off the front page ?
> 

Is that really necessary?  I mean, what breaks if we don't have
that consensus first?  As an extreme, let's say someone wants to 
put their non-technical boss (who can't type) as editor or 
author or contributor or in acknowledgements.  What gets harmed?

-d

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

---

From: "Dan Wing" <[email-masked]>
Date: Tue, 10 May 2011 17:47:23 -0700

> Behalf Of Thomas Morin
> Sent: Tuesday, May 10, 2011 7:54 AM
> To: [email-masked]
> Subject: [xml2rfc] Keeping some authors off the front page ?
> 
> Hello folks,
> 

Below (and attached) is a patch for xml2rfc 1.36 which allows using
  role="notfirstpage"
in an <author> section.

For example:
  <author fullname="Dan Wing" initials="D." 
   surname="Wing" role="notfirstpage">

This will keep that author off the first page, but the author 
still appears in the "Authors Addresses'" section, as today.

> seems there are drafts that list only editors on the front page and
> more people in the "Authors' addresses" section

Some folks edit things manually, which is a pain.

> (a) can technically do, and (b) can submit to the IETF with good
> chances of success

I expect the [email-masked] alias is built using the addresses
from the Authors Addresses' section, without regard to the first page.  
This may (not) be what is expected.

> output right after the "Authors' addresses" section (after References)

IMHO, having <contributor> which worked exactly like <author>, and 
created a "Contributor['s|s'] Address[es]" section, would be lovely.

-d

-d

-----

diff -crB xml2rfc-1.36/rfc2629.dtd xml2rfc-1.36-dwing/rfc2629.dtd
*** xml2rfc-1.36/rfc2629.dtd    2010-11-27 05:52:09.000000000 -0800
--- xml2rfc-1.36-dwing/rfc2629.dtd      2011-05-10 16:37:26.738645000 -0700
***************
*** 138,144 ****
            initials    %ATEXT;            #IMPLIED
            surname     %ATEXT;            #IMPLIED
            fullname    %ATEXT;            #IMPLIED
!           role        (editor)           #IMPLIED>

  <!ELEMENT organization
                        (%CTEXT;)>
--- 138,144 ----
            initials    %ATEXT;            #IMPLIED
            surname     %ATEXT;            #IMPLIED
            fullname    %ATEXT;            #IMPLIED
!           role        (editor|notfirstpage) #IMPLIED>

  <!ELEMENT organization
                        (%CTEXT;)>
diff -crB xml2rfc-1.36/xml2rfc.tcl xml2rfc-1.36-dwing/xml2rfc.tcl
*** xml2rfc-1.36/xml2rfc.tcl    2011-03-26 09:11:39.000000000 -0700
--- xml2rfc-1.36-dwing/xml2rfc.tcl      2011-05-10 17:26:10.096645000 -0700
***************
*** 11,17 ****

  global prog prog_version prog_url prog_ack
  set prog "xml2rfc"
! set prog_version "v1.36"
  set prog_url "http://xml.resource.org/"
  set prog_ack \
  "This document was produced
--- 11,17 ----

  global prog prog_version prog_url prog_ack
  set prog "xml2rfc"
! set prog_version "v1.36-dwing"
  set prog_url "http://xml.resource.org/"
  set prog_ack \
  "This document was produced
***************
*** 6839,6844 ****
--- 6839,6845 ----

          switch -- $av(role) {
              editor - "" {}
+             notfirstpage - "" {}

              default {
                  unexpected error "invalid role attribute: $av(role)"
***************
*** 6869,6875 ****
                  append av(abbrev) ", Ed."
              }
          }
!         set authors [linsert $authors 0 [list $av(abbrev) $ov(abbrev)]]
      }

      set lastO ""
--- 6870,6878 ----
                  append av(abbrev) ", Ed."
              }
          }
!           if {[string compare $av(role) notfirstpage]} {
!                   set authors [linsert $authors 0 [list $av(abbrev)
$ov(abbrev
)]]
!               }
      }

      set lastO ""

---

From: "Dan Wing" <[email-masked]>
Date: Tue, 10 May 2011 18:03:10 -0700

> Sent: Tuesday, May 10, 2011 9:32 AM
> To: Nico Williams
> Cc: [email-masked]
> more
> process
> Like that?
> <http://greenbytes.de/tech/webdav/rfc2046.html#rfc.section.9>?

That didn't work out so well -- RFC2046 has no Section 8, but has
two occurrences of Section 9.

-d

---

From: Julian Reschke <[email-masked]>
Date: Wed, 11 May 2011 08:26:56 +0200

> two occurrences of Section 9.

Where? What? Me confused :-)

---

From: "Dan Wing" <[email-masked]>
Date: Wed, 11 May 2011 07:12:42 -0700

> From: Julian Reschke [mailto:[email-masked]]
> Sent: Tuesday, May 10, 2011 11:27 PM
> To: Dan Wing
> Cc: 'Nico Williams'; [email-masked]

  # grep "^[0-9]\." rfc2046.txt
(snip)
  6.  Experimental Media Type Values
  7.  Summary
  9.  Security Considerations
  9.  Authors' Addresses

-d

---

From: Julian Reschke <[email-masked]>
Date: Wed, 11 May 2011 16:22:16 +0200

>    9.  Security Considerations

Oh. That's a bizarre bug in the published RFC. I don't think we need 
tool support to generate something like that, no?

---

From: Thomas Morin <[email-masked]>
Date: Wed, 11 May 2011 16:27:18 +0200

Hi Dan,

Dan Wing:
> in an<author>  section.

This patch gives exactly the wanted behavior and solves the problem for me.
Thank you!

-Thomas

---

From: "Dan Wing" <[email-masked]>
Date: Wed, 11 May 2011 07:54:52 -0700

> Sent: Wednesday, May 11, 2011 7:22 AM
> To: Dan Wing

My point is that proper tool support would avoid similar bugs
in published documents.

-d

---

From: Julian Reschke <[email-masked]>
Date: Wed, 11 May 2011 17:04:51 +0200

> My point is that proper tool support would avoid similar bugs

Agreed, but it doesn't seem to have anything to do with the rfc2629.xslt 
example I was asking for feedback on. :-)

---

From: Alice Hagens <[email-masked]>
Date: Tue, 17 May 2011 17:55:55 -0400

On May 10, 2011, at 11:35 AM, Thomas Morin wrote:
> Another path which I think might be more reasonable would be to design the toolchain independently of any attempt at a consensus on what these roles would be, and let this interpretation/policy/process stuff happen independently of the toolchain.

We agree that the tool should be flexible -- allow authors to create output as desired. For RFCs, the guidance at http://www.rfc-editor.org/policy.html#policy.authlist will remain in place, until a change is determined by a new RFC Series Editor.

Thanks,
Alice
for the RFC Production Center

---

From: Glen Zorn <[email-masked]>
Date: Wed, 18 May 2011 11:07:24 +0700

> We agree that the tool should be flexible -- allow authors to create output as desired. For RFCs, the guidance at http://www.rfc-editor.org/policy.html#policy.authlist will remain in place, until a…

I agree.  The guidelines are just that, not commandments.

---

From: Julian Reschke <[email-masked]>
Date: Wed, 18 May 2011 09:16:17 +0200

> We agree that the tool should be flexible -- allow authors to create output as desired. For RFCs, the guidance at http://www.rfc-editor.org/policy.html#policy.authlist will remain in place, until a…

Note that this policy does not allow having a different set of people on 
the front page and in the back section. It *does* allow an additional 
"Contributors" section.

Best regards, Julian

---

From: Nico Williams <[email-masked]>
Date: Wed, 18 May 2011 02:34:28 -0500

On Wed, May 18, 2011 at 2:16 AM, Julian Reschke <[email-masked]> wrote:
>> We agree that the tool should be flexible -- allow authors to create
>> output as desired. For RFCs, the guidance at
>> http://www.rfc-editor.org/policy.html#policy.authlist will remain in place,
>> until a change is determined by a new RFC Series Editor.
>> ...
>
> Note that this policy does not allow having a different set of people on the
> front page and in the back section. It *does* allow an additional
> "Contributors" section.

I don't see where it requires that the set of authors on the front
page be the same as in the Authors section.  The second statement,
however, is true, but it does not shed light on the issue at hand.

The policy says only this about what must be in the Authors section:

"
 o The Author's Address section at the end of the RFC must include the
authors listed in the front page header. The purpose of this section
is to (1) unambiguously define author/contributor identity (e.g., the
John Smith who works for FooBar Systems) and to (2) provide contact
information for future readers who have questions or comments.

   At the discretion of the author(s), contact addresses may also be
included in the Contributors section for those contributors whose
knowledge makes them useful future contacts for information about the
RFC.
"

"The Author's Address section at the end of the RFC must include the
authors listed in the front page header" does not imply that no
authors may be listed in the Authors section that aren't also on the
front page.  At best you could say that the policy strongly hints that
authors not on the front page should be listed in the Contributors
section, but it doesn't _actually_ say that.

There's a lot of "may"s (8), one "should", and one "must".  As far as
the tools go, this should mean that the tools should enforce only the
one "must" (the should is not tool enforceable).  As far as what
actually happens, that's up to the RFC-Editor and a document's
authors.

Nico
--

---

From: Thomas Morin <[email-masked]>
Date: Wed, 18 May 2011 09:35:42 +0200

Hi Julian,

Julian Reschke:
> Alice Hagens:
>> Thomas Morin:
>>> Another path which I think might be more reasonable would be to 
>>> design the toolchain independently of any attempt at a consensus on 
>>> what these roles would be, and let this 
>>> interpretation/policy/process stuff happen independently of the 
>>> toolchain.
>>
>> http://www.rfc-editor.org/policy.html#policy.authlist will remain in 
>> place, until a change is determined by a new RFC Series Editor.
>> ...
>
> Note that this policy does not allow having a different set of people 
> on the front page and in the back section. [...]

What I read is "The Author's Address section at the end of the RFC must 
*include* the authors listed in the front page header." (emphasis mine), 
which does not preclude having more authors in the "Authors' Addresses" 
section, does it ?

This interpretation seems to me as corresponding to what we sometimes 
see happen (e.g. cases where only editors are on front page, but every 
author in the "Authors' Addresses" section).

-Thomas

---

From: Julian Reschke <[email-masked]>
Date: Wed, 18 May 2011 09:44:51 +0200

> actually happens, that's up to the RFC-Editor and a document's

I agree that it's not clear as I thought.

My understanding is that there are no multiple classes of authors; and 
that if the spec needs to mention more people, they should go into the 
"Acknowledgements" section.

Alice, can this be clarified at this point? Alternatively, could you 
state how *you* read it, and whether the production center would accept 
texts where the front page only has a subset of the names mentioned in 
the back section?

Best regards, Julian

---

From: Glen Zorn <[email-masked]>
Date: Wed, 18 May 2011 14:49:37 +0700

On 5/18/2011 2:16 PM, Julian Reschke wrote:

>>> what these roles would be, and let this interpretation/policy/process
>>> stuff happen independently of the toolchain.
>>

I think that that is fine.  I also think that it important to remember
what the genesis of this policy was: IIRC, the reason for its enactment
was the carry-over of a tradition in the 3GPP* community to add names to
a document just to show company support for a proposal, which might end
up showing half a dozen people as "authors" of a draft, whether they had
done any real work on it or not.  Of course, that's not how things are
done in the IETF and it seems that that lesson has been learned.  I
think it unfortunate that the approach to dealing with the issue was
through policy rather than education but that's life.  In any case, it
might be nice to mention this in a tutorial (and maybe even establish
some _guidelines_ for authorship of a draft) in order to avoid a
recurrence of this problem in the future.

...

---

From: Nico Williams <[email-masked]>
Date: Wed, 18 May 2011 02:53:58 -0500

On Wed, May 18, 2011 at 2:44 AM, Julian Reschke <[email-masked]> wrote:
> My understanding is that there are no multiple classes of authors; and that
> if the spec needs to mention more people, they should go into the

Not really.  The policy is somewhat ambiguous, and probably so on
purpose.  Nowhere does it say what you say you think it does.

As far as the tools go, the only rule that can be enforced by xml2rfc
is that authors on the front page MUST be listed in the
Author'sAddresses section.  That's it.  The rest is guidance that
xml2rfc has no business trying to enforce (it's all "may"s anyways).

Well, you could also warn when more than five authors appear on the
front page, but that's not necessary.

> Alice, can this be clarified at this point? Alternatively, could you state
> how *you* read it, and whether the production center would accept texts
> where the front page only has a subset of the names mentioned in the back
> section?

I don't object to Alice clarifying, but if we only take the
traditional normative vs. informative language approach to analyzing
this text we'll see that there's only one thing for the tools to
enforce, and that's listed above.

Nico
--

---

From: Julian Reschke <[email-masked]>
Date: Wed, 18 May 2011 10:27:50 +0200

> enforce, and that's listed above.

Well, I disagree, that's why I'm asking for clarification.

In particular, I'm -1 on any changes to the xml2rfc DTD until we have a 
*clear* statement from the RFC Editor about what it means.

Best regards, Julian

---

From: Thomas Morin <[email-masked]>
Date: Wed, 18 May 2011 11:04:04 +0200

Hi Julian,

Julian Reschke :
> In particular, I'm -1 on any changes to the xml2rfc DTD until we have 
> a *clear* statement from the RFC Editor about what it means.

But the DTD defines a document format that's not meant to be used only 
for RFCs, doesn't it ?

-Thomas

---

From: Julian Reschke <[email-masked]>
Date: Wed, 18 May 2011 11:13:56 +0200

> But the DTD defines a document format that's not meant to be used only

No, it's also for IDs. But what's the point to put things into an 
Internet Draft when you can't have the same thing in the published spec?

Best regards, Julian