[thirdparty/openssl.git] / util / process_docs.pl

#! /usr/bin/env perl
# Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
#
# Licensed under the Apache License 2.0 (the "License").  You may not use
# this file except in compliance with the License.  You can obtain a copy
# in the file LICENSE in the source distribution or at
# https://www.openssl.org/source/license.html

use strict;
use warnings;

use File::Spec::Functions;
use File::Basename;
use File::Copy;
use File::Path;
use FindBin;
use lib "$FindBin::Bin/perl";
use OpenSSL::Glob;
use Getopt::Long;
use Pod::Usage;

use lib '.';
use configdata;

# We know we are in the 'util' directory and that our perl modules are
# in util/perl
use lib catdir(dirname($0), "perl");
use OpenSSL::Util::Pod;

my %options = ();
GetOptions(\%options,
           'sourcedir=s@',      # Source directories
           'section=i@',        # Subdirectories to look through,
                                # with associated section numbers
           'destdir=s',         # Destination directory
           #'in=s@',             # Explicit files to process (ignores sourcedir)
           'type=s',            # The result type, 'man' or 'html'
           'suffix:s',          # Suffix to add to the extension.
                                # Only used with type=man
           'remove',            # To remove files rather than writing them
           'dry-run|n',         # Only output file names on STDOUT
           'debug|D+',
          );

unless ($options{section}) {
    $options{section} = [ 1, 3, 5, 7 ];
}
unless ($options{sourcedir}) {
    $options{sourcedir} = [ catdir($config{sourcedir}, "doc"),
                            catdir($config{builddir}, "doc") ];
}
pod2usage(1) unless ( defined $options{section}
                      && defined $options{sourcedir}
                      && defined $options{destdir}
                      && defined $options{type}
                      && ($options{type} eq 'man'
                          || $options{type} eq 'html') );
pod2usage(1) if ( $options{type} eq 'html'
                  && defined $options{suffix} );

if ($options{debug}) {
    print STDERR "DEBUG: options:\n";
    foreach (sort @{$options{sourcedir}}) {
        print STDERR "DEBUG:   --sourcedir   = $_\n";
    }
    print STDERR "DEBUG:   --destdir   = $options{destdir}\n"
        if defined $options{destdir};
    print STDERR "DEBUG:   --type      = $options{type}\n"
        if defined $options{type};
    print STDERR "DEBUG:   --suffix    = $options{suffix}\n"
        if defined $options{suffix};
    foreach (sort @{$options{section}}) {
        print STDERR "DEBUG:   --section   = $_\n";
    }
    print STDERR "DEBUG:   --remove    = $options{remove}\n"
        if defined $options{remove};
    print STDERR "DEBUG:   --debug     = $options{debug}\n"
        if defined $options{debug};
    print STDERR "DEBUG:   --dry-run   = $options{\"dry-run\"}\n"
        if defined $options{"dry-run"};
}

my $symlink_exists = eval { symlink("",""); 1 };

