LU-4315 doc: updating llapi-[cha] man page style

Updating files to match the new code style for Lustre manual pages as
enforced by 'contrib/scripts/checkpatch-man.pl'.

This also includes other changes like removing < > or { } for singular
required arguments and placing [ ] around optional ones as well as
making all arguments CAPITAL and italicized, literal arguments are
bolded. Lines over 80 characters should be split at the natural line
end rather than the word that goes over the limit as fewer lines will
need to be modified when making changes if each sentence is on it's
own line.

Only using features that appear in groff 1.22.3 as this is the
available version is CentOS 8.

Checked files:
- llapi_changelog_clear.3
- llapi_changelog_fini.3
- llapi_changelog_free.3
- llapi_changelog_get_fd.3
- llapi_changelog_in_buf.3
- llapi_changelog_recv.3
- llapi_changelog_set_xflags.3
- llapi_changelog_start.3

Test-Parameters: trivial
Signed-off-by: Frederick Dilger <fdilger@whamcloud.com>
Change-Id: Id2b6f92811b8ffbe23fc7a902a14360b8cf583c5
Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/56131
Tested-by: jenkins <devops@whamcloud.com>
Tested-by: Maloo <maloo@whamcloud.com>
Reviewed-by: Andreas Dilger <adilger@whamcloud.com>
Reviewed-by: Arshad Hussain <arshad.hussain@aeoncomputing.com>
Reviewed-by: Oleg Drokin <green@whamcloud.com>

diff --git a/lustre/doc/llapi_changelog_clear.3 b/lustre/doc/llapi_changelog_clear.3
index afa79fc..b589bbf 100644 (file)
--- a/lustre/doc/llapi_changelog_clear.3
+++ b/lustre/doc/llapi_changelog_clear.3
@@ -1,4 +1,4 @@
-.TH llapi_changelog_clear 3 "2022-11-08" "" "Lustre User API"
+.TH LLAPI_CHANGELOG_CLEAR 3 2024-08-22 "Lustre User API" "Lustre Library Functions"
 .SH NAME
 llapi_changelog_clear \- Clear changelog records for a changelog consumer
 .SH SYNOPSIS
@@ -9,7 +9,6 @@ llapi_changelog_clear \- Clear changelog records for a changelog consumer
 .BI "                          long long " endrec ");"
 .fi
 .SH DESCRIPTION
-.PP
 The function
 .B llapi_changelog_clear()
 indicates that changelog records previous to
@@ -29,7 +28,6 @@ MDT node using:
 .br
 .BI "lctl --device " MDT_NAME " changelog_register"
 .SH RETURN VALUES
-.PP
 Return the file descriptor on success or a negative errno value on failure.
 .SH ERRORS
 .TP 15
@@ -46,11 +44,18 @@ is only accessible to the root user.
 An example can be found in lfs.c source file.
 .B lfs_changelog_clear
 implements the following command:
-.br
+.EX
 .BI "lfs changelog_clear " MDTNAME " " ID " " ENDREC ""
-.SH "SEE ALSO"
+.EE
+.SH AVAILABILITY
+.B llapi_changelog_clear()
+is part of the
+.BR lustre (7)
+user application interface library since before release 2.4.0
+.\" Added in commit 2.3.53-7-gf715e4e298
+.SH SEE ALSO
 .BR lfs-changelog_clear (1),
-.BR llapi_changelog_get_fd (3)
+.BR llapi_changelog_get_fd (3),
 .BR llapi_changelog_in_buf (3),
 .BR llapi_changelog_recv (3),
 .BR llapi_changelog_start (3),

diff --git a/lustre/doc/llapi_changelog_get_fd.3 b/lustre/doc/llapi_changelog_get_fd.3
index d178979..7640472 100644 (file)
--- a/lustre/doc/llapi_changelog_get_fd.3
+++ b/lustre/doc/llapi_changelog_get_fd.3
@@ -1,4 +1,4 @@
-.TH llapi_changelog_get_fd 3 "2022-11-08" "" "Lustre User API"
+.TH LLAPI_CHANGELOG_GET_FD 3 "2024-08-22 "Lustre User API" "Lustre Library Functions"
 .SH NAME
 llapi_changelog_get_fd \- Return the file descriptor of the changelog device
 .SH SYNOPSIS
