Proofreading: fixing and adding xrefs and ids for section or sidebar

en-US/01_the-debian-project.xml

@@ -1339,7 +1339,7 @@
 	  problems concerning the mailing lists.</para>
         </sidebar>
 
-        <sidebar>
+        <sidebar id="sidebar.fusionforge">
           <title><emphasis>TOOL</emphasis> FusionForge, the Swiss Army Knife of collaborative development</title>
           <indexterm><primary><literal>alioth</literal></primary></indexterm>
           <indexterm><primary>FusionForge</primary></indexterm>
@@ -1457,7 +1457,7 @@
 	frequently programmed the corresponding tools themselves). This is
 	the case of the bug tracking system (BTS), the package tracker,
 	<literal>alioth.debian.org</literal> (FusionForge
-	server, see sidebar), the services available on
+	server, see sidebar <xref linkend="sidebar.fusionforge"/>), the services available on
 	<literal>qa.debian.org</literal>,
 	<literal>lintian.debian.org</literal>,
 	<literal>buildd.debian.org</literal>,

en-US/04_installation.xml

@@ -286,7 +286,10 @@
 	This configuration is often called “dual boot”, and the Debian
 	installation system can set it up. This is done during the hard
 	drive partitioning stage of installation and while setting up the
-	bootloader (see the sidebars in those sections).</para>
+	bootloader (see the sidebars <xref linkend="sidebar.shrinking-partition"/>
+	in <xref linkend="sect.manual-partitioning"/>
+	and <xref linkend="sidebar.bootloader-dual-boot"/>
+	in <xref linkend="sect.installing-grub"/>).</para>
 
 	<para>If you already have a working Windows system, you can even
 	avoid using a CD-ROM; Debian offers a Windows program that
@@ -765,15 +768,15 @@
           </mediaobject>
         </figure>
       </section>
-      <section>
+      <section id="sect.manual-partitioning">
         <title>Manual Partitioning</title>
         <indexterm><primary>partitioning</primary><secondary>manual partitioning</secondary></indexterm>
 
 	<para>Manual partitioning allows greater flexibility, allowing the
 	user to choose the purpose and size of each partition. Furthermore,
 	this mode is unavoidable if you wish to use software RAID.</para>
 
-        <sidebar>
+        <sidebar id="sidebar.shrinking-partition">
           <title><emphasis>IN PRACTICE</emphasis> Shrinking a Windows partition.</title>
           <indexterm><primary>resize a partition</primary></indexterm>
           <indexterm><primary>shrink a partition</primary></indexterm>
@@ -804,7 +807,7 @@
 	a new partition. You can also do this with guided partitioning,
 	which is an interesting solution for a disk that already contains
 	another operating system, but which you may wish to partition for
-	Linux in a standard manner. See the previous section for more
+	Linux in a standard manner. See the <xref linkend="sect.install-autopartman-mode"/> for more
 	details on guided partitioning.</para>
 
         <sidebar>
@@ -979,7 +982,7 @@
 	meta-information that indicates the encryption algorithms
 	used).</para>
 
-        <sidebar>
+        <sidebar id="sidebar.encrypted-swap-partition">
           <title><emphasis>SECURITY</emphasis> Encrypted swap partition</title>
 
 	  <para>When an encrypted partition is used, the encryption key is
@@ -1016,7 +1019,7 @@
 	any other partition. In most cases, this partition is used as a
 	physical volume for LVM so as to protect several partitions (LVM
 	logical volumes) with the same encryption key, including the swap
-	partition (see sidebar).</para>
+	partition (see sidebar <xref linkend="sidebar.encrypted-swap-partition"/>).</para>
       </section>
     </section>
     <section>
@@ -1152,7 +1155,7 @@
         </mediaobject>
       </figure>
     </section>
-    <section>
+    <section id="sect.installing-grub">
       <title>Installing the GRUB Bootloader</title>
       <indexterm><primary>loader</primary><secondary>bootloader</secondary></indexterm>
       <indexterm><primary>bootloader</primary></indexterm>
@@ -1163,7 +1166,7 @@
       often offers a menu that allows the user to choose the kernel to load
       and/or the operating system to boot.</para>
 
