Perl documentation ()

Chas. Owens | 2 Jul 2010 01:11

Picon

Re: Announcing the Perl 5 Documentation Team

On Thu, Jul 1, 2010 at 16:40, Paul Johnson <paul <at> pjcj.net> wrote:
snip
>>   * Updating the documentation so that all examples longer than one
>>       line contain a `use` statement indicating the minimum version of
>>       Perl 5 required to run the example
>
> I'm afraid that I don't think this is a sensible suggestion at all.  I
> took a look at a few pages, almost at random.  I looked at perldata,
> perlfaq3, perllol and perlcall.  Adding C<use 5;>, as it would often be,
> a dozen or more times in a document adds little value but greatly
> detracts from the flow of the document.
>
> Is this really a problem.  Are there many people out there trying to use
> qr// on 5.003, for example?  I can see some value in noting that C<when>
> as a statement modifier is unavailable before 5.12, for example, but as
> a general policy I feel it is misguided.  Please reconsider this idea.
snip

Failure to add a use 5.010; or use 5.012; limits the features that can
be used in examples.  For instance, this example won't work even under
5.12 as it is written:

    say "foo";

It is possible that we should only add use statements to examples that
need features in 5.10 or later.

--

-- 
Chas. Owens
wonkden.net

(Continue reading)

Chas. Owens | 2 Jul 2010 01:22

Picon

Re: Announcing the Perl 5 Documentation Team

