Also, throughout the distribution we use variously TITLE (aka TITEL) and NAME with and without the file path.
I've been using
=head1 NAME
path/file - Short Description
Any objections to standardizing on that? I'd cite (most of) Perl docs for precedent. In Perl modules path/file gets replaced by Package::Name.
Mike
On 21 Feb 2004, at 06:59, Simon Glover wrote:
On Sat, 21 Feb 2004, Simon Glover wrote:
OK, here's a rewritten version of PDD 0, which reflects my view of the role that the PDDs currently play in Parrot development. Comments welcome.
Let's try that again, with the the PDD actually attached this time...
Simon
-----------------------------------------------------------------
=head1 TITLE
Parrot Design Documents
=head1 VERSION
=head2 CURRENT
Maintainer: Class: Meta PDD Number: 0 Version: 2 Status: Developing Last Modified: 20 February 2004 PDD Format: 1 Language: English
=head2 HISTORY
v2 substantially rewritten on 20 Feb 2004 by Simon Glover
v1 created on 7 Dec 2000 by BCWarnock <[EMAIL PROTECTED]>
v1 promoted to Developing as PDD 0 on 20 February 2001 by Dan Sugalski.
=head1 CHANGES
Substantially rewritten to reflect what the PDDs actually are (rather
than what we hoped they would be 3+ years ago).
=head1 ABSTRACT
This document defines the standard format for the Parrot Design Documents
(PDDs) - the basic descriptions/plans for the design of Parrot.
=head1 DESCRIPTION
The original intent of the Parrot Design Documents (which themselves were
initially Perl Design Documents) was threefold:
=over 4
=item 1
To provide a clear indication of the direction of current development
(essentially, a road map from an abstract idea to a concrete implementation).
=item 2
To act as a historical record of the rationale behind the decision, in order
to provide context to future developers, who may not have been familiar
with the original discussion.
=item 3
To provide a historical, technical and cultural perspective for future development work. Re-implementation or even tangential tasks need only address what has changed since the original PDD.
=back
Needless to say, things didn't work out this way. Some of the context
discussed above is now documented in the F<*.dev> documents (see the
F</docs/dev> directory); much of it remains undocumented. The portions
that have wound up being documented as PDDs are the basic design of
the Parrot interpreter. In other words, the PDDs describe the B<features
that the interpreter should implement>. They B<should not> discuss the
details of the actual implementation (unless they absolutely have to)
or the choices leading to that particular implementation; these are
details that should go in the relevant F<*.dev> file. On the other
hand, they B<should> detail the trade-offs made in the actual design.
=head1 IMPLEMENTATION
All newly created PDDs will adhere to the PDD standard current as of the time of proposal. An example of the currently accepted layout is given in F<docs/pdds/pdd_template.pod>, which should be used as a template for any future PDDs.
=head2 FORMAT
All PDDs will be written in POD parseable by the current stable release
of Perl. Although XML is a viable solution and has its vocal supporters,
and although Parrot is intended to be used by many groups outside of the
Perl community, we have chosen POD for its simplicity and ease of
reading in plaintext form. Conversion to other formats (e.g. HTML) is
encouraged, but the POD version should remain the master copy.
All PDDs will be written in English. British, American, or Other is the choice of the author. Translation to other languages, like all Perl documentation, is encouraged. (See S<L<"PDD TRANSLATIONS">>.)
All PDDs will contain the following information:
=over 4
=item TITLE:
A short, general description of a specific part of the Parrot design. This may be a particular subsystem (e.g. the garbage collector), or a more general topic (e.g. basic Parrot datatypes).
=item VERSION:
Contains current and selected historical metadata on the PDD itself.
=item CURRENT:
Contains the following information, current as of the date of submission.
=over 4
=item Maintainer
Required. The name and current email address for the point of contact for the PDD. This is the person to whom questions, comments, and patches should generally be addressed. This need not be the author of the document.
(In practice, non-trivial changes to the PDDs should probably be discussed on the perl6-internals mailing list before they take place).
=item Class
Required. The area of Parrot the PDD covers. This allows related PDDs to be logically grouped. The current list of valid classes is:
Internals - on the design of the Parrot interpreter Documentation - on Parrot documentation Meta - on the Parrot project as an entity Testing - on the testing of Parrot
It is expected that most PDDs will fit into a single class, but in principle a may belong to more than one class. However, peripheral excursions into the scope of another class should not warrant an actual classification (i.e. you shouldn't classify something as C<Testing> simply because you happen to mention potential tests at one or two points in the text).
=item PDD Number
Required. No two PDDs should have the same number. PDD numbers are assigned by whoever commits the PDDs to the repository, subject to the approval of the Pumpking.
=item Version
Required. A one-up integer reflecting each public revision of a PDD. This
reflects the version of the document itself, and not version of the standard
the document may provide.
=item Status
Required. The current state of the PDD. Currently, the only classifications in use are C<Informational> and C<Developing>. We hope to eventually add C<Standard>. All three are detailed below:
=over 4
=item Informational
A PDD discussing possible design choices for a particular area of Parrot.
This is non-prescriptive -- the final design may look nothing like the
suggested one -- but provides a useful way to document detailed design
concepts for later reference. For a good example, see
F</docs/pdds/pdd14_bignum.pod>.
=item Developing
An acceptable (at least, in theory) PDD that needs further fleshing out
and fine tuning. The PDD, as well as the implementation it describes, are
both under official development by the Parrot development community.
=item Standard (Version #)
A frozen snapshot of the design as it applies to Parrot at a particular moment in time. The version number should reflect that version number of Parrot that the standard was first applied to. C<Developing> PDDs are expected to eventually become C<standard>.
=back
=item Last Modified
Required. The date of the last submission.
=item PDD Format
Required. The specific PDD Standard that the PDD adheres to. This allows
scripts to better parse PDDs of multiple aging formats. The format
currently in use is PDD format 1.
=item Language
Optional. The language that the PDD is written in.
=back
=item HISTORY:
A list of free-flow descriptions of significant metadata changes, such
as status changes, or change of maintainers. Each entry should include
the version, date, and nature of the change. This provides a quick
historical overview of the major metadata changes of a PDD. This field is
not to be used for a comprehensive list of alterations to the document.
=item CHANGES:
A summary of the changes since the last version. A comprehensive change log should be kept, but only within a supporting document.
=item ABSTRACT:
A quick blurb explaining the purpose of the PDD.
=item DESCRIPTION:
A description of the general nature of the PDD and how it relates to Parrot.
=item IMPLEMENTATION:
A major section of the PDD that encapsulates a free-form discussion of any and all applicable information related to the final observations, conclusions, and what-have-you that required writing the document in the first place.
=item ATTACHMENTS:
References to supporting files that should be considered part of the PDD. Text files and image files may be in any widely accepted format, which is rather subjective. Violators may be prosecuted.
Text files and image files should only provide supplemental information; no fair hiding all the info in an attachment just to not have to write an implementation section.
=item REFERENCES:
References to additional sources of information, but not those necessary for the PDD itself.
=back
The PDD author may add any additional sections he or she wishes.
=head2 SUBMISSION CRITERIA
Proposed PDDs should be submitted to the perl6-internals mailing list (located at [EMAIL PROTECTED]) for discussion, criticism and general kibitzing. Acceptance of a particular PDD is ultimately up to the current Pumpking and/or the internals chief (a.k.a. Dan).
=head2 PDD TRANSLATIONS
Should a PDD be translated into another language, the following guidelines should be met.
=over 4
=item *
The C<Maintainer> field should reflect who did the translation.
=item *
The C<Version> number should match the original document's C<Version> number. Should multiple translated versions of a single original PDD be done (to correct spellings, etc.), the revision specific to that document version should be included in parentheses following the version number.
=item *
Attributions in the C<HISTORY> section should be left alone.
=back
=head2 PDD STATUS CHANGES
Any change to the status of a particular PDD should be approved by the current Pumpking and/or the internals chief.
=head2 AVAILABILITY
All C<Informational>, and C<Developing> PDDs should be readily available,
in a centralized location, to at least the current Parrot development
circles. All C<Standard> PDDs should be readily available, in a
centralized location, to the general public.
=head1 ATTACHMENTS
None.
=head1 REFERENCES
Dan Sugalski's original PDD guidelines at http://www.mail-archive.com/[EMAIL PROTECTED]/msg01766.html
