[LU-4315] split lfs.1 and lctl.8 man pages into one page per subcommand

• Status: Reopened
• Project: Lustre
• Type: Technical task
• Priority: Minor
• Reporter: Andreas Dilger
• Assignee: WC Triage
• Resolution: Unresolved
• Labels: cdwgbl, easy, lad23dd

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

Issue Links

• is related to: LU-7648 split lctl lfsck sub-commands to new ...
• is related to: LU-8920 don't print permanently deactivated O...
• is related to: LUDOC-134 Completely document all lctl and lfs ...
• is related to: LU-5170 lfs usability
• is related to: LU-4959 "lfs|lctl {function} --help" should s...
• 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

Comments

[Justin Miller (Inactive)]

I've written a new man page for lctl-network and wanted to get your feedback before I write too many more.

I did my best to use the IEEE Std. 1003.1 for formatting arguments. http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html

I pulled together as much information as I could from documentation, testing the command, and source code, while still trying to be succinct.

I do think that the idea of a man page for each subcommand is the best course. Otherwise, if you tried to organize by Network/Device/LFSCK, you would be basically recreating the Operations Manual.

How should new man pages be submitted for review? If it is just like source code changes I can get Josh Walgenbach to show me.

[Justin Miller (Inactive)]

Updated with 'configure|unconfigure'

[Andreas Dilger]

Hi Justin,
thanks for taking this project on. I think the page is pretty good as it stands (infinitely better than the two lines that currently exist in the lctl.8 page). It would be useful to have this submitted as a patch to Gerrit so that the patch can be commented on directly, and in particular by people who know more about LNet than I do. That would also include the other changes that are needed to make each new page useful (e.g. inclusion into lustre/doc/Makefile.am, lustre.spec.in, references from other pages, etc). You can use LU-4315 for all of the patches you submit.

One thing I noticed is that the existing usage (and recommended in this bug until moments ago) of Lustre(7) is broken and lustre(7) needs to be used instead, since man is case sensitive.

It seems to be missing a description of the "lctl --net o2iblnd some_lnet_command" style of usage to specify an LND type for later commands. While in some aspects it makes sense to include that as an option to the other LNet commands, rather than as part of the "lctl-net" command (it is useless if run just by itself), it might still be good to include a list of the different LND types so this can be updated in one place, and then referenced by other LNet-related sub-commands.

If at all possible, it makes sense to try and keep the patches independent as much as possible, so that they can be inspected, tested (a requirement for all patches even though these patches are unlikely to cause problems), refreshed as needed, and landed without affecting all of the other patches you are working on. In this case, it might make sense to plan your work a bit so that this can be done more easily:

• submit a patch to lustre/doc/Makefile.am that replaces the "paragraph" of man pages into a list of man pages, one per line, so it is somewhat easier to add new pages without conflicting with other patches. Even better would be to change the MANFILES= list to a glob, like MANFILES=*.[1-9], since it appears we are already missing a page that exists in lustre/doc but not MANFILES (ll_decode_filter_fid.8). The tricky part is that some man pages are not needed on the client, so those would have to be excluded from the glob somehow.
• work on every other sub-command first, and split your effort between lctl.8 and lfs.1, so that the patches that remove lines from lctl.8 and lfs.1 are less likely to conflict before they can be inspected and landed
• save some of the SEE ALSO changes in lctl.8 and lfs.1 to aggregate multiple changes there to avoid patch conflicts

[Andreas Dilger]

PS: in a related note - the "lctl network" usage message also seems incomplete and could be improved slightly as part of the patch for the man page. Don't feel obligated to do that if you don't want, but I thought if you are already taking time to investigate the options it might make sense to do this.

[Gerrit Updater]

Andreas Dilger ([e-mail]) uploaded a new patch: http://review.whamcloud.com/22324
Subject: LU-4315 doc: split lctl-network.8 man page from lctl.8
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 38708bd40cbf329d1c2cf4a3fbda7b5a0c0d9e7e

[Gerrit Updater]

Oleg Drokin ([e-mail]) merged in patch http://review.whamcloud.com/22324/
Subject: LU-4315 doc: split lctl-network.8 man page from lctl.8
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: 3cab078778a7735f2c1d7cf05e853b64e6863184

[Peter Jones]

Landed for 2.9

[Andreas Dilger]

Unfortunately, there is still a bunch more work to be done here.

[Andreas Dilger]

The lfs setstripe command is already being handled by the PFL project: https://review.whamcloud.com/18596

[Andreas Dilger]

The patch https://review.whamcloud.com/24228 "LU-8920 utils: don't print deactivated OSTs in 'lfs df'" splits out a separate "lfs-df.1" man page.

[Gerrit Updater]

