From fb829c2cd1c10f4e0213f05733d6178555c75f3a Mon Sep 17 00:00:00 2001
From: Jim Meyering <jim@meyering.net>
Date: Sat, 23 Oct 1999 13:30:28 +0000
Subject: import version 1.015

---
 man/help2man | 326 ++++++++++++++++++++++++++++++++---------------------------
 1 file changed, 178 insertions(+), 148 deletions(-)

(limited to 'man')

diff --git a/man/help2man b/man/help2man
index cc0f5cf5d..b05b74e02 100755
--- a/man/help2man
+++ b/man/help2man
@@ -18,6 +18,7 @@
 # Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 
 # Written by Brendan O'Dea <bod@compusol.com.au>
+# Available from ftp://ftp.gnu.org/gnu/help2man/
 
 use 5.004;
 use strict;
@@ -26,7 +27,7 @@ use Text::Tabs qw(expand);
 use POSIX qw(strftime setlocale LC_TIME);
 
 my $this_program = 'help2man';
-my $this_version = '1.013';
+my $this_version = '1.015';
 my $version_info = <<EOT;
 $this_program $this_version
 
@@ -49,7 +50,7 @@ Usage: $this_program [OPTION]... EXECUTABLE
  -o, --output=FILE       send output to `FILE'
  -N, --no-info           suppress pointer to Texinfo manual
      --help              print this help, then exit
-     --version           print $this_program program version number, then exit
+     --version           print version number, then exit
 
 EXECUTABLE should accept `--help' and `--version' options.
 EOT
@@ -73,7 +74,7 @@ GetOptions (
 die $help_info unless @ARGV == 1;
 
 my %include = ();
-my @include = (); # to retain order
+my @include = (); # retain order given in include file
 
 # Process include file (if given).  Format is:
 #
@@ -111,11 +112,7 @@ if ($include or $opt_include)
 	    unless %include;
 
 	# Compress trailing blank lines.
-	for (keys %include)
-	{
-	    $include{$_} =~ s/\n+$//;
-	    $include{$_} .= "\n" unless /^NAME$/;
-	}
+	for (keys %include) { $include{$_} =~ s/\n+$/\n/ }
     }
     else
     {
@@ -126,17 +123,14 @@ if ($include or $opt_include)
 # Turn off localisation of executable's ouput.
 @ENV{qw(LANGUAGE LANG LC_ALL)} = ('C') x 3;
 
-# Turn off localisation of date (for strftime)
+# Turn off localisation of date (for strftime).
 setlocale LC_TIME, 'C';
 
-# Expand tabs, strip trailing spaces and break into paragraphs
-sub paragraphs { split /\n\n+/, join '', expand @_ }
-
-# Grab help and version paragraphs from executable
-my @help = paragraphs `$ARGV[0] --help 2>/dev/null`
+# Grab help and version info from executable.
+my $help_text = join '', map { expand $_ } `$ARGV[0] --help 2>/dev/null`
     or die "$this_program: can't get `--help' info from $ARGV[0]\n";
 
-my @version = paragraphs `$ARGV[0] --version 2>/dev/null`
+my $version_text = join '', map { expand $_ } `$ARGV[0] --version 2>/dev/null`
     or die "$this_program: can't get `--version' info from $ARGV[0]\n";
 
 my $date = strftime "%B %Y", localtime;
@@ -165,7 +159,7 @@ if ($opt_output)
 #
 # and seperated from any copyright/author details by a blank line.
 
-$_ = shift @version;
+($_, $version_text) = split /\n+/, $version_text, 2;
 
 if (/^(\S+) +\(((?:GNU|Free) +[^)]+)\) +(.*)/ or
     /^(\S+) +- *((?:GNU|Free) +\S+) +(.*)/)
@@ -187,163 +181,193 @@ else
 
 $program =~ s!.*/!!;
 
-# no info for `info' itself
+# No info for `info' itself.
 $opt_no_info = 1 if $program eq 'info';
 
-# --name overrides --include contents
-$include{NAME} = "$program \\- $opt_name" if $opt_name;
+# --name overrides --include contents.
+$include{NAME} = "$program \\- $opt_name\n" if $opt_name;
 
-# Default (useless) NAME paragraph
-$include{NAME} ||= "$program \\- manual page for $program $version";
+# Default (useless) NAME paragraph.
+$include{NAME} ||= "$program \\- manual page for $program $version\n";
 
 # Man pages traditionally have the page title in caps.
 my $PROGRAM = uc $program;
 
