man/help2man

   1 #!/sw/tools/bin/perl -w
   2
   3 # Generate a short man page from --help and --version output.
   4 # Copyright © 1997, 98, 99 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.010';
  29 my $version_info = <<EOT;
  30 $this_program $this_version
  31
  32 Copyright (C) 1997, 98, 99 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]) =~ 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,Free} <program> <version>
 155 #   <program> ({GNU,Free} <package>) <version>
 156 #   <program> - {GNU,Free} <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|Free)\s+[^)]+)\)\s+(.*)/ or
 163     /^(\S+)\s+-\s*((?:GNU|Free)\s+\S+)\s+(.*)/)
 164 {
 165     $program = $1;
 166     $package = $2;
 167     $version = $3;
 168 }
 169 elsif (/^((?:GNU|Free)\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|\s*or):\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     # Convert some standard paragraph names
 256     if (s/^(Options|Examples):\s*\n//)
 257     {
 258         print qq(.SH \U$1\n);
 259         next unless length;
 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/mge;
 275
 276     # Option subsections have second line indented.
 277     print qq(.SS "$1"\n) if s/^(\S.*)\n(\s)/$2/;
 278
 279     my $ind = 0;
 280     for (split /\n/)
 281     {
 282         # indented paragraph
 283         if (/^\s/)
 284         {
 285             # Join continued lines when indented to the same point as
 286             # text following at least two spaces on the previous line.
 287             if ($ind > 0 and /^ {$ind}\S/)
 288             {
 289                 s/^\s+//;
 290                 print "$_\n" if $_;
 291             }
 292             else
 293             {
 294                 # use the words(s) before two or more spaces for the
 295                 # tag
 296                 s/^(\s+)//;
 297                 $ind = length $1;
 298
 299                 if (s/(\s\s+)/\n/)
 300                 {
 301                     $ind += (length $1) + index $_, "\n";
 302                 }
 303                 else
 304                 {
 305                     $ind = 0;
 306                 }
 307
 308                 print ".TP\n$_\n" if $_;
 309             }
 310         }
 311         # Anything else.
 312         else
 313         {
 314             print ".PP\n" unless $ind < 0;
 315             print "$_\n";
 316             $ind = -1;
 317         }
 318     }
 319 }
 320
 321 # Print any include items other than the ones we have already dealt
 322 # with.
 323 for (@include)
 324 {
 325     print qq(.SH "$_"\n$include{$_})
 326         unless /^(NAME|SYNOPSIS|DESCRIPTION|SEE ALSO)$/;
 327 }
 328
 329 # Refer to the real documentation.
 330 if ($include{'SEE ALSO'} or !$opt_no_info)
 331 {
 332     print qq(.SH "SEE ALSO"\n);
 333     print $include{'SEE ALSO'}, ".PP\n" if $include{'SEE ALSO'};
 334
 335     print <<EOT unless $opt_no_info;
 336 The full documentation for
 337 .B $program
 338 is maintained as a Texinfo manual.  If the
 339 .B info
 340 and
 341 .B $program
 342 programs are properly installed at your site, the command
 343 .IP
 344 .B info $program
 345 .PP
 346 should give you access to the complete manual.
 347 EOT
 348 }
 349
 350 # Output converted --version information.
 351 for (@version)
 352 {
 353     chomp;
 354
 355     # Join hyphenated lines.
 356     s/([A-Za-z])-\n */$1/g;
 357
 358     # Convert copyright symbol or (c) to nroff character.
 359     s/Copyright\s+(?:\xa9|\([Cc]\))/Copyright \\(co/g;
 360
 361     # Insert appropriate headings for copyright and author.
 362     if    (/^Copyright\s\\/) { print ".SH COPYRIGHT\n" }
 363     elsif (/^Written\s+by/)  { print ".SH AUTHOR\n" }
 364     else                     { print ".PP\n"; }
 365
 366     # Insert line breaks before additional copyright messages and the
 367     # disclaimer.
 368     s/(.)\n(Copyright\s|This is free software)/$1\n.br\n$2/g;
 369
 370     print "$_\n";
 371 }
 372
 373 exit;
 374
 375 # Convert option dashes to \- to stop nroff from hyphenating 'em, and
 376 # embolden.  Option arguments get italicised.
 377 sub convert_option
 378 {
 379     my $option = '\fB' . shift;
 380
 381     $option =~ s/-/\\-/g;
 382     unless ($option =~ s/\[=(.*)\]$/\\fR[=\\fI$1\\fR]/)
 383     {
 384         $option =~ s/=(.)/\\fR=\\fI$1/;
 385         $option =~ s/ (.)/ \\fI$1/;
 386         $option .= '\fR';
 387     }
 388
 389     $option;
 390 }