foreach my $section (sort @{$options{section}}) {
    my $subdir = "man$section";
    foreach my $sourcedir (@{$options{sourcedir}}) {
        my $podsourcedir = catfile($sourcedir, $subdir);
        my $podglob = catfile($podsourcedir, "*.pod");

        foreach my $podfile (glob $podglob) {
            my $podname = basename($podfile, ".pod");
            my $podpath = catfile($podfile);
            my %podinfo = extract_pod_info($podpath,
                                           { debug => $options{debug},
                                             section => $section });
            my @podfiles = grep { $_ ne $podname } @{$podinfo{names}};

            my $updir = updir();
            my $name = uc $podname;
            my $suffix =
                { man  => ".$podinfo{section}".($options{suffix} // ""),
                  html => ".html" } -> {$options{type}};
            my $generate =
                { man  => <<"_____",
pod2man --name=$name --section=$podinfo{section}  --center=OpenSSL --release=$config{version}  "$podpath"
_____
                  html => <<"_____",
pod2html "--podroot=$sourcedir" --htmldir=$updir --podpath=man1:man3:man5:man7 "--infile=$podpath" "--title=$podname" --quiet
_____
                } -> {$options{type}};
            my $output_dir = catdir($options{destdir}, "man$podinfo{section}");
            my $output_file = $podname . $suffix;
            my $output_path = catfile($output_dir, $output_file);

            if (! $options{remove}) {
                my @output;
                print STDERR "DEBUG: Processing, using \"$generate\"\n"
                    if $options{debug};
                unless ($options{"dry-run"}) {
                    @output = `$generate`;
                    map { s|href="http://man\.he\.net/(man\d/[^"]+)(?:\.html)?"|href="../$1.html"|g; } @output
                        if $options{type} eq "html";
                    if ($options{type} eq "man") {
                        # Because some *roff parsers are more strict than
                        # others, multiple lines in the NAME section must
                        # be merged into one.
                        my $in_name = 0;
                        my $name_line = "";
                        my @newoutput = ();
                        foreach (@output) {
                            if ($in_name) {
                                if (/^\.SH "/) {
                                    $in_name = 0;
                                    push @newoutput, $name_line."\n";
                                } else {
                                    chomp (my $x = $_);
                                    $name_line .= " " if $name_line;
                                    $name_line .= $x;
                                    next;
                                }
                            }
                            if (/^\.SH +"NAME" *$/) {
                                $in_name = 1;
                            }
                            push @newoutput, $_;
                        }
                        @output = @newoutput;
                    }
                }
                print STDERR "DEBUG: Done processing\n" if $options{debug};

                if (! -d $output_dir) {
                    print STDERR "DEBUG: Creating directory $output_dir\n"
                        if $options{debug};
                    unless ($options{"dry-run"}) {
                        mkpath $output_dir
                            or die "Trying to create directory $output_dir: $!\n";
                    }
                }
                print STDERR "DEBUG: Writing $output_path\n" if $options{debug};
                unless ($options{"dry-run"}) {
                    open my $output_fh, '>', $output_path
                        or die "Trying to write to $output_path: $!\n";
                    foreach (@output) {
                        print $output_fh $_;
                    }
                    close $output_fh;
                }
                print STDERR "DEBUG: Done writing $output_path\n" if $options{debug};
            } else {
                print STDERR "DEBUG: Removing $output_path\n" if $options{debug};
                unless ($options{"dry-run"}) {
                    while (unlink $output_path) {}
                }
            }
            print "$output_path\n";

            foreach (@podfiles) {
                my $link_file = $_ . $suffix;
                my $link_path = catfile($output_dir, $link_file);
                if (! $options{remove}) {
                    if ($symlink_exists) {
                        print STDERR "DEBUG: Linking $link_path -> $output_file\n"
                            if $options{debug};
                        unless ($options{"dry-run"}) {
                            symlink $output_file, $link_path;
                        }
                    } else {
                        print STDERR "DEBUG: Copying $output_path to link_path\n"
                            if $options{debug};
                        unless ($options{"dry-run"}) {
                            copy $output_path, $link_path;
                        }
                    }
                } else {
                    print STDERR "DEBUG: Removing $link_path\n" if $options{debug};
                    unless ($options{"dry-run"}) {
                        while (unlink $link_path) {}
                    }
                }
                print "$link_path -> $output_path\n";
            }
        }
    }
}

__END__

=pod

=head1 NAME

process_docs.pl - A script to process OpenSSL docs

=head1 SYNOPSIS

B<process_docs.pl>
[B<--sourcedir>=I<dir>]
B<--destdir>=I<dir>
B<--type>=B<man>|B<html>
[B<--suffix>=I<suffix>]
[B<--remove>]
[B<--dry-run>|B<-n>]
[B<--debug>|B<-D>]

=head1 DESCRIPTION

This script looks for .pod files in the subdirectories 'apps', 'crypto'
and 'ssl' under the given source directory.

The OpenSSL configuration data file F<configdata.pm> I<must> reside in
the current directory, I<or> perl must have the directory it resides in
in its inclusion array.  For the latter variant, a call like this would
work:

 perl -I../foo util/process_docs.pl {options ...}

