Puppet

Adding submitter info.

The problem is that rdoc2usage doesn’t generate a man file, it just generates plain text. This is as opposed to pod2man, which actually generates correctly formatted input to troff or whatever.

If you have Rdoc::usage installed, you can call puppet —help to get something like a man page, but you’ll still have to pipe the output through your READER. I’m not real fond of the tool, but I haven’t had the time to submit patches back.

See also: http://www.gnu.org/software/help2man/

I haven’t tried it, but coreutils uses it.

I just tried help2man and its output, at least combined with the output of rdoc2usage, looks horrible.

I’d love it if someone would work on this problem, because we definitely need some way to generate man pages from inline documentation.

I was showing puppet to my colegue the other day and his comment was

“The documentation is not very good. The commands don’t even have a man page …”.

So a lot of people make the first contac with a new tool from man pages. I looked at help2man and it expects sections to be in this format

Usage: bla bla bla

Examples: help the poor

whereas RDOc::usage gives something like

USAGE

===== bla bla bla

EXAMPLES

======== help the poor

so it should not be to dificult to filter the RDOC output and get —help option that plays well with help2man.

I’ve written a static NROFF man page for puppet with the current configuration options, but the installation scripts aren’t set up to install it yet.

The man page should be generated dynamically from the documentation embedded in the code, and at that time, it will probably be more appropriate to have the page (or pages) installed into ${PUPPET_HOME}/man/man8

One question that should be considered in the long term is whether or not it would be better to have documentation for each executable rather than one document covering all of the executables.

Leaving the ticket open and assigned until we can decide on that.

I’ve started a wiki page (ManPages) to work out a specification for this issue.

The author of rst2man.py took some feedback and updated the tool fixing the issues with creating puppet.conf man page.

1. In commit commit:d8991abac0b5302fe4202940b637dc4477d5e44e in branch ticket_198 I’ve updated install.rb to create a puppet.conf man page.

2. In commit commit:f335dc31f11f4bed80e91df041febdca6e33d3c2 in branch ticket_198 I’ve changed defaults.rb to remove some syntax that we were unable to convert to nroff – this mostly changed one of the RST HTML linking forms. You can see if you think it’ll be alright but I think its a minor detail.

3. Lastly, and mostly due to my short-sighted branching of master rather than 0.24.x, to ensure correct creation of man pages some of the documentation fixes I’ve submitted to 0.24.x are needed. Not sure how you want to handle this but generally if the functionality can wait to 0.25.x then this will be fine when you merge and I’ll make a note to test it.

4. The man page creation is currently enabled in install.rb – you can easily disable it by commenting out the line:

build_man(bins) if [[InstallOptions]].man