Paul Gevers wrote: >>> we mean by "APT source-list files", if only by pointing at >>> sources.list(5). >> >> I wanted to link to that man page as well, so let's find a place. I'm >> nearly of to bed now, so if you find a good spot before I do tomorrow, >> don't hesitate to mail. > > I have added a link to the manpages (3 places), but I am not totally > happy with how it reads. > > What do you think?
I don't know whether we're "allowed" to link to manpages.d.o here; the only other place I see a man page pointer is in whats-new.dbk, which just says See the <systemitem role="package">cryptsetup</systemitem> manpage On the other hand if we *are* going to point at manpages.d.o there are probably lots of other places where it might help. Reading through the patch: > From 710a6ac851e47e6952087aec89a5b7e8397cf9be Mon Sep 17 00:00:00 2001 > From: Paul Gevers <elb...@debian.org> > Date: Sun, 24 Mar 2019 20:31:48 +0100 > Subject: [PATCH] Generalize use of APT source-list files > > Closes: #864017 > --- > en/old-stuff.dbk | 36 ++++++++++---------- > en/upgrading.dbk | 85 +++++++++++++++++++++++++----------------------- > 2 files changed, 63 insertions(+), 58 deletions(-) > > diff --git a/en/old-stuff.dbk b/en/old-stuff.dbk > index 0a53d737..ec26ca91 100644 > --- a/en/old-stuff.dbk > +++ b/en/old-stuff.dbk > @@ -27,14 +27,14 @@ upgraded to the latest &oldreleasename; point release. > </section> > > <section id="old-sources"> > -<title>Checking your sources list</title> > +<title>Checking your APT source-list files</title> > <para> > -If any of the lines in your <filename>/etc/apt/sources.list</filename> > -refer to <quote><literal>stable</literal></quote>, it effectively > -points to &releasename; already. This might not be what you want if > -you are not ready yet for the upgrade. If you have already run > -<command>apt update</command>, you can still get back without > -problems by following the procedure below. > + If any of the lines in your APT source-list files (see <ulink > + > url="https://manpages.debian.org/&releasename;/apt/sources.list.5.en.html">sources.list(5)</ulink>) > + refer to <quote><literal>stable</literal></quote>, it effectively points to > + &releasename; already. This might not be what you want if you are not ready > + yet for the upgrade. If you have already run <command>apt > update</command>, > + you can still get back without problems by following the procedure below. > </para> Instead of trying to cram this into parentheses we should explain it more fully the first time we mention it: <para> The main configuration file that APT uses to decide what sources it should download packages from is <filename>/etc/apt/sources.list</filename>, but it can also use files in the <filename>/etc/apt/sources.list.d/</filename> directory - for details see <ulink url="https://manpages.debian.org/&releasename;/apt/sources.list.5.html">sources.list(5)</ulink>. If your system is using multiple source-list files then you will need to ensure they stay consistent. </para> <para> If any of your APT source-list files contain references to <quote><literal>stable</literal></quote>, this is effectively pointing to &releasename; already. This might not be what you want if you are not yet ready for the upgrade. If you have already run <command>apt update</command>, you can still get back without problems by following the procedure below. </para> Note that I've subtracted the ".en" component from the manpage URL; but it's possible that the URL should be defined in release-notes.ent instead. Oh, wait, I hadn't realised that old-stuff.dbk is only alphabetically the first section; it gets turned into an appendix. So instead the paragraph giving the full explanation should go in upgrading.dbk, and then this paragraph in old-stuff.dbk should just refer back to that: If any of your APT source-list files (see <xref linkend=???"/>) contain references to <quote><literal>stable</literal></quote>, this is effectively pointing to > <para> > If you have also already installed packages from &releasename;, there > probably > @@ -43,28 +43,28 @@ that case you will have to decide for yourself whether > you want to continue or > not. It is possible to downgrade packages, but that is not covered here. > </para> > <para> > -Open the file <filename>/etc/apt/sources.list</filename> with your favorite > + Open the relevant APT source-list file, e.g. > + <filename>/etc/apt/sources.list</filename>, with your favorite > editor (as <literal>root</literal>) and check all lines beginning with It might be a good idea to rearrange this sentence: As root, open the relevant APT source-list file (such as <filename>/etc/apt/sources.list</filename>) with your favorite editor, and check all lines beginning with > <literal>deb http:</literal>, <literal>deb https:</literal>, > -<literal>deb tor+http:</literal>, <literal>deb tor+https:</literal> or > -<literal>deb ftp:</literal> for a reference to > +<literal>deb tor+http:</literal>, <literal>deb tor+https:</literal>, > +<literal>URIs: http:</literal>, > +<literal>URIs: https:</literal>, > +<literal>URIs: tor+http:</literal> or <literal>URIs: tor+https:</literal> > +for a reference to > <quote><literal>stable</literal></quote>. If you find any, change > <literal>stable</literal> to <literal>&oldreleasename;</literal>. > </para> > -<note> > - <para> > - Lines in sources.list starting with <quote>deb ftp:</quote> and pointing > to debian.org > - addresses should be changed into <quote>deb http:</quote> lines. > - </para> > -</note> > <para> > -If you have any lines starting with <literal>deb file:</literal>, you will > have > + If you have any lines starting with <literal>deb file:</literal> or > + <literal>URIs: file:</literal>, you will have > to check for yourself if the location they refer to contains an > &oldreleasename; or a &releasename; archive. > </para> I've just noticed: "contains AN &oldreleasename;"? There has only been one releasename beginning with a vowel, and that was Debian 4.0 "Etch"! (The fact that this is an issue is one of the reasons I'm not keen on these entities.) [...] > diff --git a/en/upgrading.dbk b/en/upgrading.dbk > index a22924f3..54a6eb9f 100644 > --- a/en/upgrading.dbk > +++ b/en/upgrading.dbk > @@ -290,12 +290,14 @@ $ apt-forktracer | sort > </para> > <para> > Because of this you should review if there are any pending actions in > the > - package manager <command>aptitude</command>. If a package is > scheduled for > - removal or update in the package manager, it might negatively impact > the > - upgrade procedure. Note that correcting this is only possible if your > - <filename>sources.list</filename> still points to > <emphasis>&oldreleasename;</emphasis> > - and not to <emphasis>stable</emphasis> or > <emphasis>&releasename;</emphasis>; see <xref > - linkend="old-sources"/>. > + package manager <command>aptitude</command>. If a package is scheduled > + for removal or update in the package manager, it might negatively > impact > + the upgrade procedure. Note that correcting this is only possible if > + your APT source-list files, i.e. the files described in the <ulink > + > url="https://manpages.debian.org/&releasename;/apt/sources.list.5.en.html">sources.list(5)</ulink> > + manpage, still point to <emphasis>&oldreleasename;</emphasis> and not > to > + <emphasis>stable</emphasis> or <emphasis>&releasename;</emphasis>; see > + <xref linkend="old-sources"/>. > </para> Okay, *this* chapter is the first one to mention APT source-list files, and therefore the most natural chapter to put an explanation in. Unfortunately, this paragraph would be a really awkward place to have to do it. One possible solution would be to reverse the order of two subsections: move one or more of the later paragraphs to be before this one, and make sure the definition is given there instead. So this becomes just: <para> Because of this you should review if there are any pending actions in the package manager <command>aptitude</command>. If a package is scheduled for removal or update in the package manager, it might negatively impact the upgrade procedure. Note that correcting this is only possible if your APT source-list files (see above) still point to <emphasis>&oldreleasename;</emphasis> and not to <emphasis>stable</emphasis> or <emphasis>&releasename;</emphasis>; see <xref linkend="old-sources"/>. </para> Then we move... probably *both* "proposed-updates" and "unofficial-sources" to be before "review-actions", and insert the longwinded definition of "APT source-list files" there. Or maybe they should both be subsections of one section, with an extra introductory paragraph in common... ...sorry, the more I look at it the more I think we should rip it all out and start again. *Everything* in section 4.2 is about getting the package manager straightened out; so the stuff at the start of 4.3 is in the wrong place. > <section id="upgrade-process"> > - <title>Preparing sources for APT</title> > + <title>Preparing APT source-list files</title> > <para> > Before starting the upgrade you must set up <systemitem > - role="package">apt</systemitem>'s configuration file for package lists, > - <filename>/etc/apt/sources.list</filename>. > + role="package">apt</systemitem>'s configuration file(s) for package > lists, > + <filename>/etc/apt/sources.list</filename> and files under > + <filename>/etc/apt/sources.list.d/</filename> (see <ulink > + > url="https://manpages.debian.org/&releasename;/apt/sources.list.5.en.html">sources.list(5)</ulink>). > </para> This would make a plausible place to put the expansion if it hasn't already been done, but I'm sorry, I'm losing track... > <para> > <systemitem role="package">apt</systemitem> will consider all packages > that can > - be found via any <quote><literal>deb</literal></quote> line, and install > the package with the > - highest version number, giving priority to the first line in the > - file (thus where you have multiple mirror locations, you'd typically > first name a local > + be found via any configured archive, and install the package with the > + highest version number, giving priority to the first entry in the > + files (thus where you have multiple mirror locations, you'd typically > first name a local > hard disk, then <acronym>CD-ROM</acronym>s, and then remote mirrors). > </para> > > @@ -528,16 +532,16 @@ $ apt-forktracer | sort > </para> > <para> > Again, after adding your new sources, disable the previously existing > - <quote><literal>deb</literal></quote> lines. > + archive entries. > </para> > </section> > > <section id="localmirror"> > <title>Adding APT sources for a local mirror</title> > <para> > - Instead of using HTTP package mirrors, you may wish to modify > - <filename>/etc/apt/sources.list</filename> to use a mirror on a local > disk > - (possibly mounted over <acronym>NFS</acronym>). > + Instead of using HTTP package mirrors, you may wish to modify the APT > + source-list files to use a mirror on a local disk (possibly mounted > over > + <acronym>NFS</acronym>). > </para> Or for improved futureproofing, "Instead of remote package mirrors". Sorry, I've run out of coffee! I'll have another look at this tomorrow. -- JBR with qualifications in linguistics, experience as a Debian sysadmin, and probably no clue about this particular package