Improve markup of sscanf and swscanf documentation

- use bullet points to separate width, size and type sections, rather than using
rows in an enormous table, for consistency with sprintf and swprintf.

- use code markup for size bullet point for consistency

- use a texinfo multitable for description of the size flags, rather than some
preformatted text

- tidy up some whitespace so type flags are all aligned

2015-11-12  Jon Turney  <jon.turney@dronecode.org.uk>

	* libc/stdio/sscanf.c: Improve documentation markup.
	* libc/stdio/swscanf.c: Ditto.

Signed-off-by: Jon Turney <jon.turney@dronecode.org.uk>

3 files changed, 242 insertions, 114 deletions

diff --git a/newlib/ChangeLog b/newlib/ChangeLog
index 4045b7cd0..070622b8f 100644
--- a/newlib/ChangeLog
+++ b/newlib/ChangeLog
@@ -1,3 +1,8 @@
+2015-11-12  Jon Turney  <jon.turney@dronecode.org.uk>
+
+	* libc/stdio/sscanf.c: Improve documentation markup.
+	* libc/stdio/swscanf.c: Ditto.
+
 2015-11-17  Yaakov Selkowitz  <yselkowi@redhat.com>
 
 	* libc/include/stdlib.h (rpmatch): Declare.
diff --git a/newlib/libc/stdio/sscanf.c b/newlib/libc/stdio/sscanf.c
index a32ce5d27..7961294e7 100644
--- a/newlib/libc/stdio/sscanf.c
+++ b/newlib/libc/stdio/sscanf.c
@@ -132,12 +132,14 @@ DESCRIPTION
 
         Each format specification begins with the percent character (<<%>>).
         The other fields are:
-	o+
+	O+
 		o *
+
 		an optional marker; if present, it suppresses interpretation and
         assignment of this input field.
 
         o <[width]>
+
 		an optional maximum field width: a decimal integer,
 		which controls the maximum number of characters that
 		will be read before converting the current input field.  If the
@@ -150,58 +152,115 @@ DESCRIPTION
 		to that character are read, converted, and stored.
 		Then <<scanf>> proceeds to the next format specification.
 
-        o size
+        o <[size]>
+
 		<<h>>, <<j>>, <<l>>, <<L>>, <<t>>, and <<z>> are optional size
 		characters which override the default way that <<scanf>>
 		interprets the data type of the corresponding argument.
 
-
-.Modifier   Type(s)
-.   hh      d, i, o, u, x, n  convert input to char,
-.                             store in char object
-.
-.   h       d, i, o, u, x, n  convert input to short,
-.                             store in short object
-.
-.   h       D, I, O, U, X     no effect
-.           e, f, c, s, p
-.
-.   j       d, i, o, u, x, n  convert input to intmax_t,
-.                             store in intmax_t object
-.
-.   j       all others        no effect
-.
-.   l       d, i, o, u, x, n  convert input to long,
-.                             store in long object
-.
-.   l       e, f, g           convert input to double
-.                             store in a double object
-.
-.   l       D, I, O, U, X     no effect
-.           c, s, p
-.
-.   ll      d, i, o, u, x, n  convert to long long,
-.                             store in long long
-.
-.   L       d, i, o, u, x, n  convert to long long,
-.                             store in long long
-.
-.   L       e, f, g, E, G     convert to long double,
-.                             store in long double
-.
-.   L       all others        no effect
-.
-.   t       d, i, o, u, x, n  convert input to ptrdiff_t,
-.                             store in ptrdiff_t object
-.
-.   t       all others        no effect
-.
-.   z       d, i, o, u, x, n  convert input to size_t,
-.                             store in size_t object
-.
-.   z       all others        no effect
-.
-
+		@multitable @columnfractions 0.18 0.30 0.52
+		@headitem
+		Modifier
+		@tab
+		Type(s)
+		@tab
+		@item
+		hh
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert input to char, store in char object
+		@item
+		h
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert input to short, store in short object
+		@item
+		h
+		@tab
+		D, I, O, U, X, e, f, c, s, p
+		@tab
+		no effect
+		@item
+		j
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert input to intmax_t, store in intmax_t object
+		@item
+		j
+		@tab
+		all others
+		@tab
+		no effect
+		@item
+		l
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert input to long, store in long object
+		@item
+		l
+		@tab
+		e, f, g
+		@tab
+		convert input to double, store in a double object
+		@item
+		l
+		@tab
+		D, I, O, U, X, c, s, p
+		@tab
+		no effect
+		@item
+		ll
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert to long long, store in long long object
+		@item
+		L
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert to long long, store in long long object
+		@item
+		L
+		@tab
+		e, f, g, E, G
+		@tab
+		convert to long double, store in long double object
+		@item
+		L
+		@tab
+		all others
+		@tab
+		no effect
+		@item
+		t
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert input to ptrdiff_t, store in ptrdiff_t object
+		@item
+		t
+		@tab
+		all others
+		@tab
+		no effect
+		@item
+		z
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert input to size_t, store in size_t object
+		@item
+		z
+		@tab
+		all others
+		@tab
+		no effect
+		@end multitable
 
         o <[type]>
 
