2 # Copyright 2016 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;
16 use if $^O ne "VMS", 'File::Glob' => qw/glob/;
23 # We know we are in the 'util' directory and that our perl modules are
25 use lib catdir(dirname($0), "perl");
26 use OpenSSL::Util::Pod;
30 'sourcedir=s', # Source directory
31 'subdir=s%', # Subdirectories to look through,
32 # with associated section numbers
33 'destdir=s', # Destination directory
34 #'in=s@', # Explicit files to process (ignores sourcedir)
35 #'section=i', # Default section used for --in files
36 'type=s', # The result type, 'man' or 'html'
37 'remove', # To remove files rather than writing them
38 'dry-run|n', # Only output file names on STDOUT
42 unless ($options{subdir}) {
43 $options{subdir} = { apps => '1',
47 unless ($options{sourcedir}) {
48 $options{sourcedir} = catdir($config{sourcedir}, "doc");
50 pod2usage(1) unless ( defined $options{subdir}
51 && defined $options{sourcedir}
52 && defined $options{destdir}
53 && defined $options{type}
54 && ($options{type} eq 'man'
55 || $options{type} eq 'html') );
57 if ($options{debug}) {
58 print STDERR "DEBUG: options:\n";
59 print STDERR "DEBUG: --sourcedir = $options{sourcedir}\n"
60 if defined $options{sourcedir};
61 print STDERR "DEBUG: --destdir = $options{destdir}\n"
62 if defined $options{destdir};
63 print STDERR "DEBUG: --type = $options{type}\n"
64 if defined $options{type};
65 foreach (keys %{$options{subdir}}) {
66 print STDERR "DEBUG: --subdir = $_=$options{subdir}->{$_}\n";
68 print STDERR "DEBUG: --remove = $options{remove}\n"
69 if defined $options{remove};
70 print STDERR "DEBUG: --debug = $options{debug}\n"
71 if defined $options{debug};
72 print STDERR "DEBUG: --dry-run = $options{\"dry-run\"}\n"
73 if defined $options{"dry-run"};
76 my $symlink_exists = eval { symlink("",""); 1 };
78 foreach my $subdir (keys %{$options{subdir}}) {
79 my $section = $options{subdir}->{$subdir};
80 my $podsourcedir = catfile($options{sourcedir}, $subdir);
81 my $podglob = catfile($podsourcedir, "*.pod");
83 foreach my $podfile (glob $podglob) {
84 my $podname = basename($podfile, ".pod");
85 my $podpath = catfile($podfile);
86 my %podinfo = extract_pod_info($podpath,
87 { debug => $options{debug},
88 section => $section });
89 my @podfiles = grep { $_ ne $podname } @{$podinfo{names}};
92 my $name = uc $podname;
93 my $suffix = { man => ".$podinfo{section}",
94 html => ".html" } -> {$options{type}};
95 my $generate = { man => "pod2man --name=$name --section=$podinfo{section} --center=OpenSSL --release=$config{version} \"$podpath\"",
96 html => "pod2html \"--podroot=$options{sourcedir}\" --htmldir=$updir --podpath=apps:crypto:ssl \"--infile=$podpath\" \"--title=$podname\""
97 } -> {$options{type}};
98 my $output_dir = catdir($options{destdir}, "man$podinfo{section}");
99 my $output_file = $podname . $suffix;
100 my $output_path = catfile($output_dir, $output_file);
102 if (! $options{remove}) {
104 print STDERR "DEBUG: Processing, using \"$generate\"\n"
106 unless ($options{"dry-run"}) {
107 @output = `$generate`;
108 map { s|href="http://man\.he\.net/man|href="../man|g; } @output
109 if $options{type} eq "html";
111 print STDERR "DEBUG: Done processing\n" if $options{debug};
113 if (! -d $output_dir) {
114 print STDERR "DEBUG: Creating directory $output_dir\n" if $options{debug};
115 unless ($options{"dry-run"}) {
117 or die "Trying to create directory $output_dir: $!\n";
120 print STDERR "DEBUG: Writing $output_path\n" if $options{debug};
121 unless ($options{"dry-run"}) {
122 open my $output_fh, '>', $output_path
123 or die "Trying to write to $output_path: $!\n";
129 print STDERR "DEBUG: Done writing $output_path\n" if $options{debug};
131 print STDERR "DEBUG: Removing $output_path\n" if $options{debug};
132 unless ($options{"dry-run"}) {
133 while (unlink $output_path) {}
136 print "$output_path\n";
138 foreach (@podfiles) {
139 my $link_file = $_ . $suffix;
140 my $link_path = catfile($output_dir, $link_file);
141 if (! $options{remove}) {
142 if ($symlink_exists) {
143 print STDERR "DEBUG: Linking $link_path -> $output_file\n"
145 unless ($options{"dry-run"}) {
146 symlink $output_file, $link_path;
149 print STDERR "DEBUG: Copying $output_path to link_path\n"
151 unless ($options{"dry-run"}) {
152 copy $output_path, $link_path;
156 print STDERR "DEBUG: Removing $link_path\n" if $options{debug};
157 unless ($options{"dry-run"}) {
158 while (unlink $link_path) {}
161 print "$link_path -> $output_path\n";
172 process_docs.pl - A script to process OpenSSL docs
177 [B<--sourcedir>=I<dir>]
179 B<--type>=B<man>|B<html>
186 This script looks for .pod files in the subdirectories 'apps', 'crypto'
187 and 'ssl' under the given source directory.
189 The OpenSSL configuration data file F<configdata.pm> I<must> reside in
190 the current directory, I<or> perl must have the directory it resides in
191 in its inclusion array. For the latter variant, a call like this would
194 perl -I../foo util/process_docs.pl {options ...}
200 =item B<--sourcedir>=I<dir>
202 Top directory where the source files are found.
204 =item B<--destdir>=I<dir>
206 Top directory where the resulting files should end up
208 =item B<--type>=B<man>|B<html>
210 Type of output to produce. Currently supported are man pages and HTML files.
214 Instead of writing the files, remove them.
216 =item B<--dry-run>|B<-n>
218 Do not perform any file writing, directory creation or file removal.
220 =item B<--debug>|B<-D>
222 Print extra debugging output.
228 Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
230 Licensed under the OpenSSL license (the "License"). You may not use
231 this file except in compliance with the License. You can obtain a copy
232 in the file LICENSE in the source distribution or at
233 https://www.openssl.org/source/license.html