From owner-freebsd-doc@FreeBSD.ORG Sat Jul 10 13:40:33 2004 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 6163E16A4CE; Sat, 10 Jul 2004 13:40:33 +0000 (GMT) Received: from pittgoth.com (14.zlnp1.xdsl.nauticom.net [209.195.149.111]) by mx1.FreeBSD.org (Postfix) with ESMTP id B8D3F43D1D; Sat, 10 Jul 2004 13:40:32 +0000 (GMT) (envelope-from trhodes@FreeBSD.org) Received: from localhost.pittgoth.com (acs-24-154-239-141.zoominternet.net [24.154.239.141]) (authenticated bits=0) by pittgoth.com (8.12.11/8.12.11) with ESMTP id i6ADeJSY011540 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Sat, 10 Jul 2004 09:40:20 -0400 (EDT) (envelope-from trhodes@FreeBSD.org) Date: Sat, 10 Jul 2004 09:40:51 -0400 From: Tom Rhodes To: Giorgos Keramidas 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> X-Mailer: Sylpheed version 0.9.11claws (GTK+ 1.2.10; i386-portbld-freebsd5.2) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit cc: Tom Rhodes cc: doc@FreeBSD.org cc: Ruslan Ermilov Subject: Re: RFC: pciconf.8 options diff X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 10 Jul 2004 13:40:33 -0000 On Fri, 9 Jul 2004 10:14:29 +0300 Giorgos Keramidas 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 wrote: > > On Fri, 9 Jul 2004 02:25:34 +0300 > > Giorgos Keramidas 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