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=apps:crypto:ssl \"--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|href="../man|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