RFC: pciconf.8 options diff

[Tom Rhodes]

On Fri, 9 Jul 2004 02:25:34 +0300
Giorgos Keramidas <keramida at freebsd.org> wrote:

> I've tried to convert the description of options in pciconf.8 to the
> usual .Bl ... .El style.  The changes I made locally are:
> 
> %%
> Index: pciconf.8
> ===================================================================
> RCS file: /home/ncvs/src/usr.sbin/pciconf/pciconf.8,v
> retrieving revision 1.26
> diff -u -r1.26 pciconf.8
> --- pciconf.8	6 Jan 2004 20:23:20 -0000	1.26
> +++ pciconf.8	8 Jul 2004 23:19:51 -0000
> @@ -52,22 +52,16 @@
>  .Pa /dev/pci ,
>  normally only the super-user.
>  .Pp
> -With the
> -.Fl l
> -option, it lists all devices found by the boot probe in the following format:
> +The following options are available:
> +.Bl -tag -width indent
> +.It Fl l
> +Lists all devices found by the boot probe in the following format:
>  .Bd -literal
>  foo0 at pci0:4:0: class=0x010000 card=0x00000000 chip=0x000f1000 rev=0x01 hdr=0x00
>  bar0 at pci0:5:0: class=0x000100 card=0x00000000 chip=0x88c15333 rev=0x00 hdr=0x00
>  none0 at pci0:6:0: class=0x020000 card=0x00000000 chip=0x802910ec rev=0x00 hdr=0x00
>  .Ed
>  .Pp
> -If the
> -.Fl v
> -option is supplied,
> -.Nm
> -will attempt to load the vendor/device information database, and print
> -vendor, device, class and subclass identification strings for each device.
> -.Pp
>  The first column gives the
>  device name, unit number, and
>  .Ar selector .
> @@ -80,8 +74,10 @@
>  The
>  .Ar selector
>  is in a form which may directly be used for the other forms of the command.
> +.Pp
>  The second column is the class code, with the class byte printed as two
>  hex digits, followed by the sub-class and the interface bytes.
> +.Pp
>  The third column gives the contents of the subvendorid register, introduced
>  in revision 2.1 of the
>  .Tn PCI
> @@ -99,8 +95,11 @@
>  this card is based on.
>  It consists of two fields, identifying the chip and
>  its vendor, as above.
> +.Pp
>  The fifth column prints the chip's revision.
> +.Pp
>  The sixth column describes the header type.
> +.Pp
>  Currently assigned header types are 0 for all devices except
>  .Tn PCI
>  to

In place of all these .Pp macros, how about making them a list?
Perhaps:

.Bl -bullet
.It
I describe column one.
.It
I describe column two.
...

> @@ -115,36 +114,20 @@
>  device, which contains several (similar or independent) functions on
>  one chip.
>  .Pp
> -All invocations of
> -.Nm
> -except for
> -.Fl l
> -require a
> -.Ar selector
> -of the form
> -.Li pci Ns Va bus Ns \&: Ns Va device
> -(optionally followed by
> -.Li \&: Ns Va function ) .
> -A final colon may be appended and
> -will be ignored; this is so that the first column in the output of
> -.Nm
> -.Fl l
> -can be used without modification.
> -All numbers are base 10.
> -.Pp
> -With the
> -.Fl a
> -flag,
> +.It Fl v
> +When used in combination with
> +.Fl l ,
>  .Nm
> -determines whether any driver has been assigned to the device
> +will attempt to load the vendor/device information database, and print
> +vendor, device, class and subclass identification strings for each device.
> +.It Fl a
> +Determine whether any driver has been assigned to the device
>  identified by

s/any/a here

>  .Ar selector .
>  An exit status of zero indicates that the device has a driver;
>  non-zero indicates that it does not.
> -.Pp
> -The
> -.Fl r
> -option reads a configuration space register at byte offset
> +.It Fl r
> +Reads a configuration space register at byte offset
>  .Ar addr
>  of device
>  .Ar selector
> @@ -152,25 +135,47 @@
>  The optional second address
>  .Ar addr2
>  specifies a range to read.
> -The
> -.Fl w
> -option writes the
> +.It Fl w
> +Write the
>  .Ar value
>  into a configuration space register at byte offset
>  .Ar addr
>  of device
>  .Ar selector .
> -For both operations, the flags
> -.Fl b
> -and
> -.Fl h
> -select the width of the operation;
> -.Fl b
> -indicates a byte operation, and
> -.Fl h
> -indicates a halfword (two-byte) operation.
> -The default is to read or
> -write a longword (four bytes).
> +.It Fl b
> +When used in combination with
> +.Fl r
> +or
> +.Fl w

Perhaps a comma after w?

> +indicate that the width of the operation is 1 byte.
> +The default is to read or write a longword (four bytes).
> +.It Fl h
> +When used in combination with
> +.Fl r
> +or
> +.Fl w

Again here?

> +indicate that the width of the operation is 1 half-word (two bytes).
> +The default is to read or write a longword (four bytes).
> +.El
> +.Pp
> +All invocations of
> +.Nm
> +except for
> +.Fl l
> +require a
> +.Ar selector
> +of the form
> +.Li pci Ns Va bus Ns \&: Ns Va device
> +(optionally followed by
> +.Li \&: Ns Va function ) .

I don't think we need '()' around this text.

> +A final colon may be appended and
> +will be ignored; this is so that the first column in the output of

s/that //

> +.Nm
> +.Fl l
> +can be used without modification.
> +All numbers in the
> +.Ar selector
> +are base 10.
>  .Sh ENVIRONMENT
>  The PCI vendor/device information database is normally read from
>  .Pa /usr/share/misc/pci_vendors .
> %%
> 
> Any objections to committing this?  Comments?  Suggestions for
> improvement?
> 
> I know that the options are unsorted in the resulting manpage.
> If it's ok to sort the options with a different commit, then
> I'll do it separately.  Otherwise I'll do it in only one commit.

Remember, you are not required to take my advice.  It's only when
I demand you take my advice that you actually take my advice.  :)

-- 
Tom Rhodes