RFC: pciconf.8 options diff

[Giorgos Keramidas]

On 2004-07-08 20:59, Tom Rhodes <trhodes at freebsd.org> wrote:
> 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:

I forgot to add that there are places where things can be rewritten, but
I didn't touch those.  I planned to reorder/rearrange the text first and
then do grammar, syntax or other content changes.

> > @@ -80,8 +74,10 @@
> > [...]
> > +.Pp
> >  The second column [...]
> > +.Pp
> >  The third column [...]
>
> 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.
> ...

That seems ok too.  Even without making the change to a second-level
list, the manpage is IMHO a lot more readable when each one of `first',
`second', ... `sixth' are in separate paragraphs.

The only argument I have against a second-level list is that I tend to
prefer avoiding deeply nested lists.  If that's what everyone else
prefers though, it's fine too.

> > -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

That's part of the original text, but thanks for catching it.

> > +.It Fl b
> > +When used in combination with
> > +.Fl r
> > +or
> > +.Fl w
>
> Perhaps a comma after w?

Heh.  I spent a few moments wondering about this one.  It's probably ok
to add a comma.  Does anyone have some sort of English syntax & style
pointer that could clarify which of the two is actually correct?  My gut
feeling is that a comma *is* required.

> > +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.

I think we do.  Read the text in the formatted manpage.

    All invocations of pciconf except for -l require a selector of the
    form pcibus:device (optionally followed by :function).

Some sort of separation needs to be done.  There are other ways to write
this too, such as:

    All invocations of pciconf except for -l require a selector of the
    form pcibus:device[:function].

It's more compact and follows the well-known(?) convention of enclosing
optional parts in square brackets.

> > +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.

I have better plans for this one after the options are made into a list,
are sorted and content changes are ok to make:

    A final colon may be appended and it will be ignored.  This allows
    using the first column of `pciconf -l' without modification.

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

Thanks.  I appreciate it, but I see no comments about making the options
a list with `.Bl'.  Does that mean it's ok?

Note that there *is* a problem with the options list in the change I
posted, which I noticed this morning while reading the `nroff' output
for the changed manpage.  The sample `pciconf -l' output gets indented
too much and crosses the 80-column boundary.  I'm not sure how to solve
this without editing the pciconf output to make it look like:

                hostb0 at pci0:0:0:  class=NUM card=NUM chip=NUM rev=NUM hdr=NUM
                hostb0 at pci0:0:0:  class=NUM card=NUM chip=NUM rev=NUM hdr=NUM
                hostb0 at pci0:0:0:  class=NUM card=NUM chip=NUM rev=NUM hdr=NUM

which solves the width problems, but loses us some information (namely,
the fact that the numbers printed by pciconf are in hexadecimal).

Giorgos