mirror of https://github.com/mkerrisk/man-pages
man-pages.7: Add some further style notes for code examples
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
fa797358b5
commit
f78f2def0f
|
@ -557,48 +557,57 @@ language requirements (e.g., identifier names) dictate otherwise.
|
||||||
Manual pages can include example programs demonstrating how to
|
Manual pages can include example programs demonstrating how to
|
||||||
use a system call or library function.
|
use a system call or library function.
|
||||||
However, note the following:
|
However, note the following:
|
||||||
.TP 3
|
.IP * 3
|
||||||
*
|
|
||||||
Example programs should be written in C.
|
Example programs should be written in C.
|
||||||
.TP
|
.IP *
|
||||||
*
|
|
||||||
An example program is necessary and useful only if it demonstrates
|
An example program is necessary and useful only if it demonstrates
|
||||||
something beyond what can easily be provided in a textual
|
something beyond what can easily be provided in a textual
|
||||||
description of the interface.
|
description of the interface.
|
||||||
An example program that does nothing
|
An example program that does nothing
|
||||||
other than call an interface usually serves little purpose.
|
other than call an interface usually serves little purpose.
|
||||||
.TP
|
.IP *
|
||||||
*
|
|
||||||
Example programs should be fairly short (preferably less than 100 lines;
|
Example programs should be fairly short (preferably less than 100 lines;
|
||||||
ideally less than 50 lines).
|
ideally less than 50 lines).
|
||||||
.TP
|
.IP *
|
||||||
*
|
|
||||||
Example programs should do error checking after system calls and
|
Example programs should do error checking after system calls and
|
||||||
library function calls.
|
library function calls.
|
||||||
.TP
|
.IP *
|
||||||
*
|
|
||||||
Example programs should be complete, and compile without
|
Example programs should be complete, and compile without
|
||||||
warnings when compiled with \fIcc\ \-Wall\fP.
|
warnings when compiled with \fIcc\ \-Wall\fP.
|
||||||
.TP
|
.IP *
|
||||||
*
|
|
||||||
Where possible and appropriate, example programs should allow
|
Where possible and appropriate, example programs should allow
|
||||||
experimentation, by varying their behavior based on inputs
|
experimentation, by varying their behavior based on inputs
|
||||||
(ideally from command-line arguments, or alternatively, via
|
(ideally from command-line arguments, or alternatively, via
|
||||||
input read by the program).
|
input read by the program).
|
||||||
.TP
|
.IP *
|
||||||
*
|
|
||||||
Example programs should be laid out according to Kernighan and
|
Example programs should be laid out according to Kernighan and
|
||||||
Ritchie style, with 4-space indents.
|
Ritchie style, with 4-space indents.
|
||||||
(Avoid the use of TAB characters in source code!)
|
(Avoid the use of TAB characters in source code!)
|
||||||
|
.IP *
|
||||||
|
If there is extensive explanatory text before the
|
||||||
|
program source code, mark off the source code
|
||||||
|
with a susbsection heading
|
||||||
|
.IR "Program source" ,
|
||||||
|
as in:
|
||||||
|
|
||||||
|
.SS Program source
|
||||||
|
|
||||||
|
Always do this if the explanatory text includes a shell session log.
|
||||||
|
.PP
|
||||||
|
If you include a shell session log demonstrating the use of a program
|
||||||
|
or other system feature:
|
||||||
|
.IP * 3
|
||||||
|
Place the session log above the source code listing
|
||||||
|
.IP *
|
||||||
|
Indent the session log by four spaces.
|
||||||
|
.IP *
|
||||||
|
Boldface the user input text,
|
||||||
|
to distinguish it from output produced by the system.
|
||||||
.PP
|
.PP
|
||||||
For some examples of what example programs should look like, see
|
For some examples of what example programs should look like, see
|
||||||
.BR wait (2)
|
.BR wait (2)
|
||||||
and
|
and
|
||||||
.BR pipe (2).
|
.BR pipe (2).
|
||||||
|
|
||||||
If you include a shell session demonstrating the use of a program
|
|
||||||
or other system feature, boldface the user input text,
|
|
||||||
to distinguish it from output produced by the system.
|
|
||||||
.SS Indentation of structure definitions, shell session logs, etc.
|
.SS Indentation of structure definitions, shell session logs, etc.
|
||||||
When structure definitions, shell session logs, and so on are included
|
When structure definitions, shell session logs, and so on are included
|
||||||
in running text, indent them by 4 spaces (i.e., a block enclosed by
|
in running text, indent them by 4 spaces (i.e., a block enclosed by
|
||||||
|
|
Loading…
Reference in New Issue