Subject: [yam] draft-ietf-yam-rfc4409bis-00

From: John C Klensin <[email-masked]>
Date: Fri, 06 May 2011 11:15:16 -0400

Hi.

This draft is now in the posting queue (awaiting initial version
approval as of a few minutes ago).  It reflects the text
discussed with John Leslie and my reaction to Tony's reference
suggestion, both as discussed in earlier notes, plus the changes
I summarized earlier.

I'm aware of the several editorial issues, but think the
document is adequate for the WG --which has had too little
technical work for too long-- to have a look at.  

Those known issues are as follows.  Comments about what to do
about them are welcome, but please don't waste time telling us
they are issues:

	(1) Between changes necessitated by xml2rfc, since as
	eliminating citation anchors that start with digits, and
	most new references that I've added using the [RFCnnnn]
	form rather than descriptive names, the style of
	citation anchors is now wildly inconsistent.  Unless
	there is consensus that doing so would be a bad idea,
	I'm going to rationalize them.
	
	(2) In recent years, my attitude toward the use of
	citation anchors as subjects or objects of sentences has
	evolved from "obnoxious, but everyone is doing it" to
	"not in any document I'm responsible for".  So,
	partially in memory of Mike Padlipsky, that usage is
	going to be corrected (note that this will help with
	(1)).
	
	(3) The conversion of the table of extensions in Section
	7 from the artwork-like form of 4409 to an xml-based
	texttable (necessary to make the references work) did
	not yield beauty.   I'm not going to start fussing with
	column widths until the WG concludes that the content is
	right and even then may be inclined to leave that to the
	RFC Editor unless the WG directs otherwise.
	
	(4) 4409 used several compound references (one citation
	anchor, several RFCs).  Xml2rfc is quite hostile to
	those.  The pre-evaluation document pointed out that at
	least a few of them were unnecessary.  I've taken them
	all out.   Anyone who objects should speak up.
	
	(5) In editing, I noticed a possible organizational
	matter and became somewhat concerned about it.  If no
	one else notices or thinks it is a problem, I expect to
	leave things as they are. 

Comments and suggestions welcome.  Since the hard work should
have been complete with the pre-evaluation document, my hope is
that we can swiftly review and iterate on the text changes and
then move this into WG LC.  Of course, the WG, the co-chairs,
and the IESG may have other ideas, but I can hope.

    john

---

From: Barry Leiba <[email-masked]>
Date: Fri, 6 May 2011 17:29:14 -0400

>        all out.   Anyone who objects should speak up.

If you mean things like this:
 [SMTP-MTA, ESMTP]
...I only see one, in section 3.1 (that one).  The way we usually
handle that with xml2rfc is simply to use two xrefs, to get this:
 [SMTP-MTA][ESMTP]

That seems to work fine.  Though if removing them is OK, then it doesn't matter.

Barry

---

From: Tony Hansen <[email-masked]>
Date: Fri, 06 May 2011 18:58:43 -0400

I'm looking forward to reviewing it.

     Tony Hansen
     [email-masked]

---

From: John C Klensin <[email-masked]>
Date: Fri, 06 May 2011 22:19:34 -0400

--On Friday, May 06, 2011 17:29 -0400 Barry Leiba
<[email-masked]> wrote:

>>        (4) 4409 used several compound references (one
>> citation        anchor, several RFCs).  Xml2rfc is quite
>> hostile to        those.  The pre-evaluation document
>> pointed out that at        least a few of them were
>> unnecessary.  I've taken them        all out.   Anyone
>> who objects should speak up.
> 
> ...I only see one, in section 3.1 (that one).  The way we
> usually handle that with xml2rfc is simply to use two xrefs,
> to get this:  [SMTP-MTA][ESMTP]

No.  If you look at 4409, you will see several citations, of
which one example is "[SMTP-MTA]".  In 4409, the corresponding
reference is: 
   Postel... RFC 821...
   Partridge... RFC 974...
   Braden... RFC 1123... 
   Klensin... RFC 2821...
