Re: RFC Suggest: Use of L<> to link RFCs; "CONFLICTS WITH", "REQUIRES", "STATUS" sections

--I4VOKWutKNZEOIPu
Content-Type: multipart/mixed; boundary="bX/mw5riLlTkt+Gv"
Content-Disposition: inline


--bX/mw5riLlTkt+Gv
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

[email protected] wrote:

> RFCs are not approved or rejected.  

I was thinking for the future---eventually, the Working Group chair or Larry
or Nat might come by and say: "approve or reject".  I realize this has
happened only once so far (Nat approved my RFC 13, and created a new working
group), but I suspect it might happen in the future.  Do you agree, or am I
missing something?

> The author may withdraw them,

Good point!  I have added this into the format.  I also added dates for
approve and reject, as well as withdrawn.

A new patch is attached.  It also corrects a few errors.

-- 
Bradley M. Kuhn  -  http://www.ebb.org/bkuhn

--bX/mw5riLlTkt+Gv
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="rfc-format-bkuhn-updated.patch"

# Updated patch: bkuhn's suggestions from [email protected], incorporating skud's comments and bug fixes
# 
# To apply this patch:
# STEP 1: Chdir to the source directory.
# STEP 2: Run the 'applypatch' program with this patch file as input.
#
# If you do not have 'applypatch', it is part of the 'makepatch' package
# that you can fetch from the Comprehensive Perl Archive Network:
# http://www.perl.com/CPAN/authors/Johan_Vromans/makepatch-x.y.tar.gz
# In the above URL, 'x' should be 2 or higher.
#
# To apply this patch without the use of 'applypatch':
# STEP 1: Chdir to the source directory.
# STEP 2: Run the 'patch' program with this file as input.
#
#### End of Preamble ####

#### Patch data follows ####
diff -c 'orig/rfc-format.pod' 'new/rfc-format.pod'
Index: ./rfc-format.pod
*** ./rfc-format.pod	Wed Aug  2 14:52:38 2000
--- ./rfc-format.pod	Thu Aug 17 17:57:24 2000
***************
*** 63,68 ****
--- 63,141 ----
  One or two paragraph summary of the problem and proposed solutions,
  or feature and probable implementations.
  
+ =head2 STATUS
+ 
+ This contains the one-line status of the RFC.  The RFC can be on status
+ state at a time.  Currently, the following status states are possible:
+ 
+ =over
+ 
+ =item *
+  
+ In-Discussion
+ 
+ =item *
+ 
+ Superseded-by: L<RFC $NUMBER|perl6-RFCs/"$NUMBER">
+ 
+ Here's an example:
+ 
+     Superseded-by: L<RFC 246|perl6-RFCs/246>
+ 
+ =item *
+ 
+ Approved-by: C<$NAME $EMAIL, $DD $MON $YEAR>
+ 
+ Here's an example:
+ 
+     Approved-by: Nathan Torkington E<lt>[email protected]<gt>, 8 Aug 2000
+ 
+ =item *
+ 
+ Rejected-by: C<$NAME $EMAIL, $DD $MON $YEAR>
+ 
+ Here's an example:
+ 
+     Rejected-by: Larry Wall E<lt>[email protected]<gt>, 10 Sep 2000
+ 
+ =item *
+ 
+ Withdrawn-by-Author: C<$DD $MON $YEAR>
+ 
+ Here's an example:
+ 
+     Withdrawn-by-Author: 18 Oct 2000
+ 
+ =item *
+ 
+ Defunct
+ 
+ =back
+ 
+ =head2 REQUIRES
+ 
+ This section is optional.  If it is provided, it is a list of RFCs, that
+ must be approved for this RFC to be useful.
+ 
+ RFCs listed on separate lines are "ANDed", meaning that each line lists a
+ necessary requirement.
+ 
+ More than one RFC may be listed on one lined, joined by "S< or >".    In
+ this case, only one of the choices must be approved for this RFC to be
+ useful.
+ 
+ See L<REFERENCES> for information on how to list RFCs properly.
+ 
+ =head2 CONFLICTS WITH
+ 
+ This section is optional.  If it is provided, it is a list of RFCs, one per
+ line, that are in conflict with this RFC.  If any one of the RFCs listed in
+ this section are approved, it immediately indicates the rejection of this
+ RFC.  Conversely, if this RFC is approved, it immediately indicates the
+ rejection of all RFCs listed here.
+ 
+ See L<REFERENCES> for information on how to list RFCs properly.
+ 
  =head2 DESCRIPTION
  
  Detailed discussion of the problem or new feature.
***************
*** 78,83 ****
--- 151,170 ----
  A list of pointers to other documentation relevant to the topic.  This
  could be other RFCs, internet standards, existing Perl or
  operating-system documentation, books, and so on.
+ 
+ When other RFCs are referenced, it should be done so in the following
+ format:
+ 
+        L<RFC $NUMBER|perl6-RFCs/"$NUMBER">: $TITLE
+ 
+ Where the C<: $TITLE> portion is optional.  
+ 
+ This format should be used for reference RFCs both in this B<REFERENCES>
+ section as well as elsewhere in the text.  Typically, when RFCs are being
+ listed one per line, the C<: $TITLE> part should be included, but when RFCs
+ are referenced in flowing text, the the C<L>E<lt>C<text
+ wanted|perl6-RFCs/"$NUMBER">E<gt> format should be used.
+ 
  
  =head1 Submitting
  
