develooper Front page | perl.perl5.porters | Postings from December 2004

Re: perlpodtut

Thread Previous | Thread Next
From:
Russ Allbery
Date:
December 24, 2004 13:24
Subject:
Re: perlpodtut
Message ID:
87wtv72xw0.fsf@windlord.stanford.edu
Juerd <juerd@convolution.nl> 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"                        2
> 
> I don't think we should make it COPYRIGHT AND LICENSE.

Well, that's what was picked in the last discussion we had of this.  I
don't mind LEGAL or LICENSE, but please note that COPYRIGHT is incorrect.
It's not just the copyright; it's also the license, which is something
separate.

> In practice, "SEE ALSO" is almost always the last section, pod2man.pod
> puts it before AUTHOR even.

SEE ALSO is the third to the last section; AUTHOR is second to last and
COPYRIGHT AND LICENSE is the last section.  (I'm the maintainer of
pod2man.)  There was some discussion of section ordering when we came up
with the original ordering.  I'm happy to make changes if people think
another order makes more sense, but it is rather nice to have a consistent
order.

> 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 into an extended
discussion of it.  But it would be nice for the order in Perl's own
documentation to match the recommended order in pod2man, one way or the
other.

-- 
Russ Allbery (rra@stanford.edu)             <http://www.eyrie.org/~eagle/>

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About