Skip to content

Commit 7ace873

Browse files
jsquyresjsquyres
committed
Add MPI_T.5 man page for Open MPI-specific info
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 <[email protected]>
1 parent 0dce61b commit 7ace873

15 files changed

+908
-544
lines changed

‎HACKING

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,3 +247,26 @@ If you do not have Flex installed, it can be downloaded from the
247247
following URL:
248248

249249
https://github.com/westes/flex
250+
251+
Use of Pandoc
252+
=============
253+
254+
Similar to prior sections, you need to read/care about this section
255+
*ONLY* if you are building from a developer's tree (i.e., a Git clone
256+
of the Open MPI source tree). If you have an Open MPI distribution
257+
tarball, the contents of this section are optional -- you can (and
258+
probably should) skip reading this section.
259+
260+
The Pandoc tool is used to generate Open MPI's man pages.
261+
Specifically: Open MPI's man pages are written in Markdown; Pandoc is
262+
the tool that converts that Markdown to nroff (i.e., the format of man
263+
pages).
264+
265+
You must have Pandoc >=v1.12 when building Open MPI from a developer's
266+
tree. If configure cannot find Pandoc >=v1.12, it will abort.
267+
268+
If you need to install Pandoc, check your operating system-provided
269+
packages (to include MacOS Homebrew and MacPorts). The Pandoc project
270+
itself also offers binaries for their releases:
271+
272+
https://pandoc.org/

‎Makefile.ompi-rules

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
# $HEADER$
1010
#
1111

12+
MD2NROFF = $(OMPI_TOP_SRCDIR)/config/md2nroff.pl
13+
1214
TRIM_OPTIONS=
1315
if ! MAN_PAGE_BUILD_MPIFH_BINDINGS
1416
TRIM_OPTIONS += --nofortran
@@ -17,6 +19,8 @@ if ! MAN_PAGE_BUILD_USEMPIF08_BINDINGS
1719
TRIM_OPTIONS += --nof08
1820
endif
1921

22+
# JMS This rule can be deleted once all man pages have been converted
23+
# to markdown.
2024
.1in.1:
2125
$(OMPI_V_GEN) $(top_srcdir)/config/make_manpage.pl \
2226
--package-name='@PACKAGE_NAME@' \
@@ -26,6 +30,8 @@ endif
2630
--input=$< \
2731
--output=$@
2832

33+
# JMS This rule can be deleted once all man pages have been converted
34+
# to markdown.
2935
.3in.3:
3036
$(OMPI_V_GEN) $(top_srcdir)/config/make_manpage.pl \
3137
--package-name='@PACKAGE_NAME@' \
@@ -36,6 +42,8 @@ endif
3642
--input=$< \
3743
--output=$@
3844

45+
# JMS This rule can be deleted once all man pages have been converted
46+
# to markdown.
3947
.7in.7:
4048
$(OMPI_V_GEN) $(top_srcdir)/config/make_manpage.pl \
4149
--package-name='@PACKAGE_NAME@' \
@@ -45,6 +53,28 @@ endif
4553
--input=$< \
4654
--output=$@
4755

56+
%.1: %.1.md
57+
$(OMPI_V_GEN) $(MD2NROFF) --source=$< --dest=$@ --pandoc=$(PANDOC)
58+
59+
%.3: %.3.md
60+
$(OMPI_V_GEN) $(MD2NROFF) --source=$< --dest=$@ --pandoc=$(PANDOC)
61+
62+
%.5: %.5.md
63+
$(OMPI_V_GEN) $(MD2NROFF) --source=$< --dest=$@ --pandoc=$(PANDOC)
64+
65+
%.7: %.7.md
66+
$(OMPI_V_GEN) $(MD2NROFF) --source=$< --dest=$@ --pandoc=$(PANDOC)
67+
68+
# It is an error to "configure --disable-man-pages" and then try to
69+
# "make dist".
70+
if !OPAL_ENABLE_MAN_PAGES
71+
dist-hook:
72+
@echo "************************************************************************************"
73+
@echo "ERROR: 'make dist' inoperable when Open MPI is configured with --disable-man-pages"
74+
@echo "************************************************************************************"
75+
@/bin/false
76+
endif
77+
4878
# A little verbosity magic; "make" will show the terse output. "make
4979
# V=1" will show the actual commands used (just like the other
5080
# Automake-generated compilation/linker rules).