diff -c 'orig/rfc-sample.pod' 'new/rfc-sample.pod'
Index: ./rfc-sample.pod
*** ./rfc-sample.pod	Wed Aug  2 14:52:37 2000
--- ./rfc-sample.pod	Thu Aug 17 17:56:33 2000
***************
*** 16,24 ****
  The two main candidates for implementation are delayed delivery via
  checkpointing and the event loop.
  
  =head1 DESCRIPTION
  
! Signals may leave Perl in an inconsistent state, so that an inocuous
  C<print> in a signal handler might trigger a core-dump.  This is
  referred to as "unsafe signals".
  
--- 16,40 ----
  The two main candidates for implementation are delayed delivery via
  checkpointing and the event loop.
  
+ [Editor's note: the other RFCs referred to are fictitious]
+ 
+ =head1 STATUS
+ 
+ In-Discussion
+ 
+ =head1 REQUIRES
+ 
+ L<RFC 6|perl6-RFCs/"6">: "Standard Event Loop"  or L<RFC 7|perl6-RFCs/"7">: "Checkpointing"
+ 
+ L<RFC 0|perl6-RFCs/"0">: "Let's Rewrite Perl!"
+ 
+ =head1 CONFLICTS WITH
+ 
+ L<RFC 2|perl6-RFCs/"2">: "The Perl 6 Rewrite is a Bad Idea; Let's Not Bother!"
+ 
  =head1 DESCRIPTION
  
! Signals may leave Perl in an inconsistent state, so that an innocuous
  C<print> in a signal handler might trigger a core-dump.  This is
  referred to as "unsafe signals".
  
***************
*** 30,53 ****
  =head1 IMPLEMENTATION
  
  There are two choices for implementation: checkpointing, and event
! loop. [Editor's note: the other RFC I refer to is fictitious]
  
  =head2 Checkpointing
  
! If the Perl interpreter checkpointed itself at internally consistent
! states, those states could be used to deliver signals.  This would
! delay delivery, however, and the semantics of delayed signals might
! make some programs impossible to write correctly.
  
  =head2 Event loop
  
! RFC 6 describes a desired event loop mechanism.  If the existing
! signal mechanism (%SIG) were dropped, signals could simply become
! events that a program might or might not respond to.  This would be a
! new model of signal handling which would make it difficult to reuse
! algorithms and code for systems programming from C.
  
  =head1 REFERENCES
  
!   RFC 6: "Standard Event Loop"
!   perlvar manpage for discussion of %SIG
--- 46,79 ----
  =head1 IMPLEMENTATION
  
  There are two choices for implementation: checkpointing, and event
! loop.
  
  =head2 Checkpointing
  
! If the Perl interpreter checkpointed itself at internally consistent states,
! those states could be used to deliver signals.  This would delay delivery,
! however, and the semantics of delayed signals might make some programs
! impossible to write correctly.
! 
! L<The Checkpointing RFC|perl6-RFCs/"7"> discusses how the checkpointing
! mechanism might work.  Safe signals could be built on top of that system.
  
  =head2 Event loop
  
! L<RFC 6|perl6-RFCs/"6"> describes a desired event loop mechanism.  If the
! existing signal mechanism (%SIG) were dropped, signals could simply become
! events that a program might or might not respond to.  This would be a new
! model of signal handling which would make it difficult to reuse algorithms
! and code for systems programming from C.
  
  =head1 REFERENCES
  
! L<RFC 6|perl6-RFCs/"6">: "Standard Event Loop"
! 
! L<RFC 7|perl6-RFCs/"7">: "Checkpointing"
! 
! L<RFC 0|perl6-RFCs/"0">: "Let's Rewrite Perl!"
! 
! L<RFC 2|perl6-RFCs/"2">: "The Perl 6 Rewrite is a bad idea; let's not bother!"
! 
! perlvar manpage for discussion of %SIG
#### End of Patch data ####

#### ApplyPatch data follows ####
# Data version        : 1.0
# Date generated      : Thu Aug 17 17:59:04 2000
# Generated by        : makepatch 2.00
# Recurse directories : Yes
# p 'rfc-format.pod' 2103 966549444 0100600
# p 'rfc-sample.pod' 1659 966549393 0100600
#### End of ApplyPatch data ####

#### End of Patch kit [created: Thu Aug 17 17:59:04 2000] ####
#### Checksum: 241 7470 13910 ####

--bX/mw5riLlTkt+Gv--

--I4VOKWutKNZEOIPu
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.2 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iD8DBQE5nGA653XjJNtBs4cRAunfAKDMKMtrQ+AdioV2orQKlMOc+0YE/ACgwiTN
uCYuHxkweaXIGKaCtGpuWEA=
=xQ7r
-----END PGP SIGNATURE-----

--I4VOKWutKNZEOIPu--