@@ -8,7 +8,6 @@ llapi_changelog_get_fd \- Return the file descriptor of the changelog device
 .BI "int llapi_changelog_get_fd(void *" priv ");"
 .fi
 .SH DESCRIPTION
-.PP
 The function
 .B llapi_changelog_get_fd()
 returns the file descriptor of changelog char device for the instance
@@ -19,16 +18,21 @@ This can be used to call
 on the file descriptor to get events on the
 changelog device.
 .SH RETURN VALUES
-.PP
 Return the file descriptor on success or a negative errno value on failure.
 .SH ERRORS
 .TP 15
 .SM -EINVAL
 .I priv
 argument is invalid.
-.SH "SEE ALSO"
+.SH AVAILABILITY
+.B llapi_changelog_get_fd
+is part of the
+.BR lustre (7)
+user application interface library since release 2.4.0
+.\# Added in commit 2.3.53-7-gf715e4e298
+.SH SEE ALSO
 .BR poll (2),
-.BR llapi_changelog_clear (3)
+.BR llapi_changelog_clear (3),
 .BR llapi_changelog_in_buf (3),
 .BR llapi_changelog_recv (3),
 .BR llapi_changelog_start (3),

diff --git a/lustre/doc/llapi_changelog_in_buf.3 b/lustre/doc/llapi_changelog_in_buf.3
index 749ca37..ae214dd 100644 (file)
--- a/lustre/doc/llapi_changelog_in_buf.3
+++ b/lustre/doc/llapi_changelog_in_buf.3
@@ -1,4 +1,4 @@
-.TH llapi_changelog_in_buf 3 "2022-11-08" "" "Lustre User API"
+.TH LLAPI_CHANGELOG_IN_BUF 3 2024-08-22 "Lustre User API" "Lustre Library Functions"
 .SH NAME
 llapi_changelog_in_buf \- Check if there is changelog records in the internal buffer
 .SH SYNOPSIS
@@ -8,7 +8,6 @@ llapi_changelog_in_buf \- Check if there is changelog records in the internal bu
 .BI "int llapi_changelog_in_buf(void *" priv ");"
 .fi
 .SH DESCRIPTION
-.PP
 The function
 .B llapi_changelog_in_buf()
 checks if there are still changelog records in the read buffer for the
@@ -20,11 +19,16 @@ with
 .B llapi_changelog_recv()
 can be used to dequeue all the changelog records still in the read buffer.
 .SH RETURN VALUES
-.PP
 Returns 1 if changelogs records are present in the internal read buffer,
 otherwise return 0.
-.SH "SEE ALSO"
-.BR llapi_changelog_clear (3)
+.SH AVAILABILITY
+.B llapi_changelog_in_buf
+is part of the
+.BR lustre (7)
+user application interface library since release 2.13.0
+.\# Added in commit 2.12.56-87-ge215002883
+.SH SEE ALSO
+.BR llapi_changelog_clear (3),
 .BR llapi_changelog_get_fd (3),
 .BR llapi_changelog_recv (3),
 .BR llapi_changelog_start (3),

diff --git a/lustre/doc/llapi_changelog_recv.3 b/lustre/doc/llapi_changelog_recv.3
index 42b349e..4a6c9cd 100644 (file)
--- a/lustre/doc/llapi_changelog_recv.3
+++ b/lustre/doc/llapi_changelog_recv.3
@@ -1,4 +1,4 @@
-.TH llapi_changelog_recv 3 "2022-11-08" "" "Lustre User API"
+.TH LLAPI_CHANGELOG_RECV 3 2024-08-22 "Lustre User API" "Lustre Library Functions"
 .SH NAME
 llapi_changelog_recv, llapi_changelog_free \- Read and free a changelog records
 .SH SYNOPSIS
@@ -10,7 +10,6 @@ llapi_changelog_recv, llapi_changelog_free \- Read and free a changelog records
 .BI "int llapi_changelog_free(struct changelog_rec **" rech ");"
 .fi
 .SH DESCRIPTION
-.PP
 The function
 .B llapi_changelog_recv()
 allocates and reads the next changelog record
