Uploaded image for project: 'Puppet'
  1. Puppet
  2. PUP-3251

Man page for puppet is useless

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Normal
    • Resolution: Duplicate
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: Docs
    • Labels:
      None
    • Template:
    • Sub-team:
    • Team:
      Platform Core

      Description

      There are prerequisites for fixing this ticket:

      • Deciding how we're going to maintain man page source text. (Best bet at the moment: pod2man)
      • Making sure man pages get re-built from source text during package builds. (Currently we don't believe this happens.)
      • Making sure packages install man pages in the right place, so the system `man` command will actually work with them.

      Once engineering teams have solved this, we can bring the docs team in to talk about what the man page should actually say!


      If a user installs puppet and then types man puppet they are presented with

      PUPPET(8)                                                                           Puppet manual                                                                          PUPPET(8)
       
      NAME
             puppet
       
             [1;31mError: Could not parse application options: invalid option: --help[0m
       
      Puppet Labs, LLC                                                                   September 2014                                                                          PUPPET(8)
      

      This is caused by the following code in tasks/manpages.rake:

        # Create LEGACY binary man pages (i.e. delete me for 2.8.0)
        binary = bins + sbins
        binary.each do |bin|
          b = bin.gsub( /^s?bin\//, "")
          %x{RUBYLIB=./lib:$RUBYLIB #{bin} --help > ./man/man8/#{b}.8.ronn}
          %x{#{ronn} #{ronn_args} ./man/man8/#{b}.8.ronn}
          FileUtils.rm("./man/man8/#{b}.8.ronn")
        end
      

      That code tries to generate the man pages for puppet and extlookup2hiera. However puppet does not respond to --help and we end up with the man page from above.

      There needs to be a real man page written up for the puppet system as a whole. It should act as a landing page with instructions on how to use puppet in general.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              Unassigned Unassigned
              Reporter:
              andy Andrew Parker
              Votes:
              6 Vote for this issue
              Watchers:
              12 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Zendesk Support