Bug#115517: -- apt_preferences man page update draft #2
Thomas Hood <jdthood@yahoo.co.uk> wrote:
> Hi. I append a new SGML file. I have based this second
> SGML draft on my first TROFF draft, but I have made further
> changes. Please read through and report any mistakes to
> me and to 115517@bugs.debian.org.
Thomas, this is a huge improvement. Thanks!
I've attached a diff that fixes one spelling error and adjusts some
awkward text. The editors I've worked with forbid the use of i.e. and
e.g., so I've replaced those as well. I did not fill to make it easier
to see exactly what I changed in the diffs, but you should probably do
so where necessary. I've also inserted questions in block letters as
you did where something isn't clear to me.
Also, don't jump back and forth between the terms origin and source.
It's very confusing. Since the parameter is "o", let's stick with
origin and nuke references to source.
The major problem with this document is the organization. The details
are discussed first with no context. Even after reading the whole
document, it's still hard to figure out how the text fits in. I've got
an idea to clean this up.
The Description ends with the following text:
The file consists of a number of records formed like those in dpkg
status file: blocks of text (stanzas) separated by blank lines; each
line of text consisting of a tag followed by a colon and a string.
So far so good. The rest of the man page should describe those tags
and strings. I would therefore suggest Changing the following two
sections:
<RefSect1><Title>Versioning</>
<RefSect1><Title>Version Selection Policy</>
to an alphabetical list of tags (I'm guessing on the SGML):
<RefSect1><Title>Tags</>
<para>The tags that can be used in the preferences file as
described in this section.
<RefSect2><Title>Package</>
<RefSect2><Title>Pin</>
[Describe the syntax generally, then introduce the keys a, c, v,
o. Create a subsection for each key. The text that is found at the
beginning of the current Versioning section is limited to the "v"
key and should be moved to that subsection, while the "selection
by release" and "selection by source" should be moved to their
respective subsections ("a" and "o"?)]
<RefSect2><Title>Pin-Priority</>
[Describe the syntax generally, and then include the text that is
currently in Version Selection Policy.
I held off on doing this because I thought you'd prefer to have a go,
because the diffs would be so large as to be meaningless since you've
probably made many changes since, and because I raised more questions
than I answered ;-). I suppose I'd be willing to give the reorg a go
if you sent me the current version.
--- /tmp/apt_preferences.orig 2002-10-17 17:03:48.000000000 -0700
+++ /tmp/apt_preferences 2002-10-17 18:10:52.000000000 -0700
@@ -23,7 +23,7 @@
<RefSect1><Title>Description</>
<para>
The APT preferences file <filename>/etc/apt/preferences</> controls
- various aspects of the APT system. It is meant to be manipulable
+ various aspects of the APT system. It is meant to be manipulated
either by user or by software. The file consists of a number of
records formed like those in dpkg status file: blocks of text
(stanzas) separated by blank lines; each line of text consisting
@@ -37,10 +37,10 @@
can be made in a number of ways: by version, by release or by source.
<para>
Selection by version involves matching the package version identifier.
- This can be done either exactly (e.g., <literal/2.1.3/) or by prefix
- pattern (e.g., <literal/2.1*/). Such a pattern can be used, e.g., to ignore
- the Debian version (i.e., the latter part of the version identifier
- beginning with the hyphen). When several version identifiers match the
+ This can be done either exactly as in <literal/2.1.3/ or by prefix
+ pattern such as <literal/2.1*/. For example, such a pattern can be used to ignore
+ the Debian version in the latter part of the version identifier
+ beginning with the hyphen[WHAT HYPHEN? GIVE EXAMPLE OF THE ENTIRE IDENTIFIER AND THE PATTERN.]). When several version identifiers match the
prefix pattern, the latest version will always be selected.
<para>
Version selection is used in many different parts of APT, not just in the
@@ -52,6 +52,7 @@
each of which consists of a one-letter key, the equals sign, and a string.
Some examples:
<informalexample><programlisting>
+[HOW IS SELECTION BY RELEASE DIFFERENT THAN SELECTION BY VERSION? THIS EXAMPLE FOR RELEASE SELECTION SEEMS TO SHOW A SELECTION BY VERSION (v=2.1*).]
v=2.1*,o=Debian,c=main
l=Debian
a=stable
@@ -61,27 +62,27 @@
<VariableList>
<VarListEntry><term>a=Archive</term>
<ListItem><Para>
- This specifies the archive, e.g., <literal/stable/ or <literal/unstable/.
+ This specifies the archive, for example, <literal/stable/ or <literal/unstable/.
The archive <literal/now/ consists of all the packages that are currently
installed.
</VarListEntry>
<VarListEntry><term>c=Component</term>
<ListItem><Para>
- This specifies the component of the archive, e.g., <literal/main/ or
+ This specifies the component of the archive, for example, <literal/main/ or
<literal/contrib/. This specifier may be omitted if the archive
has no components.
</VarListEntry>
<VarListEntry><term>v=Version</term>
<ListItem><Para>
- This specifies the release level of the archive, i.e., the release version,
- e.g., <literal/3.0/ or <literal/2.1r2/.
+ This specifies the release level or version of the archive,
+ for example, <literal/3.0/ or <literal/2.1r2/.
</VarListEntry>
<VarListEntry><term>o=Origin</term>
<ListItem><Para>
- This specifies the origin of the archive. In the case of Debian the
+ This specifies the origin of the archive. It refers to the organization that has published and is responsible for the archive [CORRECT? ALSO, TIE IN TO "SOURCE".]. In the case of Debian the
origin is <literal/Debian/.
</VarListEntry>
@@ -96,11 +97,11 @@
interpreted as a shorthand specification. If the first character of the
shorthand specification is a digit then it is considered to be a release
version specifier; otherwise it is considered to be an archive specifier.
- Shorthand specifications are especially useful on the command line.
+ Shorthand specifications are especially useful on the command line. [EXAMPLE]
<para>
The final selection method is by source. This is simply the name of the
site where the package files were obtained. The null string is used for
- file URIs.
+ file URIs.[I STILL HAVE NO CLUE WHAT THIS IS. WHAT DO I TYPE? WHERE? WHAT EXACTLY IS THE "NAME OF THE SITE?" WHY IS THE NULL STRING USED FOR FILE URIs? DOES THAT MEAN THAT THE SOFTWARE REPLACES YOUR URIs WITH THE NULL STRING, OR DO YOU USE A NULL STRING AND THE SOFTWARE GUESSES THE URI?
</RefSect1>
<RefSect1><Title>Version Selection Policy</>
@@ -162,7 +163,7 @@
Assigning a priority less than 100 to a pin will prevent APT from
installing that version unless it is the only version available.
<para>
- Thus, e.g., a method for using &apt-get to track the <literal/stable/
+ Thus, a method for using &apt-get to track the <literal/stable/
archive even though one includes sources for the <literal/testing/
archive in <filename>/etc/apt/sources.list</> is to assign a priority
to <literal/stable/ versions that is higher than that assigned to
@@ -180,7 +181,7 @@
The first line specifies the package; the second specifies the pin version;
the last specifies the priority of this pin. The first word of the pin
specification may be <literal/version/, <literal/release/ or <literal/origin/
- (i.e., "source"). The remainder of the field is as described in the
+ ("source"). The remainder of the field is as described in the
Versioning section above.
<para>
Pinning all the packages listed in a particular <filename/Packages/ file
@@ -191,7 +192,7 @@
Pin-Priority: 998
</programlisting></informalexample>
The first word of the default pin specification may be <literal/release/
- or <literal/origin/ (i.e., source). If more than one entry of this kind
+ or <literal/origin/ (source). If more than one entry of this kind
appears in the preferences file, only the first one that applies will be
used. This kind of entry can be overridden by an entry that pins a
particular package. [IS THIS TRUE? CLARIFICATION NEEDED HERE.]
@@ -205,7 +206,7 @@
<RefSect2><title>Interesting Effects</>
<para>
- A downgrade is not preformed unless the version to install has
+ A downgrade is not performed unless the version to install has
priority greater than 1000. Note that it is therefore possible
that a later, lower priority version will be selected in preference
to an earlier, higher (but not higher than 1000) priority version.
@@ -226,7 +227,7 @@
<RefSect1><Title>Examples</>
<para>
The following preferences file will make APT track stable;
- i.e., it will cause apt-get always to upgrade to the latest
+ it will cause apt-get always to upgrade to the latest
stable version when its <option/install/ or <option/upgrade/
or <option/dist-upgrade command is used).
Packages may be upgraded individually to their testing versions,
@@ -244,6 +245,7 @@
Package: *
Pin: release o=Debian
Pin-Priority: -10
+ [WHAT THE HECK DOES THIS STANZA MEAN?]
</programlisting></informalexample>
<para>
The following preferences file will make APT track testing.
--
Bill Wohler <wohler@newt.com> http://www.newt.com/wohler/ GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and mh-e. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.
Reply to: