Re: Request for Review: APT manpages

[David Kalnischkies <kalnischkies+debian@gmail.com>]

On Wed, May 30, 2012 at 4:12 PM, Justin B Rye <jbr@edlug.org.uk> wrote:
> Last in the list (before I start backtracking), sources.list.5.xml.
> This is another one where I could do with some feedback, but I attach
> a patch anyway.
>
> [...]
>>  <refnamediv>
>>     <refname>sources.list</refname>
>>     <refpurpose>Package resource list for APT</refpurpose>
>>  </refnamediv>
>
> "Package resource list" is a strange name for it; it sounds as if
> it's talking about a catalogue of icons and so on used by the package
> apt.  Eventually, reading between the lines, I deduce that the APT
> developers think of each line in a sources.list file as a "resource",
> and that they're "package resources" because you can get packages from
> them (among other things).  But since this jargon is never explained
> it doesn't belong in an apropos summary.
>
> (It sounds like *useful* jargon, since it offers an alternative to the
> ambiguous word "source", but realistically we're stuck with that - at
> least until the day we rename this file "resources.conf".)
>
> I would suggest:
>
>      <refpurpose>Distribution definitions for APT</refpurpose>

Mhh, this doesn't tell me much. Distribution sounds like I am
defining what Debian, Ubuntu or $whatever will be for APT, but
I am just defining where I want to get stuff from.

Maybe
<refpurpose>List of sources to acquire package information from</refpurpose>
?


>>  <refsect1><title>Description</title>
>>    <para>The package resource list is used to locate archives of the package
>>    distribution system in use on the system.
>
> Where does "in use on the system" fit in?  Is it trying to say "for
> this machine's APT policy"?
>
>>                                              At this time, this manual page
>>    documents only the packaging system used by the Debian GNU/Linux system.
>
> Lies!  It doesn't document the packaging system, and what it does
> document applies to more than just the GNU/Linux ports.  I imagine it
> means to say "only Debian, not derivatives".  But does the "at this
> time" imply we're hoping for patches documenting Ubuntu?
>
>>    This control file is <filename>/etc/apt/sources.list</filename>.</para>
>
> *Which* control file is sources.list?
>
> Tentative rewrite:
>
>    APT uses the resource lines configured in
>    <filename>/etc/apt/sources.list</filename> to locate software archives
>    for use by the package management system. This manual page documents how
>    it works (currently from a Debian-specific viewpoint only).

In theory you could easily add additional distribution systems to APT
(in the sense of dpkg, rpm, …). In practice this is… lets say unusual,
as the following line indicates by saying it only knows about Debian systems,
which includes also all derivatives as they us the same distribution system
(aka are all compatible with the types deb and deb-src)

I am tempted to just remove the entire paragraph as completely unfitted to
start a useful description with and move the only useful information
(the path to the file in question) to the next paragraph.


>>    <para>The source list is designed to support any number of active sources and a
>>    variety of source media. The file lists one source per line, with the
>>    most preferred source listed first. The format of each line is:
>>    <literal>type uri args</literal> The first item, <literal>type</literal>
>                                     ^.                                     ^,
> Punctuation shortage.  And while I don't 100% understand this XML
> scheme, shouldn't these be replaceables rather than literals?  Or
> since it would also be helpful if the format was separated out
> into a line on its own, maybe the format should be a
> <literallayout> (and then the quotes from it can be <literal>s).
>
>>    determines the format for <literal>args</literal>. <literal>uri</literal> is
>>    a Universal Resource Identifier
>>    (URI), which is a superset of the more specific and well-known Universal
>>    Resource Locator, or URL. The rest of the line can be marked as a comment
>>    by using a #.</para>
>>  </refsect1>
>
> Now, that's a literal - <literal>#</literal>.  But do we need to
> say this?  It's normally easier to put comments between the items,
> and this text never mentions that blank lines and lines consisting
> only of comments are legal.  I think we should eliminate this
> sentence in favour of something like:
>
>     <para>
>      The source list is designed to support any number of active sources and
>      a variety of source media. The file lists one source per line, with the
>      most preferred source listed first. The format of each line is:
>             <literallayout>type uri args</literallayout>
>      The first item, <literal>type</literal>, determines the format for
>      <literal>args</literal>. <literal>uri</literal> is a Universal Resource
>      Identifier (URI), which is a superset of the more specific and well-known
>      Universal Resource Locator, or URL.
>     </para>
>     <para>
>      Individual entries cannot be continued onto a following line. Empty lines
>      are ignored, and a <literal>#</literal> character anywhere on a line marks
>      the remainder of that line as a comment.
>     </para>
>    </refsect1>

