Bug #89049 for P: SYNOPSIS contains description

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

Subject:

SYNOPSIS contains description

The SYNOPSIS contains not just short code samples but also this text: P is a combined printf, sprintf & say in 1 routine . It was designed to save on typing and undef checking when printing strings. ... This should be part of the DESCRIPTION. Currently the first sentence of the DESCRIPTION is "While designed to speed up and simplify development, isn't limited to such." That's not a description; it's a continuation of the preceding paragraph, indicating that the real description starts much earlier.

Wed Nov 06 00:08:23 2013 pause [...] tlinx.org - Severity Normal added

Wed Nov 06 00:08:23 2013 pause [...] tlinx.org - Correspondence added

A synopsis, by definition, is a "short" description. If it was intended only to be examples of usage, it might be called "USAGE"...? I hear what you are saying -- it's not following some other pod pages which put examples in their SYNOPSIS section, but I don't think this should be that confusing. Simply showing alot of calls that would look like calls to "sprintf", "printf", "print" or "say", says nothing. I.e. it is in what "P" does that is different from those calls that is important. The syntax is mostly the same (if not entirely?) as a call to one of those calls, w/the exception of being more useful about an array argument to sprintf.

Wed Nov 06 00:08:23 2013 The RT System itself - Status changed from 'new' to 'open'

Wed Nov 06 00:08:24 2013 pause [...] tlinx.org - Taken

Mon Jan 27 19:44:22 2014 pause [...] tlinx.org - Correspondence added

Synopsis no longer has such verbiage except as code comments.

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