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

--17/8oYur5Y32USnW
Content-Type: multipart/mixed; boundary="z9ECzHErBrwFF8sy"
Content-Disposition: inline


--z9ECzHErBrwFF8sy
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

I have a few suggestions to make the RFC format better.  It seemed a bit
silly to write an RFC on how the RFC format can be better, so instead I
describe them in brief here, and I attach a patch for rfc-format.pod and
rfc-sample.pod that adds these suggestions. (If this needs an RFC, please
let me know and I will RFC it.)

I am not a POD hacker, so the way I did the L<> formats and other things
might not be proper POD use; please let me know if it isn't.


The suggestions:

  * Currently, RFC references are usually put in the REFERENCES section in
    the following format:

    RFC $NUMBER: $TITLE

    I suggest, so that better linking can be provided, that we use something
    like this:

    L<perl6-RFCs/"$NUMBER">: $TITLE

    Where the ": $TITLE" part is optional

    This way, if someone writes a POD parser module that can generate nice
    HTML (or other link-able output) from RFC PODs, links can be added
    automatically without guessing.

    Of course, such L<> formatted references need not be confined to the
    REFERENCES section, if they fit well into the flowing text.

  * Standardize the STATUS section, which contains one line of data that
    indicates the status.  Status can be exactly one of the following states
    (subject to additional possible states, of course):

             In-Discussion
             Superseded-by: L<perl6-RFCs/"$NUMBER">
             Approved-by: $NAME $EMAIL
             Rejected-by: $NAME $EMAIL
             Defunct

  * Addition of a REQUIRES section, which is a list of RFCs, one per line.
    This section indicates that this RFC is useless if the listed RFC(s) are
    not approved.
  
  * Addition of a "CONFLICTS WITH" section, which is a list of RFCs, one per
    line.  This section indicates that this RFC is in direct conflict with
    the listed RFC(s), and that it is impossible to approve this RFC if any
    one of the listed RFCs are approved.

I hope you like my suggestions.  The patch is attached.

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

--z9ECzHErBrwFF8sy
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="rfc-format-bkuhn.patch"

# Changes the RFC format and sample based on bkuhn's suggestions to [email protected]
# 
# 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	Wed Aug 16 19:21:22 2000
***************
*** 63,68 ****
--- 63,121 ----
  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<perl6-RFCs/"$NUMBER">
+ 
+ =item *
+ 
+ Approved-by: $NAME $EMAIL
+ 
+ =item *
+ 
+ Rejected-by: $NAME $EMAIL
+ 
+ =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 seperate 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 ****
--- 131,150 ----
  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<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 C<L>E<lt>C<perl6-RFCs/"$NUMBER">E<gt> or
+ the C<L>E<lt>C<text wanted|perl6-RFCs/"$NUMBER">E<gt> formats.
+ 
  
  =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	Wed Aug 16 19:30:27 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 refered to are fictitious]
+ 
+ =head1 STATUS
+ 
+ In-Discussion
+ 
+ =head1 REQUIRES
+ 
+ L<perl6-RFCs/"6">: "Standard Event Loop"  or L<perl6-RFCs/"7">: "Checkpointing"
+ 
+ L<perl6-RFCs/"0">: "Let's Rewrite Perl!"
+ 
+ =head1 CONFLICTS WITH
+ 
+ L<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<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<perl6-RFCs/"6">: "Standard Event Loop"
! 
! L<perl6-RFCs/"7">: "Checkpointing"
! 
! L<perl6-RFCs/"0">: "Let's Rewrite Perl!"
! 
! L<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      : Wed Aug 16 19:33:07 2000
# Generated by        : makepatch 2.00
# Recurse directories : Yes
# p 'rfc-format.pod' 2103 966468082 0100600
# p 'rfc-sample.pod' 1659 966468627 0100600
#### End of ApplyPatch data ####

#### End of Patch kit [created: Wed Aug 16 19:33:07 2000] ####
#### Checksum: 221 6969 42261 ####

--z9ECzHErBrwFF8sy--

--17/8oYur5Y32USnW
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

iD8DBQE5myUb53XjJNtBs4cRAv9vAJ46pocpJA7rkFTB9tLhMIjzBDD5pQCfcuDR
i/A6Qmz+1T0SDyd6F3/oIyI=
=q6d4
-----END PGP SIGNATURE-----

--17/8oYur5Y32USnW--