-# Header.
-print <<EOT;
-.\\" DO NOT MODIFY THIS FILE!  It was generated by $this_program $this_version.
-.TH $PROGRAM "$section" "$date" "$package $version" FSF
-.SH NAME
-$include{NAME}
-EOT
+# Extract usage clause(s) [if any] for SYNOPSIS.
+if ($help_text =~ s/^Usage: +(\S.*)(\n *or: +\S.*)*//m)
+{
+    my @syn = $1;
+
+    if ($_ = $2)
+    {
+	for (split /\n/) { push @syn, $1 if /or: +(\S.*)/ }
+    }
+
+    my $synopsis = '';
+    for (@syn)
+    {
+	$synopsis .= ".br\n" if $synopsis;
+	s/(\S+) *//;
+	$synopsis .= ".B $1\n";
+	s/\s+$//;
+	s/(([][]|\.\.+)+)/\\fR$1\\fI/g;
+	s/^/\\fI/ unless s/^\\fR//;
+	$_ .= '\fR';
+	s/(\\fI)( *)/$2$1/g;
+	s/\\fI\\fR//g;
+	s/^\\fR//;
+	s/\\fI$//;
+	s/^\./\\&./;
+
+	$synopsis .= "$_\n";
+    }
+
+    $include{SYNOPSIS} ||= $synopsis;
+}
+
+# Process text, initial section is DESCRIPTION.
+my $sect = 'DESCRIPTION';
+$_ = "$help_text\n\n$version_text";
+
+# Normalise paragraph breaks.
+s/^\n+//;
+s/\n*$/\n/;
+s/\n\n+/\n\n/g;
 
-my $break;
-my $accumulate = 1;
-my @description = ();
+# Temporarily exchange leading dots and backslashes for tokens.
+s/^\./\x80/mg;
+s/\\/\x81/g;
 
 sub convert_option;
 
-# Output converted --help information.
-for (@help)
+while (length)
 {
-    chomp;
+    # Convert some standard paragraph names.
+    if (s/^(Options|Examples): *\n//)
+    {
+	$sect = uc $1;
+	next;
+    }
 
-    if (s/^Usage: +\S+ +(.*)\n?//)
+    # Copyright section
+    if (/^Copyright [\(\xa9]/)
     {
-	# Turn the usage clause into a synopsis.
-	my $synopsis = '';
-
-	do {
-	    my $syn = $1;
-	    $syn =~ s/(([][]|\.\.+)+)/\\fR$1\\fI/g;
-	    $syn =~ s/^/\\fI/ unless $syn =~ s/^\\fR//;
-	    $syn .= '\fR';
-	    $syn =~ s/\\fI( *)\\fR/$1/g;
-
-	    $synopsis .= ".br\n" unless $accumulate;
-	    $synopsis .= ".B $program\n";
-	    $synopsis .= "$syn\n";
-	    $accumulate = 0;
-	} while s/^(?:Usage| *or): +\S+ +(.*)\n?//;
-
-	# Include file overrides SYNOPSIS.
-	print ".SH SYNOPSIS\n", $include{SYNOPSIS} || $synopsis;
-
-	# Dump any accumulated description text.
-	print ".SH DESCRIPTION\n";
-	print @description;
-
-	# Add additional description text from include file.
-	if ($include{DESCRIPTION})
+	$sect = 'COPYRIGHT';
+	$include{$sect} ||= '';
+	$include{$sect} .= ".PP\n" if $include{$sect};
+
+	my $copy;
+	($copy, $_) = split /\n\n/, $_, 2;
+
+	for ($copy)
 	{
-	    print ".PP\n" unless $include{DESCRIPTION} =~ /^\..P/;
-	    print $include{DESCRIPTION};
+	    # Add back newline
+	    s/\n*$/\n/;
+
+	    # Convert iso9959-1 copyright symbol or (c) to nroff
+	    # character.
+	    s/^Copyright (?:\xa9|\([Cc]\))/Copyright \\(co/mg;
+
+	    # Insert line breaks before additional copyright messages
+	    # and the disclaimer.
+	    s/(.)\n(Copyright |This is free software)/$1\n.br\n$2/g;
+
+	    # Join hyphenated lines.
+	    s/([A-Za-z])-\n */$1/g;
 	}
 
-	$break = 1;
-	next unless $_;
+	$include{$sect} .= $copy;
+	$_ ||= '';
+	next;
     }
 
-    # Accumulate text if the synopsis has not been produced yet.
-    if ($accumulate)
+    # Catch bug report text.
+    if (/^Report bugs |^Email bug reports to /)
     {
-	push @description, ".PP\n" if @description;
-	push @description, "$_\n";
-	next;
+	$sect = 'REPORTING BUGS';
     }
 
-    # Convert some standard paragraph names
-    if (s/^(Options|Examples): *\n//)
+    # Author section.
+    elsif (/^Written +by/)
     {
-	print qq(.SH \U$1\n);
-	$break = '';
-	next unless length;
+	$sect = 'AUTHOR';
     }
 
-    # Catch bug report text.
-    if (/^Report bugs |^Email bug reports to /)
+    # Examples, indicated by an indented leading $, % or > are
+    # rendered in a constant width font.
+    if (/^( +)([\$\%>] )\S/)
     {
-	print qq(.SH "REPORTING BUGS"\n$_\n);
-	$break = '';
+	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";
+	    $break = '.br';
+	}
+
 	next;
     }
 
-    # Option subsections have second line indented.
-    if (s/^(\S.*)\n / /)
+    $include{$sect} ||= '';
+    # Sub-sections have a trailing colon and the second line indented.
+    if (s/^(\S.*:) *\n / /)
     {
-	print qq(.SS "$1"\n);
-	$break = '';
+	$include{$sect} .= qq(.SS "$1"\n);
     }
 
-    my $output = '';
-    while (length)
-    {
-	my $indent = 0;
+    my $indent = 0;
+    my $content = '';
 
-	# Tagged paragraph
-	if (s/^( +(\S.*?)  +)(\S.*)\n?//)
-	{
-	    $indent = length $1;
-	    $output .= ".TP\n$2\n$3\n";
-	    $break = 1;
-	}
-
-	# Indented paragraph
-	elsif (s/^( +)(\S.*)\n?//)
-	{
-	    $indent = length $1;
-	    $output .= ".IP\n$2\n";
-	    $break = 1;
-	}
+    # Tagged paragraph.
+    if (s/^( +(\S.*?)  +)(\S.*)\n//)
+    {
+	$indent = length $1;
+	$content = ".TP\n\x82$2\n\x82$3\n";
+    }
 
-	# Left justified paragraph
-	else
-	{
-	    s/(.*)\n?//;
-	    $output .= ".PP\n" if $break;
-	    $output .= "$1\n";
-	    $break = 1;
-	}
+    # Indented paragraph.
+    elsif (s/^( +)(\S.*)\n//)
+    {
+	$indent = length $1;
+	$content .= ".IP\n\x82$2\n";
+    }
 
-	# Continuations
-	$output .= "$1\n" while s/^ {$indent}(\S.*)\n?//;
+    # Left justified paragraph.
+    else
+    {
+	s/(.*)\n//;
+	$content = ".PP\n" if $include{$sect};
+	$content .= "$1\n";
     }
 
-    $_ = $output;
+    # Append continuations.
+    $content .= "$1\n" while s/^ {$indent}(\S.*)\n//;
 
-    # Escape backslashes.
-    s/\\/\\e/g;
+    # Move to next paragraph.
+    s/^\n+//;
 
-    # Convert options.
-    s/(^| )(-[][\w=-]+)/$1 . convert_option $2/mge;
-    print;
-}
+    for ($content)
+    {
+	# Leading dot protection.
+	s/\x82\./\x80/g;
+	s/\x82//g;
 
-# Print any include items other than the ones we have already dealt
-# with.
-for (@include)
-{
-    print qq(.SH "$_"\n$include{$_})
-	unless /^(NAME|SYNOPSIS|DESCRIPTION|SEE ALSO)$/;
+	# Convert options.
+	s/(^| )(-[][\w=-]+)/$1 . convert_option $2/mge;
+    }
+
+    $include{$sect} .= $content;
 }
 
 # Refer to the real documentation.
-if ($include{'SEE ALSO'} or !$opt_no_info)
+unless ($opt_no_info)
 {
-    print qq(.SH "SEE ALSO"\n);
-    print $include{'SEE ALSO'}, ".PP\n" if $include{'SEE ALSO'};
-
-    print <<EOT unless $opt_no_info;
+    $sect = 'SEE ALSO';
+    $include{$sect} ||= '';
+    $include{$sect} .= ".PP\n" if $include{$sect};
+    $include{$sect} .= <<EOT;
 The full documentation for
 .B $program
 is maintained as a Texinfo manual.  If the
@@ -358,27 +382,33 @@ should give you access to the complete manual.
 EOT
 }
 
-# Output converted --version information.
-for (@version)
-{
-    chomp;
-
-    # Join hyphenated lines.
-    s/([A-Za-z])-\n */$1/g;
-
-    # Convert copyright symbol or (c) to nroff character.
-    s/Copyright +(?:\xa9|\([Cc]\))/Copyright \\(co/g;
-
-    # Insert appropriate headings for copyright and author.
-    if    (/^Copyright \\/) { print ".SH COPYRIGHT\n" }
-    elsif (/^Written +by/)  { print ".SH AUTHOR\n" }
-    else		    { print ".PP\n"; }
+# Output header.
+print <<EOT;
+.\\" DO NOT MODIFY THIS FILE!  It was generated by $this_program $this_version.
+.TH $PROGRAM "$section" "$date" "$package $version" FSF
+EOT
 
-    # Insert line breaks before additional copyright messages and the
-    # disclaimer.
-    s/(.)\n(Copyright |This is free software)/$1\n.br\n$2/g;
+# Section ordering.
+my @pre = qw(NAME SYNOPSIS DESCRIPTION OPTIONS EXAMPLES);
+my @post = ('AUTHOR', 'REPORTING BUGS', 'COPYRIGHT', 'SEE ALSO');
+my $filter = join '|', @pre, @post;
 
-    print "$_\n";
+# Output content.
+for (@pre, (grep ! /^($filter)$/o, @include), @post)
+{
+    if ($include{$_})
+    {
+	my $quote = /\W/ ? '"' : '';
+	print ".SH $quote$_$quote\n";
+	
+	for ($include{$_})
+	{
+	    # Replace leading dot an backslash tokens.
+	    s/\x80/\\&./g;
+	    s/\x81/\\e/g;
+	    print;
+	}
+    }
 }
 
 exit;
-- 
cgit v1.2.3-54-g00ecf