Permalink
Fetching contributors…
Cannot retrieve contributors at this time
383 lines (307 sloc) 9.2 KB
#!/usr/bin/perl -w
# Generate a short man page from --help and --version output.
# Copyright © 1997, 98 Free Software Foundation, Inc.
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software Foundation,
# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
# Written by Brendan O'Dea <bod@compusol.com.au>
# and François Pinard <pinard@IRO.UMontreal.CA>
require 5.003;
use strict;
use Getopt::Long;
use POSIX qw(strftime setlocale LC_TIME);
my $RCS_Id = '$Id: help2man.PL,v 1.5.1.3 1998/10/20 10:44:46 bod Exp $';
my $this_program = 'help2man';
my $this_version = '0.0';
if ($RCS_Id =~ /\$Id:\s+(\S+)\s+(\S+)/)
{
$this_version = $2;
($this_program = $1) =~ s/(\.\w+)?,v$//;
}
my $version_info = <<EOT;
$this_program $this_version
Copyright (C) 1997, 98 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
EOT
my $help_info = <<EOT;
`$this_program' generates a man page out of `--help' and `--version' output.
Usage: $this_program [OPTION]... EXECUTABLE
--name=STRING use `STRING' as the description for the NAME paragraph
--include=FILE include material from `FILE'
--opt-include=FILE include material from `FILE' if it exists
--output=FILE send output to `FILE'
--no-info suppress pointer to Texinfo manual
--help print this help, then exit
--version print $this_program program version number, then exit
EXECUTABLE should accept `--help' and `version' options.
Report bugs to <bod\@compusol.com.au>.
EOT
my ($include, $opt_name, $opt_include, $opt_output, $opt_no_info);
# Parse options.
GetOptions (
'name=s' => \$opt_name,
'include=s' => \$include,
'opt-include=s' => \$opt_include,
'output=s' => \$opt_output,
'no-info' => \$opt_no_info,
help => sub { print $help_info; exit },
version => sub { print $version_info; exit },
) or die $help_info;
die $help_info unless @ARGV == 1;
my %include = ();
my @include = (); # to retain order
# Process include file (if given). Format is:
#
# [section name]
# verbatim text
if ($include or $opt_include)
{
if (open INC, $include || $opt_include)
{
my $sect;
while (<INC>)
{
if (/^\[([^]]+)\]/)
{
$sect = uc $1;
$sect =~ s/^\s+//;
$sect =~ s/\s+$//;
next;
}
# Silently ignore anything before the first
# section--allows for comments and revision info.
next unless $sect;
push @include, $sect unless $include{$sect};
$include{$sect} ||= '';
$include{$sect} .= $_;
}
close INC;
die "$this_program: no valid information found in `$include'\n"
unless %include;
# Compress trailing blank lines
for (keys %include)
{
$include{$_} =~ s/\n+$//;
$include{$_} .= "\n" unless /^NAME$/;
}
}
else
{
die "$this_program: can't open `$include' ($!)\n" if $include;
}
}
# Turn off localisation of executable's ouput.
@ENV{qw(LANGUAGE LANG LC_ALL)} = ('C') x 3;
# Turn off localisation of date (for strftime)
setlocale LC_TIME, 'C';
# Grab help and version paragraphs from executable
my @help = split /\n\n+/, `$ARGV[0] --help 2>/dev/null`
or die "$this_program: can't get `--help' info from $ARGV[0]\n";
my @version = split /\n\n+/, `$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;
my $program = $ARGV[0]; $program =~ s!.*/!!;
my $package = $program;
my $version;
if ($opt_output)
{
unlink $opt_output
or die "$this_program: can't unlink $opt_output ($!)\n"
if -e $opt_output;
open STDOUT, ">$opt_output"
or die "$this_program: can't create $opt_output ($!)\n";
}
# The first line of the --version information is assumed to be in one
# of the following formats:
#
# <version>
# <program> <version>
# GNU <program> <version>
# <program> (GNU <package>) <version>
# <program> - GNU <package> <version>
#
# and seperated from any copyright/author details by a blank line.
$_ = shift @version;
if (/^(\S+)\s+\((GNU\s+[^)]+)\)\s+(.*)/ or
/^(\S+)\s+-\s*(GNU\s+\S+)\s+(.*)/)
{
$program = $1;
$package = $2;
$version = $3;
}
elsif (/^(GNU\s+)?(\S+)\s+(.*)/)
{
$program = $2;
$package = $1 ? "$1$2" : $2;
$version = $3;
}
else
{
$version = $_;
}
$program =~ s!.*/!!;
# 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;
# Default (useless) NAME paragraph
$include{NAME} ||= "$program \\- manual page for $program $version";
# 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 1 "$date" "$package $version" "FSF"
.SH NAME
$include{NAME}
EOT
my $accumulate = 1;
my @description = ();
sub convert_option;
# Output converted --help information.
for (@help)
{
chomp;
if (s/^Usage:\s+\S+\s+(.*)\n?//)
{
# 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(\s*)\\fR/$1/g;
$synopsis .= ".br\n" unless $accumulate;
$synopsis .= ".B $program\n";
$synopsis .= "$syn\n";
$accumulate = 0;
} while s/^(?:Usage|\s*or):\s+\S+\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})
{
print ".PP\n" unless $include{DESCRIPTION} =~ /^\..P/;
print $include{DESCRIPTION};
}
next unless $_;
}
# Accumulate text if the synopsis has not been produced yet.
if ($accumulate)
{
push @description, ".PP\n" if @description;
push @description, "$_\n";
next;
}
# Catch start of options.
if (/^Options:/)
{
print qq(.SH OPTIONS\n);
s/Options://;
}
# Catch bug report text.
if (/^Report bugs |^Email bug reports to /)
{
print qq(.SH "REPORTING BUGS"\n$_\n);
next;
}
# Special case for tar 1.12: --label=NAME\nPATTERN.
s{(\n[ \t]*)(-V,[ \t]+--label=NAME.*)\n[ \t]+PATTERN[ \t]+}
{$1$2$1\\&...=PATTERN };
# Convert options.
s/(\s)(-[][\w=-]+|\\&\S+)/$1 . convert_option $2/ge;
# Option subsections have second line indented.
print qq(.SS "$1"\n) if s/^(\S.*)\n(\s)/$2/;
# Lines indented more than about 10 spaces may be assumed to be
# continuations of the previous line.
s/\n {10,}/ /g;
# Lines following dotted (*) or numbered points may also be
# continued if indented to the same level as the text following
# the point.
1 while s{((?:^|\n)(\s+)(?:[1-9][.)]|\*)(\s+)(?:[^\n]+))\n\2 \3(\S)}
{$1 $4}g;
# Indented paragraph.
if (/^\s/)
{
for (split /\n/)
{
s/^\s+//;
s/([^,])\s+/$1\n/;
print ".TP\n$_\n" if $_;
}
}
# Anything else.
else
{
print ".PP\n$_\n";
}
}
# 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)$/;
}
# Refer to the real documentation.
if ($include{'SEE ALSO'} or !$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;
The full documentation for
.B $program
is maintained as a Texinfo manual. If the
.B info
and
.B $program
programs are properly installed at your site, the command
.IP
.B info $program
.PP
should give you access to the complete manual.
EOT
}
# Output converted --version information.
for (@version)
{
chomp;
# Convert copyright symbol or (c) to nroff character
s/Copyright\s+(?:\xa9|\([Cc]\))/Copyright \\(co/g;
# Insert appropriate headings for copyright and author
if (/^Copyright\s\\/) { print ".SH COPYRIGHT\n" }
elsif (/^Written\s+by/) { print ".SH AUTHOR\n" }
else { print ".PP\n"; }
# Insert line breaks before additional copyright messages and the
# disclaimer
s/(.)\n(Copyright\s|This is free software)/$1\n.br\n$2/g;
print "$_\n";
}
exit;
# Convert option dashes to \- to stop nroff from hyphenating 'em, and
# embolden. Option arguments get italicised.
sub convert_option
{
my $option = '\fB' . shift;
$option =~ s/-/\\-/g;
unless ($option =~ s/\[=(.*)\]$/\\fR[=\\fI$1\\fR]/)
{
$option =~ s/=(.)/\\fR=\\fI$1/;
$option =~ s/ (.)/ \\fI$1/;
$option .= '\fR';
}
$option;
}