1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
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://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://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://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.
|
