2 # Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
4 # Licensed under the OpenSSL license (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 my @podsourcedirs = map { catfile($_, $subdir); } @{$options{sourcedir}};
88 my @podglobs = map { catfile($_, "*.pod"); } @podsourcedirs;
90 foreach my $podfile (map { glob $_ } @podglobs) {
91 my $podname = basename($podfile, ".pod");
92 my $podpath = catfile($podfile);
93 my %podinfo = extract_pod_info($podpath,
94 { debug => $options{debug},
95 section => $section });
96 my @podfiles = grep { $_ ne $podname } @{$podinfo{names}};
99 my $name = uc $podname;
100 my $suffix = { man => ".$podinfo{section}".($options{suffix} // ""),
101 html => ".html" } -> {$options{type}};
102 my $generate = { man => "pod2man --name=$name --section=$podinfo{section} --center=OpenSSL --release=$config{version} \"$podpath\"",
103 html => "pod2html \"--podroot=$options{sourcedir}\" --htmldir=$updir --podpath=man1:man3:man5:man7 \"--infile=$podpath\" \"--title=$podname\" --quiet"
104 } -> {$options{type}};
105 my $output_dir = catdir($options{destdir}, "man$podinfo{section}");
106 my $output_file = $podname . $suffix;
107 my $output_path = catfile($output_dir, $output_file);
109 if (! $options{remove}) {
111 print STDERR "DEBUG: Processing, using \"$generate\"\n"
113 unless ($options{"dry-run"}) {
114 @output = `$generate`;
115 map { s|href="http://man\.he\.net/(man\d/[^"]+)(?:\.html)?"|href="../$1.html"|g; } @output
116 if $options{type} eq "html";
117 if ($options{type} eq "man") {
118 # Because some *roff parsers are more strict than others,
119 # multiple lines in the NAME section must be merged into
128 push @newoutput, $name_line."\n";
131 $name_line .= " " if $name_line;
136 if (/^\.SH +"NAME" *$/) {
141 @output = @newoutput;
144 print STDERR "DEBUG: Done processing\n" if $options{debug};
146 if (! -d $output_dir) {
147 print STDERR "DEBUG: Creating directory $output_dir\n" if $options{debug};
148 unless ($options{"dry-run"}) {
150 or die "Trying to create directory $output_dir: $!\n";
153 print STDERR "DEBUG: Writing $output_path\n" if $options{debug};
154 unless ($options{"dry-run"}) {
155 open my $output_fh, '>', $output_path
156 or die "Trying to write to $output_path: $!\n";
162 print STDERR "DEBUG: Done writing $output_path\n" if $options{debug};
164 print STDERR "DEBUG: Removing $output_path\n" if $options{debug};
165 unless ($options{"dry-run"}) {
166 while (unlink $output_path) {}
169 print "$output_path\n";
171 foreach (@podfiles) {
172 my $link_file = $_ . $suffix;
173 my $link_path = catfile($output_dir, $link_file);
174 if (! $options{remove}) {
175 if ($symlink_exists) {
176 print STDERR "DEBUG: Linking $link_path -> $output_file\n"
178 unless ($options{"dry-run"}) {
179 symlink $output_file, $link_path;
182 print STDERR "DEBUG: Copying $output_path to link_path\n"
184 unless ($options{"dry-run"}) {
185 copy $output_path, $link_path;
189 print STDERR "DEBUG: Removing $link_path\n" if $options{debug};
190 unless ($options{"dry-run"}) {
191 while (unlink $link_path) {}
194 print "$link_path -> $output_path\n";
205 process_docs.pl - A script to process OpenSSL docs
210 [B<--sourcedir>=I<dir>]
212 B<--type>=B<man>|B<html>
213 [B<--suffix>=I<suffix>]
220 This script looks for .pod files in the subdirectories 'apps', 'crypto'
221 and 'ssl' under the given source directory.
223 The OpenSSL configuration data file F<configdata.pm> I<must> reside in
224 the current directory, I<or> perl must have the directory it resides in
225 in its inclusion array. For the latter variant, a call like this would
228 perl -I../foo util/process_docs.pl {options ...}
234 =item B<--sourcedir>=I<dir>
236 Top directory where the source files are found.
238 =item B<--destdir>=I<dir>
240 Top directory where the resulting files should end up
242 =item B<--type>=B<man>|B<html>
244 Type of output to produce. Currently supported are man pages and HTML files.
246 =item B<--suffix>=I<suffix>
248 A suffix added to the extension. Only valid with B<--type>=B<man>
252 Instead of writing the files, remove them.
254 =item B<--dry-run>|B<-n>
256 Do not perform any file writing, directory creation or file removal.
258 =item B<--debug>|B<-D>
260 Print extra debugging output.
266 Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved.
268 Licensed under the OpenSSL license (the "License"). You may not use
269 this file except in compliance with the License. You can obtain a copy
270 in the file LICENSE in the source distribution or at
271 https://www.openssl.org/source/license.html