-      <sidebar>
+      <sidebar id="sidebar.bootloader-dual-boot">
         <title><emphasis>BEWARE</emphasis> Bootloader and dual boot</title>
         <indexterm><primary>dual boot</primary></indexterm>
 

en-US/05_packaging-system.xml

@@ -658,7 +658,7 @@ SHA256: 371a559ce741394b59dbc6460470a9399be5245356a9183bbeea0f89ecaabb03</comput
         </sidebar>
       </section>
     </section>
-    <section>
+    <section id="sect.configuration-scripts">
       <title>Configuration Scripts</title>
       <indexterm><primary><filename>postinst</filename></primary></indexterm>
       <indexterm><primary><filename>preinst</filename></primary></indexterm>
@@ -892,7 +892,7 @@ SHA256: 371a559ce741394b59dbc6460470a9399be5245356a9183bbeea0f89ecaabb03</comput
       <indexterm><primary>configuration</primary><secondary>files</secondary></indexterm>
 
       <para>In addition to the maintainer scripts and control data already
-      mentioned in the previous sections, the
+      mentioned in the <xref linkend="sect.control"/> and <xref linkend="sect.configuration-scripts"/>, the
       <filename>control.tar.gz</filename> archive of a Debian package may
       contain other interesting files. The first,
       <filename>md5sums</filename>, contains the MD5 checksums for all of

en-US/06_apt.xml

@@ -236,7 +236,11 @@ deb-src http://ftp.debian.org/debian jessie-backports main contrib non-free
       months for a “point release”). The other repositories are
       partial (they do not contain all packages) and can host updates
       (packages with newer version) that APT might install. The following
-      sections will explain the purpose and the rules governing each of
+      <xref linkend="sect.security-updates"/>,
+      <xref linkend="sect.stable-updates"/>,
+      <xref linkend="sect.proposed-updates"/> and
+      <xref linkend="sect.backports"/>
+      will explain the purpose and the rules governing each of
       those repositories.</para>
 
       <para>Note that when the desired version of a package is available
@@ -307,8 +311,9 @@ deb-src http://ftp.debian.org/debian jessie-backports main contrib non-free
 	repository is where the expected updates are prepared (under the
 	supervision of the Stable Release Managers).</para>
 
-	<para>The security and stable updates documented in the former
-	sections are always included in this repository, but there is more
+	<para>The security and stable updates documented in the
+	<xref linkend="sect.security-updates"/> and <xref linkend="sect.stable-updates"/>
+	are always included in this repository, but there is more
 	too, because package maintainers also have the opportunity to fix
 	important bugs that do not deserve an immediate release.</para>
 
@@ -1197,15 +1202,15 @@ Pin-Priority: 500
       upgraded to another distribution: those will follow updates
       available in the other distributions. We will explain this behavior
       with the help of the default priorities set by APT below. Do not
-      hesitate to use <command>apt-cache policy</command> (see sidebar) to
+      hesitate to use <command>apt-cache policy</command> (see sidebar <xref linkend="sidebar.apt-cache-policy"/>) to
       verify the given priorities.</para>
 
       <para>Everything centers around the fact that APT only considers
       packages of higher or equal version than the installed one (assuming
       that <filename>/etc/apt/preferences</filename> has not been used to
       force priorities higher than 1000 for some packages).</para>
 
-      <sidebar>
+      <sidebar id="sidebar.apt-cache-policy">
         <title><emphasis>TIP</emphasis> <command>apt-cache policy</command></title>
 
 	<para>To gain a better understanding of the mechanism of priority,

en-US/07_solving-problems.xml

@@ -74,10 +74,10 @@
       documentation is sought. For example, to learn about the
       possible options for the <command>cp</command> command, you
       would type the <command>man cp</command> command at the shell
-      prompt (see sidebar).</para>
+      prompt (see sidebar <xref linkend="sidebar.shell"/>).</para>
 
 
-      <sidebar>
+      <sidebar id="sidebar.shell">
         <title><emphasis>BACK TO BASICS</emphasis> The shell, a command line interpreter</title>
         <indexterm><primary>command line interpreter</primary></indexterm>
         <indexterm><primary>shell</primary></indexterm>
