Skip to content

Commit 3ffc0c1

Browse files
joshcooperjoshcooper
committed
(PUP-12075) Render puppet man page correctly
Previously, the man/man8/puppet.8 man page wasn't formatted correctly with each subcommand and summary on a new line. This was because `puppet --help` doesn't output ronn format, just raw text. So generate `puppet.8.ronn` in valid ronn format so that it can be converted to roff. Use `man --local-file man/man8/puppet.8` to verify the results. Also don't blindly run `<bin>/<app> --help` for every app. That's left over from when puppet had multiple bin stubs.
1 parent 4266664 commit 3ffc0c1

File tree

3 files changed

+165
-16
lines changed

3 files changed

+165
-16
lines changed

‎man/man8/puppet.8‎

Lines changed: 121 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,25 +4,138 @@
44
.TH "PUPPET" "8" "August 2024" "Puppet, Inc." "Puppet manual"
55
.
66
.SH "NAME"
7-
\fBpuppet\fR
7+
\fBpuppet\fR \- an automated configuration management tool
8+
.
9+
.SH "SYNOPSIS"
10+
\fBpuppet\fR \fIsubcommand\fR [options] \fIaction\fR [options]
11+
.
12+
.SH "DESCRIPTION"
13+
Puppet, an automated administrative engine for your Linux, Unix, and Windows systems, performs administrative tasks (such as adding users, installing packages, and updating server configurations) based on a centralized specification\.
14+
.
15+
.SH "COMMANDS"
16+
.
17+
.SS "Common"
18+
\fBapply\fR
19+
.
20+
.br
21+
\~\~\~\~Apply Puppet manifests locally
22+
.
23+
.P
24+
\fBagent\fR
25+
.
26+
.br
27+
\~\~\~\~The puppet agent daemon
28+
.
29+
.P
30+
\fBconfig\fR
31+
.
32+
.br
33+
\~\~\~\~Interact with Puppet\'s settings\.
34+
.
35+
.P
36+
\fBhelp\fR
37+
.
38+
.br
39+
\~\~\~\~Display Puppet help\.
40+
.
41+
.P
42+
\fBlookup\fR
43+
.
44+
.br
45+
\~\~\~\~Interactive Hiera lookup
46+
.
47+
.P
48+
\fBmodule\fR
49+
.
50+
.br
51+
\~\~\~\~Creates, installs and searches for modules on the Puppet Forge\.
52+
.
53+
.P
54+
\fBresource\fR
55+
.
56+
.br
57+
\~\~\~\~The resource abstraction layer shell
58+
.
59+
.SS "Specialized"
60+
\fBcatalog\fR
61+
.
62+
.br
63+
\~\~\~\~Compile, save, view, and convert catalogs\.
64+
.
65+
.P
66+
\fBdescribe\fR
67+
.
68+
.br
69+
\~\~\~\~Display help about resource types
70+
.
71+
.P
72+
\fBdevice\fR
73+
.
74+
.br
75+
\~\~\~\~Manage remote network devices
76+
.
77+
.P
78+
\fBdoc\fR
79+
.
80+
.br
81+
\~\~\~\~Generate Puppet references
882
.
983
.P
10-
Usage: puppet \fIsubcommand\fR [options] \fIaction\fR [options]
84+
\fBepp\fR
85+
.
86+
.br
87+
\~\~\~\~Interact directly with the EPP template parser/renderer\.
1188
.
1289
.P
13-
Available subcommands:
90+
\fBfacts\fR
91+
.
92+
.br
93+
\~\~\~\~Retrieve and store facts\.
94+
.
95+
.P
96+
\fBfilebucket\fR
97+
.
98+
.br
99+
\~\~\~\~Store and retrieve files in a filebucket
14100
.
15101
.P
16-
Common:
102+
\fBgenerate\fR
17103
.
18104
.br
19-
agent The puppet agent daemon apply Apply Puppet manifests locally config Interact with Puppet\'s settings\. help Display Puppet help\. lookup Interactive Hiera lookup module Creates, installs and searches for modules on the Puppet Forge\. resource The resource abstraction layer shell
105+
\~\~\~\~Generates Puppet code from Ruby definitions\.
20106
.
21107
.P
22-
Specialized:
108+
\fBnode\fR
23109
.
24110
.br
25-
catalog Compile, save, view, and convert catalogs\. describe Display help about resource types device Manage remote network devices doc Generate Puppet references epp Interact directly with the EPP template parser/renderer\. facts Retrieve and store facts\. filebucket Store and retrieve files in a filebucket generate Generates Puppet code from Ruby definitions\. node View and manage node definitions\. parser Interact directly with the parser\. plugin Interact with the Puppet plugin system\. script Run a puppet manifests as a script without compiling a catalog ssl Manage SSL keys and certificates for puppet SSL clients
111+
\~\~\~\~View and manage node definitions\.
112+
.
113+
.P
114+
\fBparser\fR
115+
.
116+
.br
117+
\~\~\~\~Interact directly with the parser\.
118+
.
119+
.P
120+
\fBplugin\fR
121+
.
122+
.br
123+
\~\~\~\~Interact with the Puppet plugin system\.
124+
.
125+
.P
126+
\fBscript\fR
127+
.
128+
.br
129+
\~\~\~\~Run a puppet manifests as a script without compiling a catalog
130+
.
131+
.P
132+
\fBssl\fR
133+
.
134+
.br
135+
\~\~\~\~Manage SSL keys and certificates for puppet SSL clients
136+
.
137+
.SH "SEE ALSO"
138+
See \fBpuppet help <subcommand>\fR for help on a specific subcommand\.
26139
.
27140
.P
28-
See \'puppet help \fIsubcommand\fR \fIaction\fR\' for help on a specific subcommand action\. See \'puppet help \fIsubcommand\fR\' for help on a specific subcommand\. Puppet v8\.9\.0
141+
See \fBpuppet help <subcommand> <action>\fR for help on a specific subcommand action\.