i.e., "compound references" in the sense that one anchor
identifies a list of RFCs.  While 4409 doesn't use it, exactly
the same problem arises if one chooses to cite an STD or BCP
number that identifies multiple RFCs. That is the construction
to which I claim that xml2rfc is hostile -=the only elegant way
to do it in the current design would be 
 <reference anchor="SMTP-MTA">
      <reference>...Postel... RFC 821...</reference>
      <reference>...Partridge... RFC 974...</reference>
      <reference>...Braden... RFC 1123... </reference>
      <reference>...Klensin... RFC 2821...</reference>
 </reference>

And neither nested reference elements nor reference elements
without anchors are permitted by the DTD.

The example you cite above is one of multiple citations at the
same point rather than a single compound citation..  And,
indeed, most style manuals (along with 4409) prefer "[SMTP-MTA,
ESMTP]" to "[SMTP-MTA][ESMTP]".  FWIW, I think the tools should
help us get thing right rather than forcing us to do things that
are wrong.  But so it goes.

    john

---

From: Julian Reschke <[email-masked]>
Date: Sat, 07 May 2011 09:12:23 +0200

On 07.05.2011 04:19, John C Klensin wrote:
> ...
>        <reference>...Braden... RFC 1123...</reference>
> ...

If this is used a lot, we should consider adding it. Is it?

> are wrong.  But so it goes.

You can do this with xmlrfc when using the tools from rfc2629.xslt as 
preprocessor, see, for example, 
<http://greenbytes.de/tech/webdav/rfc2629xslt/testcase.html#rfc.section.5.11>.

Finally, I think somewhere else I saw discussion about putting 
additional information into references... There's the <annotation> 
element for that.

Best regards, Julian

---

From: John C Klensin <[email-masked]>
Date: Sat, 07 May 2011 10:59:15 -0400

--On Saturday, May 07, 2011 09:12 +0200 Julian Reschke
<[email-masked]> wrote:

>> to which I claim that xml2rfc is hostile -=the only elegant
>> way to do it in the current design would be

Julian, 

This is probably not the right place to have the discussion.
The general reference-mess topic has been discussed on the
xml2rfc list several times and has never gone anywhere.  The
issue above was, and remains, one of the main topics.  The other
two are how one references a chapter in a book that is an edited
compilation by multiple authors and how one handles journal
articles.  Conventional styles for the first look something like:

	  Jones, J., "The flavors of Kool-Aid", in Beelzebub,
	S., _Cults We Have Enjoyed_, Hades Publishing, 2012.
	Originally published in _Jonestown Chronicles_, November
	1978.

sometimes with chapter and/or page numbers.  Ordinarily, if two
articles are cited in the same book, either the second one
appears as

	Jones, M., "Optimal tub size", in Beelzebub, Op. Cit.
or, depending on the style manual,
	Jones, M., "Optimal tub size", in Beel2012.

Or the book is listed separately in the references and then
cited from both chapter references.  Those arrangements are hard
to set up, especially since one cannot put <xref> elements into
any of the elements of <reference>.

For the second, one normally sees the article's author, the
article title, the journal title, volume and issue numbers, a
date, and a range of page numbers.

To some extent, both can be faked with <seriesInfo>, but some of
the tricks I've seen to do it that way seriously violate generic
markup principles and require patching by the RFC Editor at the
nroff stage.  

>> indeed, most style manuals (along with 4409) prefer
>> "[SMTP-MTA, ESMTP]" to "[SMTP-MTA][ESMTP]".  FWIW, I think
>> the tools should help us get thing right rather than forcing
>> us to do things that are wrong.  But so it goes.
> 
> You can do this with xmlrfc when using the tools from
> rfc2629.xslt as preprocessor, see, for example,

