[LU-4315] split lfs.1 and lctl.8 man pages into one page per subcommand

• Type: Technical task
• Resolution: Unresolved
• Priority: Minor
• Labels: cdwgbl easy lug24dd utils
• Assignee: WC Triage
• Reporter: Andreas Dilger

Description

The lfs(1) and lctl(8) man pages should be split up because they are huge and unwieldy, and as a result each of the sub-commands is given too little space for its description, arguments, and examples. It is also confusing to separate the SYNOPSIS, DESCRIPTION, and EXAMPLES for each of the sub-commands. Finally, we couldn't clearly describe the availability of each sub-command for changes to make the various Lustre man pages more complete and consistent.

There should be a single page of the form lfs-getstripe.1 or lfs-df.1 for each sub-command. In some cases, very similar commands may share a single page, but e.g. lfs-setstripe.1 should reference lfs-getstripe.1 so that it can be found easily.

In particular, I'd like the man pages to follow the simple nroff and groff style of using ".I", ".B", ".IR", ".BR" so that function_names(), --option-flags, and other specific strings are bold, user-supplied arguments and variables are UPPERCASE_ITALIC, and delineators like "[|]" are regular text:

.SH SYNOPSIS
.B lfs_migrate
.RB [ -c | -s ]
.RB [ -h  ]
.RB [ -l ]
.RB [ -n ]
.RB [ -y ]
.RI [ FILE | DIRECTORY ...]

Each man page should have the standard sections:

SYNOPSIS
- one-line summary of command
- optional one-line summary of aliases

DESCRIPTION
- good description of what the command does

OPTIONS
- describe all options and their arguments

ENVIRONMENT
- optional section to describe environment variables affecting behaviour

RETURN VALUES
- describe return values and their causes

ERRORS
- optional section for API man pages (section 3) to describe return values like:
    [ERRNO]       description of error

EXAMPLES
- real-world usage examples

KNOWN BUGS
- optional section to list any known bugs

AVAILABILITY
- that it is part of lustre(7)
- which Lustre release it appeared in

SEE ALSO
- other man pages referenced by this one
- related Lustre and non-lustre commands/man pages

References to other commands' man pages should be in the form

.BR lfs (1)

See http://www.schweikhardt.net/man_page_howto.html and https://manpages.ubuntu.com/manpages/jammy/en/man7/man-pages.7.html for examples on how to write good man pages.

Issue Links

• is related to: LU-5170 lfs usability
• is related to: LUDOC-134 Completely document all lctl and lfs command options
• is related to: LU-4959 "lfs|lctl {function} --help" should show "lfs-{function}" man page
• is related to: LU-11048 lctl pool commands have no man pages
• is related to: LU-18148 Add lctl-llog_remove man page
• is related to: LU-6051 "lfs_migrate" improvements
• is related to: LU-9378 extract lfs-getstripe.1 from lfs.1
• is related to: LU-7648 split lctl lfsck sub-commands to new man pages
• is related to: LU-8920 don't print permanently deactivated OSTs in lfs df output