svn commit: r316550 - head/share/man/man9

[Bruce Evans]

On Thu, 6 Apr 2017, Ngie Cooper wrote:

> Log:
>  sbuf(9): convert SYNOPSIS section from .Fn entries to .Fo/.Fa/.Fc entries
>
>  This shortens the column count on many lines considerably.

This adds a lot of style bugs.  It increases the macro count and the row
count considerably.

>  While here, add "(void)" to sbuf_new_auto(3) for consistency with style(9)
>  recommendations.

This has nothing to do with style 9.  sbuf_new_auto() wasn't even declared
with a prototype.  Though it may have only been a style bug to not use
prototypes in 1990, it is now sually a warning and thus an error if it is
in a header file (since the user might enable -Werror and -Wsystem-headers
might not be off to break warnings in system headers.

> Modified: head/share/man/man9/sbuf.9
> ==============================================================================
> --- head/share/man/man9/sbuf.9	Thu Apr  6 02:03:35 2017	(r316549)
> +++ head/share/man/man9/sbuf.9	Thu Apr  6 02:40:52 2017	(r316550)
> @@ -66,57 +66,135 @@
> .Ft typedef\ int ( sbuf_drain_func ) ( void\ *arg, const\ char\ *data, int\ len ) ;
> .Pp
> .Ft struct sbuf *
> -.Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags"
> +.Fo sbuf_new
> +.Fa "struct sbuf *s"
> +.Fa "char *buf"
> +.Fa "int length"
> +.Fa "int flags"
> +.Fc

The .Fn macro exists so that you don't have to write verbose macros for
every arg, and so that the syntax resembles a C prototype and not a K&R-
style list of args and their types.  .Fo/.Fc is unfortunately sometimes
necessary for long arg lists, if you want not-too-long lines.  It can
also be used for complex declarations.  Perhaps for prototypes with
nested protototypes.  The nesting can be arbitrarily deep.

Bruce