Re: Giving up on emulating SYNOPSIS vspace.

[Ingo Schwarze <schwarze@usta.de>]

Kristaps Dzonsons wrote on Mon, Jun 07, 2010 at 01:12:15PM +0200:

> It's much nicer now.

Right.  The code has definitely become more systematic, and i do not
see any serious fallout.

There a a two minor issues.

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.

There is no more blank line between the .Ed and .Ft (missing term_vspace).
I guess this can be easily fixed by making .Ft and friends issue a
term_vspace after *any* preceding content, even regular text or
random macros.  Not because that would be closer to groff (not sure
whether it would), but because it looks better.

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.


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... ;-)

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.


That's all i found in libc.

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.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv