]>
Commit | Line | Data |
---|---|---|
2bc57c88 | 1 | #! /usr/bin/env perl |
83cf7abf | 2 | # Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. |
2bc57c88 | 3 | # |
9059ab42 | 4 | # Licensed under the Apache License 2.0 (the "License"). You may not use |
2bc57c88 RL |
5 | # this file except in compliance with the License. You can obtain a copy |
6 | # in the file LICENSE in the source distribution or at | |
7 | # https://www.openssl.org/source/license.html | |
8 | ||
9 | use strict; | |
10 | use warnings; | |
11 | ||
12 | use File::Spec::Functions; | |
13 | use File::Basename; | |
14 | use File::Copy; | |
15 | use File::Path; | |
8d2214c0 RL |
16 | use FindBin; |
17 | use lib "$FindBin::Bin/perl"; | |
18 | use OpenSSL::Glob; | |
2bc57c88 RL |
19 | use Getopt::Long; |
20 | use Pod::Usage; | |
21 | ||
22 | use lib '.'; | |
23 | use configdata; | |
24 | ||
ee2c1a25 RL |
25 | # We know we are in the 'util' directory and that our perl modules are |
26 | # in util/perl | |
27 | use lib catdir(dirname($0), "perl"); | |
28 | use OpenSSL::Util::Pod; | |
29 | ||
2bc57c88 RL |
30 | my %options = (); |
31 | GetOptions(\%options, | |
b608fabf | 32 | 'sourcedir=s@', # Source directories |
99d63d46 | 33 | 'section=i@', # Subdirectories to look through, |
2bc57c88 RL |
34 | # with associated section numbers |
35 | 'destdir=s', # Destination directory | |
36 | #'in=s@', # Explicit files to process (ignores sourcedir) | |
2bc57c88 | 37 | 'type=s', # The result type, 'man' or 'html' |
579a6745 RL |
38 | 'suffix:s', # Suffix to add to the extension. |
39 | # Only used with type=man | |
2bc57c88 RL |
40 | 'remove', # To remove files rather than writing them |
41 | 'dry-run|n', # Only output file names on STDOUT | |
42 | 'debug|D+', | |
43 | ); | |
44 | ||
99d63d46 RS |
45 | unless ($options{section}) { |
46 | $options{section} = [ 1, 3, 5, 7 ]; | |
2bc57c88 RL |
47 | } |
48 | unless ($options{sourcedir}) { | |
b608fabf RL |
49 | $options{sourcedir} = [ catdir($config{sourcedir}, "doc"), |
50 | catdir($config{builddir}, "doc") ]; | |
2bc57c88 | 51 | } |
99d63d46 | 52 | pod2usage(1) unless ( defined $options{section} |
2bc57c88 RL |
53 | && defined $options{sourcedir} |
54 | && defined $options{destdir} | |
55 | && defined $options{type} | |
56 | && ($options{type} eq 'man' | |
57 | || $options{type} eq 'html') ); | |
579a6745 RL |
58 | pod2usage(1) if ( $options{type} eq 'html' |
59 | && defined $options{suffix} ); | |
2bc57c88 RL |
60 | |
61 | if ($options{debug}) { | |
62 | print STDERR "DEBUG: options:\n"; | |
b608fabf RL |
63 | foreach (sort @{$options{sourcedir}}) { |
64 | print STDERR "DEBUG: --sourcedir = $_\n"; | |
65 | } | |
2bc57c88 RL |
66 | print STDERR "DEBUG: --destdir = $options{destdir}\n" |
67 | if defined $options{destdir}; | |
68 | print STDERR "DEBUG: --type = $options{type}\n" | |
69 | if defined $options{type}; | |
579a6745 RL |
70 | print STDERR "DEBUG: --suffix = $options{suffix}\n" |
71 | if defined $options{suffix}; | |
99d63d46 RS |
72 | foreach (sort @{$options{section}}) { |
73 | print STDERR "DEBUG: --section = $_\n"; | |
2bc57c88 RL |
74 | } |
75 | print STDERR "DEBUG: --remove = $options{remove}\n" | |
76 | if defined $options{remove}; | |
77 | print STDERR "DEBUG: --debug = $options{debug}\n" | |
78 | if defined $options{debug}; | |
79 | print STDERR "DEBUG: --dry-run = $options{\"dry-run\"}\n" | |
80 | if defined $options{"dry-run"}; | |
81 | } | |
82 | ||
83 | my $symlink_exists = eval { symlink("",""); 1 }; | |
84 | ||
99d63d46 RS |
85 | foreach my $section (sort @{$options{section}}) { |
86 | my $subdir = "man$section"; | |
23d221b7 RL |
87 | foreach my $sourcedir (@{$options{sourcedir}}) { |
88 | my $podsourcedir = catfile($sourcedir, $subdir); | |
89 | my $podglob = catfile($podsourcedir, "*.pod"); | |
90 | ||
91 | foreach my $podfile (glob $podglob) { | |
92 | my $podname = basename($podfile, ".pod"); | |
93 | my $podpath = catfile($podfile); | |
94 | my %podinfo = extract_pod_info($podpath, | |
95 | { debug => $options{debug}, | |
96 | section => $section }); | |
97 | my @podfiles = grep { $_ ne $podname } @{$podinfo{names}}; | |
98 | ||
99 | my $updir = updir(); | |
100 | my $name = uc $podname; | |
101 | my $suffix = | |
102 | { man => ".$podinfo{section}".($options{suffix} // ""), | |
103 | html => ".html" } -> {$options{type}}; | |
104 | my $generate = | |
105 | { man => <<"_____", | |
106 | pod2man --name=$name --section=$podinfo{section} --center=OpenSSL --release=$config{version} "$podpath" | |
107 | _____ | |
108 | html => <<"_____", | |
109 | pod2html "--podroot=$sourcedir" --htmldir=$updir --podpath=man1:man3:man5:man7 "--infile=$podpath" "--title=$podname" --quiet | |
110 | _____ | |
111 | } -> {$options{type}}; | |
112 | my $output_dir = catdir($options{destdir}, "man$podinfo{section}"); | |
113 | my $output_file = $podname . $suffix; | |
114 | my $output_path = catfile($output_dir, $output_file); | |
115 | ||
116 | if (! $options{remove}) { | |
117 | my @output; | |
118 | print STDERR "DEBUG: Processing, using \"$generate\"\n" | |
119 | if $options{debug}; | |
120 | unless ($options{"dry-run"}) { | |
121 | @output = `$generate`; | |
122 | map { s|href="http://man\.he\.net/(man\d/[^"]+)(?:\.html)?"|href="../$1.html"|g; } @output | |
123 | if $options{type} eq "html"; | |
124 | if ($options{type} eq "man") { | |
125 | # Because some *roff parsers are more strict than | |
126 | # others, multiple lines in the NAME section must | |
127 | # be merged into one. | |
128 | my $in_name = 0; | |
129 | my $name_line = ""; | |
130 | my @newoutput = (); | |
131 | foreach (@output) { | |
132 | if ($in_name) { | |
133 | if (/^\.SH "/) { | |
134 | $in_name = 0; | |
135 | push @newoutput, $name_line."\n"; | |
136 | } else { | |
137 | chomp (my $x = $_); | |
138 | $name_line .= " " if $name_line; | |
139 | $name_line .= $x; | |
140 | next; | |
141 | } | |
8d483b2d | 142 | } |
23d221b7 RL |
143 | if (/^\.SH +"NAME" *$/) { |
144 | $in_name = 1; | |
145 | } | |
146 | push @newoutput, $_; | |
8d483b2d | 147 | } |
23d221b7 | 148 | @output = @newoutput; |
8d483b2d | 149 | } |
8d483b2d | 150 | } |
23d221b7 | 151 | print STDERR "DEBUG: Done processing\n" if $options{debug}; |
2bc57c88 | 152 | |
23d221b7 RL |
153 | if (! -d $output_dir) { |
154 | print STDERR "DEBUG: Creating directory $output_dir\n" | |
155 | if $options{debug}; | |
156 | unless ($options{"dry-run"}) { | |
157 | mkpath $output_dir | |
158 | or die "Trying to create directory $output_dir: $!\n"; | |
159 | } | |
160 | } | |
161 | print STDERR "DEBUG: Writing $output_path\n" if $options{debug}; | |
2bc57c88 | 162 | unless ($options{"dry-run"}) { |
23d221b7 RL |
163 | open my $output_fh, '>', $output_path |
164 | or die "Trying to write to $output_path: $!\n"; | |
165 | foreach (@output) { | |
166 | print $output_fh $_; | |
167 | } | |
168 | close $output_fh; | |
2bc57c88 | 169 | } |
23d221b7 RL |
170 | print STDERR "DEBUG: Done writing $output_path\n" if $options{debug}; |
171 | } else { | |
172 | print STDERR "DEBUG: Removing $output_path\n" if $options{debug}; | |
173 | unless ($options{"dry-run"}) { | |
174 | while (unlink $output_path) {} | |
2bc57c88 | 175 | } |
2bc57c88 | 176 | } |
23d221b7 RL |
177 | print "$output_path\n"; |
178 | ||
179 | foreach (@podfiles) { | |
180 | my $link_file = $_ . $suffix; | |
181 | my $link_path = catfile($output_dir, $link_file); | |
182 | if (! $options{remove}) { | |
183 | if ($symlink_exists) { | |
184 | print STDERR "DEBUG: Linking $link_path -> $output_file\n" | |
185 | if $options{debug}; | |
186 | unless ($options{"dry-run"}) { | |
187 | symlink $output_file, $link_path; | |
188 | } | |
189 | } else { | |
190 | print STDERR "DEBUG: Copying $output_path to link_path\n" | |
191 | if $options{debug}; | |
192 | unless ($options{"dry-run"}) { | |
193 | copy $output_path, $link_path; | |
194 | } | |
2bc57c88 RL |
195 | } |
196 | } else { | |
23d221b7 | 197 | print STDERR "DEBUG: Removing $link_path\n" if $options{debug}; |
2bc57c88 | 198 | unless ($options{"dry-run"}) { |
23d221b7 | 199 | while (unlink $link_path) {} |
2bc57c88 RL |
200 | } |
201 | } | |
23d221b7 | 202 | print "$link_path -> $output_path\n"; |
2bc57c88 | 203 | } |
2bc57c88 RL |
204 | } |
205 | } | |
206 | } | |
207 | ||
208 | __END__ | |
209 | ||
210 | =pod | |
211 | ||
212 | =head1 NAME | |
213 | ||
214 | process_docs.pl - A script to process OpenSSL docs | |
215 | ||
216 | =head1 SYNOPSIS | |
217 | ||
218 | B<process_docs.pl> | |
219 | [B<--sourcedir>=I<dir>] | |
220 | B<--destdir>=I<dir> | |
221 | B<--type>=B<man>|B<html> | |
579a6745 | 222 | [B<--suffix>=I<suffix>] |
2bc57c88 RL |
223 | [B<--remove>] |
224 | [B<--dry-run>|B<-n>] | |
225 | [B<--debug>|B<-D>] | |
226 | ||
227 | =head1 DESCRIPTION | |
228 | ||
229 | This script looks for .pod files in the subdirectories 'apps', 'crypto' | |
230 | and 'ssl' under the given source directory. | |
231 | ||
232 | The OpenSSL configuration data file F<configdata.pm> I<must> reside in | |
233 | the current directory, I<or> perl must have the directory it resides in | |
234 | in its inclusion array. For the latter variant, a call like this would | |
235 | work: | |
236 | ||
237 | perl -I../foo util/process_docs.pl {options ...} | |
238 | ||
239 | =head1 OPTIONS | |
240 | ||
241 | =over 4 | |
242 | ||
243 | =item B<--sourcedir>=I<dir> | |
244 | ||
245 | Top directory where the source files are found. | |
246 | ||
247 | =item B<--destdir>=I<dir> | |
248 | ||
249 | Top directory where the resulting files should end up | |
250 | ||
251 | =item B<--type>=B<man>|B<html> | |
252 | ||
253 | Type of output to produce. Currently supported are man pages and HTML files. | |
254 | ||
579a6745 RL |
255 | =item B<--suffix>=I<suffix> |
256 | ||
257 | A suffix added to the extension. Only valid with B<--type>=B<man> | |
258 | ||
2bc57c88 RL |
259 | =item B<--remove> |
260 | ||
261 | Instead of writing the files, remove them. | |
262 | ||
263 | =item B<--dry-run>|B<-n> | |
264 | ||
265 | Do not perform any file writing, directory creation or file removal. | |
266 | ||
267 | =item B<--debug>|B<-D> | |
268 | ||
269 | Print extra debugging output. | |
270 | ||
271 | =back | |
272 | ||
273 | =head1 COPYRIGHT | |
274 | ||
83cf7abf | 275 | Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved. |
2bc57c88 | 276 | |
9059ab42 | 277 | Licensed under the Apache License 2.0 (the "License"). You may not use |
2bc57c88 RL |
278 | this file except in compliance with the License. You can obtain a copy |
279 | in the file LICENSE in the source distribution or at | |
280 | https://www.openssl.org/source/license.html | |
281 | ||
282 | =cut |