On Wed, 20 Jul 2011 09:06:02 +0200, David Schmitt wrote:
>
> On 20.07.2011 00:40, Daniel Pittman wrote:
> >On Tue, Jul 19, 2011 at 15:25, Jacob Helwig<ja...@puppetlabs.com> wrote:
> >>On Tue, 19 Jul 2011 15:13:40 -0700, Daniel Pittman wrote:
> >>>
> >>>On Tue, Jul 19, 2011 at 14:59, Josh Cooper<j...@puppetlabs.com> wrote:
> >>>>
> >>>>+ :desc => "The search path for modules as a list of directories
> >>>>separated by the '#{File::PATH_SEPARATOR}' character.",
> >>>
> >>>...this is just wrong. We are going to generate documentation about
> >>>this based on the platform we run our generator on, which is assured
> >>>to be wrong in one of the two common cases – since it can't run on
> >>>*both* at once.
> >>
> >>It will, however, be correct whenever someone does anything like "puppet
> >>agent --genconfig", which will be on their platform.
> >
> >*nod* True, that. Given we machine-generate our reference
> >documentation, though, we probably want to have the description cover
> >the cross-platform information some way or other. Otherwise people
> >who read the website are going to be a bit confused about our Win32
> >story. ;)
> >
> >(I couldn't think of a less ugly way to make the default for the path
> >work, BTW, so I don't object to that part. Just the documentation.)
>
> Can you write that it is "separated by either ':' or ';' depending
> on platform, with '#{File::PATH_SEPARATOR}' being the local default"
> ?
>
So, the problem with this wording is that it's not actually a "local
default". You can't change which path separator is used.
I can see adding a note something like "separated by the
'#{File::PATH_SEPARATOR}' character (varies by platform).", but I'd
really rather not have us listing out both ';' and ':'.
The bigger problem is that we're trying to serve two different purposes
with the same text. We're trying to have generic documentation suitable
for the web, and also have the documentation that is relevent for the
specific platform that we're actually running on.
This File::PATH_SEPARATOR issue is just one example of this. The color
setting, and any of the confdir or other path settings have the same
class of problem. There isn't One Default to Rule Them All, there are
the defaults and settings for the platform, and the web documentation we
generate happens to be for Linux.
--
Jacob Helwig
,----
| Join us for PuppetConf, September 22nd and 23rd in Portland, OR
| http://bit.ly/puppetconfsig
`----
signature.asc
Description: Digital signature
