Fwd: New Version Notification for draft-flanagan-7322bis-00.txt

classic Classic list List threaded Threaded
57 messages Options
123
Reply | Threaded
Open this post in threaded view
|

Fwd: New Version Notification for draft-flanagan-7322bis-00.txt

Heather Flanagan (RFC Series Editor)

FYI, I am kicking off the refresh of the RFC Style Guide. Significant changes include:

1. Style guidance for figures/images

2. Inclusion of the Musts and several of the Recommendations from the web portion of the style guide (https://www.rfc-editor.org/styleguide/part2/)
- guidance on RFCs as Compounds
- adding DOI numbers to references
- noting where the Index should go (if an RFC actually has one)
- guidance on in-text citations
- encouraging the use of HTTPS over HTTP
- specific note on IEEE references
- guidance on referenceing individual email messages on mailing lists
- removing the two spaces after a period requirement
- removing the "we will remove empty IANA considerations" guidance

3. Changing the reference format to include stream info

This is just a first pass. Additional changes being thought about (but which aren't in the doc yet, assuming they get added at all) include:
- BibTex citation format
- more citation tag guidance, particularly around using non-ASCII characters in a citation
- header/footer guidance given the new format changes
- guidance on the use of annotations in references
- adding back the Protocol Data Definitions template

If you have particular opinions on any of the above items, please start a thread and discuss.

-Heather

-------- Forwarded Message --------
Subject: New Version Notification for draft-flanagan-7322bis-00.txt
Date: Fri, 10 Mar 2017 09:28:19 -0800
From: [hidden email]
To: RFC Editor [hidden email], Heather Flanagan [hidden email], Sandy Ginoza [hidden email]


A new version of I-D, draft-flanagan-7322bis-00.txt
has been successfully submitted by Heather Flanagan and posted to the
IETF repository.

Name:		draft-flanagan-7322bis
Revision:	00
Title:		RFC Style Guide
Document date:	2017-03-10
Group:		Individual Submission
Pages:		26
URL:            https://www.ietf.org/internet-drafts/draft-flanagan-7322bis-00.txt
Status:         https://datatracker.ietf.org/doc/draft-flanagan-7322bis/
Htmlized:       https://tools.ietf.org/html/draft-flanagan-7322bis-00


Abstract:
   This document describes the fundamental and unique style conventions
   and editorial policies currently in use for the RFC Series.  It
   captures the RFC Editor's basic requirements and offers guidance
   regarding the style and structure of an RFC.  Additional guidance is
   captured on a website that reflects the experimental nature of that
   guidance and prepares it for future inclusion in the RFC Style Guide.
   This document obsoletes RFC 7322, "RFC Style Guide".

                                                                                  


Please note that it may take a couple of minutes from the time of submission
until the htmlized version and diff are available at tools.ietf.org.

The IETF Secretariat


_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Errata Reference Format

Julian Reschke
<https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.5>:

> 4.8.6.5.  Referencing Errata
>
>    The following format is required when a reference to an erratum
>    report is necessary:
>
>    [ErrNumber]  RFC Errata, Erratum ID number, RFC number, <URI>.
>
>    [Err1912]  RFC Errata, Erratum ID 1912, RFC 2978, xxx.

In V3, we'd format that as:

> <reference anchor="Err1912" quoteTitle="false" target="xxx">
>   <front>
>     <title>Errata ID 1912</title>
>     <author><organization>RFC Errata</organization></author>
>   </front>
>   <seriesInfo name="RFC" value="2978"/>
> </reference>

Observations:

1) That makes it look like this references actually RFC 2978, so the
seriesInfo element is very misleading.

2) No date is specified.

Proposal:

<reference anchor="Err1912" quoteTitle="false"
target="https://www.rfc-editor.org/errata_search.php?eid=1912">
   <front>
     <title>RFC 2978 Erratum 1912</title>
     <author><organization>RFC Errata</organization></author>
   </front>
   <seriesInfo name="RFC Errata" value="1912"/>
   <date year="2009" month="October"/>
