This file describes how the developer side of man pages work in PMIx.
The Definitive Source Of Truth man pages are the Markdown man pages in
this directory (i.e., the files ending in .<digit>.md. If you want to
edit man pages, you need to edit the .<digit>.md pages. Do NOT edit
the .<digit> nroff man pages directly; these files are automatically
generated -- you will lose any manual edits the next time those files
are generated.
The Markdown web pages are rendered in two different ways:
1. Nroff man pages. These man pages are put into the `master` branch
and later included in PMIx distribution tarballs.
2. HTML. The http://open-mpi.github.io/pmix/ web site (which is
served by the Github web servers) automatically renders the content
of the `gh-pages` branch of the PMIx repo.
Markdown syntax
===============
The definitive man pages are the Markdown man pages. To edit them,
you need to understand the syntax used in these files.
The canonical reference for Markdown is here:
http://daringfireball.net/projects/markdown/syntax
Note, however, that the PMIx Markdown man pages are served via
the Github Pages web servers, which use a system called Jekyll to
render the Markdown into HTML (https://github.com/jekyll/jekyll).
As such, there are a few Jekyll annotations in the PMIx Markdown
pages (so that they can be served up properly from Github's web
servers).
If you're familiar with Markdown, you should be ok. But there are a
small number differences and quirks with which you should be familiar:
1. The first few lines of each file are a YAML header and include
directive for Jekyll. DO NOT REMOVE THIS HEADER (or the file will
not render to HTML properly when served up from Github's web
servers). Here's a sample YAML header from pmix.7.md:
---
layout: page
title: PMIx(7)
tagline: PMIx Programmer's Manual
---
{% include JB/setup %}
The whole block is needed, and it must be the first input in the
file.
2. In Github-flavored Markdown, you may be used to using "fenced
blocks" for multi-line code blocks, like this:
```c
void my_c_code(void) {
int i;
/* Hello, world */
}
```
Such fenced blocks will not work in Jekyll. Instead, you must
delineate your code blocks with Jekyll delimiters:
{% highlight c %}
void my_c_code(void) {
int i;
/* Hello, world */
}
{% endhighlight %}
This will result in a pretty code box in the rendered HTML output,
and it will be syntax highlighted for the C language. Leave the
"c" out of the first directive if your multi-line block is not C
code, and then it won't do C syntax highlighting.
3. The PMIx man pages are full of 2-level lists of things. E.g.,
lists of functions, and then in some of the functions, there is a
sub-list of flags that can be used with that function.
The convention used in the PMIx man pages is to highlight a
word/phrase representing each list item. Then use a ":" to start
the next line that describes that item. For example:
*PMIX_FLOAT*
: A single-precision floating point value (IEEE 754).
This will make the token "PMIX_FLOAT" be highlighted in both
HTML and nroff output, and then the paragraph that comes after it
will be properly delimited and indented.
To make a sub-list inside an item, use the same format, but prefix
the sub-list items with "-", like this:
*scope*
: Flag that controls the visible scope of the data.
- *PMIX_GLOBAL*
: Indicates that the data is to be visible to all applications executed
by this user.
4. There may be a small number of places in the PMIx man pages where
there are unnumbered lists with deliberate line breaks. For
example:
foo / bar
baz / goo
: Something really intelligent
Note the first line is "foo / bar", and then there is
a deliberate line break, and then the second line is "baz / goo".
To effect the deliberate line break, you have to put two blank
spaces after "bar". To show that graphically (showing "_"
for " "):
foo / bar__
baz / goo
: Something really intelligent
5. The "SEE ALSO" items at the end of each man page are linked to
their corresponding man pages. Note that the links are made to
".html" files -- *not* ".md" files. If you care, the reason is
because the Github web servers statically generate .html files from
the .md files when you git push to the gh-pages branch. Hence, the
man pages are actually served from static .html files on the Github
web servers.
Also, since links are meaningless in nroff, they are effectively
ignored in the resulting nroff output.
Workflow
========
The workflow is like this:
1. Developer edits .<digit>.md files for new changes.
2. In a perfect world, the developer makes perfect edits and pushes
the changes up to `master`. An automated cron job will eventually
notice the new pages, and do two things:
2a. Copy the modified Markdown pages to the `gh-master` branch (so
that they go live on the web site).
2b. Re-generate any relevant nroff man pages in `master`.
The automated cron job actually does exist and does these things,
but it should only be relied upon once a developer is sure that
their changes to the Markdown man pages are correct.
3. To check that the changes will render properly, developers should
do two things:
3a. Run "make nroff". This will convert all the Markdown man pages
into nroff man pages (in the man/ directory). Check to ensure
that your changes look appropriate in the rendered nroff
output.
*CAUTION* The "pandoc" utility is used to generate the nroff
files from the Markdown source. Different versions of pandoc
will generate slightly different nroff output. Meaning: when
you run "make nroff", you might end up changing every nroff man
page, simply because your version of pandoc is different than
the last person who ran it. Please only check in your changes,
if possible.
3b. Check out the `gh-pages` branch from PMIx and copy any
modified Markdown pages into the "master/man" directory (i.e.,
the directory for man pages from the master development
branch).
Then run the "jekyll serve" command from the top-level
directory in `gh-pages`. This runs a local web server on your
computer and renders the Markdown files into HTML such that you
can point a browser to http://127.0.0.1:4000 and see the web
site.
If you make any changes to files in the tree where "jekyll" is
running, Jekyll will notice the changes and automatically
re-generate the relevant HTML. Meaning: you can just refresh
the page from http://127.0.0.1:4000 in your browser and you'll
see your changes -- there's no need to restart Jekyll to force
it to notice new changes.
