| 1 |
'\" t |
| 2 |
.\" Copyright 1992-1999, Rickard E. Faith <[email protected]> |
| 3 |
.\" Copyright 1992-1999, David A. Wheeler <[email protected]> |
| 4 |
.\" Copyright 2007, Michael Kerrisk <[email protected]> |
| 5 |
.\" Copyright, the authors of the Linux man-pages project |
| 6 |
.\" |
| 7 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 8 |
.\" |
| 9 |
.TH man-pages 7 2026-02-08 "Linux man-pages 6.18" |
| 10 |
.SH NAME |
| 11 |
man-pages \- conventions for writing Linux man pages |
| 12 |
.SH SYNOPSIS |
| 13 |
.B man |
| 14 |
.RI [ section ] |
| 15 |
.I title |
| 16 |
.SH DESCRIPTION |
| 17 |
This page describes the conventions that should be employed |
| 18 |
when writing man pages for the |
| 19 |
.IR "Linux man-pages project" , |
| 20 |
which documents the user-space API provided by the Linux kernel |
| 21 |
and the GNU C library. |
| 22 |
The project thus provides most of the pages in Section 2, |
| 23 |
many of the pages that appear in Sections 3, 4, and 7, |
| 24 |
and a few of the pages that appear in Sections 1, 5, and 8 |
| 25 |
of the man pages on a Linux system. |
| 26 |
The conventions described on this page may also be useful |
| 27 |
for authors writing man pages for other projects. |
| 28 |
.SS Sections of the manual pages |
| 29 |
The manual Sections are traditionally defined as follows: |
| 30 |
.TP |
| 31 |
.B 1 User commands (Programs) |
| 32 |
Commands that can be executed by the user from within |
| 33 |
a shell. |
| 34 |
.TP |
| 35 |
.B 2 System calls |
| 36 |
Functions which wrap operations performed by the kernel. |
| 37 |
.TP |
| 38 |
.B 3 Library calls |
| 39 |
All library functions excluding the system call wrappers |
| 40 |
(Most of the |
| 41 |
.I libc |
| 42 |
functions). |
| 43 |
.TP |
| 44 |
.B 4 Special files (devices) |
| 45 |
Files found in |
| 46 |
.I /dev |
| 47 |
which allow to access to devices through the kernel. |
| 48 |
.TP |
| 49 |
.B 5 File formats and configuration files |
| 50 |
Describes various human-readable file formats and configuration files. |
| 51 |
.TP |
| 52 |
.B 6 Games |
| 53 |
Games and funny little programs available on the system. |
| 54 |
.TP |
| 55 |
.B 7 Overview, conventions, and miscellaneous |
| 56 |
Overviews or descriptions of various topics, conventions, and protocols, |
| 57 |
character set standards, the standard filesystem layout, and miscellaneous |
| 58 |
other things. |
| 59 |
.TP |
| 60 |
.B 8 System management commands |
| 61 |
Commands like |
| 62 |
.BR mount (8), |
| 63 |
many of which only root can execute. |
| 64 |
.\" .TP |
| 65 |
.\" .B 9 Kernel routines |
| 66 |
.\" This is an obsolete manual section. |
| 67 |
.\" Once it was thought a good idea to document the Linux kernel here, |
| 68 |
.\" but in fact very little has been documented, and the documentation |
| 69 |
.\" that exists is outdated already. |
| 70 |
.\" There are better sources of |
| 71 |
.\" information for kernel developers. |
| 72 |
.SS Macro package |
| 73 |
New manual pages should be marked up using the |
| 74 |
.B groff an.tmac |
| 75 |
package described in |
| 76 |
.BR man (7). |
| 77 |
This choice is mainly for consistency: the vast majority of |
| 78 |
existing Linux manual pages are marked up using these macros. |
| 79 |
.SS Conventions for source file layout |
| 80 |
Please limit source code line length to no more than about 75 characters |
| 81 |
wherever possible. |
| 82 |
This helps avoid line-wrapping in some mail clients when patches are |
| 83 |
submitted inline. |
| 84 |
.SS Title line |
| 85 |
The first command in a man page should be a |
| 86 |
.B TH |
| 87 |
command: |
| 88 |
.P |
| 89 |
.RS |
| 90 |
.B \&.TH |
| 91 |
.I "title section date source manual-section" |
| 92 |
.RE |
| 93 |
.P |
| 94 |
The arguments of the command are as follows: |
| 95 |
.TP |
| 96 |
.I title |
| 97 |
The title of the man page. |
| 98 |
.TP |
| 99 |
.I section |
| 100 |
The section number in which the man page should be placed (e.g., |
| 101 |
.IR 7 ). |
| 102 |
.TP |
| 103 |
.I date |
| 104 |
The date of the last nontrivial change that was made to the man page. |
| 105 |
(Within the |
| 106 |
.I man-pages |
| 107 |
project, the necessary updates to these timestamps are handled |
| 108 |
automatically by scripts, so there is no need to manually update |
| 109 |
them as part of a patch.) |
| 110 |
Dates should be written in the form YYYY-MM-DD. |
| 111 |
.TP |
| 112 |
.I source |
| 113 |
The name and version of the project that provides the manual page |
| 114 |
(not necessarily the package that provides the functionality). |
| 115 |
.TP |
| 116 |
.I manual-section |
| 117 |
Normally, this should be empty, |
| 118 |
since the default value will be good. |
| 119 |
.\" |
| 120 |
.SS Sections within a manual page |
| 121 |
The list below shows conventional or suggested sections. |
| 122 |
Most manual pages should include at least the |
| 123 |
.B highlighted |
| 124 |
sections. |
| 125 |
Arrange a new manual page so that sections |
| 126 |
are placed in the order shown in the list. |
| 127 |
.P |
| 128 |
.RS |
| 129 |
.TS |
| 130 |
l l. |
| 131 |
\f[B]NAME\f[] |
| 132 |
LIBRARY [Normally only in Sections 2, 3] |
| 133 |
\f[B]SYNOPSIS\f[] |
| 134 |
CONFIGURATION [Normally only in Section 4] |
| 135 |
\f[B]DESCRIPTION\f[] |
| 136 |
OPTIONS [Normally only in Sections 1, 8] |
| 137 |
PARAMETERS |
| 138 |
EXIT STATUS [Normally only in Sections 1, 8] |
| 139 |
RETURN VALUE [Normally only in Sections 2, 3] |
| 140 |
.\" May 07: Few current man pages have an ERROR HANDLING section,,, |
| 141 |
.\" ERROR HANDLING, |
| 142 |
ERRORS [Typically only in Sections 2, 3] |
| 143 |
.\" May 07: Almost no current man pages have a USAGE section,,, |
| 144 |
.\" USAGE, |
| 145 |
.\" DIAGNOSTICS, |
| 146 |
.\" May 07: Almost no current man pages have a SECURITY section,,, |
| 147 |
.\" SECURITY, |
| 148 |
ENVIRONMENT |
| 149 |
FILES |
| 150 |
ATTRIBUTES [Normally only in Sections 2, 3] |
| 151 |
VERSIONS [Normally only in Sections 2, 3] |
| 152 |
STANDARDS |
| 153 |
HISTORY |
| 154 |
NOTES |
| 155 |
CAVEATS |
| 156 |
BUGS |
| 157 |
EXAMPLES |
| 158 |
.\" AUTHORS sections are discouraged |
| 159 |
AUTHORS [Discouraged] |
| 160 |
REPORTING BUGS [Not used in man-pages] |
| 161 |
COPYRIGHT [Not used in man-pages] |
| 162 |
\f[B]SEE ALSO\f[] |
| 163 |
.TE |
| 164 |
.RE |
| 165 |
.P |
| 166 |
.IR "Where a traditional heading would apply" ", " "please use it" ; |
| 167 |
this kind of consistency can make the information easier to understand. |
| 168 |
If you must, you can create your own |
| 169 |
headings if they make things easier to understand (this can |
| 170 |
be especially useful for pages in Sections 4 and 5). |
| 171 |
However, before doing this, consider whether you could use the |
| 172 |
traditional headings, with some subsections |
| 173 |
.RI ( .SS ) |
| 174 |
within those sections. |
| 175 |
.P |
| 176 |
The following list elaborates on the contents of each of |
| 177 |
the above sections. |
| 178 |
.TP |
| 179 |
.B NAME |
| 180 |
The name of this manual page. |
| 181 |
.IP |
| 182 |
See |
| 183 |
.BR man (7) |
| 184 |
for important details of the line(s) that should follow the |
| 185 |
.B .SH\~NAME |
| 186 |
command. |
| 187 |
All words in this line (including the word immediately |
| 188 |
following the "\[rs]\-") should be in lowercase, |
| 189 |
except where English or technical terminological convention |
| 190 |
dictates otherwise. |
| 191 |
.TP |
| 192 |
.B LIBRARY |
| 193 |
The library providing a symbol. |
| 194 |
.IP |
| 195 |
It shows the common name of the library, |
| 196 |
and in parentheses, |
| 197 |
the name of the library file |
| 198 |
and, if needed, the linker flag needed to link a program against it: |
| 199 |
.RI ( libfoo "[, " \-lfoo ]). |
| 200 |
.TP |
| 201 |
.B SYNOPSIS |
| 202 |
A brief summary of the command or function's interface. |
| 203 |
.IP |
| 204 |
For commands, this shows the syntax of the command and its arguments |
| 205 |
(including options); |
| 206 |
boldface is used for as-is text and italics are used to |
| 207 |
indicate replaceable arguments. |
| 208 |
Brackets ([]) surround optional arguments, vertical bars (|) |
| 209 |
separate choices, and ellipses (\&...) can be repeated. |
| 210 |
For functions, it shows any required data declarations or |
| 211 |
.B #include |
| 212 |
directives, followed by the function declaration. |
| 213 |
.IP |
| 214 |
Where a feature test macro must be defined in order to obtain |
| 215 |
the declaration of a function (or a variable) from a header file, |
| 216 |
then the SYNOPSIS should indicate this, as described in |
| 217 |
.BR feature_test_macros (7). |
| 218 |
.\" FIXME . Say something here about compiler options |
| 219 |
.TP |
| 220 |
.B CONFIGURATION |
| 221 |
Configuration details for a device. |
| 222 |
.IP |
| 223 |
This section normally appears only in Section 4 pages. |
| 224 |
.TP |
| 225 |
.B DESCRIPTION |
| 226 |
An explanation of what the program, function, or format does. |
| 227 |
.IP |
| 228 |
Discuss how it interacts with files and standard input, and what it |
| 229 |
produces on standard output or standard error. |
| 230 |
Omit internals and implementation details unless they're critical for |
| 231 |
understanding the interface. |
| 232 |
Describe the usual case; |
| 233 |
for information on command-line options of a program use the |
| 234 |
.B OPTIONS |
| 235 |
section. |
| 236 |
.\" If there is some kind of input grammar or complex set of subcommands, |
| 237 |
.\" consider describing them in a separate |
| 238 |
.\" .B USAGE |
| 239 |
.\" section (and just place an overview in the |
| 240 |
.\" .B DESCRIPTION |
| 241 |
.\" section). |
| 242 |
.IP |
| 243 |
When describing new behavior or new flags for |
| 244 |
a system call or library function, |
| 245 |
be careful to note the kernel or C library version |
| 246 |
that introduced the change. |
| 247 |
The preferred method of noting this information for flags is as part of a |
| 248 |
.B .TP |
| 249 |
list, in the following form (here, for a new system call flag): |
| 250 |
.RS 16 |
| 251 |
.TP |
| 252 |
.BR XYZ_FLAG " (since Linux 3.7)" |
| 253 |
Description of flag... |
| 254 |
.RE |
| 255 |
.IP |
| 256 |
Including version information is especially useful to users |
| 257 |
who are constrained to using older kernel or C library versions |
| 258 |
(which is typical in embedded systems, for example). |
| 259 |
.TP |
| 260 |
.B OPTIONS |
| 261 |
A description of the command-line options accepted by a |
| 262 |
program and how they change its behavior. |
| 263 |
.IP |
| 264 |
This section should appear only for Section 1 and 8 manual pages. |
| 265 |
.\" .TP |
| 266 |
.\" .B USAGE |
| 267 |
.\" describes the grammar of any sublanguage this implements. |
| 268 |
.TP |
| 269 |
.B PARAMETERS |
| 270 |
A description of the parameters of the function or program, |
| 271 |
and how they change its behavior. |
| 272 |
.TP |
| 273 |
.B EXIT STATUS |
| 274 |
A list of the possible exit status values of a program and |
| 275 |
the conditions that cause these values to be returned. |
| 276 |
.IP |
| 277 |
This section should appear only for Section 1 and 8 manual pages. |
| 278 |
.TP |
| 279 |
.B RETURN VALUE |
| 280 |
For Section 2 and 3 pages, this section gives a |
| 281 |
list of the values the library routine will return to the caller |
| 282 |
and the conditions that cause these values to be returned. |
| 283 |
.TP |
| 284 |
.B ERRORS |
| 285 |
For Section 2 and 3 manual pages, this is a list of the |
| 286 |
values that may be placed in |
| 287 |
.I errno |
| 288 |
in the event of an error, along with information about the cause |
| 289 |
of the errors. |
| 290 |
.IP |
| 291 |
Where several different conditions produce the same error, |
| 292 |
the preferred approach is to create separate list entries |
| 293 |
(with duplicate error names) for each of the conditions. |
| 294 |
This makes the separate conditions clear, may make the list easier to read, |
| 295 |
and allows metainformation |
| 296 |
(e.g., kernel version number where the condition first became applicable) |
| 297 |
to be more easily marked for each condition. |
| 298 |
.IP |
| 299 |
.IR "The error list should be in alphabetical order" . |
| 300 |
.TP |
| 301 |
.B ENVIRONMENT |
| 302 |
A list of all environment variables that affect the program or function |
| 303 |
and how they affect it. |
| 304 |
.TP |
| 305 |
.B FILES |
| 306 |
A list of the files the program or function uses, such as |
| 307 |
configuration files, startup files, |
| 308 |
and files the program directly operates on. |
| 309 |
.IP |
| 310 |
Give the full pathname of these files, and use the installation |
| 311 |
process to modify the directory part to match user preferences. |
| 312 |
For many programs, the default installation location is in |
| 313 |
.IR /usr/local , |
| 314 |
so your base manual page should use |
| 315 |
.I /usr/local |
| 316 |
as the base. |
| 317 |
.\" May 07: Almost no current man pages have a DIAGNOSTICS section; |
| 318 |
.\" "RETURN VALUE" or "EXIT STATUS" is preferred. |
| 319 |
.\" .TP |
| 320 |
.\" .B DIAGNOSTICS |
| 321 |
.\" gives an overview of the most common error messages and how to |
| 322 |
.\" cope with them. |
| 323 |
.\" You don't need to explain system error messages |
| 324 |
.\" or fatal signals that can appear during execution of any program |
| 325 |
.\" unless they're special in some way to the program. |
| 326 |
.\" |
| 327 |
.\" May 07: Almost no current man pages have a SECURITY section. |
| 328 |
.\".TP |
| 329 |
.\".B SECURITY |
| 330 |
.\"discusses security issues and implications. |
| 331 |
.\"Warn about configurations or environments that should be avoided, |
| 332 |
.\"commands that may have security implications, and so on, especially |
| 333 |
.\"if they aren't obvious. |
| 334 |
.\"Discussing security in a separate section isn't necessary; |
| 335 |
.\"if it's easier to understand, place security information in the |
| 336 |
.\"other sections (such as the |
| 337 |
.\" .B DESCRIPTION |
| 338 |
.\" or |
| 339 |
.\" .B USAGE |
| 340 |
.\" section). |
| 341 |
.\" However, please include security information somewhere! |
| 342 |
.TP |
| 343 |
.B ATTRIBUTES |
| 344 |
A summary of various attributes of the function(s) documented on this page. |
| 345 |
See |
| 346 |
.BR attributes (7) |
| 347 |
for further details. |
| 348 |
.TP |
| 349 |
.B VERSIONS |
| 350 |
A summary of systems where the API performs differently, |
| 351 |
or where there's a similar API. |
| 352 |
.TP |
| 353 |
.B STANDARDS |
| 354 |
A description of any standards or conventions that relate to the function |
| 355 |
or command described by the manual page. |
| 356 |
.IP |
| 357 |
The preferred terms to use for the various standards are listed as |
| 358 |
headings in |
| 359 |
.BR standards (7). |
| 360 |
.IP |
| 361 |
This section should note the current standards to which the API conforms to. |
| 362 |
.IP |
| 363 |
If the API is not governed by any standards but commonly |
| 364 |
exists on other systems, note them. |
| 365 |
If the call is Linux-specific or GNU-specific, note this. |
| 366 |
If it's available in the BSDs, note that. |
| 367 |
.IP |
| 368 |
If this section consists of just a list of standards |
| 369 |
(which it commonly does), |
| 370 |
terminate the list with a period (\[aq].\[aq]). |
| 371 |
.TP |
| 372 |
.B HISTORY |
| 373 |
A brief summary of the Linux kernel or glibc versions where a |
| 374 |
system call or library function appeared, |
| 375 |
or changed significantly in its operation. |
| 376 |
.IP |
| 377 |
As a general rule, every new interface should |
| 378 |
include a HISTORY section in its manual page. |
| 379 |
Unfortunately, |
| 380 |
many existing manual pages don't include this information |
| 381 |
(since there was no policy to do so when they were written). |
| 382 |
Patches to remedy this are welcome, |
| 383 |
but, from the perspective of programmers writing new code, |
| 384 |
this information probably matters only in the case of kernel |
| 385 |
interfaces that have been added in Linux 2.4 or later |
| 386 |
(i.e., changes since Linux 2.2), |
| 387 |
and library functions that have been added to glibc since glibc 2.1 |
| 388 |
(i.e., changes since glibc 2.0). |
| 389 |
.IP |
| 390 |
The |
| 391 |
.BR syscalls (2) |
| 392 |
manual page also provides information about kernel versions |
| 393 |
in which various system calls first appeared. |
| 394 |
.P |
| 395 |
Old versions of standards should be mentioned here, |
| 396 |
rather than in STANDARDS, |
| 397 |
for example, |
| 398 |
SUS, SUSv2, and XPG, or the SVr4 and 4.xBSD implementation standards. |
| 399 |
.TP |
| 400 |
.B NOTES |
| 401 |
Miscellaneous notes. |
| 402 |
.IP |
| 403 |
For Section 2 and 3 man pages you may find it useful to include |
| 404 |
subsections |
| 405 |
.RB ( SS ) |
| 406 |
named |
| 407 |
.I Linux\~Notes |
| 408 |
and |
| 409 |
.IR glibc\~Notes . |
| 410 |
.IP |
| 411 |
In Section 2, use the heading |
| 412 |
.I "C library/kernel differences" |
| 413 |
to mark off notes that describe the differences (if any) between |
| 414 |
the C library wrapper function for a system call and |
| 415 |
the raw system call interface provided by the kernel. |
| 416 |
.TP |
| 417 |
.B CAVEATS |
| 418 |
Warnings about typical user misuse of an API, |
| 419 |
that don't constitute an API bug or design defect. |
| 420 |
.TP |
| 421 |
.B BUGS |
| 422 |
A list of limitations, known defects or inconveniences, |
| 423 |
and other questionable activities. |
| 424 |
.TP |
| 425 |
.B EXAMPLES |
| 426 |
One or more examples demonstrating how this function, file, or |
| 427 |
command is used. |
| 428 |
.IP |
| 429 |
For details on writing example programs, |
| 430 |
see |
| 431 |
.I Example\~programs |
| 432 |
below. |
| 433 |
.TP |
| 434 |
.B AUTHORS |
| 435 |
A list of authors of the documentation or program. |
| 436 |
.IP |
| 437 |
.B "Use of an AUTHORS section is strongly discouraged" . |
| 438 |
Generally, it is better not to clutter every page with a list |
| 439 |
of (over time potentially numerous) authors; |
| 440 |
if you write or significantly amend a page, |
| 441 |
add a copyright notice as a comment in the source file. |
| 442 |
If you are the author of a device driver and want to include |
| 443 |
an address for reporting bugs, place this under the BUGS section. |
| 444 |
.TP |
| 445 |
.B REPORTING BUGS |
| 446 |
The |
| 447 |
.I man-pages |
| 448 |
project doesn't use a REPORTING BUGS section in manual pages. |
| 449 |
Information on reporting bugs is instead supplied in the |
| 450 |
script-generated COLOPHON section. |
| 451 |
However, various projects do use a REPORTING BUGS section. |
| 452 |
It is recommended to place it near the foot of the page. |
| 453 |
.TP |
| 454 |
.B COPYRIGHT |
| 455 |
The |
| 456 |
.I man-pages |
| 457 |
project doesn't use a COPYRIGHT section in manual pages. |
| 458 |
Copyright information is instead maintained in the page source. |
| 459 |
In pages where this section is present, |
| 460 |
it is recommended to place it near the foot of the page, just above SEE ALSO. |
| 461 |
.TP |
| 462 |
.B SEE ALSO |
| 463 |
A comma-separated list of related man pages, possibly followed by |
| 464 |
other related pages or documents. |
| 465 |
.IP |
| 466 |
The list should be ordered by section number and |
| 467 |
then alphabetically by name. |
| 468 |
Do not terminate this list with a period. |
| 469 |
.IP |
| 470 |
Where the SEE ALSO list contains many long manual page names, |
| 471 |
to improve the visual result of the output, it may be useful to employ the |
| 472 |
.I .ad l |
| 473 |
(don't right justify) |
| 474 |
and |
| 475 |
.I .nh |
| 476 |
(don't hyphenate) |
| 477 |
directives. |
| 478 |
Hyphenation of individual page names can be prevented |
| 479 |
by preceding words with the string "\[rs]%". |
| 480 |
.IP |
| 481 |
Given the distributed, autonomous nature of FOSS projects |
| 482 |
and their documentation, it is sometimes necessary\[em]and in many cases |
| 483 |
desirable\[em]that the SEE ALSO section includes references to |
| 484 |
manual pages provided by other projects. |
| 485 |
.SH FORMATTING AND WORDING CONVENTIONS |
| 486 |
The following subsections note some details for preferred formatting and |
| 487 |
wording conventions in various sections of the pages in the |
| 488 |
.I man-pages |
| 489 |
project. |
| 490 |
.SS SYNOPSIS |
| 491 |
Wrap the function prototype(s) in a |
| 492 |
.IR .nf / .fi |
| 493 |
pair to prevent filling. |
| 494 |
.P |
| 495 |
Forward declarations of parameters in functions |
| 496 |
should not use bold nor italics; |
| 497 |
this helps distinguish them visually from actual parameters. |
| 498 |
As an example: |
| 499 |
.P |
| 500 |
.in +4n |
| 501 |
.nf |
| 502 |
.BR "int snprintf(" "size_t size;" |
| 503 |
.BI " char " str "[restrict " size "], size_t " size , |
| 504 |
.BI " const char *restrict " format ", ...);" |
| 505 |
.fi |
| 506 |
.in |
| 507 |
.P |
| 508 |
In general, where more than one function prototype is shown in the SYNOPSIS, |
| 509 |
the prototypes should |
| 510 |
.I not |
| 511 |
be separated by blank lines. |
| 512 |
However, blank lines (achieved using |
| 513 |
.IR .P ) |
| 514 |
may be added in the following cases: |
| 515 |
.IP \[bu] 3 |
| 516 |
to separate long lists of function prototypes into related groups |
| 517 |
(see for example |
| 518 |
.BR list (3)); |
| 519 |
.IP \[bu] |
| 520 |
in other cases that may improve readability. |
| 521 |
.P |
| 522 |
In the SYNOPSIS, a long function prototype may need to be |
| 523 |
continued over to the next line. |
| 524 |
The continuation line is indented according to the following rules: |
| 525 |
.IP (1) 5 |
| 526 |
If there is a single such prototype that needs to be continued, |
| 527 |
then align the continuation line so that when the page is |
| 528 |
rendered on a fixed-width font device (e.g., on an xterm) the |
| 529 |
continuation line starts just below the start of the argument |
| 530 |
list in the line above. |
| 531 |
(Exception: the indentation may be |
| 532 |
adjusted if necessary to prevent a very long continuation line |
| 533 |
or a further continuation line where the function prototype is |
| 534 |
very long.) |
| 535 |
As an example: |
| 536 |
.IP |
| 537 |
.in +4n |
| 538 |
.nf |
| 539 |
.BI "int tcsetattr(int " fd ", int " optional_actions , |
| 540 |
.BI " const struct termios *" termios_p ); |
| 541 |
.fi |
| 542 |
.in |
| 543 |
.IP (2) |
| 544 |
But, where multiple functions in the SYNOPSIS require |
| 545 |
continuation lines, and the function names have different |
| 546 |
lengths, then align all continuation lines to start in the |
| 547 |
same column. |
| 548 |
This provides a nicer rendering in PDF output |
| 549 |
(because the SYNOPSIS uses a variable width font where |
| 550 |
spaces render narrower than most characters). |
| 551 |
As an example: |
| 552 |
.IP |
| 553 |
.in +4n |
| 554 |
.nf |
| 555 |
.BI "int getopt(int " argc ", char * const " argv[] , |
| 556 |
.BI " const char *" optstring ); |
| 557 |
.BI "int getopt_long(int " argc ", char * const " argv[] , |
| 558 |
.BI " const char *" optstring , |
| 559 |
.BI " const struct option *" longopts ", int *" longindex ); |
| 560 |
.fi |
| 561 |
.in |
| 562 |
.SS RETURN VALUE |
| 563 |
The preferred wording to describe how |
| 564 |
.I errno |
| 565 |
is set is |
| 566 |
.RI \[dq] errno |
| 567 |
is set to indicate the error" |
| 568 |
or similar. |
| 569 |
.\" Before man-pages 5.11, many different wordings were used, which |
| 570 |
.\" was confusing, and potentially made scripted edits more difficult. |
| 571 |
This wording is consistent with the wording used in both POSIX.1 and FreeBSD. |
| 572 |
.SS ATTRIBUTES |
| 573 |
.\" See man-pages commit c466875ecd64ed3d3cd3e578406851b7dfb397bf |
| 574 |
Note the following: |
| 575 |
.IP \[bu] 3 |
| 576 |
Wrap the table in this section in a |
| 577 |
.IR ".ad\ l" / .ad |
| 578 |
pair to disable text filling and a |
| 579 |
.IR .nh / .hy |
| 580 |
pair to disable hyphenation. |
| 581 |
.IP \[bu] |
| 582 |
Ensure that the table occupies the full page width through the use of an |
| 583 |
.I lbx |
| 584 |
description for one of the columns |
| 585 |
(usually the first column, |
| 586 |
though in some cases the last column if it contains a lot of text). |
| 587 |
.IP \[bu] |
| 588 |
Make free use of |
| 589 |
.IR T{ / T} |
| 590 |
macro pairs to allow table cells to be broken over multiple lines |
| 591 |
(also bearing in mind that pages may sometimes be rendered to a |
| 592 |
width of less than 80 columns). |
| 593 |
.P |
| 594 |
For examples of all of the above, see the source code of various pages. |
| 595 |
.SH STYLE GUIDE |
| 596 |
The following subsections describe the preferred style for the |
| 597 |
.I man-pages |
| 598 |
project. |
| 599 |
For details not covered below, the Chicago Manual of Style |
| 600 |
is usually a good source; |
| 601 |
try also grepping for preexisting usage in the project source tree. |
| 602 |
.P |
| 603 |
.UR https:\://www.ualberta.ca/\:computing-science/\:media-library/\:docs/\:unix-beginners.pdf |
| 604 |
UNIX for Beginners [2nd ed., Brian W.\& Kernighan] |
| 605 |
.UE |
| 606 |
also contains a noteworthy section, |
| 607 |
\[lq]Hints for Preparing Documents\[rq]. |
| 608 |
.SS Use of gender-neutral language |
| 609 |
As far as possible, use gender-neutral language in the text of man |
| 610 |
pages. |
| 611 |
Use of "they" ("them", "themself", "their") as a gender-neutral singular |
| 612 |
pronoun is acceptable. |
| 613 |
.\" |
| 614 |
.SS Formatting conventions for manual pages describing commands |
| 615 |
For manual pages that describe a command (typically in Sections 1 and 8), |
| 616 |
the arguments are always specified using italics, |
| 617 |
.IR "even in the SYNOPSIS section" . |
| 618 |
.P |
| 619 |
The name of the command, and its options, should |
| 620 |
always be formatted in bold. |
| 621 |
.\" |
| 622 |
.SS Formatting conventions for manual pages describing functions |
| 623 |
For manual pages that describe functions (typically in Sections 2 and 3), |
| 624 |
the arguments are always specified using italics, |
| 625 |
.IR "even in the SYNOPSIS section" , |
| 626 |
where the rest of the function is specified in bold: |
| 627 |
.P |
| 628 |
.BI " int myfunction(int " argc ", char **" argv ); |
| 629 |
.P |
| 630 |
Variable names should, like argument names, be specified in italics. |
| 631 |
.P |
| 632 |
Any reference to the subject of the current manual page |
| 633 |
should be written with the name in bold followed by |
| 634 |
a pair of parentheses in Roman (normal) font. |
| 635 |
For example, in the |
| 636 |
.BR fcntl (2) |
| 637 |
man page, references to the subject of the page would be written as: |
| 638 |
.BR fcntl (). |
| 639 |
The preferred way to write this in the source file is: |
| 640 |
.P |
| 641 |
.EX |
| 642 |
.BR fcntl () |
| 643 |
.EE |
| 644 |
.P |
| 645 |
(Using this format, rather than the use of "\[rs]fB...\[rs]fP()" |
| 646 |
makes it easier to write tools that parse man page source files.) |
| 647 |
.\" |
| 648 |
.SS Use semantic newlines |
| 649 |
In the source of a manual page, |
| 650 |
new sentences should be started on new lines, |
| 651 |
long sentences should be split into lines at clause breaks |
| 652 |
(commas, semicolons, colons, and so on), |
| 653 |
and long clauses should be split at phrase boundaries. |
| 654 |
This convention, sometimes known as "semantic newlines", |
| 655 |
makes it easier to see the effect of patches, |
| 656 |
which often operate at the level of |
| 657 |
individual sentences, clauses, or phrases. |
| 658 |
.\" |
| 659 |
.SS Lists |
| 660 |
There are different kinds of lists: |
| 661 |
.TP |
| 662 |
Tagged paragraphs |
| 663 |
These are used for a list of tags and their descriptions. |
| 664 |
When the tags are constants (either macros or numbers) |
| 665 |
they are in bold. |
| 666 |
Use the |
| 667 |
.B .TP |
| 668 |
macro. |
| 669 |
.IP |
| 670 |
An example is this "Tagged paragraphs" subsection is itself. |
| 671 |
.TP |
| 672 |
Ordered lists |
| 673 |
Elements are preceded by a number in parentheses (1), (2). |
| 674 |
These represent a set of steps that have an order. |
| 675 |
.IP |
| 676 |
When there are substeps, |
| 677 |
they will be numbered like (4.2). |
| 678 |
.TP |
| 679 |
Positional lists |
| 680 |
Elements are preceded by a number (index) in square brackets [4], [5]. |
| 681 |
These represent fields in a set. |
| 682 |
The first index will be: |
| 683 |
.RS |
| 684 |
.TP |
| 685 |
.B 0 |
| 686 |
When it represents fields of a C data structure, |
| 687 |
to be consistent with arrays. |
| 688 |
.PD 0 |
| 689 |
.TP |
| 690 |
.B 1 |
| 691 |
When it represents fields of a file, |
| 692 |
to be consistent with tools like |
| 693 |
.BR cut (1). |
| 694 |
.PD |
| 695 |
.RE |
| 696 |
.TP |
| 697 |
Alternatives list |
| 698 |
Elements are preceded by a letter in parentheses (a), (b). |
| 699 |
These represent a set of (normally) exclusive alternatives. |
| 700 |
.TP |
| 701 |
Bullet lists |
| 702 |
Elements are preceded by bullet symbols |
| 703 |
.RB ( \[rs][bu] ). |
| 704 |
Anything that doesn't fit elsewhere is |
| 705 |
usually covered by this type of list. |
| 706 |
.TP |
| 707 |
Numbered notes |
| 708 |
Not really a list, |
| 709 |
but the syntax is identical to "positional lists". |
| 710 |
.P |
| 711 |
There should always be exactly |
| 712 |
2 spaces between the list symbol and the elements. |
| 713 |
This doesn't apply to "tagged paragraphs", |
| 714 |
which use the default indentation rules. |
| 715 |
.\" |
| 716 |
.SS Formatting conventions (general) |
| 717 |
Paragraphs should be separated by suitable markers (usually either |
| 718 |
.I .P |
| 719 |
or |
| 720 |
.IR .IP ). |
| 721 |
Do |
| 722 |
.I not |
| 723 |
separate paragraphs using blank lines, as this results in poor rendering |
| 724 |
in some output formats (such as PostScript and PDF). |
| 725 |
.P |
| 726 |
Filenames (whether pathnames, or references to header files) |
| 727 |
are always in italics (e.g., |
| 728 |
.IR <stdio.h> ), |
| 729 |
except in the SYNOPSIS section, where included files are in bold (e.g., |
| 730 |
.BR "#include <stdio.h>" ). |
| 731 |
When referring to a standard header file include, |
| 732 |
specify the header file surrounded by angle brackets, |
| 733 |
in the usual C way (e.g., |
| 734 |
.IR <stdio.h> ). |
| 735 |
.P |
| 736 |
Special macros, which are usually in uppercase, are in bold (e.g., |
| 737 |
.BR MAXINT ). |
| 738 |
Exception: don't boldface NULL. |
| 739 |
.P |
| 740 |
When enumerating a list of error codes, the codes are in bold (this list |
| 741 |
usually uses the |
| 742 |
.B \&.TP |
| 743 |
macro). |
| 744 |
.P |
| 745 |
Complete commands should, if long, |
| 746 |
be written as an indented line on their own, |
| 747 |
with a blank line before and after the command, for example |
| 748 |
.P |
| 749 |
.in +4n |
| 750 |
.EX |
| 751 |
man 7 man\-pages |
| 752 |
.EE |
| 753 |
.in |
| 754 |
.P |
| 755 |
If the command is short, then it can be included inline in the text, |
| 756 |
in italic format, for example, |
| 757 |
.IR "man 7 man-pages" . |
| 758 |
In this case, it may be worth using nonbreaking spaces |
| 759 |
.RB ( \[rs]\[ti] ) |
| 760 |
at suitable places in the command. |
| 761 |
Command options should be written in italics (e.g., |
| 762 |
.IR \-l ). |
| 763 |
.P |
| 764 |
Expressions, if not written on a separate indented line, should |
| 765 |
be specified in italics. |
| 766 |
Again, the use of nonbreaking spaces may be appropriate |
| 767 |
if the expression is inlined with normal text. |
| 768 |
.P |
| 769 |
When showing example shell sessions, |
| 770 |
user input should be formatted in bold, |
| 771 |
for example |
| 772 |
.P |
| 773 |
.in +4n |
| 774 |
.EX |
| 775 |
.RB $ " date" ; |
| 776 |
Thu Jul 7 13:01:27 CEST 2016 |
| 777 |
.EE |
| 778 |
.in |
| 779 |
.P |
| 780 |
Any reference to another man page |
| 781 |
should be written with the name in bold, |
| 782 |
.I always |
| 783 |
followed by the section number, |
| 784 |
formatted in Roman (normal) font, without any |
| 785 |
separating spaces (e.g., |
| 786 |
.BR intro (2)). |
| 787 |
The preferred way to write this in the source file is: |
| 788 |
.P |
| 789 |
.EX |
| 790 |
.BR intro (2) |
| 791 |
.EE |
| 792 |
.P |
| 793 |
(Including the section number in cross references lets tools like |
| 794 |
.BR man2html (1) |
| 795 |
create properly hyperlinked pages.) |
| 796 |
.P |
| 797 |
Control characters should be written in bold face, |
| 798 |
with no quotes; |
| 799 |
for example, |
| 800 |
.BR \[ha]X . |
| 801 |
.SS Spelling |
| 802 |
Starting with release 2.59, |
| 803 |
.I man-pages |
| 804 |
follows American spelling conventions |
| 805 |
(previously, there was a random mix of British and American spellings); |
| 806 |
please write all new pages and patches according to these conventions. |
| 807 |
.P |
| 808 |
Aside from the well-known spelling differences, |
| 809 |
there are a few other subtleties to watch for: |
| 810 |
.IP \[bu] 3 |
| 811 |
American English tends to use the forms "backward", "upward", "toward", |
| 812 |
and so on |
| 813 |
rather than the British forms "backwards", "upwards", "towards", and so on. |
| 814 |
.IP \[bu] |
| 815 |
Opinions are divided on "acknowledgement" vs "acknowledgment". |
| 816 |
The latter is predominant, but not universal usage in American English. |
| 817 |
POSIX and the BSD license use the former spelling. |
| 818 |
In the Linux man-pages project, we use "acknowledgement". |
| 819 |
.SS BSD version numbers |
| 820 |
The classical scheme for writing BSD version numbers is |
| 821 |
.IR x.yBSD , |
| 822 |
where |
| 823 |
.I x.y |
| 824 |
is the version number (e.g., 4.2BSD). |
| 825 |
Avoid forms such as |
| 826 |
.IR "BSD 4.3" . |
| 827 |
.SS Capitalization |
| 828 |
In subsection ("SS") headings, |
| 829 |
capitalize the first word in the heading, but otherwise use lowercase, |
| 830 |
except where English usage (e.g., proper nouns) or programming |
| 831 |
language requirements (e.g., identifier names) dictate otherwise. |
| 832 |
For example: |
| 833 |
.P |
| 834 |
.in +4n |
| 835 |
.EX |
| 836 |
\&.SS Unicode under Linux |
| 837 |
.EE |
| 838 |
.in |
| 839 |
.\" |
| 840 |
.SS Indentation of structure definitions, shell session logs, and so on |
| 841 |
When structure definitions, shell session logs, and so on are included |
| 842 |
in running text, indent them by 4 spaces (i.e., a block enclosed by |
| 843 |
.I ".in\ +4n" |
| 844 |
and |
| 845 |
.IR ".in" ), |
| 846 |
format them using the |
| 847 |
.I .EX |
| 848 |
and |
| 849 |
.I .EE |
| 850 |
macros, and surround them with suitable paragraph markers (either |
| 851 |
.I .P |
| 852 |
or |
| 853 |
.IR .IP ). |
| 854 |
For example: |
| 855 |
.P |
| 856 |
.in +4n |
| 857 |
.EX |
| 858 |
\&.P |
| 859 |
\&.in +4n |
| 860 |
\&.EX |
| 861 |
int |
| 862 |
main(int argc, char *argv[]) |
| 863 |
{ |
| 864 |
return 0; |
| 865 |
} |
| 866 |
\&.EE |
| 867 |
\&.in |
| 868 |
\&.P |
| 869 |
.EE |
| 870 |
.in |
| 871 |
.SS Preferred terms |
| 872 |
The following table lists some preferred terms to use in man pages, |
| 873 |
mainly to ensure consistency across pages. |
| 874 |
.ad l |
| 875 |
.TS |
| 876 |
l l l. |
| 877 |
Term Avoid using Notes |
| 878 |
_ |
| 879 |
bit mask bitmask |
| 880 |
built-in builtin |
| 881 |
Epoch epoch T{ |
| 882 |
For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC) |
| 883 |
T} |
| 884 |
filename file name |
| 885 |
filesystem file system |
| 886 |
hostname host name |
| 887 |
inode i-node |
| 888 |
lowercase lower case, lower-case |
| 889 |
nonzero non-zero |
| 890 |
pathname path name |
| 891 |
pseudoterminal pseudo-terminal |
| 892 |
privileged port T{ |
| 893 |
reserved port, |
| 894 |
system port |
| 895 |
T} |
| 896 |
real-time T{ |
| 897 |
realtime, |
| 898 |
real time |
| 899 |
T} |
| 900 |
run time runtime |
| 901 |
saved set-group-ID T{ |
| 902 |
saved group ID, |
| 903 |
saved set-GID |
| 904 |
T} |
| 905 |
saved set-user-ID T{ |
| 906 |
saved user ID, |
| 907 |
saved set-UID |
| 908 |
T} |
| 909 |
set-group-ID set-GID, setgid |
| 910 |
set-user-ID set-UID, setuid |
| 911 |
superuser T{ |
| 912 |
super user, |
| 913 |
super-user |
| 914 |
T} |
| 915 |
superblock T{ |
| 916 |
super block, |
| 917 |
super-block |
| 918 |
T} |
| 919 |
symbolic link symlink |
| 920 |
timestamp time stamp |
| 921 |
timezone time zone |
| 922 |
uppercase upper case, upper-case |
| 923 |
usable useable |
| 924 |
user space userspace |
| 925 |
username user name |
| 926 |
x86-64 x86_64 T{ |
| 927 |
Except if referring to result of |
| 928 |
.I \%uname\~\-m |
| 929 |
or similar |
| 930 |
T} |
| 931 |
zeros zeroes |
| 932 |
.TE |
| 933 |
.P |
| 934 |
See also the discussion |
| 935 |
.I Hyphenation of attributive compounds |
| 936 |
below. |
| 937 |
.SS Terms to avoid |
| 938 |
The following table lists some terms to avoid using in man pages, |
| 939 |
along with some suggested alternatives, |
| 940 |
mainly to ensure consistency across pages. |
| 941 |
.ad l |
| 942 |
.TS |
| 943 |
l l l. |
| 944 |
Avoid Use instead Notes |
| 945 |
_ |
| 946 |
32bit 32-bit T{ |
| 947 |
same for 8-bit, 16-bit, etc. |
| 948 |
T} |
| 949 |
current process calling process T{ |
| 950 |
A common mistake made by kernel programmers when writing man pages |
| 951 |
T} |
| 952 |
manpage T{ |
| 953 |
man page, manual page |
| 954 |
T} |
| 955 |
minus infinity negative infinity |
| 956 |
non-root unprivileged user |
| 957 |
non-superuser unprivileged user |
| 958 |
nonprivileged unprivileged |
| 959 |
OS operating system |
| 960 |
plus infinity positive infinity |
| 961 |
pty pseudoterminal |
| 962 |
tty terminal |
| 963 |
Unices UNIX systems |
| 964 |
Unixes UNIX systems |
| 965 |
.TE |
| 966 |
.ad |
| 967 |
.\" |
| 968 |
.SS Trademarks |
| 969 |
Use the correct spelling and case for trademarks. |
| 970 |
The following is a list of the correct spellings of various |
| 971 |
relevant trademarks that are sometimes misspelled: |
| 972 |
.IP |
| 973 |
.TS |
| 974 |
l. |
| 975 |
DG/UX |
| 976 |
HP-UX |
| 977 |
UNIX |
| 978 |
UnixWare |
| 979 |
.TE |
| 980 |
.SS NULL, NUL, null pointer, and null byte |
| 981 |
A |
| 982 |
.I null pointer |
| 983 |
is a pointer that points to nothing, |
| 984 |
and is normally indicated by the constant |
| 985 |
.IR NULL . |
| 986 |
On the other hand, |
| 987 |
.I NUL |
| 988 |
is the |
| 989 |
.IR "null byte" , |
| 990 |
a byte with the value 0, represented in C via the character constant |
| 991 |
.IR \[aq]\[rs]0\[aq] . |
| 992 |
.P |
| 993 |
The preferred term for the pointer is "null pointer" or simply "NULL"; |
| 994 |
avoid writing "NULL pointer". |
| 995 |
.P |
| 996 |
The preferred term for the byte is "null byte". |
| 997 |
Avoid writing "NUL", since it is too easily confused with "NULL". |
| 998 |
Avoid also the terms "zero byte" and "null character". |
| 999 |
The byte that terminates a C string should be described |
| 1000 |
as "the terminating null byte"; |
| 1001 |
strings may be described as "null-terminated", |
| 1002 |
but avoid the use of "NUL-terminated". |
| 1003 |
.SS Hyperlinks |
| 1004 |
For hyperlinks, use the |
| 1005 |
.IR .UR / .UE |
| 1006 |
macro pair |
| 1007 |
(see |
| 1008 |
.BR groff_man (7)). |
| 1009 |
This produces proper hyperlinks that can be used in a web browser, |
| 1010 |
when rendering a page with, say: |
| 1011 |
.P |
| 1012 |
.in +4n |
| 1013 |
.EX |
| 1014 |
BROWSER=firefox man \-H pagename |
| 1015 |
.EE |
| 1016 |
.in |
| 1017 |
.SS Use of e.g., i.e., etc., a.k.a., and similar |
| 1018 |
In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", |
| 1019 |
"cf.", and "a.k.a." should be avoided, |
| 1020 |
in favor of suitable full wordings |
| 1021 |
("for example", "that is", "and so on", "compare to", "also known as"). |
| 1022 |
.P |
| 1023 |
The only place where such abbreviations may be acceptable is in |
| 1024 |
.I short |
| 1025 |
parenthetical asides (e.g., like this one). |
| 1026 |
.P |
| 1027 |
Always include periods in such abbreviations, as shown here. |
| 1028 |
In addition, "e.g." and "i.e." should always be followed by a comma. |
| 1029 |
.SS Em-dashes |
| 1030 |
The way to write an em-dash\[em]the glyph that appears |
| 1031 |
at either end of this subphrase\[em]in *roff is with the macro "\[rs][em]". |
| 1032 |
(On an ASCII terminal, an em-dash typically renders as two hyphens, |
| 1033 |
but in other typographical contexts it renders as a long dash.) |
| 1034 |
Em-dashes should be written |
| 1035 |
.I without |
| 1036 |
surrounding spaces. |
| 1037 |
.SS Hyphenation of attributive compounds |
| 1038 |
Compound terms should be hyphenated when used attributively |
| 1039 |
(i.e., to qualify a following noun). |
| 1040 |
Some examples: |
| 1041 |
.IP |
| 1042 |
.TS |
| 1043 |
l. |
| 1044 |
32-bit value |
| 1045 |
command-line argument |
| 1046 |
floating-point number |
| 1047 |
run-time check |
| 1048 |
user-space function |
| 1049 |
wide-character string |
| 1050 |
.TE |
| 1051 |
.SS Hyphenation with multi, non, pre, re, sub, and so on |
| 1052 |
The general tendency in modern English is not to hyphenate |
| 1053 |
after prefixes such as "multi", "non", "pre", "re", "sub", and so on. |
| 1054 |
Manual pages should generally follow this rule when these prefixes are |
| 1055 |
used in natural English constructions with simple suffixes. |
| 1056 |
The following list gives some examples of the preferred forms: |
| 1057 |
.IP |
| 1058 |
.TS |
| 1059 |
l. |
| 1060 |
interprocess |
| 1061 |
multithreaded |
| 1062 |
multiprocess |
| 1063 |
nonblocking |
| 1064 |
nondefault |
| 1065 |
nonempty |
| 1066 |
noninteractive |
| 1067 |
nonnegative |
| 1068 |
nonportable |
| 1069 |
nonzero |
| 1070 |
preallocated |
| 1071 |
precreate |
| 1072 |
prerecorded |
| 1073 |
reestablished |
| 1074 |
reinitialize |
| 1075 |
rearm |
| 1076 |
reread |
| 1077 |
subcomponent |
| 1078 |
subdirectory |
| 1079 |
subsystem |
| 1080 |
.TE |
| 1081 |
.P |
| 1082 |
Hyphens should be retained when the prefixes are used in nonstandard |
| 1083 |
English words, with trademarks, proper nouns, acronyms, or compound terms. |
| 1084 |
Some examples: |
| 1085 |
.IP |
| 1086 |
.TS |
| 1087 |
l. |
| 1088 |
non-ASCII |
| 1089 |
non-English |
| 1090 |
non-NULL |
| 1091 |
non-real-time |
| 1092 |
.TE |
| 1093 |
.P |
| 1094 |
Finally, note that "re-create" and "recreate" are two different verbs, |
| 1095 |
and the former is probably what you want. |
| 1096 |
.\" |
| 1097 |
.SS Generating optimal glyphs |
| 1098 |
Where a real minus character is required (e.g., for numbers such as \-1, |
| 1099 |
for man page cross references such as |
| 1100 |
.BR utf\-8 (7), |
| 1101 |
or when writing options that have a leading dash, such as in |
| 1102 |
.IR "ls\ \-l"), |
| 1103 |
use the following form in the man page source: |
| 1104 |
.P |
| 1105 |
.in +4n |
| 1106 |
.EX |
| 1107 |
\[rs]\- |
| 1108 |
.EE |
| 1109 |
.in |
| 1110 |
.P |
| 1111 |
This guideline applies also to code examples. |
| 1112 |
.P |
| 1113 |
The use of real minus signs serves the following purposes: |
| 1114 |
.\" https://lore.kernel.org/linux-man/[email protected]/ |
| 1115 |
.IP \[bu] 3 |
| 1116 |
To provide better renderings on various targets other than |
| 1117 |
ASCII terminals, |
| 1118 |
notably in PDF and on Unicode/UTF\-8-capable terminals. |
| 1119 |
.IP \[bu] |
| 1120 |
To generate glyphs that when copied from rendered pages will |
| 1121 |
produce real minus signs when pasted into a terminal. |
| 1122 |
.P |
| 1123 |
To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF, |
| 1124 |
use "\[rs][aq]" ("apostrophe quote"); |
| 1125 |
for example |
| 1126 |
.P |
| 1127 |
.in +4n |
| 1128 |
.EX |
| 1129 |
\[rs][aq]C\[rs][aq] |
| 1130 |
.EE |
| 1131 |
.in |
| 1132 |
.P |
| 1133 |
where |
| 1134 |
.I C |
| 1135 |
is the quoted character. |
| 1136 |
This guideline applies also to character constants used in code examples. |
| 1137 |
.P |
| 1138 |
Where a proper caret (\[ha]) that renders well in both a terminal and PDF |
| 1139 |
is required, use "\\[ha]". |
| 1140 |
This is especially necessary in code samples, |
| 1141 |
to get a nicely rendered caret when rendering to PDF. |
| 1142 |
.P |
| 1143 |
Using a naked "\[ti]" character results in a poor rendering in PDF. |
| 1144 |
Instead use "\\[ti]". |
| 1145 |
This is especially necessary in code samples, |
| 1146 |
to get a nicely rendered tilde when rendering to PDF. |
| 1147 |
.\" |
| 1148 |
.SS Example programs and shell sessions |
| 1149 |
Manual pages may include example programs demonstrating how to |
| 1150 |
use a system call or library function. |
| 1151 |
However, note the following: |
| 1152 |
.IP \[bu] 3 |
| 1153 |
Example programs should be written in C. |
| 1154 |
.IP \[bu] |
| 1155 |
An example program is necessary and useful only if it demonstrates |
| 1156 |
something beyond what can easily be provided in a textual |
| 1157 |
description of the interface. |
| 1158 |
An example program that does nothing |
| 1159 |
other than call an interface usually serves little purpose. |
| 1160 |
.IP \[bu] |
| 1161 |
Example programs should ideally be short |
| 1162 |
(e.g., a good example can often be provided in less than 100 lines of code), |
| 1163 |
though in some cases longer programs may be necessary |
| 1164 |
to properly illustrate the use of an API. |
| 1165 |
.IP \[bu] |
| 1166 |
Expressive code is appreciated. |
| 1167 |
.IP \[bu] |
| 1168 |
Comments should included where helpful. |
| 1169 |
Complete sentences in free-standing comments should be |
| 1170 |
terminated by a period. |
| 1171 |
Periods should generally be omitted in "tag" comments |
| 1172 |
(i.e., comments that are placed on the same line of code); |
| 1173 |
such comments are in any case typically brief phrases |
| 1174 |
rather than complete sentences. |
| 1175 |
.IP \[bu] |
| 1176 |
Example programs should do error checking after system calls and |
| 1177 |
library function calls. |
| 1178 |
.IP \[bu] |
| 1179 |
Example programs should be complete, and compile without |
| 1180 |
warnings when compiled with |
| 1181 |
.IR "cc\ \-Wall" . |
| 1182 |
.IP \[bu] |
| 1183 |
Where possible and appropriate, example programs should allow |
| 1184 |
experimentation, by varying their behavior based on inputs |
| 1185 |
(ideally from command-line arguments, or alternatively, via |
| 1186 |
input read by the program). |
| 1187 |
.IP \[bu] |
| 1188 |
Example programs should be laid out according to Kernighan and |
| 1189 |
Ritchie style, with 4-space indents. |
| 1190 |
(Avoid the use of TAB characters in source code!) |
| 1191 |
The following command can be used to format your source code to |
| 1192 |
something close to the preferred style: |
| 1193 |
.IP |
| 1194 |
.in +4n |
| 1195 |
.EX |
| 1196 |
indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c |
| 1197 |
.EE |
| 1198 |
.in |
| 1199 |
.IP \[bu] |
| 1200 |
For consistency, all example programs should terminate using either of: |
| 1201 |
.IP |
| 1202 |
.in +4n |
| 1203 |
.EX |
| 1204 |
exit(EXIT_SUCCESS); |
| 1205 |
exit(EXIT_FAILURE); |
| 1206 |
.EE |
| 1207 |
.in |
| 1208 |
.IP |
| 1209 |
Avoid using the following forms to terminate a program: |
| 1210 |
.IP |
| 1211 |
.in +4n |
| 1212 |
.EX |
| 1213 |
exit(0); |
| 1214 |
exit(1); |
| 1215 |
return n; |
| 1216 |
.EE |
| 1217 |
.in |
| 1218 |
.IP \[bu] |
| 1219 |
If there is extensive explanatory text before the |
| 1220 |
program source code, mark off the source code |
| 1221 |
with a subsection heading |
| 1222 |
.IR "Program source" , |
| 1223 |
as in: |
| 1224 |
.IP |
| 1225 |
.in +4n |
| 1226 |
.EX |
| 1227 |
\&.SS Program source |
| 1228 |
.EE |
| 1229 |
.in |
| 1230 |
.IP |
| 1231 |
Always do this if the explanatory text includes a shell session log. |
| 1232 |
.P |
| 1233 |
If you include a shell session log demonstrating the use of a program |
| 1234 |
or other system feature: |
| 1235 |
.IP \[bu] 3 |
| 1236 |
Place the session log above the source code listing. |
| 1237 |
.IP \[bu] |
| 1238 |
Indent the session log by four spaces. |
| 1239 |
.IP \[bu] |
| 1240 |
Boldface the user input text, |
| 1241 |
to distinguish it from output produced by the system. |
| 1242 |
.P |
| 1243 |
For some examples of what example programs should look like, see |
| 1244 |
.BR wait (2) |
| 1245 |
and |
| 1246 |
.BR pipe (2). |
| 1247 |
.SH EXAMPLES |
| 1248 |
For canonical examples of how man pages in the |
| 1249 |
.I man-pages |
| 1250 |
package should look, see |
| 1251 |
.BR pipe (2) |
| 1252 |
and |
| 1253 |
.BR fcntl (2). |
| 1254 |
.SH SEE ALSO |
| 1255 |
.BR man (1), |
| 1256 |
.BR man2html (1), |
| 1257 |
.BR attributes (7), |
| 1258 |
.BR groff (7), |
| 1259 |
.BR groff_man (7), |
| 1260 |
.BR man (7), |
| 1261 |
.BR mdoc (7) |