[Pkg-puppet-devel] [SCM] Puppet packaging for Debian branch, upstream, updated. 2.6.1rc1-141-gcdb2b90
Markus Roberts
Markus at reality.com
Mon Aug 16 12:49:01 UTC 2010
The following commit has been merged in the upstream branch:
commit 62435e551b3118b1663c67d66a9cae9f52607bc7
Author: James Turnbull <james at lovedthanlost.net>
Date: Thu Aug 12 00:53:10 2010 +1000
Rewrote functions documentation to Markdown
diff --git a/lib/puppet/parser/functions.rb b/lib/puppet/parser/functions.rb
index c238da5..b0deac5 100644
--- a/lib/puppet/parser/functions.rb
+++ b/lib/puppet/parser/functions.rb
@@ -20,7 +20,7 @@ module Puppet::Parser::Functions
@autoloader = Puppet::Util::Autoload.new(
self,
"puppet/parser/functions",
-
+
:wrap => false
)
end
@@ -94,7 +94,7 @@ module Puppet::Parser::Functions
ret += "Undocumented.\n"
end
- ret += "\n\n- **Type**: #{hash[:type]}\n\n"
+ ret += "\n\n- *Type*: #{hash[:type]}\n\n"
end
ret
diff --git a/lib/puppet/parser/functions/defined.rb b/lib/puppet/parser/functions/defined.rb
index 2930a65..90632af 100644
--- a/lib/puppet/parser/functions/defined.rb
+++ b/lib/puppet/parser/functions/defined.rb
@@ -3,7 +3,7 @@ Puppet::Parser::Functions::newfunction(:defined, :type => :rvalue, :doc => "Dete
type is defined, either as a native type or a defined type, or whether a class is defined.
This is useful for checking whether a class is defined and only including it if it is.
This function can also test whether a resource has been defined, using resource references
- (e.g., ``if defined(File['/tmp/myfile']) { ... }``). This function is unfortunately
+ (e.g., `if defined(File['/tmp/myfile']) { ... }`). This function is unfortunately
dependent on the parse order of the configuration when testing whether a resource is defined.") do |vals|
result = false
vals = [vals] unless vals.is_a?(Array)
diff --git a/lib/puppet/parser/functions/file.rb b/lib/puppet/parser/functions/file.rb
index 9631112..19ab9ba 100644
--- a/lib/puppet/parser/functions/file.rb
+++ b/lib/puppet/parser/functions/file.rb
@@ -2,7 +2,7 @@
Puppet::Parser::Functions::newfunction(
:file, :type => :rvalue,
-
+
:doc => "Return the contents of a file. Multiple files
can be passed, and the first file that exists will be read in.") do |vals|
ret = nil
diff --git a/lib/puppet/parser/functions/inline_template.rb b/lib/puppet/parser/functions/inline_template.rb
index 46e0003..9759ff6 100644
--- a/lib/puppet/parser/functions/inline_template.rb
+++ b/lib/puppet/parser/functions/inline_template.rb
@@ -1,9 +1,10 @@
Puppet::Parser::Functions::newfunction(:inline_template, :type => :rvalue, :doc =>
- "Evaluate a template string and return its value. See `the templating docs
- <http://docs.puppetlabs.com/guides/templating.html>`_ for more information. Note that
- if multiple template strings are specified, their output is all concatenated
- and returned as the output of the function.") do |vals|
- require 'erb'
+ "Evaluate a template string and return its value. See
+ [the templating docs](http://docs.puppetlabs.com/guides/templating.html) for
+ more information. Note that if multiple template strings are specified, their
+ output is all concatenated and returned as the output of the function.") do |vals|
+
+ require 'erb'
vals.collect do |string|
# Use a wrapper, so the template can't get access to the full
diff --git a/lib/puppet/parser/functions/realize.rb b/lib/puppet/parser/functions/realize.rb
index 4247b8a..c21ccd1 100644
--- a/lib/puppet/parser/functions/realize.rb
+++ b/lib/puppet/parser/functions/realize.rb
@@ -5,7 +5,7 @@ Puppet::Parser::Functions::newfunction(:realize, :doc => "Make a virtual object
when you want to know the name of the virtual object and don't want to
bother with a full collection. It is slightly faster than a collection,
and, of course, is a bit shorter. You must pass the object using a
- reference; e.g.: ``realize User[luke]``." ) do |vals|
+ reference; e.g.: `realize User[luke]`." ) do |vals|
coll = Puppet::Parser::Collector.new(self, :nomatter, nil, nil, :virtual)
vals = [vals] unless vals.is_a?(Array)
coll.resources = vals.flatten
diff --git a/lib/puppet/parser/functions/regsubst.rb b/lib/puppet/parser/functions/regsubst.rb
index c0aeef2..f655db7 100644
--- a/lib/puppet/parser/functions/regsubst.rb
+++ b/lib/puppet/parser/functions/regsubst.rb
@@ -6,37 +6,37 @@ module Puppet::Parser::Functions
:doc => "
Perform regexp replacement on a string or array of strings.
-- **Parameters** (in order):
+* *Parameters* (in order):
-:target: The string or array of strings to operate on. If an array, the replacement will be performed on each of the elements in the array, and the return value will be an array.
+ _target_ The string or array of strings to operate on. If an array, the replacement will be performed on each of the elements in the array, and the return value will be an array.
-:regexp: The regular expression matching the target string. If you want it anchored at the start and or end of the string, you must do that with ^ and $ yourself.
+ _regexp_ The regular expression matching the target string. If you want it anchored at the start and or end of the string, you must do that with ^ and $ yourself.
-:replacement: Replacement string. Can contain back references to what was matched using \\0, \\1, and so on.
+ _replacement_ Replacement string. Can contain back references to what was matched using \\0, \\1, and so on.
-:flags: Optional. String of single letter flags for how the regexp is interpreted:
+ _flags_ Optional. String of single letter flags for how the regexp is interpreted:
- - **E** Extended regexps
- - **I** Ignore case in regexps
- - **M** Multiline regexps
- - **G** Global replacement; all occurrences of the regexp in each target string will be replaced. Without this, only the first occurrence will be replaced.
+ - *E* Extended regexps
+ - *I* Ignore case in regexps
+ - *M* Multiline regexps
+ - *G* Global replacement; all occurrences of the regexp in each target string will be replaced. Without this, only the first occurrence will be replaced.
-:lang: Optional. How to handle multibyte characters. A single-character string with the following values:
+ _lang_ Optional. How to handle multibyte characters. A single-character string with the following values:
- - **N** None
- - **E** EUC
- - **S** SJIS
- - **U** UTF-8
+ - *N* None
+ - *E* EUC
+ - *S* SJIS
+ - *U* UTF-8
-- **Examples**
+* *Examples*
-Get the third octet from the node's IP address::
+Get the third octet from the node's IP address:
- $i3 = regsubst($ipaddress,'^([0-9]+)[.]([0-9]+)[.]([0-9]+)[.]([0-9]+)$','\\3')
+ $i3 = regsubst($ipaddress,'^([0-9]+)[.]([0-9]+)[.]([0-9]+)[.]([0-9]+)$','\\3')
-Put angle brackets around each octet in the node's IP address::
+Put angle brackets around each octet in the node's IP address:
- $x = regsubst($ipaddress, '([0-9]+)', '<\\1>', 'G')
+ $x = regsubst($ipaddress, '([0-9]+)', '<\\1>', 'G')
") \
do |args|
unless args.length.between?(3, 5)
diff --git a/lib/puppet/parser/functions/require.rb b/lib/puppet/parser/functions/require.rb
index 3f98c95..f15046b 100644
--- a/lib/puppet/parser/functions/require.rb
+++ b/lib/puppet/parser/functions/require.rb
@@ -12,9 +12,8 @@ relationships between classes. This function is a superset of the
class depends on the required class.
Warning: using require in place of include can lead to unwanted dependency cycles.
- For instance the following manifest, with 'require' instead of 'include'
- would produce a nasty dependence cycle, because notify imposes a before
- between File[/foo] and Service[foo]::
+
+For instance the following manifest, with 'require' instead of 'include' would produce a nasty dependence cycle, because notify imposes a before between File[/foo] and Service[foo]:
class myservice {
service { foo: ensure => running }
diff --git a/lib/puppet/parser/functions/split.rb b/lib/puppet/parser/functions/split.rb
index 5d0a9da..5239409 100644
--- a/lib/puppet/parser/functions/split.rb
+++ b/lib/puppet/parser/functions/split.rb
@@ -6,7 +6,7 @@ module Puppet::Parser::Functions
:doc => "\
Split a string variable into an array using the specified split regexp.
- Usage::
+ Usage:
$string = 'v1.v2:v3.v4'
$array_var1 = split($string, ':')
diff --git a/lib/puppet/parser/functions/sprintf.rb b/lib/puppet/parser/functions/sprintf.rb
index 5ada0fe..5eb4a4f 100644
--- a/lib/puppet/parser/functions/sprintf.rb
+++ b/lib/puppet/parser/functions/sprintf.rb
@@ -5,7 +5,7 @@ module Puppet::Parser::Functions
:doc => "Perform printf-style formatting of text.
- The first parameter is format string describing how the rest of the parameters should be formatted. See the documentation for the ``Kernel::sprintf`` function in Ruby for all the details.") do |args|
+ The first parameter is format string describing how the rest of the parameters should be formatted. See the documentation for the `Kernel::sprintf` function in Ruby for all the details.") do |args|
raise Puppet::ParseError, 'sprintf() needs at least one argument' if args.length < 1
fmt = args.shift
return sprintf(fmt, *args)
diff --git a/lib/puppet/parser/functions/template.rb b/lib/puppet/parser/functions/template.rb
index f51bcc1..6fa1103 100644
--- a/lib/puppet/parser/functions/template.rb
+++ b/lib/puppet/parser/functions/template.rb
@@ -1,6 +1,8 @@
Puppet::Parser::Functions::newfunction(:template, :type => :rvalue, :doc =>
- "Evaluate a template and return its value. See `the templating docs
- <http://docs.puppetlabs.com/guides/templating.html>`_ for more information.
+ "Evaluate a template and return its value. See
+ [the templating docs](http://docs.puppetlabs.com/guides/templating.html) for
+ more information.
+
Note that if multiple templates are specified, their output is all
concatenated and returned as the output of the function.") do |vals|
require 'erb'
diff --git a/lib/puppet/parser/functions/versioncmp.rb b/lib/puppet/parser/functions/versioncmp.rb
index b384065..94ba388 100644
--- a/lib/puppet/parser/functions/versioncmp.rb
+++ b/lib/puppet/parser/functions/versioncmp.rb
@@ -3,26 +3,26 @@ require 'puppet/util/package'
Puppet::Parser::Functions::newfunction(
:versioncmp, :type => :rvalue,
-
+
:doc => "Compares two versions
-Prototype::
+Prototype:
- \$result = versioncmp(a, b)
+ \$result = versioncmp(a, b)
- where a and b are arbitrary version strings
+Where a and b are arbitrary version strings
-This functions returns a number::
+This functions returns a number:
- * > 0 if version a is greater than version b
- * == 0 if both version are equals
- * < 0 if version a is less than version b
+* > 0 if version a is greater than version b
+* == 0 if both version are equals
+* < 0 if version a is less than version b
-Example::
+Example:
- if versioncmp('2.6-1', '2.4.5') > 0 {
- notice('2.6-1 is > than 2.4.5')
- }
+ if versioncmp('2.6-1', '2.4.5') > 0 {
+ notice('2.6-1 is > than 2.4.5')
+ }
") do |args|
diff --git a/lib/puppet/reference/configuration.rb b/lib/puppet/reference/configuration.rb
index bfa2cb8..fadd1a4 100644
--- a/lib/puppet/reference/configuration.rb
+++ b/lib/puppet/reference/configuration.rb
@@ -33,7 +33,7 @@ config = Puppet::Util::Reference.newreference(:configuration, :depth => 1, :doc
# Leave out the section information; it was apparently confusing people.
#str += "- **Section**: #{object.section}\n"
unless val == ""
- str += "- **Default**: #{val}\n"
+ str += "- *Default*: #{val}\n"
end
str += "\n"
end
@@ -47,7 +47,7 @@ Specifying Configuration Parameters
On The Command-Line
+++++++++++++++++++
-Every Puppet executable (with the exception of ``puppetdoc``) accepts all of
+Every Puppet executable (with the exception of `puppetdoc`) accepts all of
the parameters below, but not all of the arguments make sense for every executable.
I have tried to be as thorough as possible in the descriptions of the
@@ -55,60 +55,61 @@ arguments, so it should be obvious whether an argument is appropriate or not.
These parameters can be supplied to the executables either as command-line
options or in the configuration file. For instance, the command-line
-invocation below would set the configuration directory to ``/private/puppet``::
+invocation below would set the configuration directory to `/private/puppet`:
- $ puppet agent --confdir=/private/puppet
+ $ puppet agent --confdir=/private/puppet
Note that boolean options are turned on and off with a slightly different
-syntax on the command line::
+syntax on the command line:
- $ puppet agent --storeconfigs
+ $ puppet agent --storeconfigs
- $ puppet agent --no-storeconfigs
+ $ puppet agent --no-storeconfigs
The invocations above will enable and disable, respectively, the storage of
the client configuration.
Configuration Files
+++++++++++++++++++
+
As mentioned above, the configuration parameters can also be stored in a
configuration file, located in the configuration directory. As root, the
-default configuration directory is ``/etc/puppet``, and as a regular user, the
-default configuration directory is ``~user/.puppet``. As of 0.23.0, all
-executables look for ``puppet.conf`` in their configuration directory
+default configuration directory is `/etc/puppet`, and as a regular user, the
+default configuration directory is `~user/.puppet`. As of 0.23.0, all
+executables look for `puppet.conf` in their configuration directory
(although they previously looked for separate files). For example,
-``puppet.conf`` is located at ``/etc/puppet/puppet.conf`` as root and
-``~user/.puppet/puppet.conf`` as a regular user by default.
+`puppet.conf` is located at `/etc/puppet/puppet.conf` as `root` and
+`~user/.puppet/puppet.conf` as a regular user by default.
-All executables will set any parameters set within the ``main`` section,
-and each executable will also use one of the ``master``, ``agent``, or
-``user`` sections.
+All executables will set any parameters set within the `[main]` section,
+and each executable will also use one of the `[master]`, `[agent]`.
File Format
'''''''''''
+
The file follows INI-style formatting. Here is an example of a very simple
-``puppet.conf`` file::
+`puppet.conf` file:
- [main]
- confdir = /private/puppet
- storeconfigs = true
+ [main]
+ confdir = /private/puppet
+ storeconfigs = true
Note that boolean parameters must be explicitly specified as `true` or
`false` as seen above.
If you need to change file parameters (e.g., reset the mode or owner), do
-so within curly braces on the same line::
+so within curly braces on the same line:
- [main]
- myfile = /tmp/whatever {owner = root, mode = 644}
+ [main]
+ myfile = /tmp/whatever {owner = root, mode = 644}
If you're starting out with a fresh configuration, you may wish to let
the executable generate a template configuration file for you by invoking
the executable in question with the `--genconfig` command. The executable
will print a template configuration to standard output, which can be
-redirected to a file like so::
+redirected to a file like so:
- $ puppet agent --genconfig > /etc/puppet/puppet.conf
+ $ puppet agent --genconfig > /etc/puppet/puppet.conf
Note that this invocation will replace the contents of any pre-existing
`puppet.conf` file, so make a backup of your present config if it contains
@@ -117,28 +118,30 @@ valuable information.
Like the `--genconfig` argument, the executables also accept a `--genmanifest`
argument, which will generate a manifest that can be used to manage all of
Puppet's directories and files and prints it to standard output. This can
-likewise be redirected to a file::
+likewise be redirected to a file:
- $ puppet agent --genmanifest > /etc/puppet/manifests/site.pp
+ $ puppet agent --genmanifest > /etc/puppet/manifests/site.pp
Puppet can also create user and group accounts for itself (one `puppet` group
-and one `puppet` user) if it is invoked as `root` with the `--mkusers` argument::
+and one `puppet` user) if it is invoked as `root` with the `--mkusers` argument:
- $ puppet agent --mkusers
+ $ puppet agent --mkusers
Signals
-------
-The ``puppet agent`` and ``puppet master`` executables catch some signals for special
-handling. Both daemons catch (``SIGHUP``), which forces the server to restart
-tself. Predictably, interrupt and terminate (``SIGINT`` and ``SIGTERM``) will shut
-down the server, whether it be an instance of ``puppet agent`` or ``puppet master``.
-Sending the ``SIGUSR1`` signal to an instance of ``puppet agent`` will cause it to
+The `puppet agent` and `puppet master` executables catch some signals for special
+handling. Both daemons catch (`SIGHUP`), which forces the server to restart
+tself. Predictably, interrupt and terminate (`SIGINT` and `SIGTERM`) will shut
+down the server, whether it be an instance of `puppet agent` or `puppet master`.
+
+Sending the `SIGUSR1` signal to an instance of `puppet agent` will cause it to
immediately begin a new configuration transaction with the server. This
-signal has no effect on ``puppet master``.
+signal has no effect on `puppet master`.
Configuration Parameter Reference
---------------------------------
+
Below is a list of all documented parameters. Not all of them are valid with all
Puppet executables, but the executables will ignore any inappropriate values.
diff --git a/lib/puppet/reference/indirection.rb b/lib/puppet/reference/indirection.rb
index d14510c..0cdbb25 100644
--- a/lib/puppet/reference/indirection.rb
+++ b/lib/puppet/reference/indirection.rb
@@ -26,9 +26,8 @@ end
reference.header = "This is the list of all indirections, their associated terminus classes, and how you select between them.
-In general, the appropriate terminus class is selected by the application for you (e.g., ``puppet agent`` would always use the ``rest``
-terminus for most of its indirected classes), but some classes are tunable via normal settings. These will have ``terminus setting``
-documentation listed with them.
+In general, the appropriate terminus class is selected by the application for you (e.g., `puppet agent` would always use the `rest`
+terminus for most of its indirected classes), but some classes are tunable via normal settings. These will have `terminus setting` documentation listed with them.
"
diff --git a/lib/puppet/reference/metaparameter.rb b/lib/puppet/reference/metaparameter.rb
index 6a319f1..39c4b7f 100644
--- a/lib/puppet/reference/metaparameter.rb
+++ b/lib/puppet/reference/metaparameter.rb
@@ -29,14 +29,6 @@ metaparameter = Puppet::Util::Reference.newreference :metaparameter, :doc => "Al
a.to_s <=> b.to_s
}.each { |param|
str += paramwrap(param.to_s, scrub(Puppet::Type.metaparamdoc(param)), :level => 4)
- #puts "<dt>#{param}</dt>"
- #puts tab(1) + Puppet::Type.metaparamdoc(param).scrub.indent($tab)gsub(/\n\s*/,' ')
- #puts "<dd>"
- #puts indent(scrub(Puppet::Type.metaparamdoc(param)), $tab)
- #puts scrub(Puppet::Type.metaparamdoc(param))
- #puts "</dd>"
-
- #puts ""
}
rescue => detail
puts detail.backtrace
diff --git a/lib/puppet/reference/network.rb b/lib/puppet/reference/network.rb
index 15e4f67..fda7931 100644
--- a/lib/puppet/reference/network.rb
+++ b/lib/puppet/reference/network.rb
@@ -29,11 +29,11 @@ on the server, and the client knows how to call the handler's methods
appropriately.
Most handlers are meant to be started on the server, usually within
-``puppet master``, and the clients are mostly started on the client,
-usually within ``puppet agent``.
+`puppet master`, and the clients are mostly started on the client,
+usually within `puppet agent`.
You can find the server-side handler for each interface at
-``puppet/network/handler/<name>.rb`` and the client class at
-``puppet/network/client/<name>.rb``.
+`puppet/network/handler/<name>.rb` and the client class at
+`puppet/network/client/<name>.rb`.
"
diff --git a/lib/puppet/reference/providers.rb b/lib/puppet/reference/providers.rb
index ef33a55..b44b26a 100644
--- a/lib/puppet/reference/providers.rb
+++ b/lib/puppet/reference/providers.rb
@@ -47,7 +47,7 @@ providers = Puppet::Util::Reference.newreference :providers, :title => "Provider
# Add the suitability note
if missing = provider.suitable?(false) and missing.empty?
- data << "**X**"
+ data << "*X*"
suit = true
functional = true
else
@@ -86,7 +86,7 @@ providers = Puppet::Util::Reference.newreference :providers, :title => "Provider
# Add a note for every feature
features.each do |feature|
if provider.features.include?(feature)
- data << "**X**"
+ data << "*X*"
else
data << ""
end
diff --git a/lib/puppet/reference/report.rb b/lib/puppet/reference/report.rb
index 481ca2d..47fc779 100644
--- a/lib/puppet/reference/report.rb
+++ b/lib/puppet/reference/report.rb
@@ -7,16 +7,15 @@ end
report.header = "
Puppet clients can report back to the server after each transaction. This
transaction report is sent as a YAML dump of the
-``Puppet::Transaction::Report`` class and includes every log message that was
+`Puppet::Transaction::Report` class and includes every log message that was
generated during the transaction along with as many metrics as Puppet knows how
-to collect. See `ReportsAndReporting Reports and Reporting`:trac:
-for more information on how to use reports.
+to collect. See [Reports and Reporting](http://projects.puppetlabs.com/projects/puppet/wiki/Reports_And_Reporting) for more information on how to use reports.
Currently, clients default to not sending in reports; you can enable reporting
-by setting the ``report`` parameter to true.
+by setting the `report` parameter to true.
-To use a report, set the ``reports`` parameter on the server; multiple
-reports must be comma-separated. You can also specify ``none`` to disable
+To use a report, set the `reports` parameter on the server; multiple
+reports must be comma-separated. You can also specify `none` to disable
reports entirely.
Puppet provides multiple report handlers that will process client reports:
diff --git a/lib/puppet/reference/type.rb b/lib/puppet/reference/type.rb
index be8742e..2378bb8 100644
--- a/lib/puppet/reference/type.rb
+++ b/lib/puppet/reference/type.rb
@@ -16,25 +16,25 @@ type = Puppet::Util::Reference.newreference :type, :doc => "All Puppet resource
- The *namevar* is the parameter used to uniquely identify a type instance.
This is the parameter that gets assigned when a string is provided before
the colon in a type declaration. In general, only developers will need to
- worry about which parameter is the ``namevar``.
+ worry about which parameter is the `namevar`.
- In the following code::
+ In the following code:
- file { "/etc/passwd":
- owner => root,
- group => root,
- mode => 644
- }
+ file { "/etc/passwd":
+ owner => root,
+ group => root,
+ mode => 644
+ }
- ``/etc/passwd`` is considered the title of the file object (used for things like
- dependency handling), and because ``path`` is the namevar for ``file``, that
- string is assigned to the ``path`` parameter.
+ `/etc/passwd` is considered the title of the file object (used for things like
+ dependency handling), and because `path` is the namevar for `file`, that
+ string is assigned to the `path` parameter.
-- *Parameters* determine the specific configuration of the instance. They either
+ - *Parameters* determine the specific configuration of the instance. They either
directly modify the system (internally, these are called properties) or they affect
- how the instance behaves (e.g., adding a search path for ``exec`` instances or determining recursion on ``file`` instances).
+ how the instance behaves (e.g., adding a search path for `exec` instances or determining recursion on `file` instances).
-- *Providers* provide low-level functionality for a given resource type. This is
+ - *Providers* provide low-level functionality for a given resource type. This is
usually in the form of calling out to external commands.
When required binaries are specified for providers, fully qualifed paths
@@ -42,7 +42,7 @@ type = Puppet::Util::Reference.newreference :type, :doc => "All Puppet resource
binaries indicate that Puppet will search for the binary using the shell
path.
-- *Features* are abilities that some providers might not support. You can use the list
+ - *Features* are abilities that some providers might not support. You can use the list
of supported features to determine how a given provider can be used.
Resource types define features they can use, and providers can be tested to see
--
Puppet packaging for Debian
More information about the Pkg-puppet-devel
mailing list