Subject: zpcictl: Change wording of man-page and help output
From: Jan Hoeppner <jan.hoeppner@de.ibm.com>

Summary:     zpcictl: Add tool to manage PCI devices
Description: Use the zpcictl tool to manage PCI devices on the IBM Z
             platform.  Initial functions include generating firmware
             error logs, resetting PCI devices, and preparing a device
             for further repair actions.
Upstream-ID: aaaebb2030c80151ecac528f22cb9a52752b868c
Problem-ID:  RAS1703

Upstream-Description:

             zpcictl: Change wording of man-page and help output

             Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>


Signed-off-by: Jan Hoeppner <jan.hoeppner@de.ibm.com>
---
 zpcictl/zpcictl.8 |   38 +++++++++++++++-----------------------
 zpcictl/zpcictl.c |   15 ++++++++-------
 2 files changed, 23 insertions(+), 30 deletions(-)

--- a/zpcictl/zpcictl.8
+++ b/zpcictl/zpcictl.8
@@ -20,7 +20,7 @@
 .TH zpcictl 8 "Oct 2018" s390-tools zpcictl
 .
 .SH NAME
-zpcictl - Manage PCI devices on z Systems
+zpcictl - Manage PCI devices on IBM Z
 .
 .
 .SH SYNOPSIS
@@ -30,50 +30,42 @@ zpcictl - Manage PCI devices on z System
 .
 .
 .SH DESCRIPTION
-With
+Use
 .B zpcictl
-, you can manage PCI devices on the IBM z Systems platform. It is especially
-used for reporting erroneous PCI devices to the service element.
+to manage PCI devices on the IBM Z platform. In particular,
+use this command to report defective PCI devices to the service element.
 
 .B Note:
 For NVMe devices additional data (such as S.M.A.R.T. data) is collected and sent
-with any error handling action. The smartmontools are required to be installed
-for this to work.
+with any error handling action. For this extendend data collection, the
+smartmontools must be installed.
 .PP
 .
 .
 .SH DEVICE
-.B DEVICE
-can be either the PCI slot address (e.g. 0000:00:00.0) or the main device node
-of an NVMe device (e.g.
+A PCI slot address (e.g. 0000:00:00.0) or the main device node of an NVMe
+device (e.g.
 .I /dev/nvme0
 ).
 .
 .
 .SH OPTIONS
-.SS Error Handling
+.SS Error Handling Options
 .OD reset "" "DEVICE"
-Reset
-.I DEVICE
-and initiate a re-initialization of the PCI device.
+Reset and re-initialize the PCI device.
 .PP
 .
 .OD deconfigure "" "DEVICE"
-De-configure
-.I DEVICE
-and prepare for any repair action. This action will move the
-PCI device from a configured to a reserved state.
+Deconfigure the PCI device and prepare for any repair action. This action
+changes the status of the PCI device from configured to reserved.
 .PP
 .
 .OD report-error "" "DEVICE"
-Report any device error for
-.IR DEVICE .
-The
-.I DEVICE
-is marked as erroneous and no further action is initiated on it.
+Report any device error for the PCI device.
+The device is marked as defective but no further action is taken.
 .PP
 .
-.SS Misc
+.SS General Options
 .OD help "h" ""
 Print usage information, then exit.
 .PP
--- a/zpcictl/zpcictl.c
+++ b/zpcictl/zpcictl.c
@@ -27,8 +27,9 @@
 #define SMARTCTL_CMDLINE "smartctl -x %s 2>/dev/null"
 
 static const struct util_prg prg = {
-	.desc = "Use zpcictl to manage PCI devices on s390\n"
-		"DEVICE is the slot id or node of the device (e.g. /dev/nvme0)",
+	.desc = "Use zpcictl to manage PCI devices on IBM Z\n"
+		"DEVICE is the slot ID or node of the device "
+		"(e.g. 0000:00:00.0 or /dev/nvme0)",
 	.args = "DEVICE",
 	.copyright_vec = {
 		{
@@ -46,23 +47,23 @@ static const struct util_prg prg = {
 #define OPT_REPORT_ERR	130
 
 static struct util_opt opt_vec[] = {
-	UTIL_OPT_SECTION("ERROR HANDLING"),
+	UTIL_OPT_SECTION("ERROR HANDLING OPTIONS"),
 	{
 		.option = { "reset", no_argument, NULL, OPT_RESET },
-		.desc = "Reset device",
+		.desc = "Reset the device",
 		.flags = UTIL_OPT_FLAG_NOSHORT,
 	},
 	{
 		.option = { "deconfigure", no_argument, NULL, OPT_DECONF },
-		.desc = "De-configure device and prepare for any repair action",
+		.desc = "Deconfigure the device to prepare for any repair action",
 		.flags = UTIL_OPT_FLAG_NOSHORT,
 	},
 	{
 		.option = { "report-error", no_argument, NULL, OPT_REPORT_ERR },
-		.desc = "Report device error to service element (SE)",
+		.desc = "Report a device error to the service element (SE)",
 		.flags = UTIL_OPT_FLAG_NOSHORT,
 	},
-	UTIL_OPT_SECTION("MISC"),
+	UTIL_OPT_SECTION("GENERAL OPTIONS"),
 	UTIL_OPT_HELP,
 	UTIL_OPT_VERSION,
 	UTIL_OPT_END