This file describes how the developer side of man pages work in
libfabric.

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 libfabric distribution tarballs.

2. HTML.  The http:https://ofiwg.github.io/libfabric/ web site (which is
   served by the Github web servers) automatically renders the content
   of the `gh-pages` branch of the libfabric 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:https://daringfireball.net/projects/markdown/syntax

Note, however, that the libfabric 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 libfabric 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 fabric.7.md:

---
layout: page
title: fabric(7)
tagline: Libfabric Programmer's Manual
---
{% include JB/setup %}

   The whole block is needed, and it must be the first input in the
   file.

2. The libfabric 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 libfabric 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:

*FI_FLOAT_COMPLEX*
: An ordered pair of single-precision floating point values (IEEE
  754), with the first value representing the real portion of a
  complex number and the second representing the imaginary portion.

   This will make the token "FI_FLOAT_COMPLEX" 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:

*flags*
: Flags that control the configuration of the CQ.

- *FI_WRITE*
: Indicates that the application requires support for inserting user
  events into the CQ.  If this flag is set, then the fi_cq_write and
  fi_cq_writeerr operations must be supported by the provider.  If the
  FI_WRITE flag is not set, then the application may not invoke
  fi_cq_write of fi_cq_writeerr.

3. There's a small number of places in the libfabric man pages where
   there are unnumbered lists with deliberate line breaks.  For
   example:

fi_atomic / fi_atomicv  
fi_atomicto / fi_atomicmsg
: Initiates an atomic operation to remote memory

   Note the first line is "fi_atomic / fi_atomicv", and then there is
   a deliberate line break, and then the second line is "fi_atomicto /
   fi_atomicmsg".

   To effect the deliberate line break, you have to put two blank
   spaces after "fi_atomicv".  To show that graphically (showing "_"
   for " "):

fi_atomic / fi_atomicv__
fi_atomicto / fi_atomicmsg
: Initiates an atomic operation to remote memory

4. 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 libfabric 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:https://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:https://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.