Re: [apps-discuss] On citations in general

[Tim Bray <[e-mail]>]

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 <[e-mail]> wrote:
> 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
> _______________________________________________
> apps-discuss mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/apps-discuss