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
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
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 f
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 e
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).
on is a simple platform-independent documentation
tool for the computer language Perl.
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,
odules with long names need really short abstracts.
Anyway, this length should be mentioned in perlpodtut, I think.
Juerd
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
go
there. If it requires other packages, links to those packages should be
there. Etc.
> And see that part of current perlpodtut is:
> =item COPYRIGHT
> has the copyright statement. You can also put this in the AUTHOR
> section to avoid redundancy.
Yes, I'm advocati
short as to make for an odd-looking
> section.
You mean like NAME? AUTHOR? SEE ALSO? Short sections do not look odd.
And see that part of current perlpodtut is:
=item COPYRIGHT
has the copyright statement. You can also put this in the AUTHOR
section to avoid redundancy.
Juerd
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
;s, although
they are also head2's at times.
-david manura
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.
...
=item DESCRIPTION
contains a long description of what the module
s 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
explained, like abs
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
link to w3.org would come in handy?
> But I really only bring up E and E against E in the sense that
> if you're going to bring up any specific entities bring up gt and lt.
perlpod does mention E and E explicitly, even though they're
practically part of the E definition. You and pe
On Sun, Dec 26, 2004 at 12:19:44AM +0100, Juerd wrote:
> > Then I realized lots of competant programmers don't know anything about
> > HTML. Or perhaps they've only ever used WYSIWYG editors.
>
> I may have misassumed. Still, knowing that it's HTML-based is enough to
> know where to find the inf
On Sat, Dec 25, 2004 at 12:25:27AM +0100, Abigail wrote:
> On Fri, Dec 24, 2004 at 08:57:14PM +0100, Juerd wrote:
> >
> > I'm thinking of removing my email address entirely from all my modules,
> > because module documentation is too wide spread. Anyone with at least a
> > nanobrain can find out m
On Fri, Dec 24, 2004 at 10:56:09PM +0100, Juerd wrote:
> Different people learn in different ways. For many, including myself, it
> helps to see a name in one place and the same name used elsewhere. It
> makes it easier to realise that the same thing is discussed.
>
> Also, if I see where a word c
On Fri, Dec 24, 2004 at 01:23:59PM -0800, Russ Allbery wrote:
> > Most importantly, I think it's worth to note that the ordering of
> > sections doesn't matter as long as NAME's the first. I think discussing
> > this can be a waste of time.
>
> This is probably true; I don't think you need to go i
On Fri, Dec 24, 2004 at 08:57:14PM +0100, Juerd wrote:
> > > =head1 SYNOPSIS
> > >
> > > use My::Module;
> > > my $object = My::Module->new();
> > > print $object->as_string;
> > >
> > > This is called a I.
> > I would use a different example here for the code paragrap
David Nicol skribis 2004-12-24 21:45 (-0600):
> On Fri, 24 Dec 2004 22:56:09 +0100, Juerd <[EMAIL PROTECTED]> wrote:
> > * "see together"
> > And actually every single word that can be seen as Perl jargon.
> "synopsis" is not Perl jargon
I didn't imply that it was. If it were, then the best defini
On Fri, 24 Dec 2004 22:56:09 +0100, Juerd <[EMAIL PROTECTED]> wrote:
> * "see together"
> And actually every single word that can be seen as Perl jargon.
"synopsis" is not Perl jargon, it's a simple english word, a fancy way to
say "summary," and stating that it's Greek for "together, with the ey
> >We use the C<=head1> .. C<=head4> commands. (They are called I >paragraphs officially. They are paragraphs because they're separated from
> >the rest of the POD by blank lines.)
> I dont see sufficient value in explaining the official name.
I do, and think it's *VERY* important to include such
On Fri, Dec 24, 2004 at 08:57:14PM +0100, Juerd wrote:
>
> I'm thinking of removing my email address entirely from all my modules,
> because module documentation is too wide spread. Anyone with at least a
> nanobrain can find out many ways to contact me.
>
> As long as there's contact information
Juerd <[EMAIL PROTECTED]> writes:
> Google hit counts, with filetype:pod
>
> "head1 license" -"head1 license and copyright" 183
> "head1 copyright" -"head1 copyright and license" 4180
> "head1 copyright and license" 105
> "head1 license and copyright"
> This should be =head1 COPYRIGHT AND LICENSE to fit what's done
> elsewhere
Google hit counts, with filetype:pod
"head1 license" -"head1 license and copyright" 183
"head1 copyright" -"head1 copyright and license" 4180
"head1 copyright and license" 105
"head1 license and
in text".
You're right. Same is true for "a code font" (discussion of C<>). For
some reason, it was natural to me, but if I google for "a code font", I
find list of HTML tags (, , ) and perlpodtut itself :)
> > =head1 SYNOPSIS
> >
> >
Ronald J Kimball wrote:
>On Fri, Dec 24, 2004 at 11:12:05AM +0100, Juerd wrote:
>
>This looks like a very helpful tutorial. I just have a few nits... :)
>
yeay, with following addition(s)
>
>>=head2 Headings in POD
>>
>>Logical structure is important. So we use headings. There are four levels,
of the
> > object. This is mainly for debugging purposes.
1234 # Mail quotes
1234 # Standard indentation in perlpodtut
12 # Indentation for =head2
1234 # Indentation for =ove
On Fri, Dec 24, 2004 at 11:16:57AM -0800, Russ Allbery wrote:
> >> =head1 LICENSE
> >>
> >> This is released under the Artistic License. See L.
>
> > Since people like to cut & paste, this should probably be the standard
> > "same as Perl" wording plus a copyright notice.
>
> This should
Michael G Schwern <[EMAIL PROTECTED]> writes:
> On Fri, Dec 24, 2004 at 11:12:05AM +0100, Juerd wrote:
>> And there are F, S, X and Z, but they're rarely used so not worth
>> explaining in a simple tutorial.
> F<> is, I think, what you're supposed to use for URLs and email addresses
> and the lik
On Fri, Dec 24, 2004 at 11:12:05AM +0100, Juerd wrote:
> =head2 Code examples
>
> Indented paragraphs render as code, with indenting intact. It's that easy!
What does it mean for something to render as code? I think a reader will
better understand "with no extra formatting" or "as plain text".
Ronald J Kimball <[EMAIL PROTECTED]> writes:
> On Fri, Dec 24, 2004 at 11:12:05AM +0100, Juerd wrote:
>> =head2 Lists
>>
>> An example is much clearer than an explanation here.
>>
>> =head2 Methods
>>
>> =over 12
> I think that should be =over 4, since the example shows an indent of 4
On Fri, Dec 24, 2004 at 11:12:05AM +0100, Juerd wrote:
This looks like a very helpful tutorial. I just have a few nits... :)
> =head1 NAME
>
> perlpodtut - Plain Old Documentation in 5 minutes
>
> =head1 DESCRIPTION
>
> This short tutorial will teach you how to write d
2003-04-23, at
<http://perlmonks.org/?node_id=252477>, after publishing it at my own
site at <http://juerd.nl/perlpodtut> and having let #perlhelp and #perl
people read it and suggest ways to make it better.
In <http://perlmonks.org/?node=perlpodtut>, I asked the people at Pe
48 matches
Mail list logo
