Formatting and expounding on cookbook entries

0 views
Skip to first unread message

Gcomnz

unread,
Apr 14, 2005, 7:02:07 PM4/14/05
to perl6-c...@perl.org
All,

I've only written a few cookbook entries for Perl 6 / Pugs, but
there's already been plenty of feedback within the files, and it looks
like the "treat the svn like a wiki" idea might be working.

Something that stands out though is that feedback is often enough
asking for more clarification of what's going on. It would appear that
this is outside the goals of the Pleac project at present. However, I
for one am quite willing to put reasonable amount of explanation into
the Pugs cookbook tree, and I feel that it enhances the value of the
examples in many ways.

Additionally, one of the first things I realized in working through
the entries is that the individual .p6 files that I was creating are
really not runnable as a whole. For instance, a file could contain a
few separate examples, and then a sample script or two, and top it off
with an example one-liner from the command line. I briefly considered
trying to make the ones I was writing runnable, but the effort seems
to blur the examples, making them less clear and concise.

So, to explain better what's going, and to acknowledge the
unrunnability of the individual example files for the most part, I
have POD-ified (poorly, I'm not yet a god of POD) the
01strings/01-00introduction.p6 example, significantly expanding it,
adding more text, answering a question from Juerd through the
commentary, and generally making it an example driven chapter.

But before continuing in this vein, I'd like to confirm that everyone
is okay with this? It certainly makes it easier for me to express the
examples that I write, and not necessarily harder or slower to
formulate. (I'm not at all proposing that all the cookbook files have
to be that way, at least in the first pass. There's a lot of value in
just getting the examples done.)

Thanks,

Marcus Adair

publiustemp-...@yahoo.com

unread,
Apr 15, 2005, 1:17:32 AM4/15/05
to gcomnz, perl6-c...@perl.org
--- gcomnz <gco...@gmail.com> wrote:
> Additionally, one of the first things I realized in working through
> the entries is that the individual .p6 files that I was creating are
> really not runnable as a whole. For instance, a file could contain a
> few separate examples, and then a sample script or two, and top it
> off
> with an example one-liner from the command line. I briefly considered
> trying to make the ones I was writing runnable, but the effort seems
> to blur the examples, making them less clear and concise.

So far the general consensus has been this: for each recipe in the
Cookbook, try to create one file which represents the "solutions" to
the problem. Trying to put things in multiple files just for one
recipe will make things more difficult to manage. If some disagree,
that's OK. Let's hear a better idea.

In the meantime, try to keep to one file, if you can (or create
something easily scriptable to merge it together for submission to
pleac?). And don't worry if you can't run the examples because Pugs
isn't there yet. This is partially here to show off Pugs, but it's
also here to make an easy migration path for people.

The real question is whether or not the Cookbook text can be used. The
code is probably OK (it's meant to be reused), but the problem
statements -- some of which I have copied verbatim -- are in copyright.
I have a question in with O'Reilly and I've been assured that it's
been forwarded to their legal department. As soon as I have an answer,
I'll post it and let people know.

Cheers,
Ovid

--
If this message is a response to a question on a mailing list, please send
follow up questions to the list.

Web Programming with Perl -- http://users.easystreet.com/ovid/cgi_course/

Reply all
Reply to author
Forward
0 new messages