README
1This file describes how the developer side of man pages work in
2libfabric.
3
4The Definitive Source Of Truth man pages are the Markdown man pages in
5this directory (i.e., the files ending in .<digit>.md. If you want to
6edit man pages, you need to edit the .<digit>.md pages. Do NOT edit
7the .<digit> nroff man pages directly; these files are automatically
8generated -- you will lose any manual edits the next time those files
9are generated.
10
11The Markdown web pages are rendered in two different ways:
12
131. Nroff man pages. These man pages are put into the `master` branch
14 and later included in libfabric distribution tarballs.
15
162. HTML. The http://ofiwg.github.io/libfabric/ web site (which is
17 served by the Github web servers) automatically renders the content
18 of the `gh-pages` branch of the libfabric repo.
19
20Markdown syntax
21===============
22
23The definitive man pages are the Markdown man pages. To edit them,
24you need to understand the syntax used in these files.
25
26The canonical reference for Markdown is here:
27
28 http://daringfireball.net/projects/markdown/syntax
29
30Note, however, that the libfabric Markdown man pages are served via
31the Github Pages web servers, which use a system called Jekyll to
32render the Markdown into HTML (https://github.com/jekyll/jekyll).
33As such, there are a few Jekyll annotations in the libfabric Markdown
34pages (so that they can be served up properly from Github's web
35servers).
36
37If you're familiar with Markdown, you should be ok. But there are a
38small number differences and quirks with which you should be familiar:
39
401. The first few lines of each file are a YAML header and include
41 directive for Jekyll. DO NOT REMOVE THIS HEADER (or the file will
42 not render to HTML properly when served up from Github's web
43 servers). Here's a sample YAML header from fabric.7.md:
44
45---
46layout: page
47title: fabric(7)
48tagline: Libfabric Programmer's Manual
49---
50{% include JB/setup %}
51
52 The whole block is needed, and it must be the first input in the
53 file.
54
552. The libfabric man pages are full of 2-level lists of things. E.g.,
56 lists of functions, and then in some of the functions, there is a
57 sub-list of flags that can be used with that function.
58
59 The convention used in the libfabric man pages is to highlight a
60 word/phrase representing each list item. Then use a ":" to start
61 the next line that describes that item. For example:
62
63*FI_FLOAT_COMPLEX*
64: An ordered pair of single-precision floating point values (IEEE
65 754), with the first value representing the real portion of a
66 complex number and the second representing the imaginary portion.
67
68 This will make the token "FI_FLOAT_COMPLEX" be highlighted in both
69 HTML and nroff output, and then the paragraph that comes after it
70 will be properly delimited and indented.
71
72 To make a sub-list inside an item, use the same format, but prefix
73 the sub-list items with "-", like this:
74
75*flags*
76: Flags that control the configuration of the CQ.
77
78- *FI_WRITE*
79: Indicates that the application requires support for inserting user
80 events into the CQ. If this flag is set, then the fi_cq_write and
81 fi_cq_writeerr operations must be supported by the provider. If the
82 FI_WRITE flag is not set, then the application may not invoke
83 fi_cq_write of fi_cq_writeerr.
84
853. There's a small number of places in the libfabric man pages where
86 there are unnumbered lists with deliberate line breaks. For
87 example:
88
89fi_atomic / fi_atomicv
90fi_atomicto / fi_atomicmsg
91: Initiates an atomic operation to remote memory
92
93 Note the first line is "fi_atomic / fi_atomicv", and then there is
94 a deliberate line break, and then the second line is "fi_atomicto /
95 fi_atomicmsg".
96
97 To effect the deliberate line break, you have to put two blank
98 spaces after "fi_atomicv". To show that graphically (showing "_"
99 for " "):
100
101fi_atomic / fi_atomicv__
102fi_atomicto / fi_atomicmsg
103: Initiates an atomic operation to remote memory
104
1054. The "SEE ALSO" items at the end of each man page are linked to
106 their corresponding man pages. Note that the links are made to
107 ".html" files -- *not* ".md" files. If you care, the reason is
108 because the Github web servers statically generate .html files from
109 the .md files when you git push to the gh-pages branch. Hence, the
110 man pages are actually served from static .html files on the Github
111 web servers.
112
113 Also, since links are meaningless in nroff, they are effectively
114 ignored in the resulting nroff output.
115
116Workflow
117========
118
119The workflow is like this:
120
1211. Developer edits .<digit>.md files for new changes.
122
1232. In a perfect world, the developer makes perfect edits and pushes
124 the changes up to `master`. An automated cron job will eventually
125 notice the new pages, and do two things:
126
127 2a. Copy the modified Markdown pages to the `gh-master` branch (so
128 that they go live on the web site).
129
130 2b. Re-generate any relevant nroff man pages in `master`.
131
132 The automated cron job actually does exist and does these things,
133 but it should only be relied upon once a developer is sure that
134 their changes to the Markdown man pages are correct.
135
1363. To check that the changes will render properly, developers should
137 do two things:
138
139 3a. Run "make nroff". This will convert all the Markdown man pages
140 into nroff man pages (in the man/ directory). Check to ensure
141 that your changes look appropriate in the rendered nroff
142 output.
143
144 *CAUTION* The "pandoc" utility is used to generate the nroff
145 files from the Markdown source. Different versions of pandoc
146 will generate slightly different nroff output. Meaning: when
147 you run "make nroff", you might end up changing every nroff man
148 page, simply because your version of pandoc is different than
149 the last person who ran it. Please only check in your changes,
150 if possible.
151
152 3b. Check out the `gh-pages` branch from libfabric and copy any
153 modified Markdown pages into the "master/man" directory (i.e.,
154 the directory for man pages from the master development
155 branch).
156
157 Then run the "jekyll serve" command from the top-level
158 directory in `gh-pages`. This runs a local web server on your
159 computer and renders the Markdown files into HTML such that you
160 can point a browser to http://127.0.0.1:4000 and see the web
161 site.
162
163 If you make any changes to files in the tree where "jekyll" is
164 running, Jekyll will notice the changes and automatically
165 re-generate the relevant HTML. Meaning: you can just refresh
166 the page from http://127.0.0.1:4000 in your browser and you'll
167 see your changes -- there's no need to restart Jekyll to force
168 it to notice new changes.
169