develooper Front page | perl.perl6.documentation | Postings from December 2005

Building the documentation that will ship with Perl 6 and Pugs

From:
Andrew Savige
Date:
December 30, 2005 17:47
Subject:
Building the documentation that will ship with Perl 6 and Pugs
Message ID:
20051231014706.94262.qmail@web36103.mail.mud.yahoo.com
[Note: Posted to both perl6-language and perl6-documentation.
Since perl6-documentation is no longer advertised, I assume
follow ups should be posted to perl6-language only].

When Audrey gave a recent talk to Sydney.pm, she pointed out
some deficiencies in the current Pugs/Perl 6 documentation
and asked if I could help. Hence this email. In particular,
she noted:

* It is way too hard for newbies to come up to speed with p6
  and Pugs because the documentation is scattered all over the
  shop and much of it (e.g. the Apocalypses and Exegeses) is
  dangerously out of date.

* http://dev.perl.org/perl6/ needs updating.

* http://www.pugscode.org/ needs updating.

* It would be good to now start building the documentation
  that will eventually ship with Perl6 and Pugs. [Note that
  Pugs is just one implementation of Perl 6 the language
  (albeit the leading candidate for "Reference Implementation")
  thus there is a need for some Pugs-specific documentation.]
  Needless to add, she proposed that this documentation be
  built in the Pugs svn repository using the Pugs "anarchic"
  [TM] development model.

After re-acquainting myself with Perl 6/Pugs and researching
some Perl 6 documentation history, here are my thoughts:

* I'm hopeful that the p6 spec has become stable enough that
  it now makes sense to press forward with p6 documentation.

  [It seems the lack of stability of the spec was one reason
  the "Perl 6 Documentation Project" stalled (list archives:
  http://www.nntp.perl.org/group/perl.perl6.documentation)].

* Having said that, I feel the Perl 6 spec itself properly
  belongs with @Larry and any (highly-skilled) volunteers
  they invite to help them. I doubt the Pugs development
  model will work well for this owing to the phenomenal
  skill level and precision required (just a personal
  opinion, I'm interested to hear what @Larry thinks).

* I feel the Pugs model may work well for the non-formal-spec
  part (e.g. perlintro, pugsintro, tutorials, ...) of the
  documentation that will ship with Perl 6 and Pugs.
  Accordingly, that effort has already been started
  (mainly by Skud, so far) in the Pugs svn repository:
  http://svn.perl.org/perl6/pugs/trunk/docs/p6doc/.

Call to Arms
============

Volunteers are sought for building the documentation that will
ship with Perl 6 and Pugs. This documentation lives in the Pugs
svn repository under docs/p6doc/. This documentation is being
written in POD.

If you want to contribute to this effort, hang around on the
#perl6 IRC channel and ask someone for a committer bit.

How should the documentation be organised?
==========================================

Opinions are welcome on this. Certainly, there is much prior
art on how to document a computer language. I feel we should
essentially follow the p5 model, stealing good ideas from other
languages (especially Ruby and Python) where appropriate.
In particular, Ruby's PickAxe book seems a sound model for
documenting the new p6 OO libraries.

Though Audrey suggested modelling the documentation around
p5's 'perldoc perl' command, I personally prefer the (similar)
organisation at http://perldoc.perl.org/.

References
==========

* The Perl 6 Synopses, Apocalypses and Exegeses at:
  http://dev.perl.org/perl6/ (they are also stored in
  http://svn.perl.org repository). The Synopses are the
  most important of the three since they are the only ones
  being kept up to date.

Some bits from current Pugs docs/ directory that might be useful:

* docs/quickref/ (Juerd)
* docs/articles/tpr.pod (gaal) draft (unpublished) TPR Pugs article
* docs/other/porting_howto (iblech) How to port p5 modules to p6
* docs/notes/docs_evil_plan.txt (asavige)
* examples/ directory (especially Ovid's cookbook)

Some bits of Pugs docs/ directory needing more work:

* 01Overview.html
* 02Architecture.pod
* 03Evaluator.pod
* Pugs Apocrypha

* Perl6::Bible (http://search.cpan.org/dist/Perl6-Bible/).

* "Perl 6 Documentation Project"
  http://www.nntp.perl.org/group/perl.perl6.documentation

* Rod Adams S29 at http://www.rodadams.net/Perl/S29.html

* http://perldoc.perl.org/

* p5 'perldoc perl' command

* The camel book

* Python documentation http://www.python.org/

* PickAxe Reference section (for Perl Library Reference)

* Parrot documentation (www.parrotcode.org)



Send instant messages to your online friends http://au.messenger.yahoo.com 



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