Rework vis.3 so it has standard sections.

Moved the return values from the description to a proper return values
section.  Broke up the description into function description followed
by a subsection for the range and encoding.  Replaced srclen with
strlen(src) when srclen isn't an argument.  Moved the common flag argument
to its own paragraph.

input schwarze@, input + ok jmc@

1 files changed, 41 insertions, 38 deletions

diff --git a/lib/libc/gen/vis.3 b/lib/libc/gen/vis.3
index 31c67bab1ed..2eb4bb65454 100644
--- a/lib/libc/gen/vis.3
+++ b/lib/libc/gen/vis.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: vis.3,v 1.31 2014/11/30 15:54:18 schwarze Exp $
+.\"	$OpenBSD: vis.3,v 1.32 2015/01/30 00:01:59 doug Exp $
 .\"
 .\" Copyright (c) 1989, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -27,7 +27,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 30 2014 $
+.Dd $Mdocdate: January 30 2015 $
 .Dt VIS 3
 .Os
 .Sh NAME
@@ -57,19 +57,9 @@ a string which represents the character
 If
 .Fa c
 needs no encoding, it is copied in unaltered.
-The string is NUL-terminated and a pointer to the end of the string is
-returned.
-The maximum length of any encoding is four
-characters (not including the trailing NUL);
-thus, when
-encoding a set of characters into a buffer, the size of the buffer should
-be four times the number of characters encoded, plus one for the trailing
-NUL.
-The
-.Fa flag
-parameter is used for altering the default range of
-characters considered for encoding and for altering the visual
-representation.
+.Fa dst
+will be NUL-terminated and must be at least 5 bytes long
+(maximum encoding requires 4 bytes plus the NUL).
 The additional character,
 .Fa nextc ,
 is only used when selecting the
@@ -93,7 +83,7 @@ function encodes characters from
 .Fa src
 up to the first NUL, into a buffer
 .Fa dst
-(which must be at least 4 * srclen + 1 long).
+(which must be at least 4 * strlen(src) + 1 long).
 .Pp
 The
 .Fn strnvis
@@ -116,7 +106,7 @@ into a buffer
 This
 is useful for encoding a block of data that may contain NULs.
 .Pp
-All three forms NUL-terminate
+All forms NUL-terminate
 .Fa dst ,
 except for
 .Fn strnvis
@@ -125,25 +115,13 @@ when
 is zero, in which case
 .Fa dst
 is not touched.
-.Fn strvis
-and
-.Fn strvisx
-return the number of characters in
-.Fa dst
-(not including the trailing NUL).
-.Fn strnvis
-returns the length that
-.Fa dst
-would become if it were of unlimited size (similar to
-.Xr snprintf 3
-or
-.Xr strlcpy 3 ) .
-This can be used to detect truncation but it also means that
-the return value of
-.Fn strnvis
-must not be used without checking it against
-.Fa dstsize .
 .Pp
+The
+.Fa flag
+parameter is used for altering the default range of
+characters considered for encoding and for altering the visual
+representation.
+.Ss Encodings
 The encoding is a unique, invertible representation composed entirely of
 graphic characters; it can be decoded back into the original form using
 the
@@ -299,6 +277,30 @@ meta characters as
 .Ql M-C ) .
 With this flag set, the encoding is
 ambiguous and non-invertible.
+.Sh RETURN VALUES
+.Fn vis
+returns a pointer to the terminating NUL character of the string
+.Fa dst .
+.Pp
+.Fn strvis
+and
+.Fn strvisx
+return the number of characters in
+.Fa dst
+(not including the trailing NUL).
+.Pp
+.Fn strnvis
+returns the length that
+.Fa dst
+would become if it were of unlimited size (similar to
+.Xr snprintf 3
+or
+.Xr strlcpy 3 ) .
+This can be used to detect truncation, but it also means that
+the return value of
+.Fn strnvis
+must not be used without checking it against
+.Fa dstsize .
 .Sh SEE ALSO
 .Xr unvis 1 ,
 .Xr vis 1 ,
@@ -312,11 +314,12 @@ The
 and
 .Fn strvisx
 functions first appeared in
-.Bx 4.4 .
-The
+.Bx 4.4
+and
 .Fn strnvis
-function first appeared in
+in
 .Ox 2.9 .
+.Pp
 The
 .Dv VIS_ALL
 flag first appeared in