From dcd4cc178269c9c021a85e9aa7fe1684030cbb62 Mon Sep 17 00:00:00 2001
From: Guillem Jover <guillem@hadrons.org>
Date: Thu, 2 Apr 2015 19:47:08 +0200
Status: applied
Subject: [PATCH] Clarify documentation for options related to the .TH macro

Mention that these options affect the .TH macro. Add missing arguments
for the --release and --section options. Mark an macro sets as a code.
Document the effect of not passing an argument to --release. Clarify
what value --date is setting.

Signed-off-by: Guillem Jover <guillem@hadrons.org>
---
 bin/pod2man    | 37 +++++++++++++++++++------------------
 lib/Pod/Man.pm | 36 ++++++++++++++++++------------------
 2 files changed, 37 insertions(+), 36 deletions(-)

diff --git a/bin/pod2man b/bin/pod2man
index 3980fa1..f4fdd62 100755
--- a/bin/pod2man
+++ b/bin/pod2man
@@ -136,14 +136,14 @@ complete information.
 
 =item B<-c> I<string>, B<--center>=I<string>
 
-Sets the centered page header to I<string>.  The default is "User
-Contributed Perl Documentation", but also see B<--official> below.
+Sets the centered page header for the C<.TH> macro to I<string>.  The default
+is "User Contributed Perl Documentation", but also see B<--official> below.
 
 =item B<-d> I<string>, B<--date>=I<string>
 
-Set the left-hand footer string to this value.  By default, the modification
-date of the input file will be used, or the current date if input comes from
-C<STDIN>.
+Set the left-hand footer string for the C<.TH> macro to I<string>.  By default,
+the modification date of the input file will be used, or the current date if
+input comes from C<STDIN>.
 
 =item B<--errors>=I<style>
 
@@ -191,12 +191,12 @@ Accepted for backward compatibility; this option no longer does anything.
 
 =item B<-n> I<name>, B<--name>=I<name>
 
-Set the name of the manual page to I<name>.  Without this option, the manual
-name is set to the uppercased base name of the file being converted unless
-the manual section is 3, in which case the path is parsed to see if it is a
-Perl module path.  If it is, a path like C<.../lib/Pod/Man.pm> is converted
-into a name like C<Pod::Man>.  This option, if given, overrides any
-automatic determination of the name.
+Set the name of the manual page for the C<.TH> macro to I<name>.  Without this
+option, the manual name is set to the uppercased base name of the file being
+converted unless the manual section is 3, in which case the path is parsed to
+see if it is a Perl module path.  If it is, a path like C<.../lib/Pod/Man.pm>
+is converted into a name like C<Pod::Man>.  This option, if given, overrides
+any automatic determination of the name.
 
 Note that this option is probably not useful when converting multiple POD
 files at once.  The convention for Unix man pages for commands is for the
@@ -239,15 +239,16 @@ I<quotes> may also be set to the special value C<none>, in which case no
 quote marks are added around CE<lt>> text (but the font is still changed for
 troff output).
 
-=item B<-r>, B<--release>
+=item B<-r> [I<version>], B<--release>[=I<version>]
 
-Set the centered footer.  By default, this is the version of Perl you run
-B<pod2man> under.  Note that some system an macro sets assume that the
-centered footer will be a modification date and will prepend something like
-"Last modified: "; if this is the case, you may want to set B<--release> to
-the last modified date and B<--date> to the version number.
+Set the centered footer for the C<.TH> macro.  By default, this is the version
+of Perl you run B<pod2man> under.  If I<version> is not specified then it will
+default to the empty string.  Note that some system C<an> macro sets assume
+that the centered footer will be a modification date and will prepend
+something like "Last modified: "; if this is the case, you may want to
+set B<--release> to the last modified date and B<--date> to the version number.
 
-=item B<-s>, B<--section>
+=item B<-s> I<string>, B<--section>=I<string>
 
 Set the section for the C<.TH> macro.  The standard section numbering
 convention is to use 1 for user commands, 2 for system calls, 3 for
diff --git a/lib/Pod/Man.pm b/lib/Pod/Man.pm
index 5c0e69c..75df118 100644
--- a/lib/Pod/Man.pm
+++ b/lib/Pod/Man.pm
@@ -1654,16 +1654,16 @@ argument.
 
 =item center
 
-Sets the centered page header to use instead of "User Contributed Perl
-Documentation".
+Sets the centered page header to use for the C<.TH> macro instead of
+"User Contributed Perl Documentation".
 
 =item date
 
-Sets the left-hand footer.  If this option is not set, the contents of the
-environment variable POD_MAN_DATE, if set, will be used.  Failing that,
-the modification date of the input file will be used, or the current time
-if stat() can't find that file (which will be the case if the input is
-from C<STDIN>).  If obtained from the file modification date or the
+Sets the left-hand footer for the C<.TH> macro.  If this option is not set,
+the contents of the environment variable POD_MAN_DATE, if set, will be used.
+Failing that, the modification date of the input file will be used, or the
+current time if stat() can't find that file (which will be the case if the
+input is from C<STDIN>).  If obtained from the file modification date or the
 current time, he date will be formatted as C<YYYY-MM-DD>.
 
 =item errors
@@ -1702,12 +1702,12 @@ for B<troff> output.
 
 =item name
 
-Set the name of the manual page.  Without this option, the manual name is
-set to the uppercased base name of the file being converted unless the
-manual section is 3, in which case the path is parsed to see if it is a Perl
-module path.  If it is, a path like C<.../lib/Pod/Man.pm> is converted into
-a name like C<Pod::Man>.  This option, if given, overrides any automatic
-determination of the name.
+Set the name of the manual page for the C<.TH> macro.  Without this option,
+the manual name is set to the uppercased base name of the file being converted
+unless the manual section is 3, in which case the path is parsed to see if
+it is a Perl module path.  If it is, a path like C<.../lib/Pod/Man.pm> is
+converted into a name like C<Pod::Man>.  This option, if given, overrides
+any automatic determination of the name.
 
 If generating a manual page from standard input, this option is required,
 since there's otherwise no way for Pod::Man to know what to use for the
@@ -1743,11 +1743,11 @@ output).
 
 =item release
 
-Set the centered footer.  By default, this is the version of Perl you run
-Pod::Man under.  Note that some system an macro sets assume that the
-centered footer will be a modification date and will prepend something like
-"Last modified: "; if this is the case, you may want to set C<release> to
-the last modified date and C<date> to the version number.
+Set the centered footer for the C<.TH> macro.  By default, this is the
+version of Perl you run Pod::Man under.  Note that some system an macro sets
+assume that the centered footer will be a modification date and will prepend
+something like "Last modified: "; if this is the case, you may want to set
+C<release> to the last modified date and C<date> to the version number.
 
 =item section
 
-- 
2.2.1.209.g41e5f3a