=head1 OPTIONS

=over 4

=item B<--sourcedir>=I<dir>

Top directory where the source files are found.

=item B<--destdir>=I<dir>

Top directory where the resulting files should end up

=item B<--type>=B<man>|B<html>

Type of output to produce.  Currently supported are man pages and HTML files.

=item B<--suffix>=I<suffix>

A suffix added to the extension.  Only valid with B<--type>=B<man>

=item B<--remove>

Instead of writing the files, remove them.

=item B<--dry-run>|B<-n>

Do not perform any file writing, directory creation or file removal.

=item B<--debug>|B<-D>

Print extra debugging output.

=back

=head1 COPYRIGHT

Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
https://www.openssl.org/source/license.html

=cut
Commit	Line	Data
2bc57c88	1	#! /usr/bin/env perl
83cf7abf	2	# Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
2bc57c88	3	#
9059ab42	4	# Licensed under the Apache License 2.0 (the "License"). You may not use
2bc57c88 RL	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;
8d2214c0 RL	16	use FindBin;
	17	use lib "$FindBin::Bin/perl";
	18	use OpenSSL::Glob;
2bc57c88 RL	19	use Getopt::Long;
	20	use Pod::Usage;
	21
	22	use lib '.';
	23	use configdata;
	24
ee2c1a25 RL	25	# We know we are in the 'util' directory and that our perl modules are
	26	# in util/perl
	27	use lib catdir(dirname($0), "perl");
	28	use OpenSSL::Util::Pod;
	29
2bc57c88 RL	30	my %options = ();
2bc57c88 RL	31	GetOptions(\%options,
b608fabf	32	'sourcedir=s@', # Source directories
99d63d46	33	'section=i@', # Subdirectories to look through,
2bc57c88 RL	34	# with associated section numbers
	35	'destdir=s', # Destination directory
	36	#'in=s@', # Explicit files to process (ignores sourcedir)
2bc57c88	37	'type=s', # The result type, 'man' or 'html'
579a6745 RL	38	'suffix:s', # Suffix to add to the extension.
579a6745 RL	39	# Only used with type=man
2bc57c88 RL	40	'remove', # To remove files rather than writing them
	41	'dry-run\|n', # Only output file names on STDOUT
	42	'debug\|D+',
	43	);
	44
99d63d46 RS	45	unless ($options{section}) {
99d63d46 RS	46	$options{section} = [ 1, 3, 5, 7 ];
2bc57c88 RL	47	}
2bc57c88 RL	48	unless ($options{sourcedir}) {
b608fabf RL	49	$options{sourcedir} = [ catdir($config{sourcedir}, "doc"),
b608fabf RL	50	catdir($config{builddir}, "doc") ];
2bc57c88	51	}
99d63d46	52	pod2usage(1) unless ( defined $options{section}
2bc57c88 RL	53	&& defined $options{sourcedir}
	54	&& defined $options{destdir}
	55	&& defined $options{type}
	56	&& ($options{type} eq 'man'
	57	\|\| $options{type} eq 'html') );
579a6745 RL	58	pod2usage(1) if ( $options{type} eq 'html'
579a6745 RL	59	&& defined $options{suffix} );
2bc57c88 RL	60
	61	if ($options{debug}) {
	62	print STDERR "DEBUG: options:\n";
b608fabf RL	63	foreach (sort @{$options{sourcedir}}) {
	64	print STDERR "DEBUG: --sourcedir = $_\n";
	65	}
2bc57c88 RL	66	print STDERR "DEBUG: --destdir = $options{destdir}\n"
	67	if defined $options{destdir};
	68	print STDERR "DEBUG: --type = $options{type}\n"
	69	if defined $options{type};
579a6745 RL	70	print STDERR "DEBUG: --suffix = $options{suffix}\n"
579a6745 RL	71	if defined $options{suffix};
99d63d46 RS	72	foreach (sort @{$options{section}}) {
99d63d46 RS	73	print STDERR "DEBUG: --section = $_\n";
2bc57c88 RL	74	}
	75	print STDERR "DEBUG: --remove = $options{remove}\n"
	76	if defined $options{remove};
	77	print STDERR "DEBUG: --debug = $options{debug}\n"
	78	if defined $options{debug};
	79	print STDERR "DEBUG: --dry-run = $options{\"dry-run\"}\n"
	80	if defined $options{"dry-run"};
	81	}
	82
	83	my $symlink_exists = eval { symlink("",""); 1 };
	84
