[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: LU-18967 lctl-pool_new.8 man page should list pool name constraints
• 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-6051 "lfs_migrate" improvements
• is related to: LU-9378 extract lfs-getstripe.1 from lfs.1
• is related to: LU-18148 Add lctl-llog_remove man page
• is related to: LU-18189 Improve checkpatch-man.pl functionality
• is related to: LU-18890 add "lfs find -ls" option to lfs-find.1 man page
• 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

Comments

[Gerrit Updater]

"Oleg Drokin <[e-mail]>" merged in patch https://review.whamcloud.com/c/fs/lustre-release/+/56170/
Subject: LU-4315 doc: updating llapi-[g-h] man page style
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: d0a47cd7704cbd6fa8723e08f494880b83a68078

[Gerrit Updater]

"Oleg Drokin <[e-mail]>" merged in patch https://review.whamcloud.com/c/fs/lustre-release/+/57890/
Subject: LU-4315 docs: updating lfs-[m-q] mage page style
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: 117aaece71b464bfdcad54a058e4c2f9237d30c1

[Gerrit Updater]

"Oleg Drokin <[e-mail]>" merged in patch https://review.whamcloud.com/c/fs/lustre-release/+/56102/
Subject: LU-4315 doc: updating lfs-[mirr] man page style
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: edabcf5ee2fdea18d55ea86cfab2b6013de1d50a

[Gerrit Updater]

"Frederick Dilger <[e-mail]>" uploaded a new patch: https://review.whamcloud.com/c/fs/lustre-release/+/57890
Subject: LU-4315 docs: updating lfs-[m-q] mage page style
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 664d6388e38c4edcfb03f9e3ca5e3fe9cba1c482

[Gerrit Updater]

"Oleg Drokin <[e-mail]>" merged in patch https://review.whamcloud.com/c/fs/lustre-release/+/56191/
Subject: LU-4315 doc: updating ls-tu man page style
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: 155cf6d41dacc82d003367cd0df369ead420bca8

[Gerrit Updater]

"Oleg Drokin <[e-mail]>" merged in patch https://review.whamcloud.com/c/fs/lustre-release/+/56202/
Subject: LU-4315 doc: updating l[c-h] man page style
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: 9726f057424d7300cebdddeae5ad88259c2738cd

[Gerrit Updater]

"Oleg Drokin <[e-mail]>" merged in patch https://review.whamcloud.com/c/fs/lustre-release/+/56188/
Subject: LU-4315 doc: updating llapi-[o-u] man page style
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: d67847d049e250d0d06bd092af9bda1f9825500f

[Gerrit Updater]

"Oleg Drokin <[e-mail]>" merged in patch https://review.whamcloud.com/c/fs/lustre-release/+/56173/
Subject: LU-4315 doc: update llapi-layout-[f-s] man page style
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: c791602d1e000bacee6fa871ac15e715ed1363d1

[Gerrit Updater]

"Oleg Drokin <[e-mail]>" merged in patch https://review.whamcloud.com/c/fs/lustre-release/+/56131/
Subject: LU-4315 doc: updating llapi-[cha] man page style
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: 219c0bec564605a96314830fd12a1e8d8d9477f0

[Gerrit Updater]

"Oleg Drokin <[e-mail]>" merged in patch https://review.whamcloud.com/c/fs/lustre-release/+/56071/
Subject: LU-4315 doc: updating lctl-[p-s] man page style
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: f714875b1be6c05c5cadd5bff046e9b78e940ab7