@@ -433,7 +433,7 @@ ntfscp (8)           - copy file to an NTFS volume.
       you to avoid wasting time on common problems.</para>
 
       <para>Then, you should look at the software's official documentation
-      — refer to the previous section to identify the various existing
+      — refer to the <xref linkend="sect.documation-sources"/> to identify the various existing
       documentation sources. The <command>dpkg -L
       <replaceable>package</replaceable></command> command gives a list of files
       included in the package; you can therefore quickly identify the

en-US/08_basic-configuration.xml

@@ -635,8 +635,7 @@ adsl:2345:respawn:/usr/sbin/pppd call dsl-provider
 	<para>The PPTP (Point-to-Point Tunneling Protocol) protocol was
 	created by Microsoft. Deployed at the beginning of ADSL, it was
 	quickly replaced by PPPOE. If this protocol is forced on you, see
-	<xref linkend="network-infrastructure"/> in the section about
-	virtual private networks detailing PPTP.</para>
+	<xref linkend="sect.pptp"/>.</para>
       </section>
       <section id="sect.adsl-dhcp">
         <title>Modems Supporting DHCP</title>
@@ -1128,7 +1127,7 @@ nameserver 8.8.8.8
         <listitem>
 	  <para>password (optional): This is only used to join a group when
 	  one is not a usual member (with the <command>newgrp</command> or
-	  <command>sg</command> commands, see sidebar);</para>
+	  <command>sg</command> commands, see sidebar <xref linkend="sidebar.working-with-several-groups"/>);</para>
         </listitem>
         <listitem>
 	  <para><literal>gid</literal>: unique group identification
@@ -1142,7 +1141,7 @@ nameserver 8.8.8.8
 
       <para/>
 
-      <sidebar>
+      <sidebar id="sidebar.working-with-several-groups">
         <title><emphasis>BACK TO BASICS</emphasis> Working with several groups</title>
         <indexterm><primary><command>newgrp</command></primary></indexterm>
         <indexterm><primary><command>sg</command></primary></indexterm>
@@ -1248,7 +1247,7 @@ nameserver 8.8.8.8
     than their default “main” group) in order to grant them additional
     permissions. For example, a user who is included in the
     <emphasis>audio</emphasis> group can access audio devices (see sidebar
-    “Device access permissions”). This can be achieved with a
+    <xref linkend="sidebar.special-files"/>). This can be achieved with a
     command such as <command>adduser <replaceable>user</replaceable>
     <replaceable>group</replaceable></command>.</para>
 
@@ -1652,7 +1651,10 @@ mirexpress:/dev/disk/by-id# </computeroutput>
       information is mainly in the model and serial numbers of the disks,
       from which you can find the peripheral file.</para>
 
-      <para>The example configuration files given in the following sections
+      <para>The example configuration files given in the following
+      <xref linkend="sect.config-lilo"/>,
+      <xref linkend="sect.config-grub"/> and
+      <xref linkend="sect.config-yaboot"/>
       are based on the same setup: a single SATA disk, where the
       first partition is an old Windows installation and the second
       contains Debian GNU/Linux.</para>
@@ -2501,7 +2503,7 @@ arrakis:/shared /shared         nfs     defaults        0       0
 </screen>
 
       <para>Unless you need to change the configuration, you can stop here
-      and skip to the next section. If you need to change it, on the other
+      and skip to the <xref linkend="sect.kernel-build"/>. If you need to change it, on the other
       hand, or if you decide to reconfigure everything from scratch, you
       must take the time to configure your kernel. There are various
       dedicated interfaces in the kernel source directory that can be used

en-US/11_network-services.xml

@@ -179,7 +179,12 @@
 
       <para>After this first step, the administrators got the following
       configuration file; it will be used as a starting point for adding
-      some extra functionality in the next sections.</para>
+      some extra functionality in the next <xref linkend="sect.configuring-virtual-domains"/>,
+      <xref linkend="sect.restrictions-for-receiving-and-sending"/>,
+      <xref linkend="sect.setting-up-greylisting"/>,
+      <xref linkend="sect.customizing-filters-based-on-the-recipient"/>,
+      <xref linkend="sect.postfix-antivirus"/> and
+      <xref linkend="sect.authenticated-smtp"/>.</para>
 
       <example>
         <title>Initial <filename>/etc/postfix/main.cf</filename> file</title>
