From owner-freebsd-doc@FreeBSD.ORG Fri Jul 9 07:12:12 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 B2C0916A4CE; Fri, 9 Jul 2004 07:12:12 +0000 (GMT) Received: from frodo.otenet.gr (frodo.otenet.gr [195.170.0.12]) by mx1.FreeBSD.org (Postfix) with ESMTP id 6EAE643D2F; Fri, 9 Jul 2004 07:12:11 +0000 (GMT) (envelope-from keramida@ceid.upatras.gr) Received: from orion.daedalusnetworks.priv (aris.bedc.ondsl.gr [62.103.39.226]) by frodo.otenet.gr (8.12.10/8.12.10) with SMTP id i697C5ds021736; Fri, 9 Jul 2004 10:12:06 +0300 Received: from orion.daedalusnetworks.priv (orion [127.0.0.1]) i697EV63011054; Fri, 9 Jul 2004 10:14:31 +0300 (EEST) (envelope-from keramida@ceid.upatras.gr) Received: (from keramida@localhost)i697ETx7011053; Fri, 9 Jul 2004 10:14:29 +0300 (EEST) (envelope-from keramida@ceid.upatras.gr) Date: Fri, 9 Jul 2004 10:14:29 +0300 From: Giorgos Keramidas To: Tom Rhodes Message-ID: <20040709071429.GA10729@orion.daedalusnetworks.priv> References: <20040708232534.GA85731@gothmog.gr> <20040708205913.502f6911@localhost.pittgoth.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20040708205913.502f6911@localhost.pittgoth.com> cc: Ruslan Ermilov cc: doc@freebsd.org 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: Fri, 09 Jul 2004 07:12:12 -0000 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. > > @@ -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