Subject: [xml2rfc] References and book chapters

From: John C Klensin <[email-masked]>
Date: Wed, 22 Jun 2016 17:16:16 -0400

Hi.

I'm not following this list closely, but I note that the
resolution of #28 to add <refcontent> "to prevent the need to
abuse <seriesInfo>", solves only part of the problem.   A
different, but relevant, case involves references to a chapter
of a book, in it most general (and difficult) form, a book that
is actually a compendium, requiring a reference that is
something like

	Knight, S., "The Roman Alphabet", Section 24 in P.T.
	Daniels and W. Bright, The World's Writing Systems,
	Oxford University Press: 1996.

With the Section (or Chapter) number, where to put it (if at
all), page numbers and where to put them (if at all) being a
style manual issue.  For eventual pretty-printing, "The World's
Writing Systems" is usually required to be in italics.

While we don't often cite book chapters in RFCs, it does happen
and happen often enough that I've lost count of how many times
I've had this problem and had to sort it out with the RFC Editor
at AUTH48 in the nroff.  One can fake it by abusing <seriesInfo>
or, now, by abusing <refcontent>, but sensible use of generic
markup suggests that the author list, title, etc., for the book
should be separately marked up with seriesInfo used, at most,
for the publisher and maybe date information.  

The most obvious way to do that would be to allow nesting
<reference>, perhaps with some special argument, inside
<reference> but note that a chapter of a book that doesn't have
separate authorship would not be listed with authors for the
book itself, e.g.,

	Phunny, K., "On Being A Fool", Chapter 5 of _Fools,
	Idiots, and the Merely Misguided_, April 2000.

Note also that deprecating seriesInfo in the context of
<reference> eliminates its primary intended use, e.g.,

	Codd, E. F., "A relational model of data for large
	shared data banks", Communications of the ACM 13(6), p. 377,
1970

So, again, one either needs to abuse the new element --and avoid
markup of the journal title and volume, issue, and page
information separately--  of seriesInfo is actually useful.  

best,
   john

p.s. If one were striving for consistency with the naming
conventions of RFC 2629 (which would seem to be reasonable
practice to avoid making users crazy whether one likes those
conventions or not), "refcontent" should probably be spelled
"refContent".

  ------

># 28: better tools for references
> 
> Changes (by [email-masked]):
> 
>  * status:  new => closed
>  * resolution:   => fixed
> 
> Comment:
> 
>  See <https://greenbytes.de/tech/webdav/draft-iab-
>  xml2rfc-03.html#element.refcontent>

---

From: Julian Reschke <[email-masked]>
Date: Thu, 23 Jun 2016 08:45:59 +0200

On 2016-06-22 23:16, John C Klensin wrote:
> ...

FWIW, it's deprecated because it moved inside <front> (a change I think 
that isn't needed).

Best regards, Julian

---

From: John C Klensin <[email-masked]>
Date: Thu, 23 Jun 2016 09:14:03 -0400

--On Thursday, June 23, 2016 08:45 +0200 Julian Reschke
<[email-masked]> wrote:

> FWIW, it's deprecated because it moved inside <front> (a
> change I think that isn't needed).

Julian,

Thanks.  While I can see the rationale for this, I agree that it
isn't needed.  Speaking on behalf of at least some of us who
will need to learn a new system, I strongly encourage making
only those changes that are justified by necessity, not merely
some ideas of aesthetics or the equivalent.   

I note the number of members of the community who haven't ever
adopted xml2rfc (v1 or v2) because of difficulties in learning
it and fear that a lot of changes that are not strongly
motivated (or a perceived increase in complexity) may reduce v3
adoption.  Any one of these changes may be trivial (moving
seriesInfo certainly is), but they may cumulatively be a barrier
to entry.  Given the idea of xml source as the archival format
for the RFC series, lower adoption and use of v3 could create
significantly more work for the RFC Production Center with
staffing and budgetary implications for which the community may
not be fully prepared.

I'm not arguing for "no change" -- I think many of the new
elements and attributes will be very helpful (and are long
overdue).  I am more concerned about moving things around or
changing ways of doing things without the strong motivation that
exists for many of those new features.  Some of the new elements
also seem to me to be very close to the boundary between generic
and format markup.  Crossing that boundary could be a long-term
problem with the idea of a single (and archival) source format
and multiple (and potentially evolving) output/target formats.

Along the same lines, while I see the advantages to people
writing documents of making more subsidiary elements unordered,
order is easy to diagnose in a processor and correct but layers
of unordered elements makes construction of tools to analyze and
extract information from documents more difficult.  I hope those
tradeoffs, especially for homebrew or ad hoc tools, are being
considered carefully.

Finally, this experience has reinforced my concern about another
issue: the advantages of the schema description form with
alphabetized element definitions over the DTD one are obvious.
However, it makes it much harder to figure out what is going on
and how to actually write and structure a document.  One might
think about the difference as similar to the one between trying
to learn a new language from tutorials and examples rather than
being handed a dictionary.

   best,
    john