@@ -210,7 +269,7 @@ DESCRIPTION
                 characters:
 
 		o+
-		o  %
+		o %
 		No conversion is done; the percent character (<<%>>) is stored.
 
 		o c
@@ -220,7 +279,7 @@ DESCRIPTION
 		Reads a character string into the array supplied.
 		Corresponding <[arg]>: <<(char arg[])>>.
 
-		o  [<[pattern]>]
+		o [<[pattern]>]
 		Reads a non-empty character string into memory
 		starting at <[arg]>.  This area must be large
 		enough to accept the sequence and a
@@ -244,7 +303,6 @@ DESCRIPTION
 		o u
 		Reads an unsigned decimal integer into the corresponding
 		<[arg]>: <<(unsigned int *arg)>>.
-			
 
 		o U
 		Reads an unsigned decimal integer into the corresponding <[arg]>:
@@ -262,19 +320,19 @@ DESCRIPTION
 		Read a floating-point number into the corresponding <[arg]>:
 		<<(double *arg)>>.
 
-		o  i
+		o i
 		Reads a decimal, octal or hexadecimal integer into the
 		corresponding <[arg]>: <<(int *arg)>>.
 
-		o  I
+		o I
 		Reads a decimal, octal or hexadecimal integer into the
 		corresponding <[arg]>: <<(long *arg)>>.
 
-		o  n
+		o n
 		Stores the number of characters read in the corresponding
 		<[arg]>: <<(int *arg)>>.
 
-		o  p
+		o p
                 Stores a scanned pointer.  ANSI C leaves the details
 		to each implementation; this implementation treats
 		<<%p>> exactly the same as <<%U>>.  Corresponding
@@ -316,7 +374,7 @@ DESCRIPTION
 
 	where objects inclosed in square brackets are optional, and <<ddd>>
 	represents decimal, octal, or hexadecimal digits.
-	o-
+	O-
 
 RETURNS
         <<scanf>> returns the number of input fields successfully
diff --git a/newlib/libc/stdio/swscanf.c b/newlib/libc/stdio/swscanf.c
index d7ad4b867..6a469ac31 100644
--- a/newlib/libc/stdio/swscanf.c
+++ b/newlib/libc/stdio/swscanf.c
@@ -134,12 +134,14 @@ DESCRIPTION
 
         Each format specification begins with the percent character (<<%>>).
         The other fields are:
-	o+
+	O+
 		o *
+
 		an optional marker; if present, it suppresses interpretation and
         assignment of this input field.
 
         o <[width]>
+
 		an optional maximum field width: a decimal integer,
 		which controls the maximum number of characters that
 		will be read before converting the current input field.  If the
@@ -152,58 +154,121 @@ DESCRIPTION
 		to that character are read, converted, and stored.
 		Then <<wscanf>> proceeds to the next format specification.
 
-        o size
+        o <[size]>
+
 		<<h>>, <<j>>, <<l>>, <<L>>, <<t>>, and <<z>> are optional size
 		characters which override the default way that <<wscanf>>
 		interprets the data type of the corresponding argument.
 