‎config/Makefile.am

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,8 @@ EXTRA_DIST = \
2929
ltmain_pgi_tp.diff \
3030
opal_mca_priority_sort.pl \
3131
find_common_syms \
32-
make_manpage.pl
32+
make_manpage.pl \
33+
md2nroff.pl
3334

3435
maintainer-clean-local:
3536
rm -f opal_get_version.sh

‎config/md2nroff.pl

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
#!/usr/bin/env perl
2+
#
3+
# Copyright (c) 2020 Cisco Systems, Inc. All rights reserved.
4+
# $COPYRIGHT$
5+
#
6+
# Additional copyrights may follow
7+
#
8+
# $HEADER$
9+
#
10+
11+
use strict;
12+
13+
use IPC::Open3;
14+
use File::Basename;
15+
use Getopt::Long;
16+
17+
#--------------------------------------------------------------------------
18+
19+
my $source_arg;
20+
my $dest_arg;
21+
my $pandoc_arg = "pandoc";
22+
my $help_arg;
23+
my $verbose_arg;
24+
25+
my $ok = Getopt::Long::GetOptions("source=s" => \$source_arg,
26+
"dest=s" => \$dest_arg,
27+
"pandoc=s" => \$pandoc_arg,
28+
"help" => \$help_arg,
29+
"verbose" => \$verbose_arg);
30+
31+
if (!$source_arg || !$dest_arg) {
32+
print("Must specify --source and --dest\n");
33+
$ok = 0;
34+
}
35+
36+
if (!$ok || $help_arg) {
37+
print "Invalid command line argument.\n\n"
38+
if (!$ok);
39+
print "Options:
40+
--source FILE Source Markdown filename
41+
--dest FILE Destination nroff file
42+
--pandoc FILE Location of pandoc executable
43+
--help This help list
44+
--verbose Be verbose when running\n";
45+
exit($ok ? 0 : 1);
46+
}
47+
48+
#--------------------------------------------------------------------------
49+
50+
# Read in the source
51+
die "Error: $source_arg does not exist"
52+
if (! -f $source_arg);
53+
54+
my $source_content;
55+
open(FILE, $source_arg) ||
56+
die "Can't open $source_arg";
57+
$source_content .= $_
58+
while(<FILE>);
59+
close(FILE);
60+
61+
#--------------------------------------------------------------------------
62+
63+
# Figure out the section of man page
64+
die "Cannot figure out man page section from source filename"
65+
if (!($source_arg =~ m/(\d+).md$/));
66+
my $man_section = $1;
67+
68+
my $shortfile = basename($source_arg);
69+
$shortfile =~ s/\.$man_section\.md$//;
70+
71+
#--------------------------------------------------------------------------
72+
73+
my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime();
74+
my $today = sprintf("%04d-%02d-%02d", ($year+1900), $mon, $mday);
75+
76+
# Run opal_get_version.sh to get the OMPI version.
77+
my $config_dir = dirname($0);
78+
my $get_version = "$config_dir/opal_get_version.sh";
79+
my $VERSION_file = "$config_dir/../VERSION";
80+
my $out = `$get_version $VERSION_file --full`;
81+
chomp($out);
82+
83+
# Pandoc does not handle markdown links in output nroff properly, so
84+
# just remove all links. Specifically: some versions of Pandoc ignore
85+
# the links, but others handle it badly.
86+
$source_content =~ s/\[(.+)\]\((.+)\)/\1/g;
87+
88+
# Add the pandoc header
89+
$source_content = "---
90+
section: $man_section
91+
title: $shortfile
92+
header: Open MPI
93+
footer: $today
94+
---
95+
96+
$source_content";
97+
98+
#--------------------------------------------------------------------------
99+
100+
print("*** Processing: $source_arg --> $dest_arg\n")
101+
if ($verbose_arg);
102+
103+
my $pid = open3(my $child_stdin, my $child_stdout, my $child_stderr,
104+
"$pandoc_arg -s --from=markdown --to=man");
105+
print $child_stdin $source_content;
106+
close($child_stdin);
107+
my $pandoc_rendered;
108+
$pandoc_rendered .= $_
109+
while(<$child_stdout>);
110+
close($child_stdout);
111+
close($child_stderr)
112+
if ($child_stderr);
113+
waitpid($pid, 0);
114+
115+
print("Writing new file $dest_arg\n")
116+
if ($verbose_arg);
117+
118+
# Make the target directory if it does not exist (needed for VPATH
119+
# builds)
120+
my $dest_dir = dirname($dest_arg);
121+
mkdir($dest_dir)
122+
if (! -d $dest_dir);
123+
124+
# Write the output file
125+
open(FILE, ">$dest_arg") ||
126+
die "Can't open $dest_arg for writing";
127+
print FILE $pandoc_rendered;
128+
close(FILE);
129+
130+
exit(0);

