[lintian] 01/01: doc/tutorial/*: proof-read
This is an automated email from the git hooks/post-receive script.
adsb pushed a commit to branch master
in repository lintian.
commit d03b83a2756aa964c939c512dc0934b8f420698c
Author: Adam D. Barratt <adam@adam-barratt.org.uk>
Date: Tue Aug 11 19:29:41 2015 +0100
doc/tutorial/*: proof-read
Signed-off-by: Adam D. Barratt <adam@adam-barratt.org.uk>
---
doc/tutorial/Lintian/Tutorial/TestSuite.pod | 18 +++----
doc/tutorial/Lintian/Tutorial/WritingChecks.pod | 68 ++++++++++++-------------
doc/tutorial/Lintian/Tutorial/WritingTests.pod | 42 +++++++--------
3 files changed, 64 insertions(+), 64 deletions(-)
diff --git a/doc/tutorial/Lintian/Tutorial/TestSuite.pod b/doc/tutorial/Lintian/Tutorial/TestSuite.pod
index 650fd26..1a87ed8 100644
--- a/doc/tutorial/Lintian/Tutorial/TestSuite.pod
+++ b/doc/tutorial/Lintian/Tutorial/TestSuite.pod
@@ -18,9 +18,9 @@ L<Lintian::Tutorial::WritingTests>.
The Lintian test suite is an extensive collection of various test
cases. The test suite is divided into 4 "sub-suites". The majority
-of all tests are currently located in the "tests" sub-suite.
+of tests are currently located in the "tests" sub-suite.
-To run the full suite in all of its glory, simply invoke:
+To run the full suite in all its glory, simply invoke:
$ debian/rules runtests
@@ -29,11 +29,11 @@ To run the full suite in all of its glory, simply invoke:
$ mkdir -p debian/test-out
$ t/runtests -k --dump-logs t debian/test-out
-But while writing a new tag (or check) you probably only want to run a
+While writing a new tag (or check) you probably only want to run a
particular (subset of the) test(s). See L</Running a subset of the
tests> for the available options.
-When run via I<debian/rules>, the test suite respects the
+When run via I<debian/rules>, the test suite respects
"DEB_BUILD_OPTIONS=parallel=N". When using I<t/runtests> directly, use
I<-jN> to choose the number of threads. Note that "N" denotes the
amount of "worker" threads. The test runner will generally have 2
@@ -41,9 +41,9 @@ threads more than that. Also each "worker" will run lintian, which
runs multiple unpacking jobs in parallel as well.
In case you are wondering about the 2 extra threads in the test
-runner, the first of them is the "coordinator"-thread (which will
+runner, the first of them is the "coordinator" thread (which will
generally be waiting when the workers are active) and the second one
-is the "output"-thread (which handles the fancy output).
+is the "output" thread (which handles the fancy output).
=head2 Running a subset of the tests
@@ -72,7 +72,7 @@ To run all tests for a given check, use:
$ t/runtests --dump-logs -k t debian/test-out $check
$check must be the name of a check (it will test for
-checks/$check.desc) or "legacy". This will run all tests that starts
+checks/$check.desc) or "legacy". This will run all tests that start
with "$check-".
Note: The "changes" sub-suite in the new test suite does not support
@@ -90,12 +90,12 @@ To run all tests in a given sub-suite, use:
$suites is a comma-separated list of names of sub-suites to run.
-Note: this cannot be used to influence the order, in which the sub-suites
+Note: this cannot be used to influence the order in which the sub-suites
are run.
=item Running all tests designed for a specific tag
-To run all tests that has a "Test-For" or a "Test-Against" for a given
+To run all tests that have a "Test-For" or a "Test-Against" for a given
tag, use:
$ debian/rules runtests onlyrun=tag:$tag
diff --git a/doc/tutorial/Lintian/Tutorial/WritingChecks.pod b/doc/tutorial/Lintian/Tutorial/WritingChecks.pod
index f9433ab..6f4860b 100644
--- a/doc/tutorial/Lintian/Tutorial/WritingChecks.pod
+++ b/doc/tutorial/Lintian/Tutorial/WritingChecks.pod
@@ -17,17 +17,17 @@ one.
=head1 DESCRIPTION
-The basics of writing a check is outlined in the Lintian User Manual
-(§3.3). This tutorial will focus on the part of writing the actual
+The basics of writing a check are outlined in the Lintian User Manual
+(§3.3). This tutorial will focus on the act of writing the actual
check. In this tutorial, we will assume the name of the check to be
-written is called "deb/pkg-check".
+written is "deb/pkg-check".
The tutorial will work with a "binary" and "udeb" check. Checking
source packages works in a similar fashion.
=head2 Create a check I<.desc> file
-As mentioned, this tutorial will focus on the part of writing a check.
+As mentioned, this tutorial will focus on the writing of a check.
Please see the Lintian User Manual (§3.3) for how to do this part.
=head2 Create the Perl check module
@@ -48,7 +48,7 @@ Start with the template:
return;
}
-This snippet above is a simple valid check that does "nothing at all".
+The snippet above is a simple valid check that does "nothing at all".
We will extend it in just a moment, but first let us have a look at
the arguments at the setup.
@@ -70,7 +70,7 @@ At the moment, $type is one of "binary" (.deb), "udeb", "source"
(.dsc) or "changes". This argument is mostly useful if certain checks
do not apply equally to all package types being processed.
-Generally it is advisable to do check only binaries ("binary" and
+Generally it is advisable to check only binaries ("binary" and
"udeb"), sources or changes in a given check. But in rare cases, it
makes sense to lump multiple types together in the same check and this
argument helps you do that.
@@ -110,7 +110,7 @@ This is an instance of L<Lintian::ProcessableGroup>.
=back
-Now back to the part of coding.
+Now back to the coding.
=head2 Emitting a tag
@@ -148,15 +148,15 @@ Lintian/your check.
=head2 Accessing fields
-Lets do a slightly harder example. Assume we wanted to emit a tag for
+Let's do a slightly harder example. Assume we wanted to emit a tag for
all packages without a (valid) Multi-Arch field. This requires us to
A) identify if the package has a Multi-Arch field and B) identify if
-the contents of the field was valid.
+the content of the field was valid.
Starting from the top. All $info objects have a method called field,
which gives you access to a (raw) field from the control file of the
package. It returns C<undef> if said field is not present or the
-contents of said field otherwise. Note that field names must be given
+content of said field otherwise. Note that field names must be given
in all lowercase letters (i.e. use "multi-arch", not "Multi-Arch").
# deb/pkg-check is loaded as Lintian::deb::pkg_check
@@ -179,7 +179,7 @@ in all lowercase letters (i.e. use "multi-arch", not "Multi-Arch").
return;
}
-This was the first half. Lets look at checking the value. Multi-arch
+This was the first half. Let's look at checking the value. Multi-arch
fields can (currently) be one of "no", "same", "foreign" or "allowed".
One way of checking this would be using the regex:
@@ -239,17 +239,17 @@ pre-depend on the package "multiarch-support". Well, we could use the
L<< $info->relation|Lintian::Collect::Binary/relation (FIELD) >> method for
this.
-The $info->relation returns an instance of L<Lintian::Relation>. This
+$info->relation returns an instance of L<Lintian::Relation>. This
object has an "implies" method that can be used to check if a package
has an explicit dependency. Note that "implies" actually checks if
-one relations "implies" another (i.e. if you satisfied relationA then
+one relation "implies" another (i.e. if you satisfied relationA then
you definitely also satisfied relationB).
-Like with the "field"-method, field names have to be given in all
-lowercase. But "relation" will never return C<undef> (not even if the
+As with the "field"-method, field names have to be given in all
+lowercase. However "relation" will never return C<undef> (not even if the
field is missing).
-So in example:
+For example:
my $predepends = $info->relation('pre-depends');
unless ($predepends->implies('multiarch-support')) {
@@ -296,7 +296,7 @@ Inserted in the proper place, our check now looks like:
=head2 Using static data files
Currently our check mixes data and code. Namely all the valid values
-for the Multi-Arch field is currently hard-coded in our check. We can
+for the Multi-Arch field are currently hard-coded in our check. We can
move those out of the check by using a data file.
Lintian natively supports data files that are either "sets" or
@@ -335,7 +335,7 @@ Data files work with 3 access methods, "all", "known" and "value".
=item all
"all" (i.e. $data->all) returns a list of all the entries in the data
-files (for key/value tables, all returns the keys). The list is not
+file (for key/value tables, all returns the keys). The list is not
sorted in any order (not even input order).
=item known
@@ -405,7 +405,7 @@ So the resulting check is:
=head2 Accessing contents of the package
-Another very used mechanism is to check for the presence (or absence)
+Another heavily used mechanism is to check for the presence (or absence)
of a given file. Generally this is what the
L<< $info->index|Lintian::Collect::Package/index (FILE) >> and
L<< $info->sorted_index|Lintian::Collect::Package/sorted_index >> methods
@@ -413,8 +413,8 @@ are for. The "index" method returns instances of L<Lintian::Path>,
which has a number of utility methods.
If you want to loop over all files in a package, the sorted_index will
-do this for you. If you are looking for a specific file (or dir), a
-call to "index" will be much faster. For the contents of a specific dir,
+do this for you. If you are looking for a specific file (or directory), a
+call to "index" will be much faster. For the contents of a specific directory,
you can use something like:
if (my $dir = $info->index('path/to/dir/')) {
@@ -428,7 +428,7 @@ Keep in mind that using the "index" or "sorted_index" method will
require that you put "unpacked" in Needs-Info. See L</Keeping Needs-Info
up to date>.
-There is also a pair of methods for accessing the control files of a
+There are also a pair of methods for accessing the control files of a
binary package. These are
L<< $info->control_index|Lintian::Collect::Package/control_index (FILE) >> and
L<< $info->sorted_control_index|Lintian::Collect::Package/sorted_control_index >>.
@@ -442,22 +442,22 @@ L<< $info->index|Lintian::Collect::Package/index (FILE) >>. These
methods will open the underlying file for reading (the latter
applying a gzip decompression).
-However, please do assert that file is safe to read by calling
+However, please do assert that the file is safe to read by calling
L<is_open_ok|Lintian::Path/is_open_ok> first. Generally, it will
only be true for files or safely resolvable symlinks pointing to
files. Should you attempt to open a path that does not satisfy
those criteria, L<Lintian::Path> will raise a trappable error at
runtime.
-Alternatively, if you access to the underlying file object, you can
+Alternatively, if you access the underlying file object, you can
use the L<fs_path|Lintian::Path/fs_path> method. Usually, you will
want to test either L<is_open_ok|Lintian::Path/is_open_ok> or
L<is_valid_path|Lintian::Path/is_valid_path> first to ensure you do
not follow unsafe symlinks. The "is_open_ok" check will also assert
-that it is not (e.g.) a named pipe and such.
+that it is not (e.g.) a named pipe or such.
Should you call L<fs_path|Lintian::Path/fs_path> on a symlink that
-escape the package root, the method will throw a trappable error at
+escapes the package root, the method will throw a trappable error at
runtime. Once the path is returned, there are no more built-in
fail-safes. When you use the returned path, keep things like
"../../../../../etc/passwd"-symlink and "fifo" pipes in mind.
@@ -500,7 +500,7 @@ separated list and each element of Y basically falls into 3 cases.
=over 4
-=item * The element is a the word I<none>
+=item * The element is the word I<none>
In this case, the method has no "external" requirements and can be
used without any changes to your Needs-Info. The "field" method
@@ -510,7 +510,7 @@ This only makes sense if it is the only element in the list.
=item * The element is a link to a method
-In this case, the method uses another method to do is job. An example
+In this case, the method uses another method to do its job. An example
is the
L<sorted_control_index|Lintian::Collect::Binary/sorted_control_index>
method, which uses the
@@ -527,13 +527,13 @@ you have to put "bin-pkg-control" in your Needs-Info.
=back
CAVEAT: Methods can have different requirements based on the type of
-package! Example being "changelog", which requires "changelog-file"
+package! An example of this "changelog", which requires "changelog-file"
in binary packages and "Same as debfiles" in source packages.
=head2 Avoiding security issues
Over the years a couple of security issues have been discovered in
-Lintian. The problem is people can in theory create some really nasty
+Lintian. The problem is that people can in theory create some really nasty
packages. Please keep the following in mind when writing a check:
=over 4
@@ -548,12 +548,12 @@ CVE-2009-4014).
Usually 3-arg open and the non-shell variant of system/exec are
enough. When you actually need a shell pipeline, consider using
L<Lintian::Command>. It also provides a I<safe_qx> command to assist
-with capturing stdout as alternative to `$cmd` (or qx/$cmd/).
+with capturing stdout as an alternative to `$cmd` (or qx/$cmd/).
=item * Do not trust field values.
This is especially true if you intend to use the value as part of a
-file name. Verify that field contains what you expect before you use
+file name. Verify that the field contains what you expect before you use
it.
=item * Use L<Lintian::Path> (or, failing that, is_ancestor_of)
@@ -571,7 +571,7 @@ You might be tempted to think that the following code is safe:
}
This is definitely unsafe if "$filename" contains at least one
-directory segment. So if in doubt, use
+directory segment. So, if in doubt, use
L<is_ancestor_of|Lintian::Util/is_ancestor_of(PARENTDIR, PATH)> to
verify that the requested file is indeed the file you think it is. A
better version of the above would be:
@@ -600,7 +600,7 @@ Of course, it is much easier to use the L<Lintian::Path> object
}
Here you can drop the " && $ufile->is_file" if you want to permit
-safe-symlinks.
+safe symlinks.
For more information on the is_ancestor_of check, see
diff --git a/doc/tutorial/Lintian/Tutorial/WritingTests.pod b/doc/tutorial/Lintian/Tutorial/WritingTests.pod
index 45c9ab6..eb1a145 100644
--- a/doc/tutorial/Lintian/Tutorial/WritingTests.pod
+++ b/doc/tutorial/Lintian/Tutorial/WritingTests.pod
@@ -6,8 +6,8 @@ Lintian::Tutorial::WritingTests -- Short tutorial on writing tests
=head1 SYNOPSIS
-This document attempts to be a short / quick tutorial to the lintian
-test suite from a test-writer perspective. As such, it will only
+This document attempts to be a short / quick tutorial to the Lintian
+test suite from a test-writer's perspective. As such, it will only
cover the standard type of tests (from the "tests" suite).
The guide will involve writing a test for the "deb/pkg-check" check,
@@ -18,26 +18,26 @@ For running tests, please see L<Lintian::Tutorial::TestSuite> instead.
=head1 DESCRIPTION
-The lintian test suite is divided into several parts. These are:
+The Lintian test suite is divided into several parts. These are:
=over 4
=item * scripts
Small (Perl) "prove" tests. These assert that code style, data files
-or/and self-contained code units (i.e. unit tests) work as intended.
-They are B<not> used for testing lintian tags.
+and/or self-contained code units (i.e. unit tests) work as intended.
+They are B<not> used for testing Lintian tags.
=item * changes / debs / source
-These suites are small test suites that tests some particular tags for
+These suites are small test suites that test some particular tags for
I<.changes>, I<.deb> or I<.dsc> files. Typically, you will find the
more exotic tags here, which require some special fiddling and cannot
be built by a "standard" dh7 + dpkg build.
=item * tests
-This suite is the standard test suite for testing lintian tags.
+This suite is the standard test suite for testing Lintian tags.
=back
@@ -46,10 +46,10 @@ With this in mind, let us move on to the scope.
=head2 Scope of the tutorial
The "tests" suite alone is fairly complex on its own. To keep things
-simple, the tutorial itself will limit itself to creating a "native"
+simple, the tutorial will limit itself to creating a "native"
package with no special requirements in the "tests" suite.
-In particular note that the tags I<must not> be I<pedantic> for this
+In particular, note that the tags I<must not> be I<pedantic> for this
to work. If you followed the check writing tutorial and made the tags
pedantic, please change them into "I", "W" or "E" tags.
@@ -57,11 +57,11 @@ Once the basics are covered, you should be better equipped to deal
with the other ("tag testing") suites or using other features of the
"tests" suite (e.g. pedantic tags).
-=head2 The design of the lintian test suite
+=head2 The design of the Lintian test suite
-The basic design of the Lintian test suite can basically be summed up
-to I<less is more>. The Debian build system is changing all the time
-(albeit, slowly) and some times it deprecates or breaks existing
+The basic design of the Lintian test suite can be summed up
+as I<less is more>. The Debian build system is changing all the time
+(albeit, slowly) and sometimes it deprecates or breaks existing
features.
With over 400 tests all featuring the same basic parts, the test suite
@@ -71,10 +71,10 @@ files to fill in the basic files (e.g. "debian/control" and
"debian/changelog").
This means that when a new standards-version comes along, debhelper
-deprecates a feature or (more likely) lintian adds a new tag, the
+deprecates a feature or (more likely) Lintian adds a new tag, the
majority of the tests can quickly be adapted with only a minor effort.
-Since pedantic tags tends to require additional effort to avoid, most
+Since pedantic tags tend to require additional effort to avoid, most
Lintian tests do B<not> run with pedantic tags enabled.
=head2 The basics of a "native" package in the "tests" suite
@@ -87,7 +87,7 @@ in I<< t/tests/<test-name> >>.
This is the test description file. It is a deb822 file (i.e. same
syntax as I<debian/control>), which contains a number of fields.
-Lets start with the following template:
+Let's start with the following template:
Testname: pkg-deb-check-general
Sequence: 6000
@@ -118,7 +118,7 @@ Please keep the following conventions in mind:
=item The Testname should be "<check-name>-<test-name>"
Note that regular Lintian checks do I<not> have a "/", so the naming
-convention work slightly better there.
+convention works slightly better there.
=item The Sequence should always be 6000 for tests checking tags.
@@ -194,7 +194,7 @@ run by using:
$ t/runtests --dump-logs t debian/test-out pkg-deb-check-general
-Although, it will not emit the correct tags unless pkg/deb-check is
+However, it will not emit the correct tags unless pkg/deb-check is
part of the debian/main lintian profile. If your check is a part of a
different profile, add the "Profile: <name>" field to the "desc" file.
@@ -207,7 +207,7 @@ resources that may be useful to your future test writing work.
Basically, the tag-testing test cases all involve building a package
and running lintian on the result. The "tests" suite does a full
-build with dpkg-buildpackage, the other suites "hand-crafts" only the
+build with dpkg-buildpackage, the other suites "hand-craft" only the
type of artifacts they are named after (e.g. "source" produces only
source packages).
@@ -334,7 +334,7 @@ artifact.
=item *
-Else, copy I<< <test-dir>/<test-name>.changes.in >> into the build dir
+Otherwise, copy I<< <test-dir>/<test-name>.changes.in >> into the build dir
and use it as a template to create I<< <build-dir>/<test-name>.changes
>>. The result is then used as the artifact to test.
@@ -367,7 +367,7 @@ syntax as I<debian/control>), which contains a number of fields.
This file contains the "expected" output of lintian.
-This is generally sorted, though a few tests relies on the order of
+This is generally sorted, though a few tests rely on the order of
the output. This can be controlled via the "Sort" field in the "desc"
file.
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/lintian/lintian.git
Reply to: