Okay, I've done a lot to sys/net/if_tun.c, and was among other things
writing a tun(4) manpage.  But I am running into trouble with the
-mandoc macros.  I've got three main problems.

(1) .Nd and .Ss are not documented, as far as I can tell, except for
    the following passing references in mdoc(7)

     .Sh   Section Headers.  Valid headers, in the order of presentation:
           NAME           Name section, should include the `.Nm' or `.Fn' and
                          the `.Nd' macros.

     .Ss   Subsection Headers.

    and the following in mdoc.samples(7)

     .Sh NAME      The `.Sh NAME' macro is mandatory.  If not specified, the
[...]
                   is the Name Description macro, `.Nd', which separates the
                   subject name from the third item, which is the description.
                   The description should be the most terse and lucid possi-
                   ble, as the space available is small.

     .Pp     The .Pp paragraph command may be used to specify a line space
             where necessary.  The macro is not necessary after a `.Sh' or
             `.Ss' macro or before a `.Bl' macro.  (The `.Bl' macro asserts a
             vertical distance unless the -compact flag is given).

    This also, of course, makes me wonder what else is there but
    undocumented...I'm not happy with some of the choices I've made,
    because there seemed to be no appropriate macro for what I wanted.
    I'm left wondering if maybe there is one that just isn't
    documented.

(2) .Nd is not parsed.  I write

	.Sh NAME
	.Nm tun
	.Nd Dq tunnel No software network interface

    and get

	NAME
	     tun - Dq tunnel No software network interface

    What is the correct way to do this?

(3) Something is broken with .Bl, or perhaps with my understanding and
    therefore use of it.  I had a stab at doing a list, based on
    mdoc(7) and mdoc.samples(7), and indentation walks to the right
    more and more with each item, not resetting until the next .Sh!

    I write

	A large number of
	.Xr ioctl 2
	calls are also supported.  They are defined in
	.Aq Pa net/if_tun.h Ns .
	.Bl -tag -offset indent
	.It Dv TUNSDEBUG
	The argument should be a pointer to an
	.Va int ;
	this sets the internal debugging variable to that value.  What, if
	anything, this variable controls is not documented here; see the source
	code.
	.It Dv TUNGDEBUG
	The argument should be a pointer to an
	.Va int ;
	this stores the internal debugging variable's value into it.
	.It Dv TUNSMODE
	The argument should be a pointer to an
	.Va int ;
	its value must be
	.Dv IFF_POINTOPOINT
	or
	.Dv IFF_BROADCAST .
	The type of the corresponding
	.Em tun Ns Sy n
	interface is set to the supplied type.  If the value is anything else,
	an
	.Er EINVAL
	error occurs.  The interface must be down at the time; if it is up, an
	.Er EBUSY
	error occurs.
	.\" (large number of comment lines here; if I don't comment out
	.\" the rest of this list, indentation walks to the right until
	.\" I see everything hyphenated as much as possible, one word
	.\" fragment per line walking down the right margin.)
	.El
	The data control device also supports
	.Xr select 2
	for read; ...

    and I get

                          ....  A large number of ioctl(2) calls are also sup-
     ported.  They are defined in <net/if_tun.h>.

           TUNSDEBUG
             The argument should be a pointer to an int; this sets the inter-
             nal debugging variable to that value.  What, if anything, this
             variable controls is not documented here; see the source code.

                   TUNGDEBUG
                     The argument should be a pointer to an int; this stores
                     the internal debugging variable's value into it.

                           TUNSMODE
                             The argument should be a pointer to an int; its
                             value must be IFF_POINTOPOINT or IFF_BROADCAST.
                             The type of the corresponding tunn interface is
                             set to the supplied type.  If the value is any-
                             thing else, an EINVAL error occurs.  The inter-
                             face must be down at the time; if it is up, an
                             EBUSY error occurs.
                     The data control device also supports select(2) for read;

    Indentation stays at that two-tabs-over position until the next .Sh
    (with excursions, of course - for example, a .Ss line dedents by
    two characters relative to it).

Is this pilot error, a bug in the macros, intended behavior (!), or
what?  Should I file a PR?  I'm about ready to send-pr my new tun
driver, but I don't want to do that until I have a tun(4) ready to go.

					der Mouse

			    mouse@collatz.mcrcim.mcgill.edu