git.meshlink.io Git - meshlink/blob - doc/help2man

   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|\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     # 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 }