There are two points in docs/submission.pod where the word 'test' is
used is a way which, IMHO, is confusing.
1. Lines 24-29
Generally, when adding a *new test* you should add a new step
unless a test
I<clearly> belongs in a current step. For example, if we added a new
user-configurable type called C<FOOVAL>, you should add the test
for its size
in F<config/auto/sizes.pm>; however, if you were testing what
dynaloading
capabilities are available, you should create a new step.
[Emphasis ** added.]
When I come across the phrase 'new test', I immediately wonder what
the 'old' or 'previous' test might be. But this is the very first
time that the word 'test' is used in this document! The preceding
paragraph talks a lot about adding new *steps*, but makes no
reference to adding new *tests*. This does not appear to mean 'test'
in the sense of a test you might find in a t/*.t file.
2. Lines 96-100
All steps are really classes; they each exist in a unique
namespace. The
namespace used depends on the tests [sic] relative path in the
source tree minus sans [sic]
the F<config> prefix. For example, the step F<config/init/
defaults.pm> uses
the C<init::defaults> namespace.
First of all, it should have been "test's" in the second line to
indicate the possessive rather than a plural. Second, you don't need
both 'minus' and 'sans'; deleting 'minus' would probably be better.
But, here again, the term 'test' appears in this paragraph without a
preceding reference in this paragraph or the preceding one. I would
have expected something more like:
The namespace used depends on the step's relative path in the
source tree sans the F<config> prefix.
Since I'm not entirely clear as to what's intended in these two
locations, I'm not yet providing a patch. Can anyone clarify?
Thank you very much.
kid51
It probably would have been more productive if I had correctly identified the file I was
complaining about. The file in question is: docs/configuration.pod.
Having heard no objections, patch was applied tonight in r18417.
kid51