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.