</reference>

Giving:

[Err1912]  RFC Errata, RFC 2978 Erratum 1912, RFC Errata 1912, October
            2009, <https://www.rfc-editor.or/errata_search.php?eid=1912>

a) This make seriesInfo actually meaningful.

b) The URI of course should be aligned with what the future format is;
for instance <https://www.rfc-editor.org/errata/1912>.

c)
<https://greenbytes.de/tech/webdav/rfc7991.html#element.reference.attribute.quoteTitle>
allows us to have an unquoted title, but I'd like to question whether we
*really* need a special case here.

Best regards, Julian



_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Referencing Emails

Julian Reschke
In reply to this post by Heather Flanagan (RFC Series Editor)
<https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.7>:

> 4.8.6.7.  Referencing Email on Mailing Lists
>
>    When referencing emails to mailing lists, the template provided here
>    should be used:
>
>       [reftag] Sender, A., "Subject: Subject line", message to the
>
>       listname mailing list, DD Month YYYY, <URL >.

Including the day of month in a reference is something we haven't done
before, and which xml2rc won't do in references by default.

Given that we already have <reference>s that contain a day-of-month (for
internet drafts), is your suggestion to have this in ID references as
well? (that would at least be consistent, and consistency is good)

Best regards, Julian
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Placement of Index

Julian Reschke
In reply to this post by Heather Flanagan (RFC Series Editor)
<https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.10>:

> 4.10.  Index
>
>    If included, an index appears directly after any appendices and
>    before the Acknowledgements (if any).  Where applicable, it appears
>    before the "IAB Members at the Time of Approval" section.

 From an xml2rfc point of view, that's hard to implement, as "IAB
Members at the Time of Approval" and "Acknowledgements" are regular
appendices that happen to be unnumbered (using
<https://greenbytes.de/tech/webdav/rfc7991.html#element.section.attribute.numbered>).

Can we generalize this to: "it appears before any unnumbered appendix,
such as..."? Otherwise we'll need to come up with new markup to define
where to place the index (in which case you should raise an issue at
<https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis>).

Best regards, Julian
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Referencing Internet Drafts

Julian Reschke
In reply to this post by Heather Flanagan (RFC Series Editor)
<https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.4>:

> 4.8.6.4.  Referencing Internet-Drafts
>
>    References to Internet-Drafts may only appear as informative
>    references.  Given that several revisions of an I-D may be produced
>    in a short time frame, references must include the posting date
>    (month and year), the full Internet-Draft file name (including the
>    version number), and the phrase "Work in Progress".  Authors may
>    reference multiple versions of an I-D.  If the referenced I-D was
>    also later published as an RFC, then that RFC must also be listed.
>
>    [SYMBOLIC-TAG]  Last name, First initial., Ed. (if applicable) and
>    First initial.  Last name, Ed. (if applicable), "I-D Title", Work in
>    Progress, draft-string-NN, Month Year.
>
>    Example:
>
>    [RFC-STYLE] Flanagan, H. and S.  Ginoza, "RFC Style Guide", Work in
>    Progress, draft-flanagan-style-01, June 2013.

That's the same as in RFC 7322, but doesn't reflect what we actually do:

 > [RFC-STYLE] Flanagan, H. and S.  Ginoza, "RFC Style Guide",
 > draft-flanagan-style-01 (work in progress), June 2013.

If you're serious about that, you should open a change request for xml2rfc.

(FWIW, I don't see how the format proposed here is better than the one
we've been using for ages).

Best regards, Julian

_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Referencing RFCs

Julian Reschke
In reply to this post by Heather Flanagan (RFC Series Editor)
<https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.2>:

>    [RFC3080] Rose, M., "The Blocks Extensible Exchange Protocol Core,"
>    IETF, RFC 3080, DOI 10.17487/RFC3080, March 2001, http://www.rfc-
>    editor.org/info/rfc3080 .

I see two chaanges from RFC 7322 here:

1) The addition of the stream name (which I believe is a good change).
In V3, this could be implemented using (a)
<https://greenbytes.de/tech/webdav/rfc7991.html#element.refcontent> or
(b) using
<https://greenbytes.de/tech/webdav/rfc7991.html#element.seriesInfo.attribute.stream>:

a) would look like:

