> -----Original Message----- > From: G. Branden Robinson [mailto:g.branden.robinson@xxxxxxxxx] > Sent: Thursday, October 19, 2017 4:36 PM > To: Don Brace <don.brace@xxxxxxxxxxxxx> > Cc: mtk.manpages@xxxxxxxxx; linux-man@xxxxxxxxxxxxxxx; Gerry Morong > <gerry.morong@xxxxxxxxxxxxx>; John Hall <John.Hall@xxxxxxxxxxxxx>; > Kevin Barnett <kevin.barnett@xxxxxxxxxxxxx>; Bader Ali - Saleh > <bader.alisaleh@xxxxxxxxxxxxx>; Scott Teel <scott.teel@xxxxxxxxxxxxx>; > Justin Lindley <justin.lindley@xxxxxxxxxxxxx>; Scott Benesh > <scott.benesh@xxxxxxxxxxxxx> > Subject: Re: [PATCH] smartpqi: initial submit of smartpqi man page > > At 2017-10-18T10:10:39-0500, Don Brace wrote: > > This patch contains the initial submission of the > > smartpqi man page. > > Hi Don, > > Please find attached my recommended changes. > > I made many changes, most of them formatting-related. Really appreciate your effort! > > There are some issues I was unsure about; I left them in comments: > > To configure Microsemi Smart Family controllers, please refer to the > controller's User Guide documentation. > .\" Does this manual have a title? Is it freely available online? > .\" Does it have a stable URL? Can this information be moved to the SEE > .\" ALSO section? There is currently no User Guide available on-line. The guide should be packaged with the controller. There is a Documentation/scsi/smartpqi.txt entry. > > .\" What is "ioaccel"? This string appears nowhere in man-pages HEAD. This is a term for RAID volumes. When an I/O request can go directly to a physical disk bypassing the RAID engine in the controller. This results in a performance gain. > > .\" This example line is too wide for an 80-column TTY. > .B cat /sys/class/scsi_disk/1:0:3:0/device/ssd_smart_path_enabled How about: cd /sys/class/scsi_disk/1:0:3:0/device/ cat ssd_smart_path_enabled > > .SS Supported \f[BI]ioctl\fP\/() operations > .\" Does this subsection belong here, under .SH FILES ? I see your point. This should be in a different section. We saw that hpsa.4 had done the same thing. Should this be under NOTES? > > And here's one more I just thought of (forest, trees...). > > Is "SmartPQI" the correct casing when referring to the product rather > than the kernel module? The driver name is smartpqi, perhaps omitting the SmartPQI or SMARTPQI would be best for these sections. > > I checked the output on 80- and 191-column terminals and with a > PostScript viewer. > > [1] And which doesn't "work everywhere", anyway, for instance on EBCDIC > systems. IIRC, the groff guys discourage defining a string escape this > way. > [2] I don't know of another term for this. "In subsection ("SS") > headings, capitalize the first word in the heading, but otherwise > use lowercase, except where English usage (e.g., proper nouns) or > programming language requirements (e.g., identifier names) dictate > otherwise." > [3] MTK: Is this a candidate for the "Preferred terms" subsection of > man-pages(7)? > > -- > Regards, > Branden -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