‎rakelib/man/puppet.erb‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
puppet(8) - an automated configuration management tool
2+
=========
3+
4+
## SYNOPSIS
5+
6+
`puppet` <subcommand> [options] <action> [options]
7+
8+
## DESCRIPTION
9+
10+
Puppet, an automated administrative engine for your Linux, Unix, and Windows systems, performs administrative tasks
11+
(such as adding users, installing packages, and updating server configurations) based on a centralized specification.
12+
13+
## COMMANDS
14+
15+
### Common
16+
17+
<% common.each do |appname, summary, _| -%>
18+
`<%= appname.to_s %>`<br>
19+
&nbsp;&nbsp;&nbsp;&nbsp;<%= summary %>
20+
21+
<% end -%>
22+
23+
### Specialized
24+
25+
<% specialized.each do |appname, summary, _| -%>
26+
`<%= appname.to_s %>`<br>
27+
&nbsp;&nbsp;&nbsp;&nbsp;<%= summary %>
28+
29+
<% end -%>
30+
31+
## SEE ALSO
32+
See `puppet help <subcommand>` for help on a specific subcommand.
33+
34+
See `puppet help <subcommand> <action>` for help on a specific subcommand action.

‎rakelib/manpages.rake‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ task :gen_manpages do
66
Puppet.initialize_settings
77
helpface = Puppet::Face[:help, '0.0.1']
88

9-
bins = Dir.glob(%w{bin/*})
109
non_face_applications = helpface.legacy_applications
1110
faces = Puppet::Face.faces.map(&:to_s)
1211
apps = non_face_applications + faces
@@ -36,13 +35,16 @@ task :gen_manpages do
3635
FileUtils.mv("./man/man5/puppetconf.5", "./man/man5/puppet.conf.5")
3736
FileUtils.rm("./man/man5/puppetconf.5.ronn")
3837

39-
# Create LEGACY binary man pages (i.e. delete me for 2.8.0)
40-
bins.each do |bin|
41-
b = bin.gsub( /^s?bin\//, "")
42-
%x{RUBYLIB=./lib:$RUBYLIB #{bin} --help > ./man/man8/#{b}.8.ronn}
43-
%x{#{ronn} #{ronn_args} ./man/man8/#{b}.8.ronn}
44-
FileUtils.rm("./man/man8/#{b}.8.ronn")
45-
end
38+
# Create puppet binary man page
39+
# puppet --help outputs raw text, not ronn, so trying to convert that to roff
40+
# fails miserably. Render valid ronn so we can convert to roff
41+
common = helpface.common_app_summaries
42+
specialized = helpface.specialized_app_summaries
43+
template_binding = OpenStruct.new(common: common, specialized: specialized).instance_eval {binding}
44+
content = ERB.new(File.read(File.join(__dir__, 'man/puppet.erb')), trim_mode: '-').result(template_binding)
45+
File.write("./man/man8/puppet.8.ronn", content)
46+
%x{#{ronn} #{ronn_args} ./man/man8/puppet.8.ronn}
47+
FileUtils.rm("./man/man8/puppet.8.ronn")
4648

4749
apps.each do |app|
4850
%x{RUBYLIB=./lib:$RUBYLIB bin/puppet help #{app} --ronn > ./man/man8/puppet-#{app}.8.ronn}

0 commit comments

Comments
 (0)