LU-15766 doc: Improve lfs-hsm.1 to match options in lfs.c

Manual page lfs-hsm.1 has minor inconsistent formatting
issues such as:

lfs hsm_state <FILE>...
lfs hsm_action file

and missing optional argument [--archive-id NUM]. According
to lfs.c the options shall be, e.g:

{"hsm_set", lfs_hsm_set, 0, "Set HSM user flag on specified files.n"
 "usage: hsm_set [--norelease] [--noarchive] [--dirty] [--exists] "
 "[--archived] [--lost] [--archive-id NUM] <file> ..."}

This patch ensures that manual page and options
in lfs.c are in match and consistent.

Change-Id: I745958f842d74e2627ae232197cc0143c368048d
Test-Parameters: trivial
Signed-off-by: Thomas Stibor <t.stibor@gsi.de>
Reviewed-on: https://review.whamcloud.com/47099
Tested-by: jenkins <devops@whamcloud.com>
Tested-by: Maloo <maloo@whamcloud.com>
Reviewed-by: Andreas Dilger <adilger@whamcloud.com>
Reviewed-by: Etienne AUJAMES <eaujames@ddn.com>
Reviewed-by: Oleg Drokin <green@whamcloud.com>

diff --git a/lustre/doc/Makefile.am b/lustre/doc/Makefile.am
index 8792e28..06c326f 100644 (file)
--- a/lustre/doc/Makefile.am
+++ b/lustre/doc/Makefile.am
@@ -53,6 +53,10 @@ MANFILES =                                   \
        lfs-getstripe.1                         \
        lfs-heat.1                              \
        lfs-hsm.1                               \
+       lfs-hsm_action.1                        \
+       lfs-hsm_clear.1                         \
+       lfs-hsm_set.1                           \
+       lfs-hsm_state.1                         \
        lfs-ladvise.1                           \
        lfs_migrate.1                           \
        lfs-migrate.1                           \

diff --git a/lustre/doc/lfs-hsm.1 b/lustre/doc/lfs-hsm.1
index b88930c..b5261fd 100644 (file)
--- a/lustre/doc/lfs-hsm.1
+++ b/lustre/doc/lfs-hsm.1
@@ -1,38 +1,44 @@
-.TH lfs-hsm 1 "November 20, 2017" Lustre "Lustre/HSM binding utility"
+.TH LFS-HSM 1 "April 20, 2022" Lustre "Lustre/HSM binding utility"
 .SH NAME
-.Blfs hsm_command
-lfs commands used to interact with HSM features
+hsm_state, hsm_action, hsm_set, hsm_clear \- lfs commands used to interact with HSM features
 .SH SYNOPSIS
 .B lfs hsm_state
-.RB <FILE> ...
-.br
-.B  lfs hsm_action
-.RI file
-.br
-.B  lfs hsm_set|hsm_clear
-.RB [ --norelease ]
-.RB [ --noarchive ]
-.RB [ --dirty ]
-.RB [ --exists ]
-.RB [ --archived ]
-.RB [ --lost ]
-.RB [ --archive-id ]
-.RB <FILE> ...
-.br
+[\fI\,FILE\/\fR]...
+.PP
+.B lfs hsm_action
+[\fI\,FILE\/\fR]...
+.PP
+.B lfs hsm_set
+[\fB\-\-norelease\fR]
+[\fB\-\-noarchive\fR]
+[\fB\-\-exists\fR]
+[\fB\-\-archived\fR]
+[\fB\-\-lost\fR]
+[\fB\-\-archive-id\fR \fINUM\fR]
+[\fI\,FILE\/\fR]...
+.PP
+.B lfs hsm_clear
+[\fB\-\-norelease\fR]
+[\fB\-\-noarchive\fR]
+[\fB\-\-exists\fR]
+[\fB\-\-archived\fR]
+[\fB\-\-lost\fR]
+[\fI\,FILE\/\fR]...
+.PP
 .SH DESCRIPTION
 These are a set of lfs commands used to interact with Lustre/HSM binding feature.
 .TP
-.B lfs hsm_state <FILE> ...
+.B lfs hsm_state \fR[\fI\,FILE\/\fR]...
 Display the current HSM flags and archive ID for provided files.
 .TP
-.B lfs hsm_set <FILE>...
+.B lfs hsm_action \fR[\fI\,FILE\/\fR]...
+Display the in-progress HSM actions for provided files.
+.TP
+.B lfs hsm_set \fR[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
 Set provided HSM flags on file list.
 .TP
-.B lfs hsm_clear <FILE>...
+.B lfs hsm_clear \fR[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
 Clear the HSM related flags on file list.
-.TP
-.B lfs hsm_action <FILE>...
-Display the in-progress HSM actions for provided files.
 .PP
 Non-privileged user can only change the following flags:
 .B norelease
@@ -61,8 +67,8 @@ An up-to-date file copy exists in HSM backend. Useful mostly for debugging. (roo
 .B \\--lost
 File copy in HSM backend is not usable anymore and file could not be restored. It should be archived again. (root only)
 .TP
-.B \\--archive-id
-Set archive number identifier in hsm_set command. If archive-id is 0 or option is not provided, then default identifier 0 is used and means no identifier change.
+.B \\--archive-id \fINUM\fR
+Set archive number identifier to value \fINUM\fR. If archive-id is 0 or option is not provided, then default identifier 0 is used and means no identifier change.
 .SH EXAMPLES
 .TP
 .B Display current HSM flag for foo:

diff --git a/lustre/doc/lfs-hsm_action.1 b/lustre/doc/lfs-hsm_action.1
new file mode 100644 (file)
index 0000000..71e194b
--- /dev/null
+++ b/lustre/doc/lfs-hsm_action.1
@@ -0,0 +1 @@
+.so man1/lfs-hsm.1

diff --git a/lustre/doc/lfs-hsm_clear.1 b/lustre/doc/lfs-hsm_clear.1
new file mode 100644 (file)
index 0000000..71e194b
--- /dev/null
+++ b/lustre/doc/lfs-hsm_clear.1
@@ -0,0 +1 @@
+.so man1/lfs-hsm.1

diff --git a/lustre/doc/lfs-hsm_set.1 b/lustre/doc/lfs-hsm_set.1
new file mode 100644 (file)
index 0000000..71e194b
--- /dev/null
+++ b/lustre/doc/lfs-hsm_set.1
@@ -0,0 +1 @@
+.so man1/lfs-hsm.1

diff --git a/lustre/doc/lfs-hsm_state.1 b/lustre/doc/lfs-hsm_state.1
new file mode 100644 (file)
index 0000000..71e194b
--- /dev/null
+++ b/lustre/doc/lfs-hsm_state.1
@@ -0,0 +1 @@
+.so man1/lfs-hsm.1