@@ -54,9 +53,16 @@ Failed to read the changelog record on the MDT.
 An example can be found for in lfs.c source file.
 .B lfs_changelog()
 implements the following command:
-.br
+.EX
 .BI "lfs changelog [--follow] " MDTNAME " [" STARTREC " [" ENDREC "]]"
-.SH "SEE ALSO"
+.EE
+.SH AVAILABILITY
+.B llapi_changelog_recv
+is part of the
+.BR lustre (7)
+user application interface library since release 2.4.0
+.\# Added in commit 2.3.53-7-gf715e4e298
+.SH SEE ALSO
 .BR lfs-changelog (1),
 .BR llapi_changelog_clear (3),
 .BR llapi_changelog_get_fd (3),

diff --git a/lustre/doc/llapi_changelog_start.3 b/lustre/doc/llapi_changelog_start.3
index dd4505c..df6d21e 100644 (file)
--- a/lustre/doc/llapi_changelog_start.3
+++ b/lustre/doc/llapi_changelog_start.3
@@ -1,4 +1,4 @@
-.TH llapi_changelog_start 3 "2022-11-08" "" "Lustre User API"
+.TH LLAPI_CHANGELOG_START 3 2024-08-22 "Lustre User API" "Lustre Library Functions"
 .SH NAME
 llapi_changelog_start, llapi_changelog_set_xflags, llapi_changelog_fini \- Initialize and clean a read instance for MDT changelogs
 .SH SYNOPSIS
@@ -14,7 +14,6 @@ llapi_changelog_start, llapi_changelog_set_xflags, llapi_changelog_fini \- Initi
 .BI "int llapi_changelog_fini(void **" priv ");"
 .fi
 .SH DESCRIPTION
-.PP
 The function
 .B llapi_changelog_start()
 initializes a new instance
@@ -23,7 +22,7 @@ to read MDT changelogs. It opens the changelog char device
 corresponding to the MDT's name given by
 .I device
 (e.g: "lustrefs-MDT0000").
-.br
+.P
 A changelog starting point can be specified with
 .I startrec
 record number.
@@ -40,18 +39,17 @@ mask.
 .PP
 .B enum changelog_send_flag
 values:
-.nf
-.LP
+.EX
        CHANGELOG_FLAG_FOLLOW
        CHANGELOG_FLAG_BLOCK
        CHANGELOG_FLAG_JOBID
        CHANGELOG_FLAG_EXTRA_FLAGS
-.fi
+.EE
 .TP
 CHANGELOG_FLAG_FOLLOW
 Use changelog follow mode:
 .B llapi_changelog_recv()
-will not return when all records have been read.  Instead it will block until a
+will not return when all records have been read. Instead it will block until a
 new record is available. It avoids restarting an instance and re-scan for newer
 changelogs.
 .TP
@@ -78,13 +76,12 @@ parameter.
 .PP
 .B enum changelog_send_extra_flag
 values:
-.nf
-.LP
+.EX
        CHANGELOG_EXTRA_FLAG_UIDGID
        CHANGELOG_EXTRA_FLAG_NID
        CHANGELOG_EXTRA_FLAG_OMODE
        CHANGELOG_EXTRA_FLAG_XATTR
-.fi
+.EE
 .TP
 CHANGELOG_EXTRA_FLAG_UIDGID
 Pack uid/gid into the changelog record
@@ -123,11 +120,18 @@ is only accessible to the root user.
 An example can be found for in lfs.c source file.
 .B lfs_changelog()
 implements the following command:
-.br
+.EX
 .BI "lfs changelog [--follow] " MDTNAME " [" STARTREC " [" ENDREC "]]"
-.SH "SEE ALSO"
+.EE
+.SH AVAILABILITY
+.B llapi_changelog_start
+is part of the
+.BR lustre (7)
+user application interface library since release 2.4.0
+.\# Added in commit 2.3.53-7-gf715e4e298
+.SH SEE ALSO
 .BR lfs-changelog (1),
-.BR llapi_changelog_clear (3)
+.BR llapi_changelog_clear (3),
 .BR llapi_changelog_get_fd (3),
 .BR llapi_changelog_in_buf (3),
 .BR llapi_changelog_recv (3),