Description
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
Attachments
Issue Links
- is related to
-
LUDOC-134 Completely document all lctl and lfs command options
- Open
-
LU-5170 lfs usability
- 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
-
LU-9378 extract lfs-getstripe.1 from lfs.1
- Resolved
- is related to
-
LU-7648 split lctl lfsck sub-commands to new man pages
- Resolved
-
LU-8920 don't print permanently deactivated OSTs in lfs df output
- Resolved