On Thu, Jul 1, 2010 at 17:29, Ævar Arnfjörð Bjarmason <avarab <at> gmail.com> wrote:
snip
>>  * Extensive review and Modernization of all examples
>
> One thing I'd like to suggest. I think it'd improve our code examples
> a lot if we used a consistent style for them. By that I mostly mean
> not coding style (we've had that giant flamewar), but the sort of
> thing you find in "conventions used in this documentation" sections.
>
> E.g. consistently showing the return values of expressions like the
> Ruby and Python documentation do:
> http://ruby-doc.org/docs/ProgrammingRuby/html/tut_classes.html
snip

One of the things I have been doing is using a comment after a line
stating what the result of line is.

snip
>>  * Develop a plan to integrate with the [Pod2 translation project][4]
>
> It'd be great if we could get multilingular documentation of the
> ground. I think that for this to be fruitful we'd need a translation
> system so that translated documentation doesn't suffer
> bitrot. E.g. something similar to what translatewiki.org does to
> translate content, where things are split into paragraphs or sections
> and then assembled back again.
>
> Is there something like that already that can be used or improved?
snip

(Continue reading)

Chas. Owens | 2 Jul 2010 15:30

Picon

Re: Announcing the Perl 5 Documentation Team

On Fri, Jul 2, 2010 at 08:57, David Golden <xdaveg <at> gmail.com> wrote:
> On Fri, Jul 2, 2010 at 8:22 AM, Chas. Owens <chas.owens <at> gmail.com> wrote:
>> It isn't just that say wasn't added until 5.10, it is that say doesn't
>> even work without a "use 5.010;" or similar statement.  This means
>> that the person coming to the Perl for the first time will encounter
>> one of three scenarios:
>
> You're missing my point, or I'm not being sufficiently clear.
>
> The vast majority of the time, the documentation is being read by
> people who are *NOT* "coming to Perl for the first time" and thus I
> don't think that *all* documentation should be written for the
> absolute beginner.
>
> Intro-level documentation ("intro", "tutorial", "quick start",
> possibly "faq") should.  Reference documentation should not.  IMO,
> that includes things that would come from perldoc -f, etc.
>
> Yes, we want to make Perl easier to learn for the novice, but not at
> the cost of bloating the documentation for the average user.
>
> -- David
>

Lets take a quick look at what it would really look like.  I chose
substr at random and updated it to fit scenario 3.  It took four
version statements and a rewrite of the last example.  I am not
satisfied with the last example, it is still very confusing. there
must be a better example of when you would use this feature of substr.
 Also, and this shows my ignorance of the newer features, why doesn't

(Continue reading)

Caleb Cushing | 2 Jul 2010 15:46

Picon

up to date archive?

is there a current archive of this list somewhere?
http://www.mail-archive.com/perl-documentation <at> perl.org/ does NOT show
anything past 2009.

--

-- 
Caleb Cushing

http://xenoterracide.blogspot.com

Shawn H Corey | 2 Jul 2010 15:50

Picon

Re: Announcing the Perl 5 Documentation Team

On 10-07-02 09:30 AM, Chas. Owens wrote:
> Proposed style:
>
> =item substr EXPR,OFFSET
>
> Extracts a substring out of EXPR and returns it.  First character is at
> offset C<0>, or whatever you've set C<$[>  to (but don't do that).
> If OFFSET is negative (or more precisely, less than C<$[>), starts
> that far from the end of the string.  If LENGTH is omitted, returns
> everything to the end of the string.  If LENGTH is negative, leaves that
> many characters off the end of the string.

What the heck is LENGTH?

--

-- 
Just my 0.00000002 million dollars worth,
   Shawn

Programming is as much about organization and communication
as it is about coding.

The secret to great software:  Fail early & often.

Eliminate software piracy:  use only FLOSS.

Chas. Owens | 2 Jul 2010 15:56

Picon

Re: Announcing the Perl 5 Documentation Team

On Fri, Jul 2, 2010 at 09:50, Shawn H Corey <shawnhcorey <at> gmail.com> wrote:
> On 10-07-02 09:30 AM, Chas. Owens wrote:
>>
>> Proposed style:
>>
>> =item substr EXPR,OFFSET
snip
> What the heck is LENGTH?
snip

My copy and paste left out

=item substr EXPR,OFFSET,LENGTH,REPLACEMENT
X<substr> X<substring> X<mid> X<left> X<right>

=item substr EXPR,OFFSET,LENGTH

In the first example.

--

-- 
Chas. Owens
wonkden.net
The most important skill a programmer can have is the ability to read.

Chas. Owens | 2 Jul 2010 16:01

Picon

Re: up to date archive?

On Fri, Jul 2, 2010 at 09:46, Caleb Cushing <xenoterracide <at> gmail.com> wrote:
> is there a current archive of this list somewhere?
> http://www.mail-archive.com/perl-documentation <at> perl.org/ does NOT show
> anything past 2009.
snip

http://groups.google.com/group/perl.documentation/topics seems to be
working, but it isn't showing all of the emails I sent yesterday
(including the "I want to sign up" email).  I am going to try
resending now.

--

-- 
Chas. Owens
wonkden.net
The most important skill a programmer can have is the ability to read.

Chas. Owens | 2 Jul 2010 16:03

Picon

I want to sign up

If you want to sign up for the Perl 5 Documentation Team, leave an
email here or email me directly.  If you know what you want to work on
mention it, otherwise I will assign you a task.

--
Chas. Owens
wonkden.net
The most important skill a programmer can have is the ability to read.

Ævar Arnfjörð Bjarmason | 2 Jul 2010 16:27

Picon

Re: Announcing the Perl 5 Documentation Team

On Fri, Jul 2, 2010 at 13:56, Horsley, Tom <Tom.Horsley <at> ccur.com> wrote:
> Good luck with this. I'll just mention one thing that has bothered me since
> the documentation got all improved when moving from perl4 to perl5:
>
> The perl4 doc was all one giant man page, which made it really simple
> to search. It would be nice if there was a single document designed
> to be searched easily that at least had pointers to the right document
> where you'll find details of what you are searching for (in particular
> I never have any idea if something like -M is a "function" or a "operator" .

On my infinite todo list I have an item for adding a perl5 POD -> GNU
Texinfo conversion script. Then you can generate indexed docs you can
easily search through, dump the whole thing as a big man/HTML/PDF etc.

Or you could just concat all the existing core manpages now to get some of that.

Gabor Szabo | 2 Jul 2010 16:33

Picon

Re: Announcing the Perl 5 Documentation Team

On Fri, Jul 2, 2010 at 3:57 PM, David Golden <xdaveg <at> gmail.com> wrote:
> On Fri, Jul 2, 2010 at 8:22 AM, Chas. Owens <chas.owens <at> gmail.com> wrote:
>> It isn't just that say wasn't added until 5.10, it is that say doesn't
>> even work without a "use 5.010;" or similar statement.  This means
>> that the person coming to the Perl for the first time will encounter
>> one of three scenarios:
>
> You're missing my point, or I'm not being sufficiently clear.
>
> The vast majority of the time, the documentation is being read by
> people who are *NOT* "coming to Perl for the first time" and thus I
> don't think that *all* documentation should be written for the
> absolute beginner.
>
> Intro-level documentation ("intro", "tutorial", "quick start",
> possibly "faq") should.  Reference documentation should not.  IMO,
> that includes things that would come from perldoc -f, etc.
>
> Yes, we want to make Perl easier to learn for the novice, but not at
> the cost of bloating the documentation for the average user.

Interestingly I would have said that the documentation is mostly needed
by novices or by people who rarely use Perl. The difference might be
because I encounter so many people who are learning Perl.

What they usually would need, IMHO is an easy way to grab an example
of simple task.

"How can I open a file?"
or even

(Continue reading)

Group

gmane.comp.lang.perl.documentation.

Project Web Page

Perl documentation ()

Search Archive

Page

1 | 2 | 3 | 4 | 5 | 6

Articles in period: 50

July 2010

Language

Change language

Options

Current view: Threads only / Showing only 20 lines / Not hiding cited text.
Change to All messages, whole messages, or hide cited text.

Post a message
NNTP Newsgroup
Classic Gmane web interface
XML

XML

RSS Feed
List Information

About Gmane

Recent entries

Please, update docs (& pods) for Perl 5.16.3!!! (7 Mar 2013)
[ANNOUNCE] POD2::ES v5.16.2.01 (16 Nov 2012)
documentation for the split command; webpage issues (19 Jun 2012)
Perl v5.16R0, VMS and others docs issues (15 May 2012)
PerlDoc-ES project, at 33,33% done (7 Apr 2012)
Github changed pod rendering HTML format (25 Mar 2012)
Fw: Two Documents Restored from perl.net.au (24 Mar 2012)
Perl 5 wiki (13 Feb 2012)
[ANNOUNCE] POD2::ES v5.14.2.05 (30 Oct 2011)
About.com Guide for Perl [was Fwd: RE: Guide Application for [Perl]] (10 Sep 2011)
HTTP::Tiny and JSON::PP (8 Sep 2011)
new package syntax, where do I return true? (2 Jul 2011)
new package syntax, where do I return true? (2 Jul 2011)
About.com Guide for Perl [was Fwd: RE: Guide Application for [Perl]] (24 May 2011)
insufficient shift operator explanation (17 Mar 2011)
indispensability of close()-checking [was: authorial perlipc edit] (11 Nov 2010)
Documentation for ${^GLOBAL_PHASE} (1 Nov 2010)
[Resend] Patch to Get Rid of \t in perlipc.pod [was Re: [PATCH] Start (23 Oct 2010)
Additional Patches to perlopquick.pod (12 Aug 2010)
Current state of Perl 5 Documentation Team (8 Aug 2010)
Pushed 15 patches to perlopquick.pod (8 Aug 2010)

Archives

2	March 2013
1	January 2013
1	November 2012
1	September 2012
1	August 2012
1	July 2012
5	June 2012
2	May 2012
1	April 2012
3	March 2012
2	February 2012
1	October 2011
2	September 2011
5	July 2011
2	May 2011
3	March 2011
29	December 2010
21	November 2010
1	October 2010
4	September 2010
19	August 2010
50	July 2010
1	October 2009
1	August 2009
6	July 2009
9	May 2009
1	November 2008
5	January 2007
2	November 2006
1	October 2006
1	September 2006
4	July 2006
2	June 2006
7	May 2006
11	April 2006
3	March 2006
1	February 2006
9	January 2006
4	December 2005
1	November 2005
8	October 2005
3	September 2005
10	August 2005
5	July 2005
1	May 2005
21	April 2005
12	March 2005
5	February 2005
22	January 2005
30	December 2004
7	November 2004

Design

Zawodny | Right Menu | Left Menu

Your Own Design

Paste the URL of your CSS below. Download CSS template