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

--8vCeF2GUdMpe9ZbK
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

> Bradley M. Kuhn writes:
> >     L<perl6-RFCs/"$NUMBER">: $TITLE
> >=20
> >     Where the ": $TITLE" part is optional
=20
Nathan Torkington wrote:
> Why not just L<RFC21> ?  It's shorter.

The main thing I have been struggling with is (to quote perlpod(1)):

        L<name>             manual page

whereas:

       L<name/"sec">       section in other manual page

Thus, I didn't think we'd want to pollute the man page space with our RFC's,
but I did think it might be possible that there would be a "perl6-RFCs" man
page, with sections for each RFC.

Basically, I thought L<RFC21> was Bad Forum (TM).  But, I am not a POD
hacker.


Later on, I ran into this problem, again to quote perlpod(1):

       =B7 Translators will mostly add wording around a L<> link, so that
           `L<foo(1)>' becomes "the foo(1) manpage", for example (see
           pod2man for details).  Thus, you shouldn't write things like `the
           L<foo> manpage', if you want the translated document to read
           sensibly.

So, L<RFC21> will expand to "The RFC21 manpage" in pod2man.  Then, I started
using:

L<RFC 21|perl6-RFCs/"21">

which is very annoyingly too long!


I don't know any way around these problems.  Can a POD-person perhaps speak
up and make a suggestion?


> > Status can be exactly one of the following states
> >     (subject to additional possible states, of course):
> >=20
> >              In-Discussion
> >              Superseded-by: L<perl6-RFCs/"$NUMBER">
> >              Approved-by: $NAME $EMAIL
> >              Rejected-by: $NAME $EMAIL
> >              Defunct
=20
> I'd been picturing the lifetime of discussion as finite.  Rather than go
> infinitely over old ground, at some point the RFC would be frozen.  This
> means that the interested parties debated everything they could, and the
> RFC represents their best thinking.  This would mean an extra 'Frozen'
> status.

Sounds ok to me.
=20
> I'm not sure how realistic freezing an RFC is, though.  I want it because
> I suspect long-running discussions of providing diminishing returns, but I
> know enough about myself to also wonder whether this isn't a personal
> quirk.  Input requested.

We don't need to have "Frozen" be binding permanently.  "Frozen" can just be
a codeword for: "not likely to be discussed again without a really good
reason".  Thus, "Frozen" could be migrated back to "In-Discussion" if
someone makes a good case for it.  (Think of it in terms of a code
freeze---often, there are bug fixes after a freeze, but never new
development).


I envisioned "Approved-by:" and "Rejected-by:" as "no fundamental changes".
A rejected RFC would have to be rewritten as a new RFC to get discussed
again, and approved RFCs would only change for sake of verbosity and
clarifications.

Also, don't forget about Simon's "Withdrawn-by" suggestion (I believe that's
in my most recent patch).


> Status should probably be metadata in the (poorly-named) VERSION
> section, rather than a separate heading.

I agree, but can VERSION get renamed if we add status to it, or does already
too much depend on that name?

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

--8vCeF2GUdMpe9ZbK
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

iD8DBQE5n5cv53XjJNtBs4cRAokNAJ40r1YFI3+ozTHV9zw+Jw1W7ADxOQCgknD4
4TT6cbQaocshr9EQvdzU/ws=
=0AOU
-----END PGP SIGNATURE-----

--8vCeF2GUdMpe9ZbK--