Further work on packaging guide (proofreading)

1 files changed, 77 insertions, 68 deletions

diff --git a/doc/packaging.cli b/doc/packaging.cli
index 850ab8a..4b16ac7 100644
--- a/doc/packaging.cli
+++ b/doc/packaging.cli
@@ -240,7 +240,7 @@ publish if package requires staged toolchain?} for background).|
 
 \li|\l{https://github.com/build2-packaging github.com/build2-packaging}
 contains all the third-party package repositories. Someone could already be
-working on the package but haven't they finished it.|
+working on the package but haven't yet published it.|
 
 \li|\l{https://github.com/build2-packaging/WISHLIST/issues
 github.com/build2-packaging/WISHLIST} contains as issues projects that people
@@ -261,7 +261,7 @@ would like to take over the package,
 It is almost always best to use the upstream repository name as the package
 repository name. If there is no upstream repository (for example, because the
 project doesn't use a version control system), the name used in the source
-archive distribution would be the natural fallback.
+archive distribution would be the natural fallback choice.
 
 \N|See \l{#core-package-name Decide on the package name} for the complete
 picture on choosing names.|
@@ -276,7 +276,7 @@ github.com/build2-packaging} organization.
 \l{https://cppget.org cppget.org} to be under the
 \l{https://github.com/build2-packaging github.com/build2-packaging}
 organization in order to ensure some continuity in case the original
-maintainer loose interest, etc. You will still be the owner of the repository
+maintainer looses interest, etc. You will still be the owner of the repository
 and by hosting your packaging efforts under this organization (as opposed to,
 say, your personal workspace) you make it easier for others to discover your
 work and to contribute to the package maintenance.
@@ -290,13 +290,13 @@ unable to use either, \l{https://build2.org/community.xhtml#help get in touch}
 to discuss alternatives.|
 
 However, the recommended approach is to start with a repository in your
-personal workspace and then, when it is ready or in a reasonably stable shape,
-transfer it to \l{https://github.com/build2-packaging
+personal workspace and then, when it is ready or in a reasonably complete
+state, transfer it to \l{https://github.com/build2-packaging
 github.com/build2-packaging}. This gives you the freedom to make destructive
-changes to the repository (including deleting it and strating over) during the
+changes to the repository (including deleting it and starting over) during the
 initial packaging work. It also removes the pressure to perform: you can give
-it a try and if things turn out more difficult than you expected, you can
-just drop the repository.
+it a try and if things turn out more difficult than you expected, you can just
+drop the repository.
 
 \N|For repositories under \l{https://github.com/build2-packaging
 github.com/build2-packaging} the \c{master}/\c{main} branch is protected: it
@@ -308,28 +308,29 @@ under \l{https://github.com/build2-packaging github.com/build2-packaging} it
 should follow the \l{#core-repo-name Use upstream repository name as package
 repository name} guideline. In particular, there should be no prefixes like
 \c{build2-} or suffixes like \c{-package}. If the repository under your
-personal workspace does not follow this guideline, you should rename it before
-transferring it to the \l{https://github.com/build2-packaging
+personal workspace does not follow this guideline, you will need to rename it
+before transferring it to the \l{https://github.com/build2-packaging
 github.com/build2-packaging} organization.|
 
-There is one potenential problem with this approach: it is possible that
-several people start working on the same third-party project without being
-aware of each other's efforts. If the project you are packaging is relatively
-small and you don't expect it to take more than a day or two, then this is
-probably not worth worrying about. For bigger projects, however, it makes
-sense to announce your work by creating (or updating) the corresponding issue
-in \l{https://github.com/build2-packaging/WISHLIST
+There is one potential problem with this approach: it is possible that
+several people will start working on the same third-party project without
+being aware of each other's efforts. If the project you are packaging is
+relatively small and you don't expect it to take more than a day or two, then
+this is probably not worth worrying about. For bigger projects, however, it
+makes sense to announce your work by creating (or updating) the corresponding
+issue in \l{https://github.com/build2-packaging/WISHLIST
 github.com/build2-packaging/WISHLIST}.
 
 To put it all together, the recommended sequence of actions for this step:
 
 \ol|
 
-\li|Create a new empty repository under your personal workspace from GitHub
-    UI. Don't automatically add any files (\c{README}, \c{LICENSE}, etc).|
+\li|Create a new empty repository under your personal workspace from the
+    GitHub UI. Don't automatically add any files (\c{README}, \c{LICENSE},
+    etc).|
 
 \li|Set the repository description in GitHub UI to the \c{build2 package
-for <name>} line, where \c{<name>} is the project name.|
+for <name>} line, where \c{<name>} is the third-party project name.|
 
 \li|Clone the repository to your machine.||
 
@@ -343,17 +344,17 @@ have created its package repository at
 description) and can now clone it:
 
 \
-$ git clone https://github.com/<personal>/foo.git
+$ git clone git@github.com:<personal>/foo.git
 \
 
 
 \h2#core-repo-init|Initialize package repository with \c{bdep new --type empty}|
 
-Change to the root directory of the package repository that you have clonned
+Change to the root directory of the package repository that you have cloned
 on the previous step and run (continuing with our \c{foo} example):
 
 \
-$ cd foo/
+$ cd foo/ # Change to the package repository root.
 $ bdep new --type empty
 $ tree .
 ./
@@ -378,13 +379,13 @@ This file specifies the repositories from which this project will obtain its
 dependencies (see \l{intro#guide-add-remove-deps Adding and Removing
 Dependencies}). If the project you are packaging has no dependencies, then you
 can safely remove this file (it's easy to add later if this changes). And for
-projects that do have dependecies we will discuss the appropriate changes to
+projects that do have dependencies we will discuss the appropriate changes to
 this file later.|
 
 
 \li|\n\c{.gitattributes} and \c{.gitignore}\n
 
-These are the \c{git} infrastrucutre files for the repository. You shouldn't
+These are the \c{git} infrastructure files for the repository. You shouldn't
 normally need to change anything in them at this stage (see the comments
 inside for details).||
 
@@ -398,10 +399,11 @@ $ git commit -m \"Initialize repository\"
 \
 
 \N|In these guidelines we will be using the package repository setup that is
-capable of having multiple packages. This is recommended even for upstream
-projects that only provides a single package because it gives us the
-flexibility of adding new packages at a later stage without having to perform
-a major restructuring of our repository.
+capable of having multiple packages (referred to as \i{multi-package
+repository}). This is recommended even for upstream projects that only
+provides a single package because it gives us the flexibility of adding new
+packages at a later stage without having to perform a major restructuring of
+our repository.
 
 Note also that upstream providing multiple package is not the only reason we
 may end up having multiple \c{build2} packages. Another common reason is
@@ -416,12 +418,12 @@ The only notable drawback of using a multi-package setup with a single package
 is the extra subdirectory for the package and a few extra files (such as
 \c{packages.manifest} that lists the packages) in the root of the repository.
 If you are certain that the project that you are converting is unlikely to
-have multiple packages (for example, because you are the upstream) or need
-extra dependencies for its tests (a reasonable assumption for a C project),
-then you could instead go with the single-package repository where the
-repository root is the package root. See \l{bdep-new(1)} for details on how to
-initialize such a repository. In this guide, however, we will continue to
-assume a multi-package repository setup.|
+have multiple packages (for example, because you are the upstream) and won't
+need extra dependencies for its tests (a reasonable assumption for a C
+project), then you could instead go with the single-package repository where
+the repository root is the package root. See \l{bdep-new(1)} for details on
+how to initialize such a repository. In this guide, however, we will continue
+to assume a multi-package repository setup.|
 
 
 \h2#core-repo-submodule|Add upstream repository as \c{git} submodule|
@@ -432,7 +434,7 @@ upstream source code available inside the package repository, customarily in a
 subdirectory called \c{upstream/}.
 
 \N|While \c{git} submodules receive much criticism, in our case we use them
-exactly as indended: to select and track specific (release) commits of an
+exactly as intended: to select and track specific (release) commits of an
 external project. As a result, there is nothing tricky about their use for our
 purpose and all the relevant commands will be provided and explained, in case
 you are not familiar with this \c{git} mechanism.|
@@ -441,12 +443,14 @@ Given the upstream repository URL, to add it as a submodule, run the following
 command from the package repository root (continuing with our \c{foo} example):
 
 \
+$ cd foo/ # Change to the package repository root.
 $ git submodule add https://github.com/<upstream>/foo.git upstream
 \
 
 \N|You should prefer \c{https://} over \c{git://} for the upstream repository
 URL since the \c{git://} protocol may not be accessible from all networks.
-Naturally, never use a URL that requires authentication, for example, SSH.|
+Naturally, never use a URL that requires authentication, for example, SSH
+(SSH URLs start with \c{git@github.com} for GitHub).|
 
 Besides the repository URL, you also need the commit of the upstream release
 which you will be packaging. It is common practice to tag releases so the
@@ -455,7 +459,7 @@ use the commit id.
 
 Assuming the upstream release tag you are interested in is called \c{vX.Y.Z},
 to update the \c{upstream} submodule to point to this release commit, run the
-following command:
+following commands:
 
 \
 $ cd upstream/
@@ -466,23 +470,22 @@ $ cd ../
 Then add and commit these changes:
 
 \
-$ cd foo/ # Change to the package repository root.
 $ git add .
 $ git status
 $ git commit -m \"Add upstream submodule\"
 \
 
-Now we have all the upstream source code for the release that we are
-interested in available in the \c{upstream/} subdirectory of our repository.
+Now we have all the upstream source code for the version that we are
+packaging available in the \c{upstream/} subdirectory of our repository.
 
 The plan is to then use symbolic links (symlinks) to non-invasively overlay
-the \c{build2} files (\c{buildfile}, \c{manifest}, etc) with the upstream
-source code, if necessary adjusting upstream structure to split it into
-multiple packages and/or to better align with the source/output layouts
+the \c{build2}-related files (\c{buildfile}, \c{manifest}, etc) with the
+upstream source code, if necessary adjusting upstream structure to split it
+into multiple packages and/or to better align with the source/output layouts
 recommended by \c{build2} (see \l{https://build2.org/article/symlinks.xhtml
 Using Symlinks in \c{build2} Projects} for background and rationale). But
 before we can start adding symlinks to the upstream source (and other files
-like \c{README}, \c{LICENSE}, etc), we want to generate the \c{buildfile}
+like \c{README}, \c{LICENSE}, etc), we need to generate the \c{buildfile}
 templates that match the upstream source code layout. This is the subject of
 the next section.
 
@@ -491,7 +494,8 @@ Windows it's a niche feature that unfortunately could be cumbersome to use
 (see \l{https://build2.org/article/symlinks.xhtml#windows Symlinks and
 Windows} for details). However, the flexibility afforded by symlinks when
 packaging third-party projects is unmatched by any other mechanism and we
-therefore use them despite potentially sub-optimal experience on Windows.|
+therefore use them despite potentially sub-optimal packaging experience
+on Windows.|
 
 
 \h#core-package|Create package and generate \c{buildfile} templates|
@@ -517,13 +521,13 @@ recommended place to check before deciding on a name is the
 name differs from upstream, then there is likely a good reason for that and
 it is worth trying to understand what it is.
 
-\N|Tip: when trying to find the corresponding Debain package, search for the
+\N|Tip: when trying to find the corresponding Debian package, search for the
 executable file name in the package contents if you cannot fine the package by
 its upstream name. Also consider searching in the \c{unstable} distribution in
-addition to \c{testing} for newer packages.|
+addition to \c{stable} for newer packages.|
 
 Picking a name for a package that provides a library is where things can get
-more complicated. While all the recommendation that have been listed for
+more complicated. While all the recommendations that have been listed for
 executables apply equally to libraries, there are additional considerations.
 
 In \c{build2} we recommend (but not require) that new library projects use a
@@ -538,7 +542,7 @@ however, we do need to split them into two separate packages and both packages
 cannot be called \c{zstd}. So we call them \c{zstd} and \c{libzstd}.
 
 \N|If you are familiar with the Debian package naming policy, you will
-undoubtedly recognize the approach. In Debian all the library packages (with
+undoubtedly recognize this approach. In Debian all the library packages (with
 very few exceptions) start with the \c{lib} prefix. So when searching for an
 upstream name in the \l{https://packages.debian.org Debian package repository}
 make sure to prefix it with \c{lib} (unless it already starts with this
@@ -587,7 +591,7 @@ upstream naming, you nevertheless have no choice but to ignore it and forge
 your own path.
 
 Next let's look at library examples. Notice that some use the same \c{build2}
-package repository name as the executables above. That means they are part of
+package repository name as the executables above. This means they are part of
 the same multi-package repository.
 
 \
@@ -621,17 +625,20 @@ debug/release, etc) and may not correspond directly to the library name.|
 
 And, speaking of multiple components, if you realize the upstream project
 provides multiple libraries and/or executables, then you need to decide
-whether to split them into seperate \c{build2} packages and if so, how. Here,
-again, the corresponding Debian packages can be a good strating point. Note,
-however, that in this case we often deviate from their split, especially when
-it comes to libraries. For example, \c{libevent} shown in the above table
-provides several libraries (\c{libevent-core}, \c{libevent-extra}, etc) and in
-Debian it is actually split into several binary packages along these lines. In
-\c{build2}, however, there is a single package that provides all these
-libraries with everything except \c{libevent-core} being optional. An example
-which shows the decision made in a different direction would be the Boost
-libraries: in Debian all the header-only Boost libraries are bundled into a
-single package while in \c{build2} they are all seperate packages.
+whether to split them into separate \c{build2} packages and if so, how. Here,
+again, the corresponding Debian packages can be a good reference point. Note,
+however, that we often deviate from Debian's splits, especially when it comes
+to libraries. Such differences are usually due to Debian focusing on binary
+packages while in \c{build2} we are focusing on source packages.
+
+To give a few example, \c{libevent} shown in the above table provides several
+libraries (\c{libevent-core}, \c{libevent-extra}, etc) and in Debian it is
+actually split into several binary packages along these lines. In \c{build2},
+however, there is a single source package that provides all these libraries
+with everything except \c{libevent-core} being optional. An example which
+shows the decision made in a different direction would be the Boost libraries:
+in Debian all the header-only Boost libraries are bundled into a single
+package while in \c{build2} they are all separate packages.
 
 The overall criteria here can be stated as follows: if a small family of
 libraries provide complimentary functionality (like \c{libevent}), then we put
@@ -639,23 +646,25 @@ them all into a single package, usually making the additional functionality
 optional. However, if the libraries are independent (like Boost) or provide
 alternative rather than complimentary functionality (for example, like
 different backends in \c{imgui}), then we make them separate packages. Note
-that we never bundle an executable and a (public) library in a single package.
+that we never bundle an executable and a (public) library in a single package
+(because, when consumed, they usually require different
+\l{bpkg#manifest-package-depends dependency types}: build-time vs run-time).
 
 Note also that while it's a good idea to decide on the package split and all
-the package names upfront to avoid suprises later, you don't have to actually
+the package names upfront to avoid surprises later, you don't have to actually
 provide all the packages right away. For example, if upstream provides a
 library and an executable (like \c{zstd}), you can start with the library and
 the executable package can be added later (potentially by someone else).
 
-Admittedly, the recommendation in this section are all a bit fuzzy and one can
-choose different names or different package splits that could all seem
+Admittedly, the recommendations in this section are all a bit fuzzy and one
+can choose different names or different package splits that could all seem
 reasonable. If you are unsure how to split the upstream project or what names
 to use, \l{https://build2.org/community.xhtml#help get in touch} to discuss
 the alternatives. It can be quite painful to change these things after you
 have completed the remaining packaging steps.
 
-Continuing with our \c{foo} example, we will follow the recommendation and
-call the library package \c{libfoo}.
+Continuing with our \c{foo} example, we will follow the above recommendation
+and call the library package \c{libfoo}.
 
 
 \h2#core-package-struct|Decide on the package source code layout|