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

Related — Tue, 19 Sep 2023 19:25:02 +0000

I'd like to split up the lfs(1) and lctl(8) man pages because they are huge and unwieldy, and as a result I think each of the sub-commands is given too little space for its description, arguments, and examples. It is also confusing to separate the synopsys, 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 style of using ".I", ".B", ".IR", ".BR" so that function names, option flags, and other explicitly specified strings are bold, user-supplied arguments and variables are italic, and delineators 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 for more examples

Whamcloud Community JIRA

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