Send and Receive a TLSv1.3 format ServerHello
[openssl.git] / util / process_docs.pl
1 #! /usr/bin/env perl
2 # Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
3 #
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
8
9 use strict;
10 use warnings;
11
12 use File::Spec::Functions;
13 use File::Basename;
14 use File::Copy;
15 use File::Path;
16 use if $^O ne "VMS", 'File::Glob' => qw/glob/;
17 use Getopt::Long;
18 use Pod::Usage;
19
20 use lib '.';
21 use configdata;
22
23 # We know we are in the 'util' directory and that our perl modules are
24 # in util/perl
25 use lib catdir(dirname($0), "perl");
26 use OpenSSL::Util::Pod;
27
28 my %options = ();
29 GetOptions(\%options,
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
38            'debug|D+',
39           );
40
41 unless ($options{section}) {
42     $options{section} = [ 1, 3, 5, 7 ];
43 }
44 unless ($options{sourcedir}) {
45     $options{sourcedir} = catdir($config{sourcedir}, "doc");
46 }
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') );
53
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";
64     }
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"};
71 }
72
73 my $symlink_exists = eval { symlink("",""); 1 };
74
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");
79
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}};
87
88         my $updir = updir();
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);
98
99         if (! $options{remove}) {
100             my @output;
101             print STDERR "DEBUG: Processing, using \"$generate\"\n"
102                 if $options{debug};
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";
107             }
108             print STDERR "DEBUG: Done processing\n" if $options{debug};
109
110             if (! -d $output_dir) {
111                 print STDERR "DEBUG: Creating directory $output_dir\n" if $options{debug};
112                 unless ($options{"dry-run"}) {
113                     mkpath $output_dir
114                         or die "Trying to create directory $output_dir: $!\n";
115                 }
116             }
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";
121                 foreach (@output) {
122                     print $output_fh $_;
123                 }
124                 close $output_fh;
125             }
126             print STDERR "DEBUG: Done writing $output_path\n" if $options{debug};
127         } else {
128             print STDERR "DEBUG: Removing $output_path\n" if $options{debug};
129             unless ($options{"dry-run"}) {
130                 while (unlink $output_path) {}
131             }
132         }
133         print "$output_path\n";
134
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"
141                         if $options{debug};
142                     unless ($options{"dry-run"}) {
143                         symlink $output_file, $link_path;
144                     }
145                 } else {
146                     print STDERR "DEBUG: Copying $output_path to link_path\n"
147                         if $options{debug};
148                     unless ($options{"dry-run"}) {
149                         copy $output_path, $link_path;
150                     }
151                 }
152             } else {
153                 print STDERR "DEBUG: Removing $link_path\n" if $options{debug};
154                 unless ($options{"dry-run"}) {
155                     while (unlink $link_path) {}
156                 }
157             }
158             print "$link_path -> $output_path\n";
159         }
160     }
161 }
162
163 __END__
164
165 =pod
166
167 =head1 NAME
168
169 process_docs.pl - A script to process OpenSSL docs
170
171 =head1 SYNOPSIS
172
173 B<process_docs.pl>
174 [B<--sourcedir>=I<dir>]
175 B<--destdir>=I<dir>
176 B<--type>=B<man>|B<html>
177 [B<--remove>]
178 [B<--dry-run>|B<-n>]
179 [B<--debug>|B<-D>]
180
181 =head1 DESCRIPTION
182
183 This script looks for .pod files in the subdirectories 'apps', 'crypto'
184 and 'ssl' under the given source directory.
185
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
189 work:
190
191  perl -I../foo util/process_docs.pl {options ...}
192
193 =head1 OPTIONS
194
195 =over 4
196
197 =item B<--sourcedir>=I<dir>
198
199 Top directory where the source files are found.
200
201 =item B<--destdir>=I<dir>
202
203 Top directory where the resulting files should end up
204
205 =item B<--type>=B<man>|B<html>
206
207 Type of output to produce.  Currently supported are man pages and HTML files.
208
209 =item B<--remove>
210
211 Instead of writing the files, remove them.
212
213 =item B<--dry-run>|B<-n>
214
215 Do not perform any file writing, directory creation or file removal.
216
217 =item B<--debug>|B<-D>
218
219 Print extra debugging output.
220
221 =back
222
223 =head1 COPYRIGHT
224
225 Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
226
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
231
232 =cut