7ace873b50
Also added infrastructure to have developers write man pages in Markdown (vs. nroff). Pandoc >=v1.12 is used to convert those Markdown files into actual nroff man pages. Dist tarballs will contain generated nroff man pages; we don't want to require users to have Pandoc installed. Anyone who builds Open MPI from a git clone will need to have Pandoc installed (similar to how we treat Flex). You can opt out of Open MPI's Pandoc-generated man pages by configuring Open MPI with --disable-man-pages. This will also disable "make dist" (i.e., "make dist" will error if you configured with --disable-man-pages). Also removed the stuff to re-generate man pages. This commit also: 1. Includes a new man page, written in Markdown (ompi/mpi/man/man5/MPI_T.5.md) that contains Open MPI-specific information about MPI_T. 2. Includes a converted ompi/mpi/man/man3/MPI_T_init_thread.3.md (from MPI_T_init_thread.3in -- i.e., nroff) just to show that Markdown can be used throughout the Open MPI code base for man pages. 3. Made the Makefiles in ompi/mpi/man/man?/ be full-fledged Makefile.am's (vs. Makefile.extras that are designed to be included in ompi/Makefile.am). It is more convenient to test generation / installation of man pages when you can "make" and "make install" in their respective directories (vs. doing a build / install for the entire ompi project). 4. Removed logic from ompi/Makefile.am that re-generated man pages if opal_config.h changes. Other man pages -- hopefully all of them! -- will be converted to Markdown over time. Signed-off-by: Jeff Squyres <jsquyres@cisco.com>
131 строка
3.4 KiB
Perl
Исполняемый файл
131 строка
3.4 KiB
Perl
Исполняемый файл
#!/usr/bin/env perl
|
|
#
|
|
# Copyright (c) 2020 Cisco Systems, Inc. All rights reserved.
|
|
# $COPYRIGHT$
|
|
#
|
|
# Additional copyrights may follow
|
|
#
|
|
# $HEADER$
|
|
#
|
|
|
|
use strict;
|
|
|
|
use IPC::Open3;
|
|
use File::Basename;
|
|
use Getopt::Long;
|
|
|
|
#--------------------------------------------------------------------------
|
|
|
|
my $source_arg;
|
|
my $dest_arg;
|
|
my $pandoc_arg = "pandoc";
|
|
my $help_arg;
|
|
my $verbose_arg;
|
|
|
|
my $ok = Getopt::Long::GetOptions("source=s" => \$source_arg,
|
|
"dest=s" => \$dest_arg,
|
|
"pandoc=s" => \$pandoc_arg,
|
|
"help" => \$help_arg,
|
|
"verbose" => \$verbose_arg);
|
|
|
|
if (!$source_arg || !$dest_arg) {
|
|
print("Must specify --source and --dest\n");
|
|
$ok = 0;
|
|
}
|
|
|
|
if (!$ok || $help_arg) {
|
|
print "Invalid command line argument.\n\n"
|
|
if (!$ok);
|
|
print "Options:
|
|
--source FILE Source Markdown filename
|
|
--dest FILE Destination nroff file
|
|
--pandoc FILE Location of pandoc executable
|
|
--help This help list
|
|
--verbose Be verbose when running\n";
|
|
exit($ok ? 0 : 1);
|
|
}
|
|
|
|
#--------------------------------------------------------------------------
|
|
|
|
# Read in the source
|
|
die "Error: $source_arg does not exist"
|
|
if (! -f $source_arg);
|
|
|
|
my $source_content;
|
|
open(FILE, $source_arg) ||
|
|
die "Can't open $source_arg";
|
|
$source_content .= $_
|
|
while(<FILE>);
|
|
close(FILE);
|
|
|
|
#--------------------------------------------------------------------------
|
|
|
|
# Figure out the section of man page
|
|
die "Cannot figure out man page section from source filename"
|
|
if (!($source_arg =~ m/(\d+).md$/));
|
|
my $man_section = $1;
|
|
|
|
my $shortfile = basename($source_arg);
|
|
$shortfile =~ s/\.$man_section\.md$//;
|
|
|
|
#--------------------------------------------------------------------------
|
|
|
|
my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime();
|
|
my $today = sprintf("%04d-%02d-%02d", ($year+1900), $mon, $mday);
|
|
|
|
# Run opal_get_version.sh to get the OMPI version.
|
|
my $config_dir = dirname($0);
|
|
my $get_version = "$config_dir/opal_get_version.sh";
|
|
my $VERSION_file = "$config_dir/../VERSION";
|
|
my $out = `$get_version $VERSION_file --full`;
|
|
chomp($out);
|
|
|
|
# Pandoc does not handle markdown links in output nroff properly, so
|
|
# just remove all links. Specifically: some versions of Pandoc ignore
|
|
# the links, but others handle it badly.
|
|
$source_content =~ s/\[(.+)\]\((.+)\)/\1/g;
|
|
|
|
# Add the pandoc header
|
|
$source_content = "---
|
|
section: $man_section
|
|
title: $shortfile
|
|
header: Open MPI
|
|
footer: $today
|
|
---
|
|
|
|
$source_content";
|
|
|
|
#--------------------------------------------------------------------------
|
|
|
|
print("*** Processing: $source_arg --> $dest_arg\n")
|
|
if ($verbose_arg);
|
|
|
|
my $pid = open3(my $child_stdin, my $child_stdout, my $child_stderr,
|
|
"$pandoc_arg -s --from=markdown --to=man");
|
|
print $child_stdin $source_content;
|
|
close($child_stdin);
|
|
my $pandoc_rendered;
|
|
$pandoc_rendered .= $_
|
|
while(<$child_stdout>);
|
|
close($child_stdout);
|
|
close($child_stderr)
|
|
if ($child_stderr);
|
|
waitpid($pid, 0);
|
|
|
|
print("Writing new file $dest_arg\n")
|
|
if ($verbose_arg);
|
|
|
|
# Make the target directory if it does not exist (needed for VPATH
|
|
# builds)
|
|
my $dest_dir = dirname($dest_arg);
|
|
mkdir($dest_dir)
|
|
if (! -d $dest_dir);
|
|
|
|
# Write the output file
|
|
open(FILE, ">$dest_arg") ||
|
|
die "Can't open $dest_arg for writing";
|
|
print FILE $pandoc_rendered;
|
|
close(FILE);
|
|
|
|
exit(0);
|