Re: Giving up on emulating SYNOPSIS vspace.

[Kristaps Dzonsons <kristaps@bsd.lv>]

> 1) SYNOPSIS macros following non-SYNOPSIS-specific text
> -------------------------------------------------------
> Consider /usr/src/lib/libc/compat-43/sigvec.3:
> 
>   .Sh SYNOPSIS
>   .Fd #include <signal.h>
>   .Pp
>   .Bd -literal
>   struct sigvec {
>   	void     (*sv_handler)();
>   	int      sv_mask;
>   	int      sv_flags;
>   };
>   .Ed
>   .Ft int
>   .Fn sigvec "int sig" "struct sigvec *vec" "struct sigvec *ovec"
> 
> I think this is sane usage.

I agree.  I'm yet to find a good way to document structs.  This is as 
good as any.  And I agree: if `Ft' (and/or all SYNOPSIS-set macros) 
assert prior vspace for /all/ non-like elements, we'll capture this 
usage fine.

> Besides, the .Pp after the .Fd causes *two* blank lines.
> One would be sufficient.
> But that is not important, lets just add it to the TODO list
> and not worry about it right now.

Agreed.  Pp should be a little smarter in general about when it's a noop 
(i.e., on a newline as it is).

> 2) global variables
> -------------------
> Consider /usr/src/lib/libc/rpc/svc.3:
> 
>   .Ft int
>   .Fn svc_destroy "SVCXPRT *xprt"
>   .Ft struct pollfd *
>   .Fa svc_pollfd ;
>   .Ft int
>   .Fa svc_max_pollfd ;
>   .Ft fd_set
>   .Fa svc_fdset ;
>   .Ft fd_set
>   .Fa *__svc_fdset ;
>   .Ft int
>   .Fa __svc_fdsetsize ;
>   .Ft int
>   .Fa svc_fds ;
>   .Ft int
>   .Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in"
> 
> I think this is acceptable usage; probably using .Va instead of .Fa
> would be a bit better, but apart from that, i wouldn't know how to
> express this in a better way.  (NB, it wasn't RPC variable naming
> conventions i was trying to praise here... ;-)

`Vt' is documented for use in this case.

> 
> There is no more blank line between the .Ft/.Fa (or .Ft/.Va) pairs.
> It think it might be good to treat .Ft/.Fa and .Ft/.Va exactly
> like .Ft/.Fn.  Why not just *always* issue the blank line before
> .Ft, whatever may be following?  Wouldn't that make the code even
> simpler, all the while improving the results?  I really can't think
> of any sane construct that might not want a blank line before .Ft
> in the synopsis - and even less find one in real manuals.

I agree, although it should be Vt (there aren't any "F" in the Ft/Fa).

> That's all i found in libc.

Nice!

> Of course, large portions of man9 are still garbled for the lack
> of .nr support, but that's another matter.
> 
> So, i'm going to commit this to OpenBSD, we can fix the two minor
> issues presented above in tree, either now or later.

Can you commit fixes to BSD.lv as well?

Thanks,

Kristaps
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv