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 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 for more examples
Attachments
Issue Links
- is related to
-
LUDOC-134 Completely document all lctl and lfs command options
-
- Open
-
-
-
- Open
-
-
LU-4959
"lfs|lctl {function} --help" should show "lfs-{function}" man page
-
- Open
-
-
LU-11048
lctl pool commands have no man pages
-
- Open
-
-
LU-6051 "lfs_migrate" improvements
-
- Resolved
-
-
-
- Resolved
-
- is related to
-
LU-7648
split lctl lfsck sub-commands to new man pages
-
- Resolved
-
-
-
- Resolved
-