[LUDOC-134] Completely document all lctl and lfs command options

• Status: Open
• Project: Lustre Documentation
• Type: Bug
• Priority: Major
• Reporter: Linda Bebernes (Inactive)
• Assignee: Lustre Manual Triage
• Resolution: Unresolved
• Labels: QContent
• Story Points: 5
• Business Value: 13
• Severity: 3

Description

Notes from Brett Lee in email 3/27/13
...provide more verbose explanations to the options available to the commands. For example, I think it may be the“lctl list_param –R” that lists all the parameters. It would be great to know which of these are valid (implemented, still supported, etc.) for each version (or at least the version of the manual). Then there are other settings available, like the client, server and network tuneables, and there’s not much explanation of what each does. So, expanding the amount of information about the “details” within Lustre would be my vote for the second thing.

Man pages (code changes) will need to be updated as well.

Issue Links

• is related to: LUDOC-135 Review /proc documentation for comple...
• is related to: LU-4315 split lfs.1 and lctl.8 man pages into...
• is related to: LU-5170 lfs usability

Comments

[Andreas Dilger]

The man pages in the manual are just postscript formatted versions of the actual man pages. If any work is done to improve them, it should be done in the lustre source tree. In particular, it would be best to split up the huge lctl.8 and lfs.1 man pages into one page per command (e.g. lfs-df.1, lfs-setstripe.1, etc), each one with a proper description, list of command-line options, explanation for each option, etc.

[Andreas Dilger]

I think for the sake of maintainability that it would make more sense to just reference the man pages on the system, rather than trying to keep the manual up-to-date with every change that is made to the man pages themselves.

The only other sane option would be to have a script that takes the man pages and formats them automatically into the correct format for the manual (one file per man page), and then include them into the manual. Doing the updates by editing the manual, or having to reformat them by hand is not sustainable.