Add explicit include syntax for prepending, replacing or appending to

generated output for a section

1 files changed, 82 insertions, 40 deletions

diff --git a/help2man.PL b/help2man.PL
index 55ce351..525deda 100755
--- a/help2man.PL
+++ b/help2man.PL
@@ -16,7 +16,7 @@ use 5.008;
 use Config;
 use Getopt::Long;
 
-my ($program, $version) = ('help2man', '1.42.1');
+my ($program, $version) = ('help2man', '1.43.1');
 
 my %opts;
 die "Usage: $0 [--quiet] [--stdout] [--with-gettext] [--name] [--version]\n"
@@ -241,18 +241,32 @@ configure_locale unless $encoding;
 # No substitutions for the remainder of the script:
 print OUT <<'!NO!SUBS!';
 my %include = ();
+my %replace = ();
 my %append = ();
+my %append_match = ();
 my @include = (); # retain order given in include file
 
 # Process include file (if given).  Format is:
 #
-#   [section name]
-#   verbatim text
+#   Optional initial text, ignored.  May include lines starting with `-'
+#   which are processed as options.
 #
-# or
+#   [section]
+#   Verbatim text to be included in the named section.  By default at
+#   the start, but in the case of `name' and `synopsis' the content
+#   will replace the autogenerated contents.
+#
+#   [<section]
+#   Verbatim text to be inserted at the start of the named section.
+#
+#   [=section]
+#   Verbatim text to replace the named section.
+#
+#   [>section]
+#   Verbatim text to be appended to the end of the named section.
 #
 #   /pattern/
-#   verbatim text
+#   Verbatim text for inclusion below a paragraph matching `pattern'.
 #
 
 while (@opt_include)
@@ -264,7 +278,7 @@ while (@opt_include)
 	unless open INC, $inc;
 
     my $key;
-    my $hash = \%include;
+    my $hash;
 
     while (<INC>)
     {
@@ -279,7 +293,25 @@ while (@opt_include)
 	    $key =~ s/^\s+//;
 	    $key =~ s/\s+$//;
 	    $hash = \%include;
-	    push @include, $key unless $include{$key};
+	    # Handle explicit [<section], [=section] and [>section]
+	    if ($key =~ s/^([<>=])\s*//)
+	    {
+		if    ($1 eq '>') { $hash = \%append; }
+		elsif ($1 eq '=') { $hash = \%replace; }
+	    }
+	    # NAME/SYNOPSIS replace by default
+	    elsif ($key eq _('NAME') or $key eq _('SYNOPSIS'))
+	    {
+		$hash = \%replace;
+	    }
+	    else
+	    {
+		$hash = \%include;
+	    }
+
+	    push @include, $key
+		unless $include{$key} or $replace{$key} or $append{$key};
+
 	    next;
 	}
 
@@ -296,7 +328,7 @@ while (@opt_include)
 		die "$inc:$.:$@";
 	    }
 
-	    $hash = \%append;
+	    $hash = \%append_match;
 	    next;
 	}
 
@@ -315,18 +347,17 @@ while (@opt_include)
 	    next;
 	}
 
-	$hash->{$key} ||= '';
 	$hash->{$key} .= $_;
     }
 
     close INC;
 
     kark N_("%s: no valid information found in `%s'"), $this_program, $inc
-    	unless $key;
+	unless $key;
 }
 
 # Compress trailing blank lines.
-for my $hash (\(%include, %append))
+for my $hash (\(%include, %replace, %append, %append_match))
 {
     for (keys %$hash) { $hash->{$_} =~ s/\n+$/\n/ }
 }