99d63d46 RS	85	foreach my $section (sort @{$options{section}}) {
99d63d46 RS	86	my $subdir = "man$section";
23d221b7 RL	87	foreach my $sourcedir (@{$options{sourcedir}}) {
	88	my $podsourcedir = catfile($sourcedir, $subdir);
	89	my $podglob = catfile($podsourcedir, "*.pod");
	90
	91	foreach my $podfile (glob $podglob) {
	92	my $podname = basename($podfile, ".pod");
	93	my $podpath = catfile($podfile);
	94	my %podinfo = extract_pod_info($podpath,
	95	{ debug => $options{debug},
	96	section => $section });
	97	my @podfiles = grep { $_ ne $podname } @{$podinfo{names}};
	98
	99	my $updir = updir();
	100	my $name = uc $podname;
	101	my $suffix =
	102	{ man => ".$podinfo{section}".($options{suffix} // ""),
	103	html => ".html" } -> {$options{type}};
	104	my $generate =
	105	{ man => <<"_____",
	106	pod2man --name=$name --section=$podinfo{section} --center=OpenSSL --release=$config{version} "$podpath"
	107	_____
	108	html => <<"_____",
	109	pod2html "--podroot=$sourcedir" --htmldir=$updir --podpath=man1:man3:man5:man7 "--infile=$podpath" "--title=$podname" --quiet
	110	_____
	111	} -> {$options{type}};
	112	my $output_dir = catdir($options{destdir}, "man$podinfo{section}");
	113	my $output_file = $podname . $suffix;
	114	my $output_path = catfile($output_dir, $output_file);
	115
	116	if (! $options{remove}) {
	117	my @output;
	118	print STDERR "DEBUG: Processing, using \"$generate\"\n"
	119	if $options{debug};
	120	unless ($options{"dry-run"}) {
	121	@output = `$generate`;
	122	map { s\|href="http://man\.he\.net/(man\d/[^"]+)(?:\.html)?"\|href="../$1.html"\|g; } @output
	123	if $options{type} eq "html";
	124	if ($options{type} eq "man") {
	125	# Because some *roff parsers are more strict than
	126	# others, multiple lines in the NAME section must
	127	# be merged into one.
	128	my $in_name = 0;
	129	my $name_line = "";
	130	my @newoutput = ();
	131	foreach (@output) {
	132	if ($in_name) {
	133	if (/^\.SH "/) {
	134	$in_name = 0;
	135	push @newoutput, $name_line."\n";
	136	} else {
	137	chomp (my $x = $_);
	138	$name_line .= " " if $name_line;
	139	$name_line .= $x;
	140	next;
	141	}
8d483b2d	142	}
23d221b7 RL	143	if (/^\.SH +"NAME" *$/) {
	144	$in_name = 1;
	145	}
	146	push @newoutput, $_;
8d483b2d	147	}
23d221b7	148	@output = @newoutput;
8d483b2d	149	}
8d483b2d	150	}
23d221b7	151	print STDERR "DEBUG: Done processing\n" if $options{debug};
2bc57c88	152
23d221b7 RL	153	if (! -d $output_dir) {
	154	print STDERR "DEBUG: Creating directory $output_dir\n"
	155	if $options{debug};
	156	unless ($options{"dry-run"}) {
	157	mkpath $output_dir
	158	or die "Trying to create directory $output_dir: $!\n";
	159	}
	160	}
	161	print STDERR "DEBUG: Writing $output_path\n" if $options{debug};
2bc57c88	162	unless ($options{"dry-run"}) {
23d221b7 RL	163	open my $output_fh, '>', $output_path
	164	or die "Trying to write to $output_path: $!\n";
	165	foreach (@output) {
	166	print $output_fh $_;
	167	}
	168	close $output_fh;
2bc57c88	169	}
23d221b7 RL	170	print STDERR "DEBUG: Done writing $output_path\n" if $options{debug};
	171	} else {
	172	print STDERR "DEBUG: Removing $output_path\n" if $options{debug};
	173	unless ($options{"dry-run"}) {
	174	while (unlink $output_path) {}
2bc57c88	175	}
2bc57c88	176	}
23d221b7 RL	177	print "$output_path\n";
	178
	179	foreach (@podfiles) {
	180	my $link_file = $_ . $suffix;
	181	my $link_path = catfile($output_dir, $link_file);
	182	if (! $options{remove}) {
	183	if ($symlink_exists) {
	184	print STDERR "DEBUG: Linking $link_path -> $output_file\n"
	185	if $options{debug};
	186	unless ($options{"dry-run"}) {
	187	symlink $output_file, $link_path;
	188	}
	189	} else {
	190	print STDERR "DEBUG: Copying $output_path to link_path\n"
	191	if $options{debug};
	192	unless ($options{"dry-run"}) {
	193	copy $output_path, $link_path;
	194	}
2bc57c88 RL	195	}
2bc57c88 RL	196	} else {
23d221b7	197	print STDERR "DEBUG: Removing $link_path\n" if $options{debug};
2bc57c88	198	unless ($options{"dry-run"}) {
23d221b7	199	while (unlink $link_path) {}
2bc57c88 RL	200	}
2bc57c88 RL	201	}
23d221b7	202	print "$link_path -> $output_path\n";
2bc57c88	203	}
2bc57c88 RL	204	}
	205	}
	206	}
	207
	208	__END__
	209
	210	=pod
	211
	212	=head1 NAME
	213
	214	process_docs.pl - A script to process OpenSSL docs
	215
	216	=head1 SYNOPSIS
	217
	218	B<process_docs.pl>
	219	[B<--sourcedir>=I<dir>]
	220	B<--destdir>=I<dir>
	221	B<--type>=B<man>\|B<html>