<reference  anchor='RFC3080'
target='http://www.rfc-editor.org/info/rfc3080'>
   <front>
     <title>The Blocks Extensible Exchange Protocol Core</title>
     <author initials='M.' surname='Rose' fullname='M. Rose'/>
     <date year='2001' month='March' />
   </front>
   <refcontent>IETF</refconfent>
   <seriesInfo name='RFC' value='3080'/>
   <seriesInfo name='DOI' value='10.17487/RFC3080'/>
</reference>

b) would look like:

<reference  anchor='RFC3080'
target='http://www.rfc-editor.org/info/rfc3080'>
   <front>
     <title>The Blocks Extensible Exchange Protocol Core</title>
     <author initials='M.' surname='Rose' fullname='M. Rose'/>
     <date year='2001' month='March' />
   </front>
   <seriesInfo name='RFC' value='3080' stream='IETF'/>
   <seriesInfo name='DOI' value='10.17487/RFC3080'/>
</reference>

Both format require changes to the citations library.

Format (b) has the drawback of being ambiguous, because multiple
seriesInfo elements might carry conflicting information. We'd also have
to define the special cases, both for the vocabulary (what if a W3C
document says stream="IETF"???) and the HTML spec.

2) The URI appears without angle brackets. I'll guess that's a
formatting error caused by xml2rfc not processing the <eref> in the
source as intended.

Best regards, Julian



_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Referencing STDs and BCPs

Julian Reschke
In reply to this post by Heather Flanagan (RFC Series Editor)
<https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.3>:

>    For an STD or BCP that contains two or more RFCs:
>
>    [STDXXX]  Last name, First initial., Ed. (if applicable), "RFC
>    Title", Stream, Sub-series number, RFC number, DOI, Date of
>    publication.
>
>             Last name, First initial., Ed. (if applicable)
>             and First initial. Last name, Ed. (if applicable),
>             "RFC Title", Stream, Sub-series number, RFC number, DOI,
>             Date of publication.
>
>             <http://www.rfc-editor.org/info/std#>
>
>    Example:
>
>    [STD13]  Mockapetris, P., "Domain names - concepts and facilities",
>    STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987.
>
>      Mockapetris, P., "Domain names - implementation and
>      specification", STD 13, RFC 1035, DOI 10.17487/RFC1035,
>      November 1987.
>
>             <http://www.rfc-editor.org/info/std13>

(1) It seems the formatting is broken? Is the first entry really
supposed to be different from the second one?

(2) Why do the individual entries not have a link to
<http://www.rfc-editor.org/info/rfc#>?

(3) What if the spec prose actually wants to refer to one of the
documents in the document set?

Best regards, Julian
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Referencing Internet Drafts

Julian Reschke
In reply to this post by Julian Reschke
...furthermore:

<https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.4>:

>    (...)  If the referenced I-D was
>    also later published as an RFC, then that RFC must also be listed.

There are cases where this doesn't make a lot of sense - if one cites a
specific historic Internet Draft because something that was later
removed or changed, why would it be relevant whether a later draft was
subsequently published as RFC?

Best regards, Julian
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Referencing RFCs

Julian Reschke
In reply to this post by Julian Reschke
On 2017-03-11 16:04, Julian Reschke wrote:

> <https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.2>:
>
>>    [RFC3080] Rose, M., "The Blocks Extensible Exchange Protocol Core,"
>>    IETF, RFC 3080, DOI 10.17487/RFC3080, March 2001, http://www.rfc-
>>    editor.org/info/rfc3080 .
>
> I see two chaanges from RFC 7322 here:
>
> 1) The addition of the stream name (which I believe is a good change).
> In V3, this could be implemented using (a)
> <https://greenbytes.de/tech/webdav/rfc7991.html#element.refcontent> or
> (b) using
> <https://greenbytes.de/tech/webdav/rfc7991.html#element.seriesInfo.attribute.stream>:
>
>
> a) would look like:
>
> <reference  anchor='RFC3080'
> target='http://www.rfc-editor.org/info/rfc3080'>
>   <front>
>     <title>The Blocks Extensible Exchange Protocol Core</title>
>     <author initials='M.' surname='Rose' fullname='M. Rose'/>
>     <date year='2001' month='March' />
>   </front>
>   <refcontent>IETF</refconfent>
>   <seriesInfo name='RFC' value='3080'/>
>   <seriesInfo name='DOI' value='10.17487/RFC3080'/>
> </reference>
>
> b) would look like:
>
> <reference  anchor='RFC3080'
> target='http://www.rfc-editor.org/info/rfc3080'>
>   <front>
>     <title>The Blocks Extensible Exchange Protocol Core</title>
>     <author initials='M.' surname='Rose' fullname='M. Rose'/>
>     <date year='2001' month='March' />
>   </front>
>   <seriesInfo name='RFC' value='3080' stream='IETF'/>
>   <seriesInfo name='DOI' value='10.17487/RFC3080'/>
> </reference>
>
> Both format require changes to the citations library.
>
> Format (b) has the drawback of being ambiguous, because multiple
> seriesInfo elements might carry conflicting information. We'd also have
> to define the special cases, both for the vocabulary (what if a W3C
> document says stream="IETF"???) and the HTML spec.
>
> 2) The URI appears without angle brackets. I'll guess that's a
> formatting error caused by xml2rfc not processing the <eref> in the
> source as intended.

and 3): what exactly should go in for the independent stream?

Best regards, Julian



_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Placement of Index

Martin J. Dürst
In reply to this post by Julian Reschke
On 2017/03/11 23:20, Julian Reschke wrote:

