summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/writing.docbook74
1 files changed, 35 insertions, 39 deletions
diff --git a/doc/writing.docbook b/doc/writing.docbook
index afe0b8b..e50025e 100644
--- a/doc/writing.docbook
+++ b/doc/writing.docbook
@@ -2,9 +2,9 @@
<title>Writing Patchsets</title>
<para>
-This chapter will try to cover all the needed knowledge to write a new
-patchset for autoepatch, as well as to maintain the ones already
-present in the distribution.
+This chapter will try to prove the necessary information to write a new patchset
+for autoepatch, as well as to maintain the ones already present in the
+distribution.
</para>
<sect1 id="writingthescript">
@@ -20,10 +20,9 @@ or not if the patching is not completed as intended.
</para>
<para>
-To facilitate writing new patchsets, the names of the functions that
-are defined into the patchset's script are standardised, so that the
-parameters they get and the result they echo out can be relied upon
-and used by autoepatch safely.
+To facilitate writing new patchsets, the names of the functions that are defined
+into the patchset's script are standardised, so that the parameters they get and
+the result they echo out can be relied upon and used by autoepatch safely.
</para>
<variablelist>
@@ -32,20 +31,19 @@ and used by autoepatch safely.
<listitem>
<para>
- This function is the basis to start writing a new patchset, it is
- used to identify where the patches are going to be applied. The
- results are simply returned on the standard output, one per
- line. This function is supposed to check if the patch should or
- should not be applied over a file or a directory, by grepping, if
- needed, for key phrases that would show if the patch is needed or
- not.
+ This function is the basis to start writing a new patchset, it is used to
+ identify where the patches are going to be applied. The results are simply
+ returned on the standard output, one per line. This function is supposed to
+ check if the patch should or should not be applied over a file or a
+ directory, by grepping (if needed) for key phrases that would show if the
+ patch is needed or not.
</para>
<para>
- This function is not supposed to check for the applicability of
- the patch on the current system. The reason for this is that it's
- way simpler to test all patchsets every time, so that if errors
- are added to the patchset, they can be fixed immediately.
+ This function is not supposed to check for the applicability of the patch on
+ the current system. The reason for this is that it's simpler to test all
+ patchsets every time, so that if errors are added to the patchset, they can
+ be fixed immediately.
</para>
</listitem>
@@ -56,21 +54,21 @@ and used by autoepatch safely.
<listitem>
<para>
- This function is called in the case the patchset failed to apply
- entirely; it is supposed to return 0 (truth value) if the patch is
- important, and autoepatch has to fail if it's not applied (and
- thus stop the merge process), or 1 (untruth value) if the patch is
- optional and/or it's not of first importance for the current setup.
+ This function is called in the case the patchset failed to apply entirely;
+ it is supposed to return 0 (true) if the patch is important, and autoepatch
+ has to fail if it's not applied (and thus stop the merge process), or 1
+ (false) if the patch is optional and/or it's not of primary importance for
+ the current setup.
</para>
<para>
- The reason to have this function is that some patches might be only
- needed on some targets (for instance Gentoo/FreeBSD, or uClibc or
- Darwin systems), or only in some situations (newer autotools,
- newer glibc or linux-headers), and for the rest of the cases, it's
- just an assurance and a testing purpose to apply the patch on
- every use. So the failure on autoepatch, when a patchset fails to
- apply, is entirely decided by the value returned by this function.
+ The reason to have this function is that some patches might be only needed
+ on some targets (for instance Gentoo/FreeBSD, or uClibc or Darwin systems),
+ or only in some situations (newer autotools, newer glibc or linux-headers).
+ For the rest of the possible cases, it's just additional assurance (and
+ another testing method) to apply the patch on every use. So the failure on
+ autoepatch, when a patchset fails to apply, is entirely decided by the value
+ returned by this function.
</para>
</listitem>
</varlistentry>
@@ -80,18 +78,16 @@ and used by autoepatch safely.
<listitem>
<para>
- This function is the core of those patchsets without actual patch
- files to apply. It is called once per target to execute some
- commands on the given parameter. It is useful to run a sed
- command, or to parse the file in some complex way, and produce
- either a new output or changing the target file.
+ This function is the core of those patchsets without actual patch files to
+ apply. It is called once per target to execute some commands on the given
+ parameter. It is useful to run a sed command, or to parse the file in some
+ complex way and produce either a new output or to change the target file.
</para>
<para>
- Another likely usage of this ind of patchsets is to operate on a
- given directory, where you have to change the files according to
- some other file, for example if you're gonna change some gettext
- support.
+ Another likely usage of this kind of patchset is to operate on a given
+ directory, where you have to change the files according to some other file,
+ for example if you're going to change some gettext support.
</para>
</listitem>