From fcd9510d21ab703e4077aa28a1763752355b4164 Mon Sep 17 00:00:00 2001
From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com>
Date: Thu, 12 Dec 2024 17:31:32 +1000
Subject: [PATCH] Add Source and Debug appendix

To make existing content extra visible

jsc#SLL-456
---
 xml/app-access-src-debug.xml | 110 +++++++++++++++++++++++++++++++++++
 xml/art-quickstart.xml       |   9 +++
 2 files changed, 119 insertions(+)
 create mode 100644 xml/app-access-src-debug.xml

diff --git a/xml/app-access-src-debug.xml b/xml/app-access-src-debug.xml
new file mode 100644
index 0000000..2663e5a
--- /dev/null
+++ b/xml/app-access-src-debug.xml
@@ -0,0 +1,110 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?xml-stylesheet href="urn:x-suse:xslt:profiling:docbook51-profile.xsl"
+ type="text/xml"
+ title="Profiling step"?>
+<!DOCTYPE appendix
+[
+  <!ENTITY % entities SYSTEM "generic-entities.ent">
+    %entities;
+]>
+
+<appendix xml:id="app-access-src-debug" xml:lang="en"
+ xmlns="http://docbook.org/ns/docbook" version="5.1"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>Accessing the <literal>Source</literal> or <literal>Debug</literal> repositories</title>
+  <info>
+    <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
+      <dm:bugtracker></dm:bugtracker>
+      <dm:translation>yes</dm:translation>
+    </dm:docmanager>
+  </info>
+
+  <para>
+    Mirroring the <literal>Source</literal> or <literal>Debug</literal> repositories and enabling them on your system are documented as part of <xref linkend="mirror-repositories-with-rmt"/> and <xref linkend="register-rhel-with-rmt"/>.
+  </para>
+  <para>
+    However, if your &rhla; system is already registered with the &rmt; server and you just need to enable individual repositories, this section highlights the relevant steps.
+  </para>
+  <itemizedlist>
+    <title>Requirements</title>
+    <listitem>
+      <para>
+        The &rmt; server is installed and up to date.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        The &productname; &productnumber; product is enabled on the &rmt; server.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Your &rhla; system is registered with the &rmt; server.
+      </para>
+    </listitem>
+  </itemizedlist>
+
+  <para>
+    Repositories must be mirrored on the &rmt; server before you can access them on your system. <literal>Source</literal> and <literal>Debug</literal> repositories are not mirrored by default. Use this procedure to mirror any additional repositories you need:
+  </para>
+  <procedure xml:id="pro-mirror-src-debug">
+    <title>Mirroring additional repositories on the &rmt; server</title>
+    <step>
+      <para>
+        List the &productname; &productnumber; repositories:
+      </para>
+<screen>&prompt.root;<command>rmt-cli repos list --all | grep &reponameshort;[A-Z\-]&productnumber;</command></screen>
+      <para>
+        If the repositories you need already have the status <literal>Mirror</literal>, skip this procedure and go to <xref linkend="pro-enable-src-debug"/>.
+      </para>
+    </step>
+    <step>
+      <para>
+        Enable the repositories using their four-digit repository ID. You can enable multiple repositories at once:
+      </para>
+<screen>&prompt.root;<command>rmt-cli repos enable <replaceable>REPO_ID1</replaceable> <replaceable>REPO_ID2</replaceable> <replaceable>REPO_ID3</replaceable></command></screen>
+    </step>
+    <step>
+      <para>
+        Start package mirroring for the enabled repositories:
+      </para>
+<screen>&prompt.root;<command>rmt-cli mirror</command></screen>
+      <para>
+        This will take some time to complete.
+      </para>
+    </step>
+  </procedure>
+
+  <para>
+    After the repositories finish mirroring, use this procedure to enable them on your &rhla; system:
+  </para>
+  <procedure xml:id="pro-enable-src-debug">
+    <title>Enabling additional repositories on &rhel;</title>
+    <step>
+      <para>
+        List the available repositories:
+      </para>
+<screen>&prompt.root;<command>dnf repolist all</command></screen>
+      <para>
+        Be aware that all &productname; &productnumber; repositories are listed and can be enabled even if they are not mirrored on the &rmt; server. However, you can only download content from a repository if it is mirrored on the &rmt; server.
+      </para>
+    </step>
+    <step>
+      <para>
+        Enable the repositories you need using their <literal>repo id</literal>. You can enable multiple repositories at once:
+      </para>
+<screen>&prompt.root;<command>dnf config-manager --enable <replaceable>REPO_ID1</replaceable> <replaceable>REPO_ID2</replaceable> <replaceable>REPO_ID3</replaceable></command></screen>
+    </step>
+    <step>
+      <para>
+        Run the update command to make sure there are no errors:
+      </para>
+<screen>&prompt.root;<command>dnf update</command></screen>
+      <para>
+        If you enabled a repository that is not mirrored on the &rmt; server, you will see a <literal>404</literal> error.
+      </para>
+    </step>
+  </procedure>
+
+</appendix>
diff --git a/xml/art-quickstart.xml b/xml/art-quickstart.xml
index b22b501..c539896 100644
--- a/xml/art-quickstart.xml
+++ b/xml/art-quickstart.xml
@@ -48,6 +48,14 @@
     <phrase>Administration</phrase>
   </meta>
   <revhistory xml:id="rh-art-quickstart">
+    <revision>
+      <date>2024-12-13</date>
+      <revdescription>
+        <para>
+          Add Source and Debug appendix.
+        </para>
+      </revdescription>
+    </revision>
     <revision>
       <date>2024-12-11</date>
       <revdescription>
@@ -382,5 +390,6 @@
     </varlistentry>
   </variablelist>
  </section>
+ <xi:include href="app-access-src-debug.xml"/>
  <xi:include href="common_legal.xml"/>
 </article>