Subject: [apps-discuss] On citations in general

From: Barry Leiba <[email-masked]>
Date: Wed, 25 Apr 2012 11:06:16 -0400

While I'm on the topic of citations, let me throw something out to
this crowd before sending it to the general IETF discussion list.

There are various styles of using citations, and various strongly held
opinions about which ones are good, which evil, and which lie
somewhere between.  I don't want to make this a religious argument,
though I'm pretty sure it will be that, but here:

I consider that a citation in the text serves two purposes.  One is to
explain where the information came from, and the other is to make it
easy to get to the cited document.  As cute as it may be to say things
like, "To use items defined in [EMAIL], one must additionally...", I
find that it's not very helpful when I reading documents.

What I prefer to see -- what helps me the most as a reader -- is both
short text and an RFC number.  Often, if the short text is properly
chosen, I don't have to look at the referenced document at all.  And
when I do, I can find it immediately from the RFC number in the
citation, without having to bounce to the bottom of the doc and look
at the references.  Of course, if there are repeated citations, I
don't expect every one to have the full thing, and just the RFC
citation is enough.

Here's the sort of thing I'm talking about (made-up examples, mostly):

"...is done through SMTP [RFC5321]..."
"...SHOULD be signed using DKIM [RFC6376]..."
"The script can use the External-lists extension [RFC6134] to..."
"If a DNS block list [RFC5782] includes an IP address..."

It's also sometimes very useful to have section numbers in the
citations, when one needs to be referred to a specific point in the
cited document.  Consider this, from one of the httpbis documents:

"The field value consists of a single URI-reference.  When it has the
form of a relative reference ([RFC3986], Section 4.2), the final value
is computed by resolving it against the effective request URI
([RFC3986], Section 5)."

I find all of these to be MUCH more useful to the reader than, say,
"The script can use [RFC6134] to...", or, "If a [DNSBL] includes an IP
address...", even though the full information is in the References
section in any case.

Comments?

Barry

---

From: Tim Bray <[email-masked]>
Date: Wed, 25 Apr 2012 08:23:24 -0700

If only there were a technology which allowed citations to be made
actual actionable usable links directly to the targeted source. A text
with this sort of thing would be so great that we’d need a new name
for it... supertext? ultratext? hypertext?

 -T

On Wed, Apr 25, 2012 at 8:06 AM, Barry Leiba <[email-masked]> wrote:
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 25 Apr 2012 09:26:14 -0600

> Comments?

I think this topic is more appropriate for the rfc-interest list. In
fact, the RFC Editor had a Citations Committee for a while...

/psa

---

From: Barry Leiba <[email-masked]>
Date: Wed, 25 Apr 2012 11:35:55 -0400

> actual actionable usable links directly to the targeted source.

Yeh, eliminating your biting sarcasm: we're often reviewing these
things offline, and sometimes even from printed text.  Not having to
flip back and forth can be useful.

Barry

---

From: Tony Finch <[email-masked]>
Date: Wed, 25 Apr 2012 16:43:16 +0100

> Comments?

I think all your suggestions are excellent.

Tony.
-- 
f.anthony.n.finch  <[email-masked]>  http://dotat.at/
Biscay: Southwest 6 to gale 8, occasionally severe gale 9 at first. Very rough
or high. Squally showers. Poor, becoming moderate.

---

From: SM <[email-masked]>
Date: Wed, 25 Apr 2012 09:58:25 -0700

Hi Barry,
>this crowd before sending it to the general IETF discussion list.

Peter already commented on rfc-interest.

>though I'm pretty sure it will be that, but here:

It's unfortunately going to turn into one.

>find that it's not very helpful when I reading documents.

Yes.

>don't expect every one to have the full thing, and just the RFC

I find that having the RFC number makes the text for some RFCs more readable.

>cited document.  Consider this, from one of the httpbis documents:

Yes, especially for a long document.

BTW, this is more of a matter of style.

Regards,
-sm

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 25 Apr 2012 11:03:36 -0600

> BTW, this is more of a matter of style.

Exactly. And the RFC Editor Style Guide is being updated even as we
speak. Thus this is relevant for the rfc-interest list.

Peter

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: Andrew Sullivan <[email-masked]>
Date: Wed, 25 Apr 2012 13:26:30 -0400

> BTW, this is more of a matter of style.

And consequently of religion.  I'd prefer that we not talk about it,
either here or on rfc-i, since in both cases I think we will explore
every rathole possible (and some impossible ones) involving Fowler
vs. Strunk&White, MLA vs. Chicago, involving whatever
your 3d grade teacher said even though s/he couldn't write worth a
tinker's dam (yes, that's how it's spelled), and the Oxford comma and
requirements for its use.  I have the Gowers edition Fowler on my
book-shelf, and I am as happy to waive it about as the next person.
But I don't think we're going to be more productive that way.

Best,

A

-- 
Andrew Sullivan
[email-masked]

---

From: Blaine Cook <[email-masked]>
Date: Wed, 25 Apr 2012 19:09:28 +0100

Why not just use links as Tim suggests with descriptive text in the content
of the anchor? I don't see how offline reading is a blocker.

b.

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 25 Apr 2012 12:37:26 -0600

> But I don't think we're going to be more productive that way.

Agreed. Indeed, perhaps we could learn from Jon Postel's advice to
authors: read a recent RFC and emulate its style.

/psa

---

From: Barry Leiba <[email-masked]>
Date: Wed, 25 Apr 2012 14:45:24 -0400

> But I don't think we're going to be more productive that way.

Yeh, you're probably right.

Never mind.  Let's drop this thread.

Barry

---

From: Nico Williams <[email-masked]>
Date: Wed, 25 Apr 2012 13:49:50 -0500

> of the anchor? I don't see how offline reading is a blocker.

That's fine for HTML rendering, not so much for .txt rendering.
Though maybe it's time to obsolete .txt, if we won't allow UTF-8 in
.txt ever anyways in case -gasp!- someone's terminal displays garbage
(because you know that *never* happens and never possibly could as
long as we refrain from putting UTF-8 in RFCs).  (Hey, this sarcasm
thing is pretty fun!)

Though personally, I *like* .txt.  For one I get to apply the find |
xargs egrep pattern, and I really like being able to use advanced
regular expressions like that.  I can also apply various text indexing
tools; I've been thinking that a SQLite3 FTS RFC and I-D DB toolset
would be handy.  Web search engines aren't anywhere near as powerful
for searching such a small document set -- web search engines are
great for searching data/doc sets I could *never* store copies of
locally.  Also, less(1) is fantastic for reading RFCs and has much
faster startup/load times than any browser out there.  Sometimes less,
is more, and spartan .txt (with UTF-8 for bleep's sakes) is fabulous.
I suppose what I need is elinks(1) with regexp support, and to keep
rendered (as .txt) forms around for find | xargs egrep searching (or
else local web search indexes).  But, really, from a simplicity point
of view, .txt is just hard to beat.

Nico
--

---

From: Julian Reschke <[email-masked]>
Date: Wed, 25 Apr 2012 22:36:17 +0200

> for it... supertext? ultratext? hypertext?

xml2rfc source + extensions formatted through rfc2629.xslt?