2 # Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
4 # Licensed under the Apache License 2.0 (the "License"). You may not use
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
12 use File::Spec::Functions;
17 use lib "$FindBin::Bin/perl";
25 # We know we are in the 'util' directory and that our perl modules are
27 use lib catdir(dirname($0), "perl");
28 use OpenSSL::Util::Pod;
32 'sourcedir=s@', # Source directories
33 'section=i@', # Subdirectories to look through,
34 # with associated section numbers
35 'destdir=s', # Destination directory
36 #'in=s@', # Explicit files to process (ignores sourcedir)
37 'type=s', # The result type, 'man' or 'html'
38 'suffix:s', # Suffix to add to the extension.
39 # Only used with type=man
40 'remove', # To remove files rather than writing them
41 'dry-run|n', # Only output file names on STDOUT
45 unless ($options{section}) {
46 $options{section} = [ 1, 3, 5, 7 ];
48 unless ($options{sourcedir}) {
49 $options{sourcedir} = [ catdir($config{sourcedir}, "doc"),
50 catdir($config{builddir}, "doc") ];
52 pod2usage(1) unless ( defined $options{section}
53 && defined $options{sourcedir}
54 && defined $options{destdir}
55 && defined $options{type}
56 && ($options{type} eq 'man'
57 || $options{type} eq 'html') );
58 pod2usage(1) if ( $options{type} eq 'html'
59 && defined $options{suffix} );
61 if ($options{debug}) {
62 print STDERR "DEBUG: options:\n";
63 foreach (sort @{$options{sourcedir}}) {
64 print STDERR "DEBUG: --sourcedir = $_\n";
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};
70 print STDERR "DEBUG: --suffix = $options{suffix}\n"
71 if defined $options{suffix};
72 foreach (sort @{$options{section}}) {
73 print STDERR "DEBUG: --section = $_\n";
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"};
83 my $symlink_exists = eval { symlink("",""); 1 };
85 foreach my $section (sort @{$options{section}}) {
86 my $subdir = "man$section";
87 foreach my $sourcedir (@{$options{sourcedir}}) {
88 my $podsourcedir = catfile($sourcedir, $subdir);
89 my $podglob = catfile($podsourcedir, "*.pod");
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}};
100 my $name = uc $podname;
102 { man => ".$podinfo{section}".($options{suffix} // ""),
103 html => ".html" } -> {$options{type}};
106 pod2man --name=$name --section=$podinfo{section} --center=OpenSSL --release=$config{version} "$podpath"
109 pod2html "--podroot=$sourcedir" --htmldir=$updir --podpath=man1:man3:man5:man7 "--infile=$podpath" "--title=$podname" --quiet
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);
116 if (! $options{remove}) {
118 print STDERR "DEBUG: Processing, using \"$generate\"\n"
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.
135 push @newoutput, $name_line."\n";
138 $name_line .= " " if $name_line;
143 if (/^\.SH +"NAME" *$/) {
148 @output = @newoutput;
151 print STDERR "DEBUG: Done processing\n" if $options{debug};
153 if (! -d $output_dir) {
154 print STDERR "DEBUG: Creating directory $output_dir\n"
156 unless ($options{"dry-run"}) {
158 or die "Trying to create directory $output_dir: $!\n";
161 print STDERR "DEBUG: Writing $output_path\n" if $options{debug};
162 unless ($options{"dry-run"}) {
163 open my $output_fh, '>', $output_path
164 or die "Trying to write to $output_path: $!\n";
170 print STDERR "DEBUG: Done writing $output_path\n" if $options{debug};
172 print STDERR "DEBUG: Removing $output_path\n" if $options{debug};
173 unless ($options{"dry-run"}) {
174 while (unlink $output_path) {}
177 print "$output_path\n";
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"
186 unless ($options{"dry-run"}) {
187 symlink $output_file, $link_path;
190 print STDERR "DEBUG: Copying $output_path to link_path\n"
192 unless ($options{"dry-run"}) {
193 copy $output_path, $link_path;
197 print STDERR "DEBUG: Removing $link_path\n" if $options{debug};
198 unless ($options{"dry-run"}) {
199 while (unlink $link_path) {}
202 print "$link_path -> $output_path\n";
214 process_docs.pl - A script to process OpenSSL docs
219 [B<--sourcedir>=I<dir>]
221 B<--type>=B<man>|B<html>
222 [B<--suffix>=I<suffix>]
229 This script looks for .pod files in the subdirectories 'apps', 'crypto'
230 and 'ssl' under the given source directory.
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
237 perl -I../foo util/process_docs.pl {options ...}
243 =item B<--sourcedir>=I<dir>
245 Top directory where the source files are found.
247 =item B<--destdir>=I<dir>
249 Top directory where the resulting files should end up
251 =item B<--type>=B<man>|B<html>
253 Type of output to produce. Currently supported are man pages and HTML files.
255 =item B<--suffix>=I<suffix>
257 A suffix added to the extension. Only valid with B<--type>=B<man>
261 Instead of writing the files, remove them.
263 =item B<--dry-run>|B<-n>
265 Do not perform any file writing, directory creation or file removal.
267 =item B<--debug>|B<-D>
269 Print extra debugging output.
275 Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved.
277 Licensed under the Apache License 2.0 (the "License"). You may not use
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