@@ -347,7 +378,7 @@ my $version;
 if ($opt_output)
 {
     unlink $opt_output or kark N_("%s: can't unlink %s (%s)"),
-    	$this_program, $opt_output, $! if -e $opt_output;
+	$this_program, $opt_output, $! if -e $opt_output;
 
     open STDOUT, ">$opt_output"
 	or kark N_("%s: can't create %s (%s)"), $this_program, $opt_output, $!;
@@ -390,13 +421,15 @@ $opt_no_info = 1 if $program eq 'info';
 # Translators: "NAME", "SYNOPSIS" and other one or two word strings in all
 # upper case are manual page section headings.  The man(1) manual page in your
 # language, if available should provide the conventional translations.
-for ($include{_('NAME')})
+if ($opt_name)
 {
-    if ($opt_name) # --name overrides --include contents.
-    {
-	$_ = "$program \\- $opt_name\n";
-    }
-    elsif ($_) # Use first name given as $program
+    # --name overrides --include contents.
+    $replace{_('NAME')} = "$program \\- $opt_name\n";
+}
+
+for ($replace{_('NAME')} || ($include{_('NAME')} ||= ''))
+{
+    if ($_) # Use first name given as $program
     {
 	$program = $1 if /^([^\s,]+)(?:,?\s*[^\s,\\-]+)*\s+\\?-/;
     }
@@ -462,7 +495,7 @@ if ($help_text =~ s/^($PAT_USAGE):( +(\S+))(.*)((?:\n(?: {6}\1| *($PAT_USAGE_CON
 	$synopsis .= "$_\n";
     }
 
-    $include{_('SYNOPSIS')} ||= $synopsis;
+    $include{_('SYNOPSIS')} .= $synopsis;
 }
 
 # Process text, initial section is DESCRIPTION.
@@ -491,13 +524,13 @@ s/\\/\x82/g;
 # "(?:[\\w-]+ +)?" in the bug reporting pattern is used to indicate an
 # optional word, so that either "Report bugs" or "Report _program_ bugs" will
 # be matched.
-my $PAT_BUGS		= _('Report +(?:[\w-]+ +)?bugs|Email +bug +reports +to');
-my $PAT_AUTHOR		= _('Written +by');
-my $PAT_OPTIONS		= _('Options');
-my $PAT_ENVIRONMENT	= _('Environment');
-my $PAT_FILES		= _('Files');
-my $PAT_EXAMPLES	= _('Examples');
-my $PAT_FREE_SOFTWARE	= _('This +is +free +software');
+my $PAT_BUGS          = _('Report +(?:[\w-]+ +)?bugs|Email +bug +reports +to');
+my $PAT_AUTHOR        = _('Written +by');
+my $PAT_OPTIONS       = _('Options');
+my $PAT_ENVIRONMENT   = _('Environment');
+my $PAT_FILES         = _('Files');
+my $PAT_EXAMPLES      = _('Examples');
+my $PAT_FREE_SOFTWARE = _('This +is +free +software');
 
 # Start a new paragraph (if required) for these.
 s/([^\n])\n($PAT_BUGS|$PAT_AUTHOR) /$1\n\n$2 /og;
@@ -555,7 +588,6 @@ while (length)
 	my $indent = $1;
 	my $prefix = $2;
 	my $break = '.IP';
-	$include{$sect} ||= '';
 	while (s/^$indent\Q$prefix\E(\S.*)\n*//)
 	{
 	    $include{$sect} .= "$break\n\\f(CW$prefix$1\\fR\n";
@@ -566,12 +598,11 @@ while (length)
     }
 
     my $matched = '';
-    $include{$sect} ||= '';
 
     # Sub-sections have a trailing colon and the second line indented.
     if (s/^(\S.*:) *\n / /)
     {
-	$matched .= $& if %append;
+	$matched .= $& if %append_match;
 	$include{$sect} .= qq(.SS "$1"\n);
     }
 
@@ -581,7 +612,7 @@ while (length)
     # Option with description.
     if (s/^( {1,10}([+-]\S.*?))(?:(  +(?!-))|\n( {20,}))(\S.*)\n//)
     {
-	$matched .= $& if %append;
+	$matched .= $& if %append_match;
 	$indent = length ($4 || "$1$3");
 	$content = ".TP\n\x84$2\n\x84$5\n";
 	unless ($4)
@@ -594,7 +625,7 @@ while (length)
     # Option without description.
     elsif (s/^ {1,10}([+-]\S.*)\n//)
     {
-	$matched .= $& if %append;
+	$matched .= $& if %append_match;
 	$content = ".HP\n\x84$1\n";
 	$indent = 80; # not continued
     }
@@ -602,7 +633,7 @@ while (length)
     # Indented paragraph with tag.
     elsif (s/^( +(\S.*?)  +)(\S.*)\n//)
     {
-	$matched .= $& if %append;
+	$matched .= $& if %append_match;
 	$indent = length $1;
 	$content = ".TP\n\x84$2\n\x84$3\n";
     }
@@ -610,7 +641,7 @@ while (length)
     # Indented paragraph.
     elsif (s/^( +)(\S.*)\n//)
     {
-	$matched .= $& if %append;
+	$matched .= $& if %append_match;
 	$indent = length $1;
 	$content = ".IP\n\x84$2\n";
     }
@@ -619,7 +650,7 @@ while (length)
     else
     {
 	s/(.*)\n//;
-	$matched .= $& if %append;
+	$matched .= $& if %append_match;
 	$content = ".PP\n" if $include{$sect};
 	$content .= "$1\n";
     }
@@ -627,7 +658,7 @@ while (length)
     # Append continuations.
     while ($indent ? s/^ {$indent}(\S.*)\n// : s/^(\S.*)\n//)
     {
-	$matched .= $& if %append;
+	$matched .= $& if %append_match;
 	$content .= "\x84$1\n";
     }
 
@@ -679,14 +710,14 @@ while (length)
     }
 
     # Check if matched paragraph contains /pat/.
-    if (%append)
+    if (%append_match)
     {
-	for my $pat (keys %append)
+	for my $pat (keys %append_match)
 	{
 	    if ($matched =~ $pat)
 	    {
-		$content .= ".PP\n" unless $append{$pat} =~ /^\./;
-		$content .= $append{$pat};
+		$content .= ".PP\n" unless $append_match{$pat} =~ /^\./;
+		$content .= $append_match{$pat};
 	    }
 	}
     }
@@ -700,7 +731,6 @@ unless ($opt_no_info)
     my $info_page = $opt_info || $program;
 
     $sect = _('SEE ALSO');
-    $include{$sect} ||= '';
     $include{$sect} .= ".PP\n" if $include{$sect};
     $include{$sect} .= sprintf _(<<'EOT'), $program, $program, $info_page;
 The full documentation for
@@ -717,6 +747,18 @@ should give you access to the complete manual.
 EOT
 }
 
+# Append additional text.
+while (my ($sect, $text) = each %append)
+{
+    $include{$sect} .= $append{$sect};
+}
+
+# Replace sections.
+while (my ($sect, $text) = each %replace)
+{
+    $include{$sect} = $replace{$sect};
+}
+
 # Output header.
 print <<EOT;
 .\\" DO NOT MODIFY THIS FILE!  It was generated by $this_program $this_version.