RFC: pciconf.8 options diff

[Tom Rhodes]

On Fri, 9 Jul 2004 10:14:29 +0300
Giorgos Keramidas <keramida at ceid.upatras.gr> wrote:

Sorry for the lateness of this reply, I got tricked into being
guest DJ Friday night.  :(

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

That is 'ok' with me.  Content changes seperate.  :)

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

Your first comment is very true; however, on the next comment,
well, I don't really care much.  I just thought the output would
have looked 'neater' and it would make the separation between
the parts more distinct.

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

No problem, please fix that too at some point.  :)

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

In English a comma designates a pause, hence if you read it out
loud without a pause it sounds like a run on and/or an awful lot
to say.  As for a 'rule', well, my college English books are at
home and I am at work.  Want me to check for you?

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

My only problem was that it the separation seemed superfluous, the
text would sound just fine as part of the sentence.  Perhaps:

... of the form pcibus:device; optionally followed by a :function
delimiter.

would sound better?

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

I really didn't understand you here, do you mean that this will
be the new sentence eventually?

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

Yes, I think that would 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).

Have you tried it with the .Dl macro?  /me is too lazy to see
how the current markup looks.

-- 
Tom Rhodes