Details

    • Type: Technical task
    • Status: Reopened
    • Priority: Minor
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: None
    • Labels:
    • Rank (Obsolete):
      11811

      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

            Activity

              People

              • Assignee:
                sguminsx Steve Guminski (Inactive)
                Reporter:
                adilger Andreas Dilger
              • Votes:
                2 Vote for this issue
                Watchers:
                8 Start watching this issue

                Dates

                • Created:
                  Updated: