Sync CABAL branch with release-1_0 branch.
[tinc] / 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 }