-
-.Modifier   Type(s)
-.   hh      d, i, o, u, x, n  convert input to char,
-.                             store in char object
-.
-.   h       d, i, o, u, x, n  convert input to short,
-.                             store in short object
-.
-.   h       e, f, c, s, p     no effect
-.
-.   j       d, i, o, u, x, n  convert input to intmax_t,
-.                             store in intmax_t object
-.
-.   j       all others        no effect
-.
-.   l       d, i, o, u, x, n  convert input to long,
-.                             store in long object
-.
-.   l       e, f, g           convert input to double
-.                             store in a double object
-.
-.   l       c, s, [           the input is stored in a wchar_t object
-.
-.   l       p                 no effect
-.
-.   ll      d, i, o, u, x, n  convert to long long,
-.                             store in long long
-.
-.   L       d, i, o, u, x, n  convert to long long,
-.                             store in long long
-.
-.   L       e, f, g, E, G     convert to long double,
-.                             store in long double
-.
-.   L       all others        no effect
-.
-.   t       d, i, o, u, x, n  convert input to ptrdiff_t,
-.                             store in ptrdiff_t object
-.
-.   t       all others        no effect
-.
-.   z       d, i, o, u, x, n  convert input to size_t,
-.                             store in size_t object
-.
-.   z       all others        no effect
-.
-
+		@multitable @columnfractions 0.18 0.30 0.52
+		@headitem
+		Modifier
+		@tab
+		Type(s)
+		@tab
+		@item
+		hh
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert input to char, store in char object
+		@item
+		h
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert input to short, store in short object
+		@item
+		h
+		@tab
+		e, f, c, s, p
+		@tab
+		no effect
+		@item
+		j
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert input to intmax_t, store in intmax_t object
+		@item
+		j
+		@tab
+		all others
+		@tab
+		no effect
+		@item
+		l
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert input to long, store in long object
+		@item
+		l
+		@tab
+		e, f, g
+		@tab
+		convert input to double, store in a double object
+		@item
+		l
+		@tab
+		c, s, [
+		@tab
+		the input is stored in a wchar_t object
+		@item
+		l
+		@tab
+		p
+		@tab
+		no effect
+		@item
+		ll
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert to long long, store in long long object
+		@item
+		L
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert to long long, store in long long object
+		@item
+		L
+		@tab
+		e, f, g, E, G
+		@tab
+		convert to long double, store in long double object
+		@item
+		L
+		@tab
+		all others
+		@tab
+		no effect
+		@item
+		t
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert input to ptrdiff_t, store in ptrdiff_t object
+		@item
+		t
+		@tab
+		all others
+		@tab
+		no effect
+		@item
+		z
+		@tab
+		d, i, o, u, x, n
+		@tab
+		convert input to size_t, store in size_t object
+		@item
+		z
+		@tab
+		all others
+		@tab
+		no effect
+		@end multitable
 
         o <[type]>
 
@@ -212,7 +277,7 @@ DESCRIPTION
                 characters:
 
 		o+
-		o  %
+		o %
 		No conversion is done; the percent character (<<%>>) is stored.
 
 		o c
@@ -225,7 +290,7 @@ DESCRIPTION
 		Corresponding <[arg]>: <<(char arg[])>>.
 		If an <<l>> specifier is present, the corresponding <[arg]> is a <<(wchar_t *arg)>>.
 
-		o  [<[pattern]>]
+		o [<[pattern]>]
 		Reads a non-empty character string into memory
 		starting at <[arg]>.  This area must be large
 		enough to accept the sequence and a
@@ -244,7 +309,7 @@ DESCRIPTION
 		o u
 		Reads an unsigned decimal integer into the corresponding
 		<[arg]>: <<(unsigned int *arg)>>.
-			
+
 		o x,X
 		Read a hexadecimal integer into the corresponding <[arg]>:
 		<<(int *arg)>>.
@@ -257,19 +322,19 @@ DESCRIPTION
 		Read a floating-point number into the corresponding <[arg]>:
 		<<(double *arg)>>.
 
-		o  i
+		o i
 		Reads a decimal, octal or hexadecimal integer into the
 		corresponding <[arg]>: <<(int *arg)>>.
 
-		o  n
+		o n
 		Stores the number of characters read in the corresponding
 		<[arg]>: <<(int *arg)>>.
 
-		o  p
+		o p
                 Stores a scanned pointer.  ANSI C leaves the details
 		to each implementation; this implementation treats
 		<<%p>> exactly the same as <<%U>>.  Corresponding
-		<[arg]>: <<(void **arg)>>.  
+		<[arg]>: <<(void **arg)>>.
                 o-
 
 	A <[pattern]> of characters surrounded by square brackets can be used
@@ -303,7 +368,7 @@ DESCRIPTION
 
 	where objects inclosed in square brackets are optional, and <<ddd>>
 	represents decimal, octal, or hexadecimal digits.
-	o-
+	O-
 
 RETURNS
         <<wscanf>> returns the number of input fields successfully