Document packages and repositories files for git repositories

3 files changed, 77 insertions, 40 deletions

diff --git a/bpkg/rep-add.cli b/bpkg/rep-add.cli
index 3925074..ff202a5 100644
--- a/bpkg/rep-add.cli
+++ b/bpkg/rep-add.cli
@@ -38,7 +38,8 @@ namespace bpkg
 
      A bpkg repository is \i{archive}-based. That is, it contains a collection
      of various packages/versions as archive files. For more information on
-     the structure of bpkg repositories refer to the \cb{bpkg} manual.
+     the structure of bpkg repositories refer to the \l{bpkg \cb{bpkg}
+     manual}.
 
      A git repository is \i{version control}-based. That is, it normally
      contains multiple versions of the same package (but can also contain
@@ -85,17 +86,14 @@ namespace bpkg
      contains \cb{manifest}, then it is assumed to be a single-package
      repository with the \cb{manifest} file being its package manifest.
      Otherwise the \cb{packages} file should list the available packages as
-     directory paths relative to the repository root (which in turn should
-     contain the \cb{manifest} files). The \cb{packages} file is a manifest
-     (see the \cb{bpkg} manual for details on the manifest file format) that
-     should contain one or more \cb{location} values in the POSIX path
-     representation. For example:
-
-     \
-     : 1
-     location: src/libfoo/
-     location: src/foo/
-     \
+     described in \l{bpkg#manifest-package-list-git Package List Manifest for
+     \c{git} Repositories}.
+
+     A git repository may also contain the \cb{repositories} file in the root
+     directory of the repository. This file can be used to describe the
+     repository itself as well as specify its prerequisite and complement
+     repositories. See \l{bpkg#manifest-repository-list Repository List
+     Manifest} for details on the format and semantics of this file.
 
      Supported git protocols are \cb{git://}, \cb{http://}, and \cb{https://}
      for remote repositories and \cb{file://} for local repositories. While
diff --git a/doc/cli.sh b/doc/cli.sh
index a925838..661d65c 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -38,12 +38,14 @@ function compile ()
 
   cli -I .. -v project="bpkg" -v version="$version" -v date="$date" \
 --include-base-last "${o[@]}" --generate-html --html-prologue-file \
-man-prologue.xhtml --html-epilogue-file man-epilogue.xhtml --html-suffix \
-.xhtml ../bpkg/$n.cli
+man-prologue.xhtml --html-epilogue-file man-epilogue.xhtml --html-suffix .xhtml \
+--link-regex '%bpkg(#.+)?%build2-package-manager-manual.xhtml$1%' \
+../bpkg/$n.cli
 
   cli -I .. -v project="bpkg" -v version="$version" -v date="$date" \
 --include-base-last "${o[@]}" --generate-man --man-prologue-file \
 man-prologue.1 --man-epilogue-file man-epilogue.1 --man-suffix .1 \
+--link-regex '%bpkg(#.+)?%$1%' \
 ../bpkg/$n.cli
 }
 
@@ -72,6 +74,7 @@ cli -I .. \
 --html-prologue-file doc-prologue.xhtml \
 --html-epilogue-file doc-epilogue.xhtml \
 --link-regex '%b([-.].+)%../../build2/doc/b$1%' \
+--link-regex '%build2(#.+)?%../../build2/doc/build2-build-system-manual.xhtml$1%' \
 --output-prefix build2-package-manager- manual.cli
 
 html2ps -f doc.html2ps:a4.html2ps -o build2-package-manager-manual-a4.ps build2-package-manager-manual.xhtml
diff --git a/doc/manual.cli b/doc/manual.cli
index 6e57b7d..02287bd 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -28,8 +28,7 @@ Note also that if you are strating a new project that will use the \c{build2}
 toolchain, then it is strongly recommended that you use the \i{standard
 versioning} scheme which is a more strictly defined subset of semanic
 versioning and that allows automation of many version management tasks. See
-\l{https://build2.org/build2/doc/build2-build-system-manual.xhtml#module-version
-Version Module} for details.
+\l{build2#module-version Version Module} for details.
 
 The \c{bpkg} package version has the following form:
 
@@ -857,12 +856,12 @@ Note that the comment of the matching exclusion is used by the web interface
 (\c{brep}) to display the reason for the build exclusion.
 
 
-\h#manifest-package-list|Package List Manifest|
+\h#manifest-package-list-bpkg|Package List Manifest for \c{bpkg} Repositories|
 
-The package list manifest (the \c{packages} file found in the repository root
-directory) describes the list of packages available in the repository. First
-comes a manifest that describes the list itself (referred to as the list
-manifest). The list manifest synopsis is presented next:
+The package list manifest (the \c{packages} file found in the \c{bpkg}
+repository root directory) describes the list of packages available in the
+repository. First comes a manifest that describes the list itself (referred to
+as the list manifest). The list manifest synopsis is presented next:
 
 \
 sha256sum: <sum>
@@ -880,7 +879,7 @@ sha256sum: <sum>
 
 The detailed description of each value follows in the subsequent sections.
 
-\h2#manifest-package-list-sha256sum|\c{sha256sum} (list manifest)|
+\h2#manifest-package-list-bpkg-sha256sum|\c{sha256sum} (list manifest)|
 
 \
 sha256sum: <sum>
@@ -896,7 +895,7 @@ was fetched is the same as the one that was used to create the \c{packages}
 file. This also means that if \c{repositories} is modified in any way, then
 \c{packages} must be regenerated as well.]
 
-\h2#manifest-package-list-package-location|\c{location} (package manifest)|
+\h2#manifest-package-list-bpkg-package-location|\c{location} (package manifest)|
 
 \
 location: <path>
@@ -910,7 +909,7 @@ them all into the repository root directory, it can get untidy. With
 \c{location} we allow for sub-directories.]
 
 
-\h2#manifest-package-list-package-sha256sum|\c{sha256sum} (package manifest)|
+\h2#manifest-package-list-bpkg-package-sha256sum|\c{sha256sum} (package manifest)|
 
 \
 sha256sum: <sum>
@@ -920,12 +919,47 @@ The SHA256 checksum of the package archive file. The \i{sum} value should be
 64 characters long (that is, just the SHA256 value, no file name or any other
 markers), be calculated in the binary mode, and use lower-case letters.
 
+
+\h#manifest-package-list-git|Package List Manifest for \c{git} Repositories|
+
+The package list manifest (the \c{packages} file found in the \c{git}
+repository root directory) describes the list of packages available in the
+repository. It is a (potentially empty) sequence of manifests with the
+following synopsis:
+
+\
+location: <path>
+\
+
+The detailed description of each value follows in the subsequent sections.
+
+As an example, if our repository contained the \c{src/} subdirectory that in
+turn contained the \c{libfoo} and \c{foo} packages, then the corresponding
+\c{packages} file could look like this:
+
+\
+: 1
+location: src/libfoo/
+:
+location: src/foo/
+\
+
+\h2#manifest-package-list-git-location|\c{location}|
+
+\
+location: <path>
+\
+
+The path to the package directory relative to the repository root. It should
+be in the POSIX representation.
+
+
 \h#manifest-repository|Repository Manifest|
 
 The repository manifest (only used as part of the repository manifest list
-described below) describes a \c{bpkg} repository. The manifest synopsis is
-presented next followed by the detailed description of each value in
-subsequent sections.
+described below) describes a \c{bpkg} or \c{git} repository. The manifest
+synopsis is presented next followed by the detailed description of each value
+in subsequent sections.
 
 \
 [location]: <uri>
