develooper Front page | perl.bootstrap | Postings from July 2000

Re: Mailing lists and RFCs

From:
Tim Bunce
Date:
July 28, 2000 02:56
Subject:
Re: Mailing lists and RFCs
Message ID:
20000728100823.C12542@ig.co.uk
On Fri, Jul 28, 2000 at 12:36:05AM -0600, Nathan Torkington wrote:
> 
> The RFC format is plain text, slightly structured.  I've enclosed
> a sample at the end of this message.  The major components are:
>  - Title
>  - Metadata (Maintainer, Date, Version, Mailing List, Number)
>  - Abstract
>  - Description of the change
>  - List of possible implementations (doesn't have to be at the bit
>    level unless you're talking a bit-level change) that were discussed,
>    with quick summary of pros and cons.
>  - Suggested choice of implementation.

I'd like to (strongly) suggest that the RFCs use basic pod.

Even if only for the titles and verbatim sections. It seems crazy to me
that as a community we're blessed with an excellent very-plain-text
very simple markup system that we all know - and then we don't use it!

Here's your original sample RFC:

> Sample RFC: This Is The Title
> 
> Maintainer: Nathan Torkington <gnat@frii.com>
> Date: 1 April 2000
> Version: 1
> Mailing List: perl6-internals
> Number: 1
> 
> Abstract
> --------
> 
> Perl6 should have no dollar signs.
> 
> Description
> -----------
> 
> The dollar signs make Perl hard to read, therefore the language should
> not have them.  All variables would be scalars, and the dereference
> syntax used to access complex data structures.
> 
> This can go on and on for section after section.
> 
> Implementation
> --------------
> 
> This could be done two ways: with a rewrite of the parser or with
> a modification to `use strict'.  `strict' is probably best.
> 
> Parser
> ------
> 
> Modifying the parser would involve bad juju.
> 
> strict.pm
> ---------
> 
> This might be retrofittable to perl5.


=head1 TITLE

This Is The Title

=head1 VERSION

Maintainer: Nathan Torkington <gnat@frii.com>
Date: 1 April 2000
Version: 1
Mailing List: perl6-internals
Number: 1

=head1 Abstract

Perl6 should have no dollar signs.

=head1 Description

The dollar signs make Perl hard to read, therefore the language should
not have them.  All variables would be scalars, and the dereference
syntax used to access complex data structures.

This can go on and on for section after section.

=head1 Implementation

This could be done two ways: with a rewrite of the parser or with
a modification to `use strict'.  `strict' is probably best.

=head1 Parser

Modifying the parser would involve bad juju.

=head1 strict.pm

This might be retrofittable to perl5.

=cut

All I've done is
1/ remove the ascii underlining
2/ add =head1 to the headings
3/ add an =cut so we know it's not been truncated
4/ restructure the TITLE/VERSION part slightly

Can we agree on using POD soon, before we have a flood of non-pod RFCs?

Tim.



nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About