579a6745	222	[B<--suffix>=I<suffix>]
2bc57c88 RL	223	[B<--remove>]
	224	[B<--dry-run>\|B<-n>]
	225	[B<--debug>\|B<-D>]
	226
	227	=head1 DESCRIPTION
	228
	229	This script looks for .pod files in the subdirectories 'apps', 'crypto'
	230	and 'ssl' under the given source directory.
	231
	232	The OpenSSL configuration data file F<configdata.pm> I<must> reside in
	233	the current directory, I<or> perl must have the directory it resides in
	234	in its inclusion array. For the latter variant, a call like this would
	235	work:
	236
	237	perl -I../foo util/process_docs.pl {options ...}
	238
	239	=head1 OPTIONS
	240
	241	=over 4
	242
	243	=item B<--sourcedir>=I<dir>
	244
	245	Top directory where the source files are found.
	246
	247	=item B<--destdir>=I<dir>
	248
	249	Top directory where the resulting files should end up
	250
	251	=item B<--type>=B<man>\|B<html>
	252
	253	Type of output to produce. Currently supported are man pages and HTML files.
	254
579a6745 RL	255	=item B<--suffix>=I<suffix>
	256
	257	A suffix added to the extension. Only valid with B<--type>=B<man>
	258
2bc57c88 RL	259	=item B<--remove>
	260
	261	Instead of writing the files, remove them.
	262
	263	=item B<--dry-run>\|B<-n>
	264
	265	Do not perform any file writing, directory creation or file removal.
	266
	267	=item B<--debug>\|B<-D>
	268
	269	Print extra debugging output.
	270
	271	=back
	272
	273	=head1 COPYRIGHT
	274
83cf7abf	275	Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved.
2bc57c88	276
9059ab42	277	Licensed under the Apache License 2.0 (the "License"). You may not use
2bc57c88 RL	278	this file except in compliance with the License. You can obtain a copy
	279	in the file LICENSE in the source distribution or at
	280	https://www.openssl.org/source/license.html
	281
	282	=cut