# 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;
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
-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
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:
#
unless %include;
# Compress trailing blank lines.
- for (keys %include)
- {
- $include{$_} =~ s/\n+$//;
- $include{$_} .= "\n" unless /^NAME$/;
- }
+ for (keys %include) { $include{$_} =~ s/\n+$/\n/ }
}
else
{
# 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;
#
# 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+) +(.*)/)
$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
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;
projects / thirdparty / coreutils.git / commitdiff
