This document outlines an evil plan for improving Pugs documentation. --- START AudreyT brain-dump --------------------------------- This section is essentially disorganised notes taken while AudreyT brain-dumped to asavige in Marrickville, Sydney (while drinking caffeine-free Diet Coke) December 11 2005. AudreyT: since I've liberally interpreted what you said, please correct as you see fit. Next day, Skud (author of Perl 5's perlintro) was leg-roped into helping out at Audrey's Sydney.pm talk, then promptly created a docs/p6doc directory with a view to gradually growing a draft of the documentation that will eventually ship with p6 (with a structure loosely modelled on p5 'perldoc perl'). For now, it seems best to use POD for this. Perhaps a new 'p6doc' command will be created, similar to the p5 'perldoc' command (perhaps p6doc implementation will be based on Perl6::Bible 'p6bible' command). It seems that p6-intro and pugs-intro are important and should be done early to help those starting out with Pugs. Also, it may be easiest to start with perlfaq, then gradually build tutorials. Perl6::Bible should be transformed into Perl6::Spec (e.g. Perl::Spec::Operators, ...) to focus on the p6 specification, while removing dangerously obsolete material, in particular the Apocalypses and Exegeses. Also, stub all Synopses S01 .. S33; if they are empty, say so explicitly. According to docs/AES, Liz is working on S17 (Concurrency), Kane/Rafl on S22 (CPAN), Ingy/Mugwump on S26 (Perl Documentation), Ingy on S27 (Perl Culture), Rod Adams on S29 (functions). These have a status of "unofficial"; perhaps some of these might be better called "draft" (though I guess that would require agreement from @Larry). And auto-update Perl6::Spec onto CPAN from svn regularly (alas, Perl6::Bible has fallen out of date). Note that Perl6::Spec should focus on *specification*, not implementation. This is an important change from p5 (where the implementation *was* the specification). Like Python today, it is hoped there will be multiple p6 implementations (of which Pugs is but one). To achieve that, the specification *must* be nailed down precisely for the implementor. Update: see Larry's response on this issue at: http://www.nntp.perl.org/group/perl.perl6.language/24396 Perhaps the best way to organize the Perl Standard Library is to model it on the reference section of the PickAxe (see Summary p.423-426). Page 426 (change "Modules" to "Roles"). e.g. Enumerable. S29 should be folded into this (a la Ruby Kernel module). S29 could be just a list of standard imports with the details in the Perl Standard Library chapter. As of December 2005, there are a number of problems with the Pugs/Perl6 documentation: * 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. In particular: -- the Architecture section is wrong -- the FAQ needs more work -- Lots of undefined jargon (e.g. strong v static typing) -- you can compile to native code -- the Talks section stops at 2004 -- the Who's Who does not mention the Pugs team or Patrick Michaud -- the Status consists of only one vague line -- the Synopses are OK -- the Apocalypses and Exegeses and RFCs are out of date -- Planet Perl Six is not for the uniniated XXX: Does anyone know where the source code for this web site lives (svn.perl.org?) and the mechanism for updating it (Robert Spier?). * http://www.pugscode.org needs updating. -- "I'd like to help..." needs expanding (and add link to pugs::hack) -- overview/download ok, rest needs work -- need a Pugs Architectural Overview Some bits from current Pugs docs/ directory that might be useful: * docs/quickref/ (Juerd) * docs/articles/tpr.pod (gaal) TPR Pugs article * docs/other/porting_howto (iblech) How to port p5 modules to p6 Bits of Pugs docs/ directory needing more work: -- 01Overview.html -- 02Architecture.pod -- 03Evaluator.pod -- Pugs Apocrypha --- END AudreyT brain-dump ----------------------------------- This section is extra ideas not in original AudreyT brain-dump. Eventually, we trust this evil plan document will be transformed into a more coherent form. It is worth noting at this point that earlier efforts in this area have not met with sparkling success: * The "Perl 6 Documentation Project" (mailing list archives http://www.nntp.perl.org/group/perl.perl6.documentation) started in Nov 2002 and stalled about one year later. This project was led by Michael Lazzaro who complained it was "impossible to to coax p6l into a disciplined decision-making list" (which I guess is why it stalled). See also http://cog.cognitivity.com/perl6/. There are many names from that project that may be happy to help out here; those who registered interest then are: Michael Lazzaro, arcadi, Garret Goebel, Dave Storrs, Tanton Gibbs, Brent Dax, Markus Laire, Angel Faus, Andrew Wilson, Marco Escarcaga, Luke Palmer, Richard Nuttal, Dave Whipp, Jonathan Scott Duff, Allison Randal, Carlos Ramirez, Piers Cawley, Joseph Ryan, Erik Steven Harrison. * Perl6::Bible (http://search.cpan.org/dist/Perl6-Bible/). Apart from a too-cute name and not being automatically updated, this CPAN module is cluttered with dangerously out-of-date material, notably the Apocalypses and Exegeses. The Apocalypses and Exegeses are now historical documents; only the Synopses are being kept up to date (in http://svn.perl.org/perl6/doc/trunk/design/syn/). * Rod Adams S29 at http://www.rodadams.net/Perl/S29.html seems to have stalled ... well, the last update was made on 16 March 2005. Language specifications (e.g. Guido for Python, Bjarne for C++, ...) are traditionally written by the language designer/s for the sound reason that they alone understand the subject matter intimately enough to perform this exacting task. Realistically, there appears little that non-Perl 6 design team folks can contribute in the area of documenting the p6 Specification; that seems to be a job for @Larry. However, the overall structure, tools (and some of the content) of the documentation that will eventually ship with Perl 6 (i.e. docs/p6doc) does seem a realistic goal. Since this is a big job, it seems sensible to offer committer bits to participants in the old "Perl 6 Documentation Project". Perhaps send a message to perl6-documentation@perl.org asking for contributors (though I wasn't involved in this project, it seems to have been focussed more on the p6 specification rather than on the documentation that will eventually ship with p6). There is much (perhaps too much;-) prior art on how to document a computer language (e.g. study how Ruby, Python, Java, Haskell, ... do it and steal the best ideas from each) ... or just convert p5 perldoc to p6. Some references that may prove useful: * http://perldoc.perl.org/ (I prefer this to 'perldoc perl') Organised as follows: -- Overview -- Tutorials -- FAQs -- History/Changes -- License -- Reference -- Language -- Functions -- Operators -- Special variables -- Pragmas -- Core modules -- Utilities -- Internals -- Platform specific -- Links -- CPAN -- perl.com -- perl.org -- Perl Mongers -- Perl Monks -- Planet Perl -- Use Perl * p5 'perldoc perl' Organised as follows: -- Overview -- Tutorials -- Reference Manual -- Internals and C Language Interface -- Miscellaneous -- Language-Specific -- Platform-Specific * The camel book * Python documentation http://www.python.org/ Organised as follows: -- Tutorial -- Global Module Index -- Library Reference -- Language Reference -- Extending and Embedding -- Python C/API -- Documenting Python -- Installing Python Modules -- Distributing Python Modules * Ruby http://www.ruby-lang.org/ This looks a mess to me. * PickAxe Reference section (for Perl Library Reference) * dev.perl.org * Perl6::Bible * gaal's TPR article * Pugs examples/ directory (especially Ovid's cookbook) * Parrot documentation (www.parrotcode.org) -- Chip is taking parrot documentation very seriously (I applaud him for this) and I think a graduate student is currently working on it.