Steve Guminski ([e-mail]) uploaded a new patch: https://review.whamcloud.com/24371
Subject: LU-4315 docs: Split man pages into one page per subcommand
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 7e47a5023bd4291a3292c7fe64a169038bbfd28a

[Gerrit Updater]

Oleg Drokin ([e-mail]) merged in patch https://review.whamcloud.com/24371/
Subject: LU-4315 docs: Fix Makefile.am to have one man page per line
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: 0eb8208e199c90f25368b3b0c25858248f874ccd

[Peter Jones]

Landed for 2.10

[Steve Guminski (Inactive)]

The recently landed patch is only the first of several patches required to address this ticket, so I've reopened it.

[Gerrit Updater]

Andreas Dilger ([e-mail]) uploaded a new patch: https://review.whamcloud.com/31406
Subject: LU-4315 doc: correct lfs migrate man page separation
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: f17b498fb52a1bc404dc2d74756379211bfb712a

[Gerrit Updater]

Oleg Drokin ([e-mail]) merged in patch https://review.whamcloud.com/31406/
Subject: LU-4315 doc: correct lfs migrate man page separation
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: 4214a2f33ce7ad2745b414d81a3279993ae50ffe

[Gerrit Updater]

Andreas Dilger ([e-mail]) uploaded a new patch: https://review.whamcloud.com/35242
Subject: LU-4315 doc: split lctl get_param and set_param man pages
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 474e51cb4da78bc15a57089daaf7b71d5fe88a03

[Gerrit Updater]

Oleg Drokin ([e-mail]) merged in patch https://review.whamcloud.com/35242/
Subject: LU-4315 doc: split lctl get_param and set_param man pages
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: 7e9d38ea8187f47b47f0e230a3ad31dee2834849

[Gerrit Updater]

Andreas Dilger ([e-mail]) uploaded a new patch: https://review.whamcloud.com/35649
Subject: LU-4315 doc: add separate lctl-list_param man page
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 168ee96a075a025a3452df4b3db82220166040d7

[Gerrit Updater]

Oleg Drokin ([e-mail]) merged in patch https://review.whamcloud.com/35649/
Subject: LU-4315 doc: add separate lctl-list_param man page
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: 956eeec06548f85c249b5a7495dc9bbdcb30b86b

[Tim Day]

State of man pages (for lfs) right now, by my estimation:

• setstripe - lfs-setstripe.1 
• getstripe - lfs-getstripe.1
• setdirstripe - lfs-setdirstripe.1
• getdirstripe - lfs-getdirstripe.1        
• mkdir - lfs-mkdir.1          
• rm_entry  - lfs-rm_entry.8     
• rmentry - lfs-rmentry.8      
• unlink_foreign - NONE     
• pool_list - NONE  
• find - lfs-find.1       
• check - NONE    
• osts - NONE              
• mdts - NONE     
• df - lfs-df.1
• getname - lfs-getname.1      
• setquota - lfs-setquota.1           
• quota - lfs-quota.1          
• project - lfs-project.1       
• flushctx - lfs-flushctx.1      
• changelog - lfs-changelog.1         
• changelog_clear - lfs-changelog_clear.1
• fid2path - lfs-fid2path.1      
• path2fid - lfs-path2fid.1  
• rmfid - lfs-rmfid.1               
• data_version - NONE
• hsm_state - lfs-hsm_state.1    
• hsm_set - lfs-hsm_set.1       
• hsm_clear - lfs-hsm_clear.1          
• hsm_action - lfs-hsm_action.1      
• hsm_archive - NONE    
• hsm_restore - NONE
• hsm_release - NONE         
• hsm_remove - NONE      
• hsm_cancel - NONE    
• swap_layouts - NONE
• migrate - lfs-migrate.1, lfs_migrate.1 (the wrapper script)           
• mv - NONE            
• ladvise - lfs-ladvise.1       
• mirror  - lfs-mirror-*.1  (mirror has a lot of pages)
• getsom - lfs-getsom.1              
• heat_get - split lfs-heat.1?  
• heat_set - split lfs-heat.1?
• pcc - lfs-pcc.1, lfs-pcc-detach.1         
• help - NONE                
• exit - NONE          
• quit - NONE       
• --version - NONE 
• --list-commands - NONE

Some of the pages need to be split up. Some new ones need to be created. And some stubs should be made for the trivial commands, so "lfs help" will have a page to show (in the future).

[Andreas Dilger]

Note that "lfs mv" is an alias for "lfs migrate -m", so should be a stub for that.

[Andreas Dilger]

It's also not clear that "lfs-version", "lfs-list-commands", "lfs-help", "lfs-exit", and "lfs-quit" need their own man pages? Those are more like infrastructure for the "lfs" command itself, and not separate sub-commands.