Date: Sat, 10 Jul 2004 09:40:51 -0400 From: Tom Rhodes <trhodes@FreeBSD.org> To: Giorgos Keramidas <keramida@ceid.upatras.gr> Cc: Ruslan Ermilov <ru@FreeBSD.org> Subject: Re: RFC: pciconf.8 options diff Message-ID: <20040710094051.033eee5e@localhost.pittgoth.com> In-Reply-To: <20040709071429.GA10729@orion.daedalusnetworks.priv> References: <20040708232534.GA85731@gothmog.gr> <20040708205913.502f6911@localhost.pittgoth.com> <20040709071429.GA10729@orion.daedalusnetworks.priv>
next in thread | previous in thread | raw e-mail | index | archive | help
On Fri, 9 Jul 2004 10:14:29 +0300 Giorgos Keramidas <keramida@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@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. 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@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). Have you tried it with the .Dl macro? /me is too lazy to see how the current markup looks. -- Tom Rhodes
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20040710094051.033eee5e>