Bug #89048 for P: SYNOPSIS is confusing

Mon Sep 30 07:29:53 2013 l.mai [...] web.de - Ticket created

Subject:

SYNOPSIS is confusing

The SYNOPSIS is supposed to give a short overview of a module's functionality in the form of one or more lines of Perl code. P has this instead: P FILEHANDLE, FORMAT, LIST P FORMAT, LIST P @ARRAY $s=P @ARRAY; P $s; # same output as "P @ Pe # same as P, but output to STDERR The first and second lines are not Perl code; they're some abstract template. I'd expect to find this in the DESCRIPTION. The third line is a Perl fragment (not a complete statement due to lack of ';'). The fourth line is Perl code. The fifth line simply lists a function name with a short description in English. This should probably be cleaned up to use the same type of description for all lines, preferably Perl code for consistency with other modules.

Mon Sep 30 14:10:56 2013 perl-diddler [...] tlinx.org - Correspondence added

From:

perl-diddler [...] tlinx.org

On Mon Sep 30 07:29:53 2013, l.mai@web.de wrote: Show quoted text

> The SYNOPSIS is supposed to give a short overview of a module's > functionality

--- Thank you for your report! I agree with the above part.... in the form of one or more lines of Perl code. ---- But I don't agree to ^this^ part. A synopsis is a summary (short overview). As such, it seemed more descriptive to use symbolic names like "FORMAT" rather than multiple examples. The first 2 lines were designed to parallel summary lines 1 & 3 of the printf function on the perlfunc manpage -- with P (at this point) requiring a comma after the FILEHANDLE (something that might change in the future -- but only if I can keep the current syntax as well, as not doing so would break existing code). The others might be improved on, but, but I didn't want to fall in to the unclear example given for printf of printf FORMAT, LIST -- when FORMAT,LIST is, itself a list in perl, with the printf function -- but NOT with the sprintf function, where they aren't "really" a list, even though they are, syntactically. But I'll look at the other lines and see if I can tidy them up and/or make them more clear. (FWIW, I haven't responded to your 1st 2 reports as it's fairly obvious they need to be fixed, so thanks... not sure why that one one got truncated...). Given the volume, I hope you'll understand if addressing all of these doesn't happen immediately -- but I will be working on them. Thanks again!

Mon Sep 30 14:10:57 2013 The RT System itself - Status changed from 'new' to 'open'

Tue Oct 01 08:21:22 2013 zefram [...] fysh.org - Correspondence added

Subject:	Re: [rt.cpan.org #89048] SYNOPSIS is confusing
Date:	Tue, 1 Oct 2013 13:21:04 +0100
To:	bug-P [...] rt.cpan.org
From:	Zefram <zefram [...] fysh.org>

Linda Walsh wrote: Show quoted text

>But I don't agree to ^this^ part. A synopsis is a summary (short >overview). As such, it seemed more descriptive to use symbolic names like >"FORMAT" rather than multiple examples.

It's customary for the synopsis to use symbolic names, but in the form of Perl variable names. So P $filehandle, $format, @list; P $format, @list; and the like would be totally acceptable. These are symbolic, rather than concrete examples, but they're also valid Perl code. -zefram

Wed Nov 06 00:10:46 2013 pause [...] tlinx.org - Correspondence added

On Tue Oct 01 08:21:22 2013, zefram@fysh.org wrote: Show quoted text

> > P $filehandle, $format, @list; > P $format, @list; > > and the like would be totally acceptable. These are symbolic, rather > than concrete examples, but they're also valid Perl code.

---- I agree, BUT I am trying to follow the examples given with printf in perlfunc, with the point being for it to parallel it's example syntax.

Wed Nov 06 00:11:27 2013 pause [...] tlinx.org - Taken

Mon Jan 27 19:42:49 2014 pause [...] tlinx.org - Correspondence added

I rewrote much of that documentation, making it more clear, but didn't get rid of the use of pseudo code format(s) that are used on the perlfunc manpage.

Mon Jan 27 19:42:50 2014 pause [...] tlinx.org - Status changed from 'open' to 'resolved'