@@ -1089,7 +1123,8 @@ description.
 \
 
 The X.509 certificate for the repository. It should be in the PEM format and
-can only be specified for the base repository.
+can only be specified for the base repository. Currently only used for the
+\c{bpkg} repository type.
 
 The certificate should contain the \c{CN} and \c{O} components in the subject
 as well as the \c{email:} component in the subject alternative names. The
@@ -1100,7 +1135,7 @@ repository name(s) that are authenticated with this certificate. See
 
 If this value is present then the \c{packages} file must be signed with the
 corresponding private key and the signature saved in the \c{signature} file.
-See \l{#manifest-signature Signature Manifest} for details.
+See \l{#manifest-signature-bpkg Signature Manifest} for details.
 
 
 \h#manifest-repository-list|Repository List Manifest|
@@ -1149,23 +1184,24 @@ https://pkg.example.org/1/math/stable
 \
 
 
-\h#manifest-signature|Signature Manifest|
+\h#manifest-signature-bpkg|Signature Manifest for \c{bpkg} Repositories|
 
-The signature manifest (the \c{signature} file found in the repository root
-directory) contains the signature of the repository's \c{packages} file. In
-order to detect the situation where the downloaded \c{signature} and
-\c{packages} files belong to different updates, the manifest contains both the
-checksum and the signature (which is the encrypted checksum). [Note: we cannot
-rely on just the signature since a mismatch could mean either a split update
-or tampering.] The manifest synopsis is presented next followed by the
-detailed description of each value in subsequent sections.
+The signature manifest (the \c{signature} file found in the \c{bpkg}
+repository root directory) contains the signature of the repository's
+\c{packages} file. In order to detect the situation where the downloaded
+\c{signature} and \c{packages} files belong to different updates, the manifest
+contains both the checksum and the signature (which is the encrypted
+checksum). [Note: we cannot rely on just the signature since a mismatch could
+mean either a split update or tampering.] The manifest synopsis is presented
+next followed by the detailed description of each value in subsequent
+sections.
 
 \
 sha256sum: <sum>
 signature: <sig>
 \
 
-\h2#manifest-signature-sha256sum|\c{sha256sum}|
+\h2#manifest-signature-bpkg-sha256sum|\c{sha256sum}|
 
 \
 sha256sum: <sum>
@@ -1176,7 +1212,7 @@ characters long (that is, just the SHA256 value, no file name or any other
 markers), be calculated in the binary mode, and use lower-case letters.
 
 
-\h2#manifest-signature-signature|\c{signature}|
+\h2#manifest-signature-bpkg-signature|\c{signature}|
 
 \
 signature: <sig>