From 03f4eff287a003d7d1a4f09f71ffd66406d88a90 Mon Sep 17 00:00:00 2001
From: Nathan Cutler <ncutler@suse.com>
Date: Sun, 21 Jul 2024 15:18:32 +0200
Subject: [PATCH] xml/obs_local_building.xml: improve readability

As a first-time reader I was confused by the current text, so I quickly came up
with some edits to make the chapter more intelligible.

Signed-off-by: Nathan Cutler <ncutler@suse.com>
---
 xml/book-obs-user-guide.xml                   |  2 +-
 ...sc_building.xml => obs_local_building.xml} | 37 ++++++++++++-------
 2 files changed, 25 insertions(+), 14 deletions(-)
 rename xml/{osc_building.xml => obs_local_building.xml} (80%)

diff --git a/xml/book-obs-user-guide.xml b/xml/book-obs-user-guide.xml
index fe79d836..69e158f8 100644
--- a/xml/book-obs-user-guide.xml
+++ b/xml/book-obs-user-guide.xml
@@ -63,7 +63,7 @@
  <part xml:id="par-working">
   <title>Usage</title>
   <xi:include href="obs_basic_workflow.xml"/>
-  <xi:include href="osc_building.xml"/>
+  <xi:include href="obs_local_building.xml"/>
 
   <xi:include href="obs_source_services.xml"/>
   <!-- tbd: <xi:include href="obs_signing.xml"/>-->
diff --git a/xml/osc_building.xml b/xml/obs_local_building.xml
similarity index 80%
rename from xml/osc_building.xml
rename to xml/obs_local_building.xml
index aee4b590..30222a26 100644
--- a/xml/osc_building.xml
+++ b/xml/obs_local_building.xml
@@ -4,7 +4,7 @@
   <!ENTITY % entities SYSTEM "entity-decl.ent">
     %entities;
 ]>
-<chapter version="5.1" xml:id="cha-obs-building"
+<chapter version="5.1" xml:id="cha-obs-local-building"
  xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink">
@@ -12,8 +12,8 @@
  <info>
   <abstract>
    <para>
-      Every build which happens on the server can also be executed locally in the same environment using
-      the osc tool. All what you need is to checkout the source code and build the build recipe. The 
+      Every build that happens on the server can also be executed locally in the same environment using
+      the osc tool. All you need is to check out the source code and run <command>osc build</command> to run the build recipe. The
       following explains it for RPM format, but it works for any. osc will download needed binaries
       and execute the local build.
    </para>
@@ -21,8 +21,19 @@
  </info>
  <remark>toms 2017-08-18: Also integrate content from obs_build_containers.xml</remark>
  
- <sect1 xml:id="sec-obs-building-generic">
-  <title>Generic build options</title>
+ <sect1 xml:id="sec-obs-local-building-generic">
+  <title>Generic Local Build Options</title>
+  <para>
+     Frequently, local builds are undertaken on local checkouts of source packages that
+     already reside on an &obsa; server - for example, to test changes before commiting
+     them to the server.
+  </para>
+  <para>
+     It is also possible to trigger a local build in an arbitrary local directory containing
+     sources, without any corresponding source package on an &obsa; server. (However, osc
+     will still need a connection to the server in order to download build dependencies.)
+     The following text describes what the source directory should contain, at a minimum.
+  </para>
   <para>
      Independent of the build format you need at least one source file as build description.
      The file name and structure is format specific. You can find some supported formats described below.
@@ -49,8 +60,9 @@
    </listitem>
   </itemizedlist>
   <para>
-   For existing packages, this is already the case. To build an
-   existing package, the general procedure is as follows:</para>
+   In the typical case of source packages locally checked out from an &obsa;
+   server, this is already the case. To build an existing package, the general
+   procedure is as follows:</para>
   <procedure>
    <step>
     <para>
@@ -83,8 +95,8 @@
    </step>
    <step>
     <para>
-     The simplest way to run a build is just to call the build command. osc will try
-     to detect your installed OS and build for it if possible.
+     The simplest way to run a build is just to call the <command>osc build</command>
+     command. osc will try to detect your installed OS and build for it if possible.
     </para>
     <screen>&prompt.user;<command>osc</command> build</screen>
     <para>
@@ -95,8 +107,7 @@
    </step>
    <step>
     <para>
-	It will download the required dependencies and execute the build script. Therefore it needs to ask for root 
-	permissions in most cases.
+	It will download the required dependencies and execute the build script. Therefore it needs to ask for root permissions in most cases.
     </para>
     <variablelist>
      <varlistentry>
@@ -141,8 +152,8 @@ The buildroot was: /var/tmp/build-root/openSUSE_Tumbleweed-x86_64</screen>
   </procedure>
  </sect1>
 
- <sect1 xml:id="sec-obs-building-advanced">
-  <title>Advanced Build Environment Handling</title>
+ <sect1 xml:id="sec-obs-local-building-advanced">
+  <title>Advanced Local Build Environment Handling</title>
   <para>
 	  The default build environment for local builds is usually chroot. While this is simplest environment
 	  and is therefore easy and fast to handle, it has also a number of shortcomings. For one it is