Removing the first paragraph, stripping details from the second and copying
verbatim your second paragraph lets me end up with:

   <para>
   The source list <filename>/etc/apt/sources.list</filename> is
designed to support
   any number of active sources and a variety of source media. The
file lists one
   source per line, with the most preferred source listed first. The
information available
   from the configured sources is acquired by <command>apt-get update</command>
   (or by an equivalent command from another APT front-end).
   </para>
   <para>
   Each line specifying a source starts with type (e.g.
<literal>deb-src</literal>)
   followed by options and arguments for this type.
   Individual entries cannot be continued onto a following line. Empty lines
   are ignored, and a <literal>#</literal> character anywhere on a line marks
   the remainder of that line as a comment.
   </para>

I stripped the details of the line format as there are patches out there which
do not really use an URI (beside that i don't want to define what an URI is as
this is not really important) and is way better described later for the
supported types anyway.



>>    If <literal>distribution</literal> does not specify an exact path, at least
>>    one <literal>component</literal> must be present.</para>
>>
>>    <para><literal>distribution</literal> may also contain a variable,
>>    <literal>$(ARCH)</literal>
>>    which expands to the Debian architecture (i386, m68k, powerpc, ...)
>
> It's possible that native-anglophone C-coders use this ", ...)"
> syntax, but I haven't seen it in any text written by non-techies.
> And m68k is cobwebby.
>
>     which expands to the Debian architecture (such as amd64 or mips)

In defense, it is more of a math-thing than limited to c-coders:
"The natural numbers are 1, 2, 3, 4, 5, …"

(I used "amd64 or armel" just because the later has more
 media coverage than mips currently)


>>    <para><literal>options</literal> is always optional and needs to be surounded by
>>    square brackets. It can consist of multiple settings in the form
>
> "Settings"... can we say "settings"?  "Configuration items" would be
> a bit clunky...

I like "settings" here specifically to avoid that people could come to
the conclusion that they could write usual "configuration items" here.

But i am not really sure what you mean here.

(and for the record: I added another "r" to surounded)


>>     <varlistentry><term>ftp</term>
>>     <listitem><para>
>>     The ftp scheme specifies an FTP server for the archive. APT's FTP behavior
>>     is highly configurable; for more information see the
>>     &apt-conf; manual page. Please note that a ftp proxy can be specified
>>     by using the <envar>ftp_proxy</envar> environment variable. It is possible
>>     to specify a http proxy (http proxy servers often understand ftp urls)
>>     using this method and ONLY this method. ftp proxies using http specified in
>>     the configuration file will be ignored.</para></listitem>
>>     </varlistentry>
>
> Where this is talking about the protocols rather than the keywords
> they should be capitalised; and so should "URLs", and it's "an
> {FTP,HTTP} proxy", and the shoutiness should be replaced by
> <emphasis> tags.
>
> But more importantly, I don't understand what this stuff about HTTP
> proxies is trying to say (or what the ONLY is intended to restrict),
> so I can't fix this bit.  Can anyone explain it more clearly, please?

(I had to look this up)
Imagine you want to use an FTP server and between you and this server
is a proxy. Usually a proxy speaks the same protocol as the server it
speaks to (in this case it should be FTP).

Now imagine your network has only an HTTP proxy, but you still want to
use an FTP server - but you know that this proxy supports talking to the
FTP server. In that case you can specify this HTTP proxy in the ftp_proxy
environment variable and APT will detect that it has to use it's http method
to talk to the HTTP proxy instead of using FTP as the proxy will not
understand this -- but this auto-detection only works if you have used
ftp_proxy, if you have set it in Acquire::ftp::proxy it will not work.

In short: Instead of "method" it reads "environment variable" now.
Not that much better, but should be at least more understandable.


Best regards

David Kalnischkies