Hi David, David Gwynne wrote on Tue, Apr 03, 2018 at 02:01:33PM +1000:
> i landed on this manpage and got confused cos it looked different > to the rest of them. Note that the style of having multiple synopses in multiple sections of a page is used in more than one page - though admittedly in few: * openssl(1) * ifconfig(8) * bus_dma(9) * kern(9) * pmap(9) * uvm(9) In general, i don't like splitting the SYNOPSIS in this way much because until a few years ago, OpenBSD was the only operating system supporting it. Now, all systems using mandoc support it, but groff still doesn't, so it is still non-portable. Besides, the syntax .nr nS 1 (as described in roff(7)) is exceedingly ugly and non-obvious, originally an OpenBSD-specific hack. So if we can reduce the usage of this feature, i'm generally in favour, even though i don't have much hope that openssl(1) and ifconfig(8) can survive without it. > this shuffles it a bit to make it less different. > the main change is to move the function prototypes up to the synopsis. Sure, in the case at hand, that may be less surprising: The page is short and the SYNOPSIS is only split into two parts. > the other, less important change is to replace some headers with > subheaders. I know that jmc@ does not consider the difference between headers and subheaders very important, in particular when splitting a large DESCRIPTION into multiple parts. I'm often a bit more in favour of using subheaders than he is. In this case, i like subheaders better than separate sections, in particular since the page is short enough such that the subsections won't be of excessive length. > ok? OK schwarze@ Ingo > Index: autoconf.9 > =================================================================== > RCS file: /cvs/src/share/man/man9/autoconf.9,v > retrieving revision 1.16 > diff -u -p -r1.16 autoconf.9 > --- autoconf.9 11 Dec 2015 16:07:02 -0000 1.16 > +++ autoconf.9 3 Apr 2018 03:58:20 -0000 > @@ -41,6 +41,21 @@ > .Sh SYNOPSIS > .In sys/param.h > .In sys/device.h > +.Ft "void *" > +.Fn config_search "cfmatch_t func" "struct device *parent" "void *aux" > +.Ft "void *" > +.Fn config_rootsearch "cfmatch_t func" "char *rootname" "void *aux" > +.Ft "struct device *" > +.Fo config_found_sm > +.Fa "struct device *parent" > +.Fa "void *aux" > +.Fa "cfprint_t print" > +.Fa "cfmatch_t submatch" > +.Fc > +.Ft "struct device *" > +.Fn config_found "struct device *parent" "void *aux" "cfprint_t print" > +.Ft "struct device *" > +.Fn config_rootfound "char *rootname" "void *aux" > .Sh DESCRIPTION > Autoconfiguration is the process of matching hardware devices with an > appropriate device driver. > @@ -77,14 +92,7 @@ ends with a unit number. > The unit number identifies an instance of the driver. > Device data structures are allocated dynamically during autoconfiguration, > giving a unique address for each instance. > -.Sh INDIRECT CONFIGURATION > -.nr nS 1 > -.Ft "void *" > -.Fn config_search "cfmatch_t func" "struct device *parent" "void *aux" > -.Ft "void *" > -.Fn config_rootsearch "cfmatch_t func" "char *rootname" "void *aux" > -.nr nS 0 > -.Pp > +.Ss Indirect Configuration > The > .Fn config_search > function performs indirect configuration of physical devices by iterating > @@ -142,17 +150,7 @@ itself. > Note that this function is designed so that it can be used to apply an > arbitrary function to all potential children. > In this case callers may choose to ignore the return value. > -.Sh DIRECT CONFIGURATION > -.nr nS 1 > -.Ft "struct device *" > -.Fn config_found_sm "struct device *parent" "void *aux" "cfprint_t print" \ > - "cfmatch_t submatch" > -.Ft "struct device *" > -.Fn config_found "struct device *parent" "void *aux" "cfprint_t print" > -.Ft "struct device *" > -.Fn config_rootfound "char *rootname" "void *aux" > -.nr nS 0 > -.Pp > +.Ss Direct Configuration > The > .Fn config_found_sm > function performs direct configuration on a physical device.
