From: Jarkko Hietaniemi <jhi@iki.fi>
Date: Mon, 23 Apr 2001 21:29:24 +0000 (+0000)
Subject: Synchronize h2xs and pod2man some more on the documentation
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=09c48e649033e5a9b2303aae4df65dd5ad6b6d6c;p=p5sagit%2Fp5-mst-13.2.git

Synchronize h2xs and pod2man some more on the documentation
templates they propose.

p4raw-id: //depot/perl@9796
---

diff --git a/pod/pod2man.PL b/pod/pod2man.PL
index f320a3c..7a50fc5 100644
--- a/pod/pod2man.PL
+++ b/pod/pod2man.PL
@@ -423,6 +423,8 @@ LE<lt>E<gt>, but other things in this section probably should be when
 appropriate.  You may need to use the C<LE<lt>...|...E<gt>> syntax to keep
 B<pod2man> and B<pod2text> from being too verbose; see perlpod(1).
 
+If the package has a mailing list, include a URL here.
+
 If the package has a web site, include a URL here.
 
 =item AUTHOR
@@ -433,10 +435,28 @@ so that users have a way of contacting you is a good idea.  Remember that
 program documentation tends to roam the wild for far longer than you expect
 and pick an e-mail address that's likely to last if possible.
 
+=item COPYRIGHT AND LICENSE
+
+For copyright
+
+  Copyright YEAR(s) by YOUR NAME(s)
+
+(No, (C) is not needed.  No, "all rights reserved" is not needed.)
+
+For licensing the easiest way is to use the same licensing as Perl itself:
+
+  This library is free software; you can redistribute it and/or modify
+  it under the same terms as Perl itself. 
+
+This makes it easy for people to use your module with Perl.  Note that
+this licensing is neither an endorsement or a requirement, you are of
+course free to choose any licensing.
+
 =item HISTORY
 
-Programs derived from other sources sometimes have this, or you might keep a
-modification log here.
+Programs derived from other sources sometimes have this, or you might
+keep a modification log here.  If the log gets overly long or detailed,
+consider maintaining it in a separate file, though.
 
 =back
 
diff --git a/utils/h2xs.PL b/utils/h2xs.PL
index d38b676..1b4f387 100644
--- a/utils/h2xs.PL
+++ b/utils/h2xs.PL
@@ -1059,25 +1059,29 @@ my $pod = <<"END" unless $opt_P;
 #
 #Blah blah blah.
 $exp_doc$meth_doc$revhist
-#=head1 AUTHOR
 #
-#$author, E<lt>${email}E<gt>
+#=head1 SEE ALSO
 #
-#=head1 MAILING LIST
+#Mention other useful documentation such as the documentation of
+#related modules or operating system documentation (such as man pages
+#in UNIX), or any relevant external documentation such as RFCs or
+#standards.
 #
 #If you have a mailing list set up for your module, mention it here.
 #
+#If you have a web site set up for your module, mention it here.
+#
+#=head1 AUTHOR
+#
+#$author, E<lt>${email}E<gt>
+#
 #=head1 COPYRIGHT AND LICENSE
 #
-#Copyright (C) YEAR YOURNAMEHERE
+#Copyright YEAR(S) by YOUR NAME(s)
 #
 #This library is free software; you can redistribute it and/or modify
 #it under the same terms as Perl itself. 
 #
-#=head1 SEE ALSO
-#
-#L<perl>.
-#
 #=cut
 END