On Tue, 04 Jan 2005 00:15:13 +0100, David Landgren <[EMAIL PROTECTED]> wrote:
> Juerd wrote:
> "You can either mix POD with code"... I know what you mean, but I think
> "intersperse" or "intermingle" describe the effect more clearly.
"by lines" or "by whole lines" to keep people from trying to do
Juerd wrote:
Attached is the revised version of perlpodtut, based on your well
appreciated feedback. The second attachment is the diff with the
previous version.
[...]
=head1 NAME
perlpodtut - Plain Old Documentation in 5 minu
Discussing the sections is a very good idea, IMO, and eventually you
could come up with formal standard for them, but perlpodtut is not the
thing that should change the world. It should lag behind common
practice.
If this new formal standard can be made detailed enough, we can perhaps
start having
Juerd <[EMAIL PROTECTED]> writes:
> Discussing the sections is a very good idea, IMO, and eventually you
> could come up with formal standard for them, but perlpodtut is not the
> thing that should change the world. It should lag behind common
> practice.
> If this new formal standard can be made
ack,
> submit bug reports and patches.
pod2man says this should go into the AUTHOR section if it's just a contact
point for the author / maintainer.
> Does the module have a project web site
> (e.g. on sourceforge)? and specifically
> - Where can the software be obtained?
. technical questions, provide
feedback, submit bug reports and patches. Does the module have a
project web site (e.g. on sourceforge)? and specifically
- Where can the software be obtained? or downloaded from? what about
development snapshots and CVS copies? This might be the AVAILABI
David Nicol skribis 2004-12-30 0:17 (-0600):
> See L for discussion of the rarely used F, S, X and Z.
I've chosen not to refer to perlpod or perlpodspec or pod2man except
in the SEE ALSO section. Otherwise almost every paragraph would need
this.
Juerd
okeydoke. I would strike the "not worth explaining in a simple turorial"
clause, since it is obvious. Just say they're rarely used, or leave them out
entirely.
saying "F,S,X and Z are rarely used." just intriduces the question of,
well what do they do? and confuses rather than enlightens.
On Wed, 29 Dec 2004 22:12:03 -0500, David Manura <[EMAIL PROTECTED]> wrote:
> OLD: And there are F, S, X and Z, but they're rarely used so not worth
> explaining in
> a simple tutorial.
> NEW: And there are F, S, X and Z, but they're rarely used and not worth
> explaining in
> a simple tutorial.
David Manura <[EMAIL PROTECTED]> writes:
> AUTHOR seems rather more in the same boat as some usages of BUGS or
> MAINTENANCE
> (e.g.
> http://search.cpan.org/~abigail/Regexp-Common-2.118/lib/Regexp/Common.pm).
> This is where one looks to contact someone to ask technical questions,
> offer sugges
David Manura <[EMAIL PROTECTED]> writes:
> I think what is missing in perlpodtut is a high-level summary or clear
> statement of what POD is intended for and what it's scope and
> limitations are. There are multipurpose formatting languages like HTML,
> which can be used even for web application
COPYRIGHT and LICENSE do seem appropriate together This is where one
looks if one wants to copy, modify, or distribute the software.
AUTHOR seems rather more in the same boat as some usages of BUGS or
MAINTENANCE (e.g.
http://search.cpan.org/~abigail/Regexp-Common-2.118/lib/Regexp/Common.pm).
Juerd wrote:
David Manura skribis 2004-12-28 1:11 (-0500):
POD stands for Plain Old Documentation and is the formatting
language that the official Perl documentation and CPAN modules use.
Several translators exist for it, which can turn POD into manpages,
HTML, LaTeX, RTF, etc.
Recommen
Michael G Schwern skribis 2004-12-29 13:30 (-0500):
> The "Module::Name - One line module description" has been pretty standard
> stuff for a long time. No, MakeMaker's stuff shouldn't be changed at this
> point, its a simple convention so we can pull an abstract out of POD. The
> line length sh
On Wed, Dec 29, 2004 at 10:15:55AM -0800, Russ Allbery wrote:
> > They both need to be mentioned, because they are both important. The
> > copyright statement is not part of the licensing information and vice
> > versa. So choosing between COPYRIGHT and LICENSE is out of the question,
> > and this
Juerd <[EMAIL PROTECTED]> writes:
>>NAME - contains the module or script name, a dash and a short
>>description (the abstract).
>> How short? One line or sentence? One paragraph?
> I don't think any rules for this exist. I try to keep it within one
> line.
It has to be one line. That l
On Wed, Dec 29, 2004 at 10:47:58AM +0100, Juerd wrote:
> >NAME - contains the module or script name, a dash and a short
> >description (the abstract).
> > How short? One line or sentence? One paragraph?
>
> I don't think any rules for this exist. I try to keep it within one
> line.
>
> D
Juerd <[EMAIL PROTECTED]> writes:
> They both need to be mentioned, because they are both important. The
> copyright statement is not part of the licensing information and vice
> versa. So choosing between COPYRIGHT and LICENSE is out of the question,
> and this is why I didn't want "COPYRIGHT or
> > COPYRIGHT and LICENSE are now mentioned separately.
> This seems to be moving in a direction that no one else is going. Why
> did you choose to take this approach?
They both need to be mentioned, because they are both important. The
copyright statement is not part of the licensing informatio
David Manura skribis 2004-12-28 1:11 (-0500):
>POD stands for Plain Old Documentation and is the formatting
>language that the official Perl documentation and CPAN modules use.
>Several translators exist for it, which can turn POD into manpages,
>HTML, LaTeX, RTF, etc.
> Recommende
David Manura skribis 2004-12-28 23:57 (-0500):
> Why are "functions, methods and things" (i.e. "API") given in a head2
> section rather than a head1?
Because that is what perlfunc does*, because pod2man suggests that
DESCRIPTION should include "discussion of the program or functions",
because the
On Tue, Dec 28, 2004 at 11:57:44PM -0500, David Manura wrote:
> Why are "functions, methods and things" (i.e. "API") given in a head2
> section rather than a head1?
Because they're all subheadings of DESCRIPTION. Don't nit-pick too far
into it, its just a common convention and this tutorial shou
On Tue, Dec 28, 2004 at 01:11:57AM -0500, David Manura wrote:
> What about mentioning pod2html?
Because its a buggy throwback with a disasterous interface? If you're
going to mention a POD-to-HTML converter please mention something else.
--
Michael G Schwern [EMAIL PROTECTED] http://w
Why are "functions, methods and things" (i.e. "API") given in a head2
section rather than a head1?
First, the "API" of a module is quite a bit different in nature from its
"description." An API is formal, structured, and precise. A
description is more prose and intended to give big picture ex
I like it. A few comments though.
POD stands for Plain Old Documentation and is the formatting
language that the official Perl documentation and CPAN modules use.
Several translators exist for it, which can turn POD into manpages,
HTML, LaTeX, RTF, etc.
Recommended grammar improvement:
Juerd <[EMAIL PROTECTED]> writes:
> COPYRIGHT and LICENSE are now mentioned separately.
This seems to be moving in a direction that no one else is going. Why did
you choose to take this approach? I don't think COPYRIGHT makes a good
section in isolation; it will almost always be so short as to
Attached is the revised version of perlpodtut, based on your well
appreciated feedback. The second attachment is the diff with the
previous version.
I removed the derivation of SYNOPSIS. Not because I agree that it has no
place here, but because consistency would demand that more words are
explain
27 matches
Mail list logo
