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 'section=i@', # Subdirectories to look through,
32 # with associated section numbers
33 'destdir=s', # Destination directory
34 #'in=s@', # Explicit files to process (ignores sourcedir)
35 'type=s', # The result type, 'man' or 'html'
36 'remove', # To remove files rather than writing them
37 'dry-run|n', # Only output file names on STDOUT
41 unless ($options{section}) {
42 $options{section} = [ 1, 3, 5, 7 ];
44 unless ($options{sourcedir}) {
45 $options{sourcedir} = catdir($config{sourcedir}, "doc");
47 pod2usage(1) unless ( defined $options{section}
48 && defined $options{sourcedir}
49 && defined $options{destdir}
50 && defined $options{type}
51 && ($options{type} eq 'man'
52 || $options{type} eq 'html') );
54 if ($options{debug}) {
55 print STDERR "DEBUG: options:\n";
56 print STDERR "DEBUG: --sourcedir = $options{sourcedir}\n"
57 if defined $options{sourcedir};
58 print STDERR "DEBUG: --destdir = $options{destdir}\n"
59 if defined $options{destdir};
60 print STDERR "DEBUG: --type = $options{type}\n"
61 if defined $options{type};
62 foreach (sort @{$options{section}}) {
63 print STDERR "DEBUG: --section = $_\n";
65 print STDERR "DEBUG: --remove = $options{remove}\n"
66 if defined $options{remove};
67 print STDERR "DEBUG: --debug = $options{debug}\n"
68 if defined $options{debug};
69 print STDERR "DEBUG: --dry-run = $options{\"dry-run\"}\n"
70 if defined $options{"dry-run"};
73 my $symlink_exists = eval { symlink("",""); 1 };
75 foreach my $section (sort @{$options{section}}) {
76 my $subdir = "man$section";
77 my $podsourcedir = catfile($options{sourcedir}, $subdir);
78 my $podglob = catfile($podsourcedir, "*.pod");
80 foreach my $podfile (glob $podglob) {
81 my $podname = basename($podfile, ".pod");
82 my $podpath = catfile($podfile);
83 my %podinfo = extract_pod_info($podpath,
84 { debug => $options{debug},
85 section => $section });
86 my @podfiles = grep { $_ ne $podname } @{$podinfo{names}};
89 my $name = uc $podname;
90 my $suffix = { man => ".$podinfo{section}",
91 html => ".html" } -> {$options{type}};
92 my $generate = { man => "pod2man --name=$name --section=$podinfo{section} --center=OpenSSL --release=$config{version} \"$podpath\"",
93 html => "pod2html \"--podroot=$options{sourcedir}\" --htmldir=$updir --podpath=man1:man3:man5:man7 \"--infile=$podpath\" \"--title=$podname\""
94 } -> {$options{type}};
95 my $output_dir = catdir($options{destdir}, "man$podinfo{section}");
96 my $output_file = $podname . $suffix;
97 my $output_path = catfile($output_dir, $output_file);
99 if (! $options{remove}) {
101 print STDERR "DEBUG: Processing, using \"$generate\"\n"
103 unless ($options{"dry-run"}) {
104 @output = `$generate`;
105 map { s|href="http://man\.he\.net/(man\d/[^"]+)(?:\.html)?"|href="../$1.html"|g; } @output
106 if $options{type} eq "html";
108 print STDERR "DEBUG: Done processing\n" if $options{debug};
110 if (! -d $output_dir) {
111 print STDERR "DEBUG: Creating directory $output_dir\n" if $options{debug};
112 unless ($options{"dry-run"}) {
114 or die "Trying to create directory $output_dir: $!\n";
117 print STDERR "DEBUG: Writing $output_path\n" if $options{debug};
118 unless ($options{"dry-run"}) {
119 open my $output_fh, '>', $output_path
120 or die "Trying to write to $output_path: $!\n";
126 print STDERR "DEBUG: Done writing $output_path\n" if $options{debug};
128 print STDERR "DEBUG: Removing $output_path\n" if $options{debug};
129 unless ($options{"dry-run"}) {
130 while (unlink $output_path) {}
133 print "$output_path\n";
135 foreach (@podfiles) {
136 my $link_file = $_ . $suffix;
137 my $link_path = catfile($output_dir, $link_file);
138 if (! $options{remove}) {
139 if ($symlink_exists) {
140 print STDERR "DEBUG: Linking $link_path -> $output_file\n"
142 unless ($options{"dry-run"}) {
143 symlink $output_file, $link_path;
146 print STDERR "DEBUG: Copying $output_path to link_path\n"
148 unless ($options{"dry-run"}) {
149 copy $output_path, $link_path;
153 print STDERR "DEBUG: Removing $link_path\n" if $options{debug};
154 unless ($options{"dry-run"}) {
155 while (unlink $link_path) {}
158 print "$link_path -> $output_path\n";
169 process_docs.pl - A script to process OpenSSL docs
174 [B<--sourcedir>=I<dir>]
176 B<--type>=B<man>|B<html>
183 This script looks for .pod files in the subdirectories 'apps', 'crypto'
184 and 'ssl' under the given source directory.
186 The OpenSSL configuration data file F<configdata.pm> I<must> reside in
187 the current directory, I<or> perl must have the directory it resides in
188 in its inclusion array. For the latter variant, a call like this would
191 perl -I../foo util/process_docs.pl {options ...}
197 =item B<--sourcedir>=I<dir>
199 Top directory where the source files are found.
201 =item B<--destdir>=I<dir>
203 Top directory where the resulting files should end up
205 =item B<--type>=B<man>|B<html>
207 Type of output to produce. Currently supported are man pages and HTML files.
211 Instead of writing the files, remove them.
213 =item B<--dry-run>|B<-n>
215 Do not perform any file writing, directory creation or file removal.
217 =item B<--debug>|B<-D>
219 Print extra debugging output.
225 Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
227 Licensed under the OpenSSL license (the "License"). You may not use
228 this file except in compliance with the License. You can obtain a copy
229 in the file LICENSE in the source distribution or at
230 https://www.openssl.org/source/license.html