[ViewVC] Annotation of: cvs/gvpe/doc/help2man

#!/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>

use 5.004;
use strict;
use Getopt::Long;
use POSIX qw(strftime setlocale LC_TIME);

my $this_program = 'help2man';
my $this_version = '1.006';
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.

Written by Brendan O'Dea <bod\@compusol.com.au>
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.
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;

    # Join hyphenated lines.
    s/([A-Za-z])-\n */$1/g;

    # 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;
}
Revision:	1.1
Committed:	Sat Mar 1 15:53:02 2003 UTC (21 years, 2 months ago) by pcg
Branch:	MAIN
Log Message:	* empty log message *
#	User	Rev	Content
1	pcg	1.1	#!/usr/bin/perl -w
2
3			# Generate a short man page from --help and --version output.
4			# Copyright © 1997, 98 Free Software Foundation, Inc.
5
6			# This program is free software; you can redistribute it and/or modify
7			# it under the terms of the GNU General Public License as published by
8			# the Free Software Foundation; either version 2, or (at your option)
9			# any later version.
10
11			# This program is distributed in the hope that it will be useful,
12			# but WITHOUT ANY WARRANTY; without even the implied warranty of
13			# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14			# GNU General Public License for more details.
15
16			# You should have received a copy of the GNU General Public License
17			# along with this program; if not, write to the Free Software Foundation,
18			# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
19
20			# Written by Brendan O'Dea <bod@compusol.com.au>
21
22			use 5.004;
23			use strict;
24			use Getopt::Long;
25			use POSIX qw(strftime setlocale LC_TIME);
26
27			my $this_program = 'help2man';
28			my $this_version = '1.006';
29			my $version_info = <<EOT;
30			$this_program $this_version
31
32			Copyright (C) 1997, 98 Free Software Foundation, Inc.
33			This is free software; see the source for copying conditions. There is NO
34			warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
35
36			Written by Brendan O'Dea <bod\@compusol.com.au>
37			EOT
38
39			my $help_info = <<EOT;
40			`$this_program' generates a man page out of `--help' and `--version' output.
41
42			Usage: $this_program [OPTION]... EXECUTABLE
43
44			--name=STRING use `STRING' as the description for the NAME paragraph
45			--include=FILE include material from `FILE'
46			--opt-include=FILE include material from `FILE' if it exists
47			--output=FILE send output to `FILE'
48			--no-info suppress pointer to Texinfo manual
49			--help print this help, then exit
50			--version print $this_program program version number, then exit
51
52			EXECUTABLE should accept `--help' and `version' options.
53			EOT
54
55			my ($include, $opt_name, $opt_include, $opt_output, $opt_no_info);
56
57			# Parse options.
58			GetOptions (
59			'name=s' => \$opt_name,
60			'include=s' => \$include,
61			'opt-include=s' => \$opt_include,
62			'output=s' => \$opt_output,
63			'no-info' => \$opt_no_info,
64			help => sub { print $help_info; exit },
65			version => sub { print $version_info; exit },
66			) or die $help_info;
67
68			die $help_info unless @ARGV == 1;
69
70			my %include = ();
71			my @include = (); # to retain order
72
73			# Process include file (if given). Format is:
74			#
75			# [section name]
76			# verbatim text
77
78			if ($include or $opt_include)
79			{
80			if (open INC, $include \|\| $opt_include)
81			{
82			my $sect;
83
84			while (<INC>)
85			{
86			if (/^\[([^]]+)\]/)
87			{
88			$sect = uc $1;
89			$sect =~ s/^\s+//;
90			$sect =~ s/\s+$//;
91			next;
92			}
93
94			# Silently ignore anything before the first
95			# section--allows for comments and revision info.
96			next unless $sect;
97
98			push @include, $sect unless $include{$sect};
99			$include{$sect} \|\|= '';
100			$include{$sect} .= $_;
101			}
102
103			close INC;
104
105			die "$this_program: no valid information found in `$include'\n"
106			unless %include;
107
108			# Compress trailing blank lines.
109			for (keys %include)
110			{
111			$include{$_} =~ s/\n+$//;
112			$include{$_} .= "\n" unless /^NAME$/;
113			}
114			}
115			else
116			{
117			die "$this_program: can't open `$include' ($!)\n" if $include;
118			}
119			}
120
121			# Turn off localisation of executable's ouput.
122			@ENV{qw(LANGUAGE LANG LC_ALL)} = ('C') x 3;
123
124			# Turn off localisation of date (for strftime)
125			setlocale LC_TIME, 'C';
126
127			# Grab help and version paragraphs from executable
128			my @help = split /\n\n+/, `$ARGV[0] --help 2>/dev/null`
129			or die "$this_program: can't get `--help' info from $ARGV[0]\n";
130
131			my @version = split /\n\n+/, `$ARGV[0] --version 2>/dev/null`
132			or die "$this_program: can't get `--version' info from $ARGV[0]\n";
133
134			my $date = strftime "%B %Y", localtime;
135			my $program = $ARGV[0]; $program =~ s!.*/!!;
136			my $package = $program;
137			my $version;
138
139			if ($opt_output)
140			{
141			unlink $opt_output
142			or die "$this_program: can't unlink $opt_output ($!)\n"
143			if -e $opt_output;
144
145			open STDOUT, ">$opt_output"
146			or die "$this_program: can't create $opt_output ($!)\n";
147			}
148
149			# The first line of the --version information is assumed to be in one
150			# of the following formats:
151			#
152			# <version>
153			# <program> <version>
154			# GNU <program> <version>
155			# <program> (GNU <package>) <version>
156			# <program> - GNU <package> <version>
157			#
158			# and seperated from any copyright/author details by a blank line.
159
160			$_ = shift @version;
161
162			if (/^(\S+)\s+\((GNU\s+[^)]+)\)\s+(.*)/ or
163			/^(\S+)\s+-\s(GNU\s+\S+)\s+(.)/)
164			{
165			$program = $1;
166			$package = $2;
167			$version = $3;
168			}
169			elsif (/^(GNU\s+)?(\S+)\s+(.*)/)
170			{
171			$program = $2;
172			$package = $1 ? "$1$2" : $2;
173			$version = $3;
174			}
175			else
176			{
177			$version = $_;
178			}
179
180			$program =~ s!.*/!!;
181
182			# no info for `info' itself
183			$opt_no_info = 1 if $program eq 'info';
184
185			# --name overrides --include contents
186			$include{NAME} = "$program \\- $opt_name" if $opt_name;
187
188			# Default (useless) NAME paragraph
189			$include{NAME} \|\|= "$program \\- manual page for $program $version";
190
191			# Man pages traditionally have the page title in caps.
192			my $PROGRAM = uc $program;
193
194			# Header.
195			print <<EOT;
196			.\" DO NOT MODIFY THIS FILE! It was generated by $this_program $this_version.
197			.TH $PROGRAM 1 "$date" "$package $version" "FSF"
198			.SH NAME
199			$include{NAME}
200			EOT
201
202			my $accumulate = 1;
203			my @description = ();
204
205			sub convert_option;
206
207			# Output converted --help information.
208			for (@help)
209			{
210			chomp;
211
212			if (s/^Usage:\s+\S+\s+(.*)\n?//)
213			{
214			# Turn the usage clause into a synopsis.
215			my $synopsis = '';
216
217			do {
218			my $syn = $1;
219			$syn =~ s/(([][]\|\.\.+)+)/\\fR$1\\fI/g;
220			$syn =~ s/^/\\fI/ unless $syn =~ s/^\\fR//;
221			$syn .= '\fR';
222			$syn =~ s/\\fI(\s*)\\fR/$1/g;
223
224			$synopsis .= ".br\n" unless $accumulate;
225			$synopsis .= ".B $program\n";
226			$synopsis .= "$syn\n";
227			$accumulate = 0;
228			} while s/^(?:Usage\|\sor):\s+\S+\s+(.)\n?//;
229
230			# Include file overrides SYNOPSIS.
231			print ".SH SYNOPSIS\n", $include{SYNOPSIS} \|\| $synopsis;
232
233			# Dump any accumulated description text.
234			print ".SH DESCRIPTION\n";
235			print @description;
236
237			# Add additional description text from include file.
238			if ($include{DESCRIPTION})
239			{
240			print ".PP\n" unless $include{DESCRIPTION} =~ /^\..P/;
241			print $include{DESCRIPTION};
242			}
243
244			next unless $_;
245			}
246
247			# Accumulate text if the synopsis has not been produced yet.
248			if ($accumulate)
249			{
250			push @description, ".PP\n" if @description;
251			push @description, "$_\n";
252			next;
253			}
254
255			# Catch start of options.
256			if (/^Options:/)
257			{
258			print qq(.SH OPTIONS\n);
259			s/Options://;
260			}
261
262			# Catch bug report text.
263			if (/^Report bugs \|^Email bug reports to /)
264			{
265			print qq(.SH "REPORTING BUGS"\n$_\n);
266			next;
267			}
268
269			# Special case for tar 1.12: --label=NAME\nPATTERN.
270			s{(\n[ \t])(-V,[ \t]+--label=NAME.)\n[ \t]+PATTERN[ \t]+}
271			{$1$2$1\\&...=PATTERN };
272
273			# Convert options.
274			s/(\s)(-[][\w=-]+\|\\&\S+)/$1 . convert_option $2/ge;
275
276			# Option subsections have second line indented.
277			print qq(.SS "$1"\n) if s/^(\S.*)\n(\s)/$2/;
278
279			# Lines indented more than about 10 spaces may be assumed to be
280			# continuations of the previous line.
281			s/\n {10,}/ /g;
282
283			# Lines following dotted (*) or numbered points may also be
284			# continued if indented to the same level as the text following
285			# the point.
286			1 while s{((?:^\|\n)(\s+)(?:[1-9][.)]\|\*)(\s+)(?:[^\n]+))\n\2 \3(\S)}
287			{$1 $4}g;
288
289			# Indented paragraph.
290			if (/^\s/)
291			{
292			for (split /\n/)
293			{
294			s/^\s+//;
295			s/([^,])\s+/$1\n/;
296			print ".TP\n$_\n" if $_;
297			}
298			}
299			# Anything else.
300			else
301			{
302			print ".PP\n$_\n";
303			}
304			}
305
306			# Print any include items other than the ones we have already dealt
307			# with.
308			for (@include)
309			{
310			print qq(.SH "$_"\n$include{$_})
311			unless /^(NAME\|SYNOPSIS\|DESCRIPTION\|SEE ALSO)$/;
312			}
313
314			# Refer to the real documentation.
315			if ($include{'SEE ALSO'} or !$opt_no_info)
316			{
317			print qq(.SH "SEE ALSO"\n);
318			print $include{'SEE ALSO'}, ".PP\n" if $include{'SEE ALSO'};
319
320			print <<EOT unless $opt_no_info;
321			The full documentation for
322			.B $program
323			is maintained as a Texinfo manual. If the
324			.B info
325			and
326			.B $program
327			programs are properly installed at your site, the command
328			.IP
329			.B info $program
330			.PP
331			should give you access to the complete manual.
332			EOT
333			}
334
335			# Output converted --version information.
336			for (@version)
337			{
338			chomp;
339
340			# Join hyphenated lines.
341			s/([A-Za-z])-\n */$1/g;
342
343			# Convert copyright symbol or (c) to nroff character.
344			s/Copyright\s+(?:\xa9\|\([Cc]\))/Copyright \\(co/g;
345
346			# Insert appropriate headings for copyright and author.
347			if (/^Copyright\s\\/) { print ".SH COPYRIGHT\n" }
348			elsif (/^Written\s+by/) { print ".SH AUTHOR\n" }
349			else { print ".PP\n"; }
350
351			# Insert line breaks before additional copyright messages and the
352			# disclaimer.
353			s/(.)\n(Copyright\s\|This is free software)/$1\n.br\n$2/g;
354
355			print "$_\n";
356			}
357
358			exit;
359
360			# Convert option dashes to \- to stop nroff from hyphenating 'em, and
361			# embolden. Option arguments get italicised.
362			sub convert_option
363			{
364			my $option = '\fB' . shift;
365
366			$option =~ s/-/\\-/g;
367			unless ($option =~ s/\[=(.*)\]$/\\fR[=\\fI$1\\fR]/)
368			{
369			$option =~ s/=(.)/\\fR=\\fI$1/;
370			$option =~ s/ (.)/ \\fI$1/;
371			$option .= '\fR';
372			}
373
374			$option;
375			}