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 'suffix:s', # Suffix to add to the extension.
38 # Only used with type=man
39 'remove', # To remove files rather than writing them
40 'dry-run|n', # Only output file names on STDOUT
44 unless ($options{subdir}) {
45 $options{subdir} = { apps => '1',
49 unless ($options{sourcedir}) {
50 $options{sourcedir} = catdir($config{sourcedir}, "doc");
52 pod2usage(1) unless ( defined $options{subdir}
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 print STDERR "DEBUG: --sourcedir = $options{sourcedir}\n"
64 if defined $options{sourcedir};
65 print STDERR "DEBUG: --destdir = $options{destdir}\n"
66 if defined $options{destdir};
67 print STDERR "DEBUG: --type = $options{type}\n"
68 if defined $options{type};
69 print STDERR "DEBUG: --suffix = $options{suffix}\n"
70 if defined $options{suffix};
71 foreach (keys %{$options{subdir}}) {
72 print STDERR "DEBUG: --subdir = $_=$options{subdir}->{$_}\n";
74 print STDERR "DEBUG: --remove = $options{remove}\n"
75 if defined $options{remove};
76 print STDERR "DEBUG: --debug = $options{debug}\n"
77 if defined $options{debug};
78 print STDERR "DEBUG: --dry-run = $options{\"dry-run\"}\n"
79 if defined $options{"dry-run"};
82 my $symlink_exists = eval { symlink("",""); 1 };
84 foreach my $subdir (keys %{$options{subdir}}) {
85 my $section = $options{subdir}->{$subdir};
86 my $podsourcedir = catfile($options{sourcedir}, $subdir);
87 my $podglob = catfile($podsourcedir, "*.pod");
89 foreach my $podfile (glob $podglob) {
90 my $podname = basename($podfile, ".pod");
91 my $podpath = catfile($podfile);
92 my %podinfo = extract_pod_info($podpath,
93 { debug => $options{debug},
94 section => $section });
95 my @podfiles = grep { $_ ne $podname } @{$podinfo{names}};
98 my $name = uc $podname;
99 my $suffix = { man => ".$podinfo{section}".($options{suffix} // ""),
100 html => ".html" } -> {$options{type}};
101 my $generate = { man => "pod2man --name=$name --section=$podinfo{section} --center=OpenSSL --release=$config{version} \"$podpath\"",
102 html => "pod2html \"--podroot=$options{sourcedir}\" --htmldir=$updir --podpath=apps:crypto:ssl \"--infile=$podpath\" \"--title=$podname\""
103 } -> {$options{type}};
104 my $output_dir = catdir($options{destdir}, "man$podinfo{section}");
105 my $output_file = $podname . $suffix;
106 my $output_path = catfile($output_dir, $output_file);
108 if (! $options{remove}) {
110 print STDERR "DEBUG: Processing, using \"$generate\"\n"
112 unless ($options{"dry-run"}) {
113 @output = `$generate`;
114 map { s|href="http://man\.he\.net/(man\d/[^"]+)(?:\.html)?"|href="../$1.html|g; } @output
115 if $options{type} eq "html";
117 print STDERR "DEBUG: Done processing\n" if $options{debug};
119 if (! -d $output_dir) {
120 print STDERR "DEBUG: Creating directory $output_dir\n" if $options{debug};
121 unless ($options{"dry-run"}) {
123 or die "Trying to create directory $output_dir: $!\n";
126 print STDERR "DEBUG: Writing $output_path\n" if $options{debug};
127 unless ($options{"dry-run"}) {
128 open my $output_fh, '>', $output_path
129 or die "Trying to write to $output_path: $!\n";
135 print STDERR "DEBUG: Done writing $output_path\n" if $options{debug};
137 print STDERR "DEBUG: Removing $output_path\n" if $options{debug};
138 unless ($options{"dry-run"}) {
139 while (unlink $output_path) {}
142 print "$output_path\n";
144 foreach (@podfiles) {
145 my $link_file = $_ . $suffix;
146 my $link_path = catfile($output_dir, $link_file);
147 if (! $options{remove}) {
148 if ($symlink_exists) {
149 print STDERR "DEBUG: Linking $link_path -> $output_file\n"
151 unless ($options{"dry-run"}) {
152 symlink $output_file, $link_path;
155 print STDERR "DEBUG: Copying $output_path to link_path\n"
157 unless ($options{"dry-run"}) {
158 copy $output_path, $link_path;
162 print STDERR "DEBUG: Removing $link_path\n" if $options{debug};
163 unless ($options{"dry-run"}) {
164 while (unlink $link_path) {}
167 print "$link_path -> $output_path\n";
178 process_docs.pl - A script to process OpenSSL docs
183 [B<--sourcedir>=I<dir>]
185 B<--type>=B<man>|B<html>
186 [B<--suffix>=I<suffix>]
193 This script looks for .pod files in the subdirectories 'apps', 'crypto'
194 and 'ssl' under the given source directory.
196 The OpenSSL configuration data file F<configdata.pm> I<must> reside in
197 the current directory, I<or> perl must have the directory it resides in
198 in its inclusion array. For the latter variant, a call like this would
201 perl -I../foo util/process_docs.pl {options ...}
207 =item B<--sourcedir>=I<dir>
209 Top directory where the source files are found.
211 =item B<--destdir>=I<dir>
213 Top directory where the resulting files should end up
215 =item B<--type>=B<man>|B<html>
217 Type of output to produce. Currently supported are man pages and HTML files.
219 =item B<--suffix>=I<suffix>
221 A suffix added to the extension. Only valid with B<--type>=B<man>
225 Instead of writing the files, remove them.
227 =item B<--dry-run>|B<-n>
229 Do not perform any file writing, directory creation or file removal.
231 =item B<--debug>|B<-D>
233 Print extra debugging output.
239 Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
241 Licensed under the OpenSSL license (the "License"). You may not use
242 this file except in compliance with the License. You can obtain a copy
243 in the file LICENSE in the source distribution or at
244 https://www.openssl.org/source/license.html