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.
Attachments
Issue Links
- is related to
-
LU-5170 lfs usability
-
- Open
-
-
-
- Open
-
-
-
- Resolved
-
-
LU-4959
"lfs|lctl {function} --help" should show "lfs-{function}" man page
-
- Open
-
-
LU-11048
lctl pool commands have no man pages
-
- Resolved
-
-
LU-6051 "lfs_migrate" improvements
-
- Resolved
-
-
-
- Resolved
-
-
-
- Resolved
-
-
-
- Resolved
-
-
-
- Resolved
-
- is related to
-
LU-7648
split lctl lfsck sub-commands to new man pages
-
- Resolved
-
-
-
- Resolved
-
(5 is related to, 2 is related to )
Activity
| Labels | Original: cdwgbl easy lug24dd | New: cdwgbl easy lug24dd utils |
| Assignee | Original: Fred Dilger [ fdilger ] | New: WC Triage [ wc-triage ] |
| Description |
Original:
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}}|https://man7.org/linux/man-pages/man1/nroff.1.html] and [{{groff}}|https://man7.org/linux/man-pages/man7/groff_man_style.7.html] 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: {noformat} .SH SYNOPSIS .B lfs_migrate .RB [ -c | -s ] .RB [ -h ] .RB [ -l ] .RB [ -n ] .RB [ -y ] .RI [ FILE | DIRECTORY ...] {noformat} Each man page should have the standard sections: {noformat} 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 {noformat} References to other commands' man pages should be in the form {noformat} .BR lfs (1) {noformat} See [http://www.schweikhardt.net/man_page_howto.html] and [https://linux.die.net/man/7/man-pages] for more examples |
New:
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}}|https://man7.org/linux/man-pages/man1/nroff.1.html] and [{{groff}}|https://man7.org/linux/man-pages/man7/groff_man_style.7.html] 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: {noformat} .SH SYNOPSIS .B lfs_migrate .RB [ -c | -s ] .RB [ -h ] .RB [ -l ] .RB [ -n ] .RB [ -y ] .RI [ FILE | DIRECTORY ...] {noformat} Each man page should have the standard sections: {noformat} 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 {noformat} References to other commands' man pages should be in the form {noformat} .BR lfs (1) {noformat} 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. |
| Description |
Original:
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}}|https://man7.org/linux/man-pages/man1/nroff.1.html] 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: {noformat} .SH SYNOPSIS .B lfs_migrate .RB [ -c | -s ] .RB [ -h ] .RB [ -l ] .RB [ -n ] .RB [ -y ] .RI [ FILE | DIRECTORY ...] {noformat} Each man page should have the standard sections: {noformat} 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 {noformat} References to other commands' man pages should be in the form {noformat} .BR lfs (1) {noformat} See [http://www.schweikhardt.net/man_page_howto.html] and [https://linux.die.net/man/7/man-pages] for more examples |
New:
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}}|https://man7.org/linux/man-pages/man1/nroff.1.html] and [{{groff}}|https://man7.org/linux/man-pages/man7/groff_man_style.7.html] 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: {noformat} .SH SYNOPSIS .B lfs_migrate .RB [ -c | -s ] .RB [ -h ] .RB [ -l ] .RB [ -n ] .RB [ -y ] .RI [ FILE | DIRECTORY ...] {noformat} Each man page should have the standard sections: {noformat} 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 {noformat} References to other commands' man pages should be in the form {noformat} .BR lfs (1) {noformat} See [http://www.schweikhardt.net/man_page_howto.html] and [https://linux.die.net/man/7/man-pages] for more examples |
| Description |
Original:
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}}|https://man7.org/linux/man-pages/man1/nroff.1.html] 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: {noformat} .SH SYNOPSIS .B lfs_migrate .RB [ -c | -s ] .RB [ -h ] .RB [ -l ] .RB [ -n ] .RB [ -y ] .RI [ FILE | DIRECTORY ...] {noformat} Each man page should have the standard sections: {noformat} 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 {noformat} References to other commands' man pages should be in the form {noformat} .BR lfs (1) {noformat} See [http://www.schweikhardt.net/man_page_howto.html] for more examples |
New:
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}}|https://man7.org/linux/man-pages/man1/nroff.1.html] 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: {noformat} .SH SYNOPSIS .B lfs_migrate .RB [ -c | -s ] .RB [ -h ] .RB [ -l ] .RB [ -n ] .RB [ -y ] .RI [ FILE | DIRECTORY ...] {noformat} Each man page should have the standard sections: {noformat} 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 {noformat} References to other commands' man pages should be in the form {noformat} .BR lfs (1) {noformat} See [http://www.schweikhardt.net/man_page_howto.html] and [https://linux.die.net/man/7/man-pages] for more examples |
| Assignee | Original: WC Triage [ wc-triage ] | New: Fred Dilger [ fdilger ] |