syslog.3: Reorganize page text for easier parsing and better readability

Inspired by comments from Ian Abbott and Walter Harms

Reported-by: Ian Abbott <abbotti@mev.co.uk>
Reported-by: Walter Harms <wharms@bfs.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man3/syslog.3

@@ -1,4 +1,5 @@
 .\" Written  Feb 1994 by Steve Greenland (stevegr@neosoft.com)
+.\" and Copyright 2001, 2017 Michael Kerrisk <mtk.manpages@gmail.com>
 .\"
 .\" %%%LICENSE_START(VERBATIM)
 .\" Permission is granted to make and distribute verbatim copies of this
@@ -58,14 +59,10 @@ Feature Test Macro Requirements for glibc (see
     Glibc 2.19 and earlier:
         _BSD_SOURCE
 .SH DESCRIPTION
-.BR closelog ()
-closes the file descriptor being used to write to the system logger.
-The use of
-.BR closelog ()
-is optional.
-.sp
+.SS openlog()
 .BR openlog ()
 opens a connection to the system logger for a program.
+
 The string pointed to by
 .I ident
 is prepended to every message, and is typically set to the program name.
@@ -92,6 +89,7 @@ Values for
 and
 .I facility
 are given below.
+
 The use of
 .BR openlog ()
 is optional; it will automatically be called by
@@ -99,10 +97,12 @@ is optional; it will automatically be called by
 if necessary, in which case
 .I ident
 will default to NULL.
-.sp
+.\"
+.SS syslog() and vsyslog()
 .BR syslog ()
 generates a log message, which will be distributed by
 .BR syslogd (8).
+
 The
 .I priority
 argument is formed by ORing the
@@ -110,8 +110,8 @@ argument is formed by ORing the
 and the
 .I level
 values (explained below).
-The remaining arguments
-are a
+
+The remaining arguments are a
 .IR format ,
 as in
 .BR printf (3)
@@ -132,10 +132,15 @@ with the difference that it takes a set of arguments which have
 been obtained using the
 .BR stdarg (3)
 variable argument list macros.
-
-The subsections below list the parameters used to set the values of
-.IR option , " facility" ", and " priority .
-.SS option
+.\"
+.SS closelog()
+.BR closelog ()
+closes the file descriptor being used to write to the system logger.
+The use of
+.BR closelog ()
+is optional.
+.\"
+.SS Values for \fIoption\fP
 The
 .I option
 argument to
@@ -170,7 +175,8 @@ Print to \fIstderr\fP as well.
 .TP
 .B LOG_PID
 Include PID with each message.
-.SS facility
+.\"
+.SS Values for \fIfacility\fP
 The
 .I facility
 argument is used to specify what type of program is logging the message.
@@ -219,7 +225,8 @@ generic user-level messages
 .TP
 .B LOG_UUCP
 UUCP subsystem
-.SS level
+.\"
+.SS Values for \fIlevel\fP
 This determines the importance of the message.
 The levels are, in order of decreasing importance:
 .TP 15
@@ -276,6 +283,7 @@ and
 (but not
 .BR vsyslog ())
 are specified in SUSv2, POSIX.1-2001, and POSIX.1-2008.
+
 POSIX.1-2001 specifies only the
 .B LOG_USER
 and
@@ -289,6 +297,7 @@ and
 the other
 .I facility
 values appear on most UNIX systems.
+
 The
 .B LOG_PERROR
 value for