> <https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.10>:
>
>> 4.10.  Index
>>
>>    If included, an index appears directly after any appendices and
>>    before the Acknowledgements (if any).  Where applicable, it appears
>>    before the "IAB Members at the Time of Approval" section.
>
> From an xml2rfc point of view, that's hard to implement, as "IAB Members
> at the Time of Approval" and "Acknowledgements" are regular appendices
> that happen to be unnumbered (using
> <https://greenbytes.de/tech/webdav/rfc7991.html#element.section.attribute.numbered>).

> Can we generalize this to: "it appears before any unnumbered appendix,
> such as..."? Otherwise we'll need to come up with new markup to define
> where to place the index (in which case you should raise an issue at
> <https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis>).

Even better, can we just make sure that the index is at the very end of
the document? That's the case in all good books and other publications I
know. The reason for this is very clear: If one wants to find something
in the document, one goes to the index. But that means one has to find
the index first. So the index has to be at a place where it's easy to
find, and the end of the document assures that. That in no way applies
to any of the appendices.

Regards,   Martin.
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Fwd: New Version Notification for draft-flanagan-7322bis-00.txt

Julian Reschke
In reply to this post by Heather Flanagan (RFC Series Editor)
On 2017-03-10 21:27, Heather Flanagan (RFC Series Editor) wrote:
> FYI, I am kicking off the refresh of the RFC Style Guide. Significant
> changes include:
> ...

Out of curiosity: what's the plan here? The draft is two months old,
feedback was sent, then... silence?

Best regards, Julian
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Fwd: New Version Notification for draft-flanagan-7322bis-00.txt

Heather Flanagan (RFC Series Editor)
On 5/3/17 1:00 AM, Julian Reschke wrote:
> On 2017-03-10 21:27, Heather Flanagan (RFC Series Editor) wrote:
>> FYI, I am kicking off the refresh of the RFC Style Guide. Significant
>> changes include:
>> ...
>
> Out of curiosity: what's the plan here? The draft is two months old,
> feedback was sent, then... silence?
>
>

The plan is to have a -01 out this month. I was discussing some of the
areas of potential change (capitalization of working group, referencing
subseries) with the RPC yesterday, and will be discussing normative
references for open source code with the IESG at their retreat in mid-May.

-Heather


_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Errata Reference Format

Heather Flanagan (RFC Series Editor)
In reply to this post by Julian Reschke
On 3/11/17 5:55 AM, Julian Reschke wrote:

> <https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.5>:
>
>> 4.8.6.5.  Referencing Errata
>>
>>    The following format is required when a reference to an erratum
>>    report is necessary:
>>
>>    [ErrNumber]  RFC Errata, Erratum ID number, RFC number, <URI>.
>>
>>    [Err1912]  RFC Errata, Erratum ID 1912, RFC 2978, xxx.
>
> In V3, we'd format that as:
>
>> <reference anchor="Err1912" quoteTitle="false" target="xxx">
>>   <front>
>>     <title>Errata ID 1912</title>
>>     <author><organization>RFC Errata</organization></author>
>>   </front>
>>   <seriesInfo name="RFC" value="2978"/>
>> </reference>
>
> Observations:
>
> 1) That makes it look like this references actually RFC 2978, so the
> seriesInfo element is very misleading.
>
> 2) No date is specified.
>
> Proposal:
>
> <reference anchor="Err1912" quoteTitle="false"
> target="https://www.rfc-editor.org/errata_search.php?eid=1912">
>   <front>
>     <title>RFC 2978 Erratum 1912</title>
>     <author><organization>RFC Errata</organization></author>
>   </front>
>   <seriesInfo name="RFC Errata" value="1912"/>
>   <date year="2009" month="October"/>
> </reference>
>
> Giving:
>
> [Err1912]  RFC Errata, RFC 2978 Erratum 1912, RFC Errata 1912, October
>            2009, <https://www.rfc-editor.or/errata_search.php?eid=1912>
>
> a) This make seriesInfo actually meaningful.
>
> b) The URI of course should be aligned with what the future format is;
> for instance <https://www.rfc-editor.org/errata/1912>.
>
> c)
> <https://greenbytes.de/tech/webdav/rfc7991.html#element.reference.attribute.quoteTitle>
> allows us to have an unquoted title, but I'd like to question whether we
> *really* need a special case here.
>
> Best regards, Julian
>

Hello all,

The effort to make better, stable errata URLs is done. The format of the
URL is:

<a href="https://www.rfc-editor.org/errata/eid####">https://www.rfc-editor.org/errata/eid####

