Date: Fri, 9 Jul 2004 10:14:29 +0300 From: Giorgos Keramidas <keramida@ceid.upatras.gr> To: Tom Rhodes <trhodes@freebsd.org> Cc: doc@freebsd.org Subject: Re: RFC: pciconf.8 options diff Message-ID: <20040709071429.GA10729@orion.daedalusnetworks.priv> In-Reply-To: <20040708205913.502f6911@localhost.pittgoth.com> References: <20040708232534.GA85731@gothmog.gr> <20040708205913.502f6911@localhost.pittgoth.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On 2004-07-08 20:59, Tom Rhodes <trhodes@freebsd.org> wrote:
> On Fri, 9 Jul 2004 02:25:34 +0300
> Giorgos Keramidas <keramida@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@pci0:0:0: class=NUM card=NUM chip=NUM rev=NUM hdr=NUM
hostb0@pci0:0:0: class=NUM card=NUM chip=NUM rev=NUM hdr=NUM
hostb0@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20040709071429.GA10729>