Re: [PATCH] smartpqi: initial submit of smartpqi man page

["G. Branden Robinson" <g.branden.robinson-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

[-- Attachment #1: Type: text/plain, Size: 3241 bytes --]

At 2017-10-20T22:10:55+0000, Don Brace wrote:
> > -----Original Message-----
> > From: G. Branden Robinson [mailto:g.branden.robinson-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org]
> > I made many changes, most of them formatting-related.
> 
> Really appreciate your effort!

Thanks!

> > There are some issues I was unsure about; I left them in comments:

Just FYI, these were as much for Michael Kerrisk's feedback as yours.
I'm just a volunteer like most people on the linux-man list, so please
don't feel that all of these issues have to be resolved before the page
can make it in; Mr. Kerrisk is the gatekeeper.

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

My preference as a committed non-professional sysadmin is to never have
to dig up a piece of paper to find out how to configure my hardware.  :)

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

I hope that's restricted to read operations.  ;-)

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

I checked and the original too-wide line is also too wide on troff's
PostScript output device, and runs into the page margin.

Your solution is one obvious one; another would be to put a shell
line-continuation into the example.

.IP
For example:
.in +4n
.EX
.RB "$ " cat /sys/class/scsi_disk/1:0:3:0/device/\\e
.RB "> " ssd_smart_path_enabled
0
.EE
.in

Which renders as:

              For example:
                  $ cat /sys/class/scsi_disk/1:0:3:0/device/\
                  > ssd_smart_path_enabled
                  0

But with the user input in boldface.

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

Yup, I noticed that, too.  When Michael K. has a chance to review my
suggestions, I'm happy to supply patches to cciss(4) and hpsa(4) to
"parallelize" the three.

> > 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 have no preference here; I just wanted to make sure the orthography
was right.  I don't want anyone getting flamed by their trademark
lawyer.  :D

-- 
Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]