Re: autoconf.9 consistency
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.911 Dec 2015 16:07:02 - 1.16 > +++ autoconf.93 Apr 2018 03:58:20 - > @@ -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.
Re: autoconf.9 consistency
morning. to be honest, I think it's fine as it is now. the intention was obviously to keep the two systems separate. but I don't strongly object to your diff either, so if you feel it is more useful to have it in a more standard format, fine. jmc, sitting on the fence... Original Message From: da...@gwynne.id.au Sent: 3 April 2018 5:01 am To: j...@openbsd.org; schwa...@openbsd.org Cc: tech@openbsd.org Subject: autoconf.9 consistency i landed on this manpage and got confused cos it looked different to the rest of them. this shuffles it a bit to make it less different. the main change is to move the function prototypes up to the synopsis. the other, less important change is to replace some headers with subheaders. ok? 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 - 1.16 +++ autoconf.9 3 Apr 2018 03:58:20 - @@ -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.
autoconf.9 consistency
i landed on this manpage and got confused cos it looked different to the rest of them. this shuffles it a bit to make it less different. the main change is to move the function prototypes up to the synopsis. the other, less important change is to replace some headers with subheaders. ok? 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 - 1.16 +++ autoconf.9 3 Apr 2018 03:58:20 - @@ -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.
