Man page for puppet is useless

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.