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;
24 'sourcedir=s', # Source directory
25 'subdir=s%', # Subdirectories to look through,
26 # with associated section numbers
27 'destdir=s', # Destination directory
28 #'in=s@', # Explicit files to process (ignores sourcedir)
29 #'section=i', # Default section used for --in files
30 'type=s', # The result type, 'man' or 'html'
31 'remove', # To remove files rather than writing them
32 'dry-run|n', # Only output file names on STDOUT
36 unless ($options{subdir}) {
37 $options{subdir} = { apps => '1',
41 unless ($options{sourcedir}) {
42 $options{sourcedir} = catdir($config{sourcedir}, "doc");
44 pod2usage(1) unless ( defined $options{subdir}
45 && defined $options{sourcedir}
46 && defined $options{destdir}
47 && defined $options{type}
48 && ($options{type} eq 'man'
49 || $options{type} eq 'html') );
51 if ($options{debug}) {
52 print STDERR "DEBUG: options:\n";
53 print STDERR "DEBUG: --sourcedir = $options{sourcedir}\n"
54 if defined $options{sourcedir};
55 print STDERR "DEBUG: --destdir = $options{destdir}\n"
56 if defined $options{destdir};
57 print STDERR "DEBUG: --type = $options{type}\n"
58 if defined $options{type};
59 foreach (keys %{$options{subdir}}) {
60 print STDERR "DEBUG: --subdir = $_=$options{subdir}->{$_}\n";
62 print STDERR "DEBUG: --remove = $options{remove}\n"
63 if defined $options{remove};
64 print STDERR "DEBUG: --debug = $options{debug}\n"
65 if defined $options{debug};
66 print STDERR "DEBUG: --dry-run = $options{\"dry-run\"}\n"
67 if defined $options{"dry-run"};
70 my $symlink_exists = eval { symlink("",""); 1 };
72 foreach my $subdir (keys %{$options{subdir}}) {
73 my $section = $options{subdir}->{$subdir};
74 my $podsourcedir = catfile($options{sourcedir}, $subdir);
75 my $podglob = catfile($podsourcedir, "*.pod");
77 foreach my $podfile (glob "$podglob") {
78 my $podname = basename($podfile, ".pod");
79 my $podpath = catfile($podfile);
80 my %podinfo = ( section => $section );
82 print STDERR "DEBUG: Reading $podpath\n" if $options{debug};
83 open my $pod_fh, $podpath or die "Trying to read $podpath: $!\n";
86 if (m|^=for\s+comment\s+openssl_manual_section:\s*([0-9])\s*$|) {
87 print STDERR "Found section number $1\n" if $options{debug};
88 $podinfo{section} = $1;
90 last if m|^=head1| && defined $podinfo{lastsect} eq "NAME";
91 if (m|^head1=\s*(.*)|) {
92 $podinfo{lastsect} = $1;
93 $podinfo{lastsect} =~ s/\s+$//;
94 $podinfo{lastsecttext} = "";
96 next if (m|^=| || m|^\s*$|);
97 $podinfo{lastsecttext} .= " " if $podinfo{lastsecttext};
98 $podinfo{lastsecttext} .= $_;
101 $podinfo{lastsecttext} =~ s| - .*$||;
102 print STDERR "DEBUG: Done reading $podpath\n" if $options{debug};
105 grep { $_ ne $podname }
107 split(m|,|, $podinfo{lastsecttext});
110 my $name = uc $podname;
111 my $suffix = { man => ".$podinfo{section}",
112 html => ".html" } -> {$options{type}};
113 my $generate = { man => "pod2man --name=$name --section=$podinfo{section} --center=OpenSSL --release=$config{version} \"$podpath\"",
114 html => "pod2html \"--podroot=$options{sourcedir}\" --htmldir=$updir --podpath=apps:crypto:ssl \"--infile=$podpath\" \"--title=$podname\""
115 } -> {$options{type}};
116 my $output_dir = catdir($options{destdir}, "man$podinfo{section}");
117 my $output_file = $podname . $suffix;
118 my $output_path = catfile($output_dir, $output_file);
120 if (! $options{remove}) {
122 print STDERR "DEBUG: Processing, using \"$generate\"\n"
124 unless ($options{"dry-run"}) {
125 @output = `$generate`;
126 map { s|href="http://man\.he\.net/man|href="../man|g; } @output
127 if $options{type} eq "html";
129 print STDERR "DEBUG: Done processing\n" if $options{debug};
131 if (! -d $output_dir) {
132 print STDERR "DEBUG: Creating directory $output_dir\n" if $options{debug};
133 unless ($options{"dry-run"}) {
135 or die "Trying to create directory $output_dir: $!\n";
138 print STDERR "DEBUG: Writing $output_path\n" if $options{debug};
139 unless ($options{"dry-run"}) {
140 open my $output_fh, '>', $output_path
141 or die "Trying to write to $output_path: $!\n";
147 print STDERR "DEBUG: Done writing $output_path\n" if $options{debug};
149 print STDERR "DEBUG: Removing $output_path\n" if $options{debug};
150 unless ($options{"dry-run"}) {
151 while (unlink $output_path) {}
154 print "$output_path\n";
156 foreach (@podfiles) {
157 my $link_file = $_ . $suffix;
158 my $link_path = catfile($output_dir, $link_file);
159 if (! $options{remove}) {
160 if ($symlink_exists) {
161 print STDERR "DEBUG: Linking $link_path -> $output_file\n"
163 unless ($options{"dry-run"}) {
164 symlink $output_file, $link_path;
167 print STDERR "DEBUG: Copying $output_path to link_path\n"
169 unless ($options{"dry-run"}) {
170 copy $output_path, $link_path;
174 print STDERR "DEBUG: Removing $link_path\n" if $options{debug};
175 unless ($options{"dry-run"}) {
176 while (unlink $link_path) {}
179 print "$link_path -> $output_path\n";
190 process_docs.pl - A script to process OpenSSL docs
195 [B<--sourcedir>=I<dir>]
197 B<--type>=B<man>|B<html>
204 This script looks for .pod files in the subdirectories 'apps', 'crypto'
205 and 'ssl' under the given source directory.
207 The OpenSSL configuration data file F<configdata.pm> I<must> reside in
208 the current directory, I<or> perl must have the directory it resides in
209 in its inclusion array. For the latter variant, a call like this would
212 perl -I../foo util/process_docs.pl {options ...}
218 =item B<--sourcedir>=I<dir>
220 Top directory where the source files are found.
222 =item B<--destdir>=I<dir>
224 Top directory where the resulting files should end up
226 =item B<--type>=B<man>|B<html>
228 Type of output to produce. Currently supported are man pages and HTML files.
232 Instead of writing the files, remove them.
234 =item B<--dry-run>|B<-n>
236 Do not perform any file writing, directory creation or file removal.
238 =item B<--debug>|B<-D>
240 Print extra debugging output.
246 Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
248 Licensed under the OpenSSL license (the "License"). You may not use
249 this file except in compliance with the License. You can obtain a copy
250 in the file LICENSE in the source distribution or at
251 https://www.openssl.org/source/license.html