Further work on packaging guide (repository README)

1 files changed, 77 insertions, 11 deletions

diff --git a/doc/packaging.cli b/doc/packaging.cli
index 5f14903..2ed4ffb 100644
--- a/doc/packaging.cli
+++ b/doc/packaging.cli
@@ -41,6 +41,8 @@
 //
 // @@ Note: showing UNIX command lines but should be straightforward to adjust
 //    for Windows.
+//
+// @@ Add zstd as PACKAGE-README.md examples.
 
 "
 \h0#preface|Preface|
@@ -354,14 +356,14 @@ $ git clone git@github.com:<personal>/foo.git
 \
 
 
-\h2#core-repo-init|Initialize package repository with \c{bdep new --type empty}|
+\h2#core-repo-init|Initialize package repository with \c{bdep new}|
 
 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/ # Change to the package repository root.
-$ bdep new --type empty
+$ bdep new --type empty,third-party
 $ tree -a .
 ./
 ├── .bdep/
@@ -374,14 +376,17 @@ $ tree -a .
 └── repositories.manifest
 \
 
+\N|We use the special \c{third-party} sub-option which is meant for converting
+third-party projects to \c{build2}. See \l{bdep-new(1)} for details.|
+
 This command creates a number of files in the root of the repository:
 
 \dl|
 
 \li|\n\c{README.md}\n
 
-This is the project \c{README}. We will discuss the recommended content for
-this file later.|
+This is the repository \c{README.md}. We will discuss the recommended content
+for this file later.|
 
 \li|\n\c{repositories.manifest}\n
 
@@ -3820,6 +3825,16 @@ For \c{<SUMMARY-OF-FUNCTIONALITY>} it's best to copy a paragraph or two from
 the upstream documentation, usually from \c{README.md} or the project's web
 page.
 
+\N|If \c{bdep new} was able to extract the summary from upstream \c{README},
+then the summary in the heading (first line) will contain that information.
+Otherwise, you would want to adjust it, similar to \c{manifest} above. Using
+the \c{summary} value form the \c{manifest}, perhaps slightly shortened,
+is a good idea.|
+
+If there is a single package, then \c{<SUMMARY>} in the heading can be the
+same as in \c{PACKAGE-README.md}. If there are multiple packages, then use
+an overall summary of the upstream project.
+
 If the package contains a single importable target, as is typical with
 libraries, then it makes sense to drop the \"Importable targets\" section
 since it won't add anything that hasn't already been said in the \"Usage\"
@@ -3853,23 +3868,74 @@ $ git push
 \
 
 
-\h#core-proj-readme|Adjust project \c{README.md}|
+\h#core-proj-readme|Adjust package repository \c{README.md}|
 
 With all the package files taken care of, the last file we need to adjust is
 \c{README.md} in the root of our package repository (it was created on the
-\l{#core-repo-init Initialize package repository with \c{bdep new --type
-empty}} step).
+\l{#core-repo-init Initialize package repository with \c{bdep new}} step).
 
 \N|If you need to add additional packages and are doing this one package at a
 time (for example, first library then executable in the \"library and
 executable\" project), then this is the point where you would want to restart
 from \l{#core-package Create package and generate \c{buildfile} templates} for
 another iteration. Only once all the packages are added does it make sense
-to continue with updating project \c{README.md}.|
+to continue with updating this \c{README.md}.|
+
+The primary purpose of the package repository \c{README.md} is to provide
+setup instructions as well as any other relevant information for the
+devlopment of the packages as opposed to their consumption. However, it's also
+a good idea to privide a brief summary of what this package repostiory is
+about and to point users interested in consumption to the
+\c{PACKAGE-README.md} files.
+
+The template generated by \c{bdep-new} establishes the recommended structure
+that achieves these objectives. It includes a number of placeholders enclosed
+in \c{< >}, such as \c{<UPSTREAM-URL>} and \c{<SUMMARY-OF-FUNCTIONALITY>},
+that need to be replaced with the repository-specific content. While all the
+placeholders should be self-explanatory, below are a couple of guidelines.
+
+If there is a single package, then \c{<SUMMARY>} in the heading can be the
+same as in \c{PACKAGE-README.md}. If there are multiple packages, then use
+an overall summary of the upstream project.
+
+For \c{<SUMMARY-OF-FUNCTIONALITY>} it's best to copy a paragraph or two from
+the upstream documentation, usually from \c{README.md} or the project's web
+page.
+
+If there are multiple packages in the repository, then it's recommended to
+replace a single link to \c{PACKAGE-README.md} with a list of links (this
+also gives an idea which packages are available). For example:
+
+\
+... If you want to use `foo` in your `build2`-based project, then
+instead see the accompanying `PACKAGE-README.md` files:
+
+* [`libfoo/PACKAGE-README.md`](libfoo/PACKAGE-README.md)
+* [`foo/PACKAGE-README.md`](foo/PACKAGE-README.md)
+\
+
+The remainder of the generated \c{README.md} file are the standard \c{bdep}
+initialization instructions. Adjust them if your package repository requires
+anything special (for example, a host configuration). This is also the place
+to mention anything unusual, such as that upstream does not use semver.
+
+For inspiration, see
+\l{https://github.com/build2-packaging/zstd/blob/v1.5.5/README.md
+\c{README.md}} in the \l{https://github.com/build2-packaging/zstd/tree/v1.5.5
+\c{zstd}} package repository.
+
+Once the repository \c{README.md} is ready, commit and push the changes. You
+may also want to view the result on GitHub to make sure everything is rendered
+correctly.
 
-@@ Purpose.
+\
+$ cd foo/ # Change to the package repository root.
+$ git add .
+$ git status
+$ git commit -m \"Adjust package repository README.md\"
+$ git push
+\
 
-@@ Commit and push.
 
 \h#core-release-publish|Release and publish|
 
@@ -3902,7 +3968,7 @@ the repository once transferred). To get an invite,
 \l{https://build2.org/community.xhtml#help get in touch} not forgetting to
 mention your GitHub user name.
 
-Then, if your repository has any prefixes, such as \c{build2-}, or suffixes
+If your repository has any prefixes, such as \c{build2-}, or suffixes
 such as \c{-package}, then the next step is to rename it to follow the
 \l{#core-repo-name Use upstream repository name as package repository name}
 guideline. Go to the repository's Settings on GitHub where you should see the