@@ -246,7 +251,7 @@ inet_protocols = all
         </para>
       </sidebar>
     </section>
-    <section>
+    <section id="sect.configuring-virtual-domains">
       <title>Configuring Virtual Domains</title>
       <indexterm><primary>domain</primary><secondary>virtual</secondary></indexterm>
       <indexterm><primary>virtual domain</primary></indexterm>
@@ -386,7 +391,7 @@ sophie@falcot.org falcot.org/sophie
         </example>
       </section>
     </section>
-    <section>
+    <section id="sect.restrictions-for-receiving-and-sending">
       <title>Restrictions for Receiving and Sending</title>
 
       <para>The growing number of unsolicited bulk emails
@@ -774,7 +779,7 @@ body_checks = regexp:/etc/postfix/body_checks
 	messages.</para>
       </section>
     </section>
-    <section>
+    <section id="sect.setting-up-greylisting">
       <title>Setting Up <foreignphrase>greylisting</foreignphrase></title>
       <indexterm><primary>greylisting</primary></indexterm>
 
@@ -879,10 +884,11 @@ smtpd_recipient_restrictions = permit_mynetworks,
         </para>
       </sidebar>
     </section>
-    <section>
+    <section id="sect.customizing-filters-based-on-the-recipient">
       <title>Customizing Filters Based On the Recipient</title>
 
-      <para>The last two sections reviewed many of the possible
+      <para>The <xref linkend="sect.restrictions-for-receiving-and-sending"/> and
+      <xref linkend="sect.setting-up-greylisting"/> reviewed many of the possible
       restrictions. They all have their use in limiting the amount of
       received spam, but they also all have their drawbacks. It is
       therefore more and more common to customize the set of filters
@@ -1032,7 +1038,7 @@ smtpd_milters = inet:[127.0.0.1]:10002
       <para>All messages handled by Postfix now go through the antivirus
       filter.</para>
     </section>
-    <section>
+    <section id="sect.authenticated-smtp">
       <title>Authenticated SMTP</title>
 
       <para>Being able to send emails requires an SMTP server to be

en-US/13_workstation.xml

@@ -561,8 +561,8 @@
 
       <para>Strictly speaking, Debian <emphasis
       role="distribution">Jessie</emphasis> contains Icedove, and not
-      Thunderbird, for legal reasons we will detail in the “Iceweasel,
-      Firefox and others” section later on; but apart from their names
+      Thunderbird, for legal reasons we will detail in the sidebar
+      <xref linkend="sidebar.firefox-iceweasel"/> later on; but apart from their names
       (and icons), there are no real differences between them.</para>
     </section>
   </section>
@@ -1008,7 +1008,9 @@
 
     <para>However, one should keep in mind that it is only a solution among
     others, and the problem can also be tackled with a virtual machine or
-    VNC; both of these solutions are detailed in the sidebars.</para>
+    VNC; both of these solutions are detailed in the sidebars
+    <xref linkend="sidebar.virtual-machines"/> and
+    <xref linkend="sidebar.wts-or-vnc"/>.</para>
 
     <para>Let us start with a reminder: emulation allows executing a
     program (developed for a target system) on a different host system. The
@@ -1065,7 +1067,7 @@
     will determine conclusively whether emulation is fully
     functional.</para>
 
-    <sidebar>
+    <sidebar id="sidebar.virtual-machines">
       <title><emphasis>ALTERNATIVE</emphasis> Virtual machines</title>
 
       <para>An alternative to emulating Microsoft's operating system is to
@@ -1076,7 +1078,7 @@
       Bochs).</para>
     </sidebar>
 
-    <sidebar>
+    <sidebar id="sidebar.wts-or-vnc">
       <title><emphasis>ALTERNATIVE</emphasis> <foreignphrase>Windows Terminal Server</foreignphrase> or VNC</title>
 
       <para>Yet another possibility is to remotely run the legacy Windows