Right.  But I don't really care what shows up in I-Ds.  As far
as I know, the only way to do it for RFCs involves putting in a
comment, something like:
	   <!-- RFC Editor: please fix this so it comes out as
	[Ref1,Ref2] and not [Ref1][Ref2] -->

Pretty easy to fix in the nroff, but it makes the idea of using
xml2rfc as a final markup form pretty delusional unless the
marked-up files are used with a really powerful style sheet or
equivalent (rfc2626.xslt is a major step in that direction but,
IMO, the answer to a different question).

> additional information into references... There's the
> <annotation> element for that.

I use <annotation> regularly for odd situations.  Indeed, my
first working/test versions of making XML from 4409 ended up
with arrangements like

 <reference anchor="SMTP-MTA">
      <front>
         <title>Simple Mail Transfer Protocol</title>
         <author initials="J." surname="Klensin" ></author>
         <date month="October" year="2001" />
      </front>
	   <annotation>
      Postel, J., "Simple Mail Transfer Protocol", STD
      10, RFC 821, August 1982.

      Partridge, C., "Mail routing and the domain
      system", STD 10, RFC 974, January 1986.

      Braden, R., "Requirements for Internet Hosts -
      Application and Support", STD 3, RFC 1123, October
      1989.

      Klensin, J., "Simple Mail Transfer Protocol", RFC
      2821, April 2001. </annotation>
    </reference>

That was sufficient to get things to compile so that I could do
a diff on the substantive part, but it illustrates the major
problem with <annotation>, which is that one really needs it to
either behave like <t> or permit <t> in its content so that one
can format things, build lists, insert cross-references, etc.
(fwiw, the same comment applies to <cref>, which is also much
less useful than it might be because it requires CTEXT).  The
minor problem is that the break and vertical spacing associated
with <annotation> are appropriate in some situations and not in
others, resulting in more "please make this format in a
reasonable way" notes to the RFC Editor.

As far as whether it is "used a lot", there is an unfortunate
cause and effect interaction.  Make it hard enough to do things
the right way and all but the most stubborn people stop.  There
are lots of circumstances in which we should be referencing STDs
or BCPs, not RFCs, but the difficulties of doing that with
xml2rfc result in the choice not even being thought about.  Or
we have to result in notes to the RFC Editor... an approach that
is error-prone and extra work for everyone.  So it is not
possible to document how much it is used, much less how much it
would be used if doing so were logical and convenient.

best regards,
   john

---

From: Dave CROCKER <[email-masked]>
Date: Sat, 07 May 2011 10:46:13 -0700

> If this is used a lot, we should consider adding it. Is it?

Interesting.  I've never seen that convention in regular publications.

As for using an STD citation, the STD is a single citation.  The fact that it's 
"purpose" is as an indirect pointer to a set of documents probably does not put 
it in a class of its own:  is true for /most/ citations.  Most of what we cite 
contain points to other references.

That an STD is 'pure' in the sense of having no content other than those 
multiple citations does make it look interesting, but there are other such 
documents that primarily serve to aggregate references.

d/

-- 

   Dave Crocker
   Brandenburg InternetWorking
   bbiw.net

---

From: John C Klensin <[email-masked]>
Date: Mon, 09 May 2011 15:20:28 -0400

> Interesting.  I've never seen that convention in regular

At some level, that is irrelevant.  It is in use in RFCs and
has, IIR, rather a long history.   Also see the STD and BCP
comments below.

And, of course, we may have different definitions of "regular
publications", different selections of what we read and see, or
even different ideas about what is included in "that
convention".  In particular, as I said in an earlier note, I
find trying to use <seriesInfo> as a way to sneak unstructured
text into a reference problematic from the standpoint of generic
markup and possible structuring and external indexing; others
may not care and may, as a consequence, consider this
category/convention much smaller than I do.

