man-pages.7: Add some further style notes for code examples

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man7/man-pages.7

@@ -557,48 +557,57 @@ language requirements (e.g., identifier names) dictate otherwise.
 Manual pages can include example programs demonstrating how to
 use a system call or library function.
 However, note the following:
-.TP 3
-*
+.IP * 3
 Example programs should be written in C.
-.TP
-*
+.IP *
 An example program is necessary and useful only if it demonstrates
 something beyond what can easily be provided in a textual
 description of the interface.
 An example program that does nothing
 other than call an interface usually serves little purpose.
-.TP
-*
+.IP *
 Example programs should be fairly short (preferably less than 100 lines;
 ideally less than 50 lines).
-.TP
-*
+.IP *
 Example programs should do error checking after system calls and
 library function calls.
-.TP
-*
+.IP *
 Example programs should be complete, and compile without
 warnings when compiled with \fIcc\ \-Wall\fP.
-.TP
-*
+.IP *
 Where possible and appropriate, example programs should allow
 experimentation, by varying their behavior based on inputs
 (ideally from command-line arguments, or alternatively, via
 input read by the program).
-.TP
-*
+.IP *
 Example programs should be laid out according to Kernighan and
 Ritchie style, with 4-space indents.
 (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
 For some examples of what example programs should look like, see
 .BR wait (2)
 and
 .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.
 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