(e.g., https://www.rfc-editor.org/errata/eid4920)

Note that for the concatenated records (the "Full Records" in a search
on the RFC Editor website) those remain URL search strings.

I will be adjusting the Style Guide, and the RPC will manage the
references as needed for documents in our queue.

Please let me know if you have any questions!
Heather
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Errata Reference Format

Julian Reschke
On 2017-05-05 01:33, Heather Flanagan (RFC Series Editor) wrote:
> ...
> Hello all,
>
> The effort to make better, stable errata URLs is done. The format of the
> URL is:
>
> <a href="https://www.rfc-editor.org/errata/eid####">https://www.rfc-editor.org/errata/eid####
>
> (e.g., https://www.rfc-editor.org/errata/eid4920)

Awesome.

> Note that for the concatenated records (the "Full Records" in a search
> on the RFC Editor website) those remain URL search strings.

I assume you mean "all errata for RFC x"? I think it would be good to
also have a nicer URI for these, but it's not as important than the
actual erratum ID...

> ...

Best regards, Julian




_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Errata Reference Format

Heather Flanagan (RFC Series Editor)
On 5/4/17 11:29 PM, Julian Reschke wrote:

> On 2017-05-05 01:33, Heather Flanagan (RFC Series Editor) wrote:
>> ...
>> Hello all,
>>
>> The effort to make better, stable errata URLs is done. The format of the
>> URL is:
>>
>> <a href="https://www.rfc-editor.org/errata/eid####">https://www.rfc-editor.org/errata/eid####
>>
>> (e.g., https://www.rfc-editor.org/errata/eid4920)
>
> Awesome.
>
>> Note that for the concatenated records (the "Full Records" in a search
>> on the RFC Editor website) those remain URL search strings.
>
> I assume you mean "all errata for RFC x"? I think it would be good to
> also have a nicer URI for these, but it's not as important than the
> actual erratum ID...

Yes, when you search for all errata for an RFC _and_ click on the "Full
Records" option instead of the "Summary Table" option.

-Heather
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Referencing Emails

Heather Flanagan (RFC Series Editor)
In reply to this post by Julian Reschke
On 3/11/17 6:05 AM, Julian Reschke wrote:

> <https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.7>:
>
>> 4.8.6.7.  Referencing Email on Mailing Lists
>>
>>    When referencing emails to mailing lists, the template provided here
>>    should be used:
>>
>>       [reftag] Sender, A., "Subject: Subject line", message to the
>>
>>       listname mailing list, DD Month YYYY, <URL >.
>
> Including the day of month in a reference is something we haven't done
> before, and which xml2rc won't do in references by default.
>
> Given that we already have <reference>s that contain a day-of-month (for
> internet drafts), is your suggestion to have this in ID references as
> well? (that would at least be consistent, and consistency is good)
>

Internet Draft references are styled after RFC references, which do not
include a specific day of publication. I think email is a very different
beast, and having a date specified helps the reader find the correct
message. We're trying to being consistent in like-to-like things.

I understand this may require a feature request for the next xml2rfc.

-Heather
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Placement of Index

Heather Flanagan (RFC Series Editor)
In reply to this post by Julian Reschke
On 3/11/17 6:20 AM, Julian Reschke wrote:

> <https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.10>:
>
>> 4.10.  Index
>>
>>    If included, an index appears directly after any appendices and
>>    before the Acknowledgements (if any).  Where applicable, it appears
>>    before the "IAB Members at the Time of Approval" section.
>
> From an xml2rfc point of view, that's hard to implement, as "IAB Members
> at the Time of Approval" and "Acknowledgements" are regular appendices
> that happen to be unnumbered (using
> <https://greenbytes.de/tech/webdav/rfc7991.html#element.section.attribute.numbered>).
>
>
> Can we generalize this to: "it appears before any unnumbered appendix,
> such as..."? Otherwise we'll need to come up with new markup to define
> where to place the index (in which case you should raise an issue at
> <https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis>).
>

What I would like to see is the index as the second to last thing; I
think Author's Address should be last. I'm assuming, however, that will
result in the same problem re: unnumbered appendixes?

-Heather
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Referencing RFCs

Heather Flanagan (RFC Series Editor)
In reply to this post by Julian Reschke
On 3/11/17 7:04 AM, Julian Reschke wrote:

> <https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.2>:
>
>>    [RFC3080] Rose, M., "The Blocks Extensible Exchange Protocol Core,"
>>    IETF, RFC 3080, DOI 10.17487/RFC3080, March 2001, http://www.rfc-
>>    editor.org/info/rfc3080 .
>
> I see two chaanges from RFC 7322 here:
>
> 1) The addition of the stream name (which I believe is a good change).
> In V3, this could be implemented using (a)
> <https://greenbytes.de/tech/webdav/rfc7991.html#element.refcontent> or
> (b) using
> <https://greenbytes.de/tech/webdav/rfc7991.html#element.seriesInfo.attribute.stream>:
>
>
> a) would look like:
>
> <reference  anchor='RFC3080'
> target='http://www.rfc-editor.org/info/rfc3080'>
>   <front>
>     <title>The Blocks Extensible Exchange Protocol Core</title>
>     <author initials='M.' surname='Rose' fullname='M. Rose'/>
>     <date year='2001' month='March' />
>   </front>
>   <refcontent>IETF</refconfent>
>   <seriesInfo name='RFC' value='3080'/>
>   <seriesInfo name='DOI' value='10.17487/RFC3080'/>
> </reference>
>
> b) would look like:
>
> <reference  anchor='RFC3080'
> target='http://www.rfc-editor.org/info/rfc3080'>
>   <front>
>     <title>The Blocks Extensible Exchange Protocol Core</title>
>     <author initials='M.' surname='Rose' fullname='M. Rose'/>
>     <date year='2001' month='March' />
>   </front>
>   <seriesInfo name='RFC' value='3080' stream='IETF'/>
>   <seriesInfo name='DOI' value='10.17487/RFC3080'/>
> </reference>
>
> Both format require changes to the citations library.
>
> Format (b) has the drawback of being ambiguous, because multiple
> seriesInfo elements might carry conflicting information. We'd also have
> to define the special cases, both for the vocabulary (what if a W3C
> document says stream="IETF"???) and the HTML spec.
>
> 2) The URI appears without angle brackets. I'll guess that's a
> formatting error caused by xml2rfc not processing the <eref> in the
> source as intended.
>

We can't use submissionType because it's not allowed in <reference>?

-Heather
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Referencing STDs and BCPs

Heather Flanagan (RFC Series Editor)
In reply to this post by Julian Reschke
On 3/11/17 7:35 AM, Julian Reschke wrote:

> <https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.3>:
>
>>    For an STD or BCP that contains two or more RFCs:
>>
>>    [STDXXX]  Last name, First initial., Ed. (if applicable), "RFC
>>    Title", Stream, Sub-series number, RFC number, DOI, Date of
>>    publication.
>>
>>             Last name, First initial., Ed. (if applicable)
>>             and First initial. Last name, Ed. (if applicable),
>>             "RFC Title", Stream, Sub-series number, RFC number, DOI,
>>             Date of publication.
>>
>>             <http://www.rfc-editor.org/info/std#>
>>
>>    Example:
>>
>>    [STD13]  Mockapetris, P., "Domain names - concepts and facilities",
>>    STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987.
>>
>>      Mockapetris, P., "Domain names - implementation and
>>      specification", STD 13, RFC 1035, DOI 10.17487/RFC1035,
>>      November 1987.
>>
>>             <http://www.rfc-editor.org/info/std13>
>
> (1) It seems the formatting is broken? Is the first entry really
> supposed to be different from the second one?

Yes, the formatting is broken. Subseries references have long been a
pain to implement; they're still not right.

>
> (2) Why do the individual entries not have a link to
> <http://www.rfc-editor.org/info/rfc#>?

Because if someone is referring to the subseries, then they should go to
the subseries info page for the full list of RFCs and errata associated
with that document set.

>
> (3) What if the spec prose actually wants to refer to one of the
> documents in the document set?

They they shouldn't refer to the subseries; they should just reference
the individual RFC. If they want to do both (reference the subseries and
later specifically reference an RFC within that subseries) then I think
we're going to have a discussion with the author to figure out what
exactly they are trying to do. Are they trying to point someone to
whatever the current standard or best practice is, or are they trying to
point to a snapshot in time? Both are perfectly reasonable things to do,
and we'd adjust the references accordingly.

-Heather
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: Referencing Internet Drafts

Heather Flanagan (RFC Series Editor)
In reply to this post by Julian Reschke
On 3/11/17 7:38 AM, Julian Reschke wrote:

> ...furthermore:
>
> <https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.4>:
>
>>    (...)  If the referenced I-D was
>>    also later published as an RFC, then that RFC must also be listed.
>
> There are cases where this doesn't make a lot of sense - if one cites a
> specific historic Internet Draft because something that was later
> removed or changed, why would it be relevant whether a later draft was
> subsequently published as RFC?

I can see a situation, in a purely historic context, where this might be
unnecessary. I can see many more situations where having the information
that an I-D became an RFC, and the fact that material was removed before
approval to publish means that the material should be considered
carefully in a larger context, is important. I think it's more likely to
have the latter situation than the former, and so the guidance makes sense.

-Heather
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
123