While I'm not a big fan of the Chicago Manual, the current RFC
Editor Production Center staff likes it, so let's start with it
as a norm.   The current edition has, IIR, shifted much more
strongly to the assumption that materials will be written with
citations anchors ("note reference numbers") pointing to notes
that point to bibliographic entries rather than using the RFC
convention (and their earlier one) of citations pointing
directly to bibliographic entries ("references") and overloading
the latter.  But the assumption isn't new.  I could quote other
style guides, or give you examples from particular publications,
but the style guide is general and the Chicago one is what the
RFC Editor is trying to use, so...   (All citations below refer
to the current (16th) edition. )

(1) "...more than one note reference should never occur at a
single location (such as ⁵,⁶)..."  (in the event that you
can't render the last three characters before the right
parenthesis, they are superscript-5, comma, and superscript-6,
i.e., what we would show in RFCs as "[5,6]" or maybe "[5],[6]").
The manual does cite the AMA referencing rules as an exception
to this principle.  (Section 14.23)

   Note that, if one isn't going to have multiple citation
anchors ("note references") at a single point, and is going to
combine notes and (bibliographic) references as the RFC Series
generally does, there is no alternative other than making those
references compound.

  Also, our occasional efforts to say things equivalent to
"[Section 1.1 of RFC9999]" --which is also not possible with
xml2rfc and results in a collection of ad hoc solutions-- is
ultimately a way to get around the convention that specific
section and page number references appear in notes and not in
bibliographies.

(2) "...The number of note references in a sentence or paragraph
can sometimes be reduced by grouping several citations in a
single note..." followed by a rather long example of multiple
references separated by semicolons.  (Section 14.52)

(3) Book chapters and the like are covered in Section 14.112,
including specifically the 'Author1, Author2, "Chapter Name". In
_Title_, BookAuthor1 and BookAuthor2...' form.  Section 14.113
explicitly discusses listing the book once and then
cross-referencing it from the bibliographic entries for various
chapters.

(4) Section 14.119 gives several examples of compound references
for the purposes of properly identifying citations of reprint
editions and multiple-source materials.

> As for using an STD citation, the STD is a single citation.
> The fact that it's "purpose" is as an indirect pointer to a
> set of documents probably does not put it in a class of its
> own:  is true for /most/ citations.  Most of what we cite
> That an STD is 'pure' in the sense of having no content other
> than those multiple citations does make it look interesting,
> but there are other such documents that primarily serve to
> aggregate references.

I don't immediately see how you would turn this into practice,
and your "other such documents ... serve to aggregate
references" comment identifies the problem I'm having.  If there
actually were such a thing as an STD "document", even if all it
did was to aggregate references, then the bibliographic entry
could look like:

<reference anchor="STD9999">
  <front>
  <title>Warping the Woof</title>
  <author><organization> IESG </organization></author>
  <date year="2011" month="February" day="30"/>
  </front>
  <seriesInfo name="STD" value="9999"/>
</reference>

But we don't have a title, we don't have an agreed-upon author
or organization, and we don't have a date.  The list in
ftp://ftp.rfc-editor.org/in-notes/std-index.txt seems to assume
that the author and title of the numerically-first RFC in an STD
package is the name of the STD, but that is more than a little
irrational from a bibliographic standpoint and certainly is not
a convention to which the community (or the IAB, or any RFC
Editor-related group in my memory) has ever agreed.   The
closest we could get in xml2rfc, even after a change or two to
the slightly-mythical Style Guide, would be:

	<reference anchor="STD0010">
	  <front/>
	  <seriesInfo name="STD" value="10"/>
	  <seriesInfo name="RFC" value="821"/>
	  <seriesInfo name="STD" value="1869"/>
	  <seriesInfo name="STD" value="974"/>
	</reference>

I'm fairly sure that wouldn't compile and more sure that it
would produce something that it would take an expert to
interpret if it did compile.  So, if you take the position that
an STD should be a single citation (with which I agree), how
would you propose constructing the reference for it without some
change, either in the RFC formatting rules, to xml2rfc, or both?

best,
   john