Folks, I''ve been looking at creating a set of man pages for puppet and I''m trying to come up with a reasonable hierarchy. I''d appreciate any suggestions. So far, here''s what I''ve come up with: - puppet(1) - puppetca(1) - puppetdoc(1) - puppetrun(1) - puppetca.conf(5) - puppetd.conf(5) - puppetmasterd.conf(5) - puppetd(8) - puppetmasterd(8) At this point I am still working out the technical details of converting some of the existing reference documentation to valid man pages. However, I felt it prudent to have a shared sense of where this is going before I get too far into it. So, if you have comments or suggestions, please speak up. Thanks, -David
On Apr 1, 2007, at 8:27 PM, David Narayan wrote:> Folks, > > I''ve been looking at creating a set of man pages for puppet and I''m > trying to come up with a reasonable hierarchy. I''d appreciate any > suggestions.Great, glad to hear it.> So far, here''s what I''ve come up with: > > - puppet(1) > - puppetca(1) > - puppetdoc(1)I''ve been considering puppetdoc an internal tool, only used to generate the reference documentation. Is it something people think should be a more widely-suitable tool?> - puppetrun(1) > > - puppetca.conf(5) > - puppetd.conf(5) > - puppetmasterd.conf(5) > > - puppetd(8) > - puppetmasterd(8) > > At this point I am still working out the technical details of > converting some of the existing reference documentation to valid man > pages. However, I felt it prudent to have a shared sense of where this > is going before I get too far into it. So, if you have comments or > suggestions, please speak up.Note that ''puppet'' is a stand-alone executable plus the framework; would you have a man page for the framework in general? Also, it''s probably a good idea to have a single ''puppet- configuration'' man page or something with the central configuration parameters; else, 9/10s of all of the executable man pages will be that. There are some bits from the central core that should be mentioned in each man page (probably as part of a section that''s the same in all of them); e.g., --configprint is very useful for configuration debugging. It also might be nice to have man pages devoted to general concepts, and to the language. -- Commit suicide. A hundred thousand lemmings can''t be wrong. --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
On 4/1/07, Luke Kanies <luke@madstop.com> wrote: [snip]> > > So far, here''s what I''ve come up with: > > > > - puppet(1) > > - puppetca(1) > > - puppetdoc(1) > > I''ve been considering puppetdoc an internal tool, only used to > generate the reference documentation. Is it something people think > should be a more widely-suitable tool? >I think puppetdoc should probably be a development/documentation tool. And, in that context, it should probably not be installed into /usr[/local]/bin along with the other executables.> > - puppetrun(1) > > > > - puppetca.conf(5) > > - puppetd.conf(5) > > - puppetmasterd.conf(5) > > > > - puppetd(8) > > - puppetmasterd(8) > >I might also mention here that puppetd and puppetmasterd are good candidates for /usr[/local]/sbin instead of /usr[/local]/bin.> > At this point I am still working out the technical details of > > converting some of the existing reference documentation to valid man > > pages. However, I felt it prudent to have a shared sense of where this > > is going before I get too far into it. So, if you have comments or > > suggestions, please speak up. > > Note that ''puppet'' is a stand-alone executable plus the framework; > would you have a man page for the framework in general? >That''s a good question - to which I don''t have a great answer yet. One option is to have a separate puppetintro(5) page that describes the framework in general and leave puppet(1) for the executable.> Also, it''s probably a good idea to have a single ''puppet- > configuration'' man page or something with the central configuration > parameters; else, 9/10s of all of the executable man pages will be > that. There are some bits from the central core that should be > mentioned in each man page (probably as part of a section that''s the > same in all of them); e.g., --configprint is very useful for > configuration debugging. >I agree. Perhaps puppet_config(5) or puppetconf(5).> It also might be nice to have man pages devoted to general concepts, > and to the language. >True. Perhaps something akin to puppetintro(5), puppetlang(5), and/or puppetref(5). -David
On Apr 2, 2007, at 6:12 PM, David Narayan wrote:> > I think puppetdoc should probably be a development/documentation tool. > And, in that context, it should probably not be installed into > /usr[/local]/bin along with the other executables.Ok; if that''s the case, it probably doesn''t need a man page, either.> I might also mention here that puppetd and puppetmasterd are good > candidates for /usr[/local]/sbin instead of /usr[/local]/bin.I think some packages do that. That''s essentially a packaging issue, although I know my install script has some control over that. It''s been filed as a bug for ages, but... I just haven''t gotten around to fix it.> That''s a good question - to which I don''t have a great answer yet. One > option is to have a separate puppetintro(5) page that describes the > framework in general and leave puppet(1) for the executable.Any of them are fine with me, as long as a decision is made. :)>> Also, it''s probably a good idea to have a single ''puppet- >> configuration'' man page or something with the central configuration >> parameters; else, 9/10s of all of the executable man pages will be >> that. There are some bits from the central core that should be >> mentioned in each man page (probably as part of a section that''s the >> same in all of them); e.g., --configprint is very useful for >> configuration debugging. >> > > I agree. Perhaps puppet_config(5) or puppetconf(5).Sounds good.>> It also might be nice to have man pages devoted to general concepts, >> and to the language. >> > > True. Perhaps something akin to puppetintro(5), puppetlang(5), and/or > puppetref(5).Okay, let me know when you''re done. :) -- I don''t know the key to success, but the key to failure is trying to please everybody. -- Bill Cosby --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com