‎config/ompi_config_files.m4

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,9 @@ AC_DEFUN([OMPI_CONFIG_FILES],[
4545
ompi/mpi/tool/Makefile
4646
ompi/mpi/tool/profile/Makefile
4747

48+
ompi/mpi/man/man3/Makefile
49+
ompi/mpi/man/man5/Makefile
50+
4851
ompi/tools/ompi_info/Makefile
4952
ompi/tools/wrappers/Makefile
5053
ompi/tools/wrappers/mpicc-wrapper-data.txt

‎config/opal_setup_man_pages.m4

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
dnl -*- shell-script -*-
2+
dnl
3+
dnl Copyright (c) 2020 Cisco Systems, Inc. All rights reserved.
4+
dnl
5+
dnl $COPYRIGHT$
6+
dnl
7+
dnl Additional copyrights may follow
8+
dnl
9+
dnl $HEADER$
10+
dnl
11+
12+
dnl
13+
dnl Just in case someone looks for it here someday, here is a
14+
dnl conveninent reference for what Markdown pandoc supports:
15+
dnl
16+
dnl https://rmarkdown.rstudio.com/authoring_pandoc_markdown.html
17+
dnl
18+
19+
AC_DEFUN([OPAL_SETUP_MAN_PAGES],[
20+
AC_ARG_ENABLE(man-pages,
21+
[AC_HELP_STRING([--disable-man-pages],
22+
[Do not generate/install man pages (default: enable)])])
23+
24+
PANDOC=
25+
OPAL_ENABLE_MAN_PAGES=0
26+
AC_MSG_CHECKING([if want man pages])
27+
AS_IF([test -z "$enable_man_pages" || test "$enable_man_pages" = "yes"],
28+
[AC_MSG_RESULT([yes])
29+
OPAL_ENABLE_MAN_PAGES=1
30+
_OPAL_SETUP_PANDOC],
31+
[AC_MSG_RESULT([no])])
32+
33+
AC_SUBST(PANDOC)
34+
AM_CONDITIONAL([OPAL_ENABLE_MAN_PAGES], [test $OPAL_ENABLE_MAN_PAGES -eq 1])
35+
])
36+
37+
dnl Back-end pandoc setup
38+
AC_DEFUN([_OPAL_SETUP_PANDOC],[
39+
OPAL_VAR_SCOPE_PUSH([min_major_version min_minor_version pandoc_version pandoc_major pandoc_minor])
40+
41+
# If we need to generate man pages, we need pandoc >v1.12.
42+
AC_PATH_PROG([PANDOC], [pandoc])
43+
44+
# If we found Pandoc, check its version. We need >=v1.12.
45+
# To be clear: I know that v1.12 works, and I know that v1.9 does not
46+
# work. I did not test the versions in between to know exactly what
47+
# the lowest version is that works. Someone is free to update this
48+
# check someday to be more accurate if they wish.
49+
min_major_version=1
50+
min_minor_version=12
51+
AS_IF([test -n "$PANDOC"],
52+
[pandoc_version=`pandoc --version | head -n 1 | awk '{ print $[2] }'`
53+
pandoc_major=`echo $pandoc_version | cut -d\. -f1`
54+
pandoc_minor=`echo $pandoc_version | cut -d\. -f2`
55+
AC_MSG_CHECKING([pandoc version])
56+
AC_MSG_RESULT([major: $pandoc_major, minor: $pandoc_minor])
57+
58+
AC_MSG_CHECKING([if pandoc version is >=v$min_major_version.$min_minor_version])
59+
AS_IF([test $pandoc_major -lt $min_major_version], [PANDOC=])
60+
AS_IF([test $pandoc_major -eq $min_major_version && test $pandoc_minor -lt $min_minor_version],
61+
[PANDOC=])
62+
AS_IF([test -n "$PANDOC"],
63+
[AC_MSG_RESULT([yes])],
64+
[AC_MSG_RESULT([no])])
65+
])
66+
67+
AS_IF([test -z "$PANDOC" || test -n "`echo $PANDOC | $GREP missing`"],
68+
[AS_IF([test ! -f "$srcdir/ompi/mpi/man/man5/MPI_T.5"],
69+
[AC_MSG_WARN([*** Could not find a suitable pandoc on your system.])
70+
AC_MSG_WARN([*** You need pandoc >=$min_major_version.$min_minor_version to build Open MPI man pages.])
71+
AC_MSG_WARN([*** See pandoc.org.])
72+
AC_MSG_WARN([*** NOTE: If you are building from a tarball downloaded from www.open-mpi.org, you do not need Pandoc])
73+
AC_MSG_ERROR([Cannot continue])
74+
])
75+
])
76+
77+
OPAL_VAR_SCOPE_POP
78+
])

‎configure.ac

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -981,6 +981,12 @@ if test -z "$LEX" || \
981981
fi
982982
fi
983983

984+
#
985+
# Setup man page processing
986+
#
987+
988+
OPAL_SETUP_MAN_PAGES
989+
984990
#
985991
# File system case sensitivity
986992
#

‎ompi/Makefile.am

Lines changed: 7 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,9 @@ SUBDIRS = \
9898
mpi/fortran/use-mpi-f08 \
9999
mpi/fortran/mpiext-use-mpi-f08 \
100100
$(MCA_ompi_FRAMEWORK_COMPONENT_DSO_SUBDIRS) \
101-
$(OMPI_CONTRIB_SUBDIRS)
101+
$(OMPI_CONTRIB_SUBDIRS) \
102+
mpi/man/man3 \
103+
mpi/man/man5
102104

103105
if OMPI_WANT_JAVA_BINDINGS
104106
SUBDIRS += \
@@ -131,7 +133,9 @@ DIST_SUBDIRS = \
131133
$(OMPI_MPIEXT_ALL_SUBDIRS) \
132134
$(MCA_ompi_FRAMEWORKS_SUBDIRS) \
133135
$(MCA_ompi_FRAMEWORK_COMPONENT_ALL_SUBDIRS) \
134-
$(OMPI_CONTRIB_DIST_SUBDIRS)
136+
$(OMPI_CONTRIB_DIST_SUBDIRS) \
137+
mpi/man/man3 \
138+
mpi/man/man5
135139

136140
# Build the main MPI library
137141

@@ -163,7 +167,6 @@ noinst_LTLIBRARIES =
163167
include_HEADERS =
164168
dist_ompidata_DATA =
165169
lib@OMPI_LIBMPI_NAME@_la_SOURCES += $(headers)
166-
nodist_man_MANS =
167170

168171
# Conditionally install the header files
169172

@@ -190,27 +193,11 @@ include runtime/Makefile.am
190193
include win/Makefile.am
191194
include tools/Makefile.am
192195
include mpi/Makefile.am
193-
include mpi/man/man3/Makefile.extra
194196
include mpiext/Makefile.am
195197
include patterns/net/Makefile.am
196198
include patterns/comm/Makefile.am
197199
include mca/Makefile.am
198200
include util/Makefile.am
199201

200-
# Ensure that the man page directory exists before we try to make man
201-
# page files (because ompi/mpi/man/man3 has no config.status-generated
202-
# Makefile)
203-
dir_stamp = $(top_builddir)/$(subdir)/mpi/man/man3/.dir-stamp
204-
205-
# Also ensure that the man pages are rebuilt if the opal_config.h file
206-
# changes (e.g., configure was run again, meaning that the release
207-
# date or version may have changed)
208-
$(nodist_man_MANS): $(dir_stamp) $(top_builddir)/opal/include/opal_config.h
209-
210-
$(dir_stamp):
211-
$(MKDIR_P) `dirname $@`
212-
touch "$@"
213-
214-
# Remove the generated man pages
215202
distclean-local:
216-
rm -f $(nodist_man_MANS) $(dir_stamp) mpiext/static-components.h
203+
rm -f mpiext/static-components.h

0 commit comments

Comments
 (0)