Re: [PATCH v2 1/2] docs: fix sparse-checkout docs link

[Elijah Newren <newren@gmail.com>]

On Thu, Jan 19, 2023 at 9:34 AM ZheNing Hu via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: ZheNing Hu <adlternative@gmail.com>
>
> There is a linking error when other documents want to refer to
> technical/sparse-checkout.txt, Also, there is something wrong
> with the format of the paragraphs in sparse-checkout.txt, which
> makes acsiidoc compile errors.
>
> So fix the format of sparse-checkout.txt, and link it in the
> Makefile to correct that.
>
> Signed-off-by: ZheNing Hu <adlternative@gmail.com>
> ---
>  Documentation/Makefile                      |  1 +
>  Documentation/technical/sparse-checkout.txt | 43 ++++++++++++++-------
>  2 files changed, 30 insertions(+), 14 deletions(-)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 9c67c3a1c50..7540da27b8c 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -121,6 +121,7 @@ TECH_DOCS += technical/reftable
>  TECH_DOCS += technical/scalar
>  TECH_DOCS += technical/send-pack-pipeline
>  TECH_DOCS += technical/shallow
> +TECH_DOCS += technical/sparse-checkout
>  TECH_DOCS += technical/trivial-merge
>  SP_ARTICLES += $(TECH_DOCS)
>  SP_ARTICLES += technical/api-index
> diff --git a/Documentation/technical/sparse-checkout.txt b/Documentation/technical/sparse-checkout.txt
> index fa0d01cbda4..52e86764a6c 100644
> --- a/Documentation/technical/sparse-checkout.txt
> +++ b/Documentation/technical/sparse-checkout.txt
> @@ -1,3 +1,6 @@
> +Sparse Checkout Design Notes
> +============================
> +
>  Table of contents:
>
>    * Terminology
> @@ -14,7 +17,8 @@ Table of contents:
>    * Reference Emails
>
>
> -=== Terminology ===
> +Terminology
> +-----------
>
>  cone mode: one of two modes for specifying the desired subset of files
>         in a sparse-checkout.  In cone-mode, the user specifies
> @@ -92,7 +96,8 @@ vivifying: When a command restores a tracked file to the working tree (and
>         file), this is referred to as "vivifying" the file.
>
>
> -=== Purpose of sparse-checkouts ===
> +Purpose of sparse-checkouts
> +---------------------------
>
>  sparse-checkouts exist to allow users to work with a subset of their
>  files.
> @@ -255,7 +260,8 @@ will perceive the checkout as dense, and commands should thus behave as if
>  all files are present.
>
>
> -=== Usecases of primary concern ===
> +Usecases of primary concern
> +---------------------------
>
>  Most of the rest of this document will focus on Behavior A and Behavior
>  B.  Some notes about the other two cases and why we are not focusing on
> @@ -300,7 +306,8 @@ Behavior C do not assume they are part of the Behavior B camp and propose
>  patches that break things for the real Behavior B folks.
>
>
> -=== Oversimplified mental models ===
> +Oversimplified mental models
> +----------------------------
>
>  An oversimplification of the differences in the above behaviors is:
>
> @@ -313,7 +320,8 @@ An oversimplification of the differences in the above behaviors is:
>               they can later lazily be populated instead.
>
>
> -=== Desired behavior ===
> +Desired behavior
> +----------------
>
>  As noted previously, despite the simple idea of just working with a subset
>  of files, there are a range of different behavioral changes that need to be
> @@ -544,7 +552,8 @@ understanding these differences can be beneficial.
>    * gitk?
>
>
> -=== Behavior classes ===
> +Behavior classes
> +----------------
>
>  From the above there are a few classes of behavior:
>
> @@ -611,7 +620,8 @@ From the above there are a few classes of behavior:
>      specification.
>
>
> -=== Subcommand-dependent defaults ===
> +Subcommand-dependent defaults
> +-----------------------------
>
>  Note that we have different defaults depending on the command for the
>  desired behavior :
> @@ -751,7 +761,8 @@ desired behavior :
>      implemented.
>
>
> -=== Sparse specification vs. sparsity patterns ===
> +Sparse specification vs. sparsity patterns
> +------------------------------------------
>
>  In a well-behaved situation, the sparse specification is given directly
>  by the $GIT_DIR/info/sparse-checkout file.  However, it can transiently
> @@ -823,7 +834,8 @@ under behavior B index operations are lumped with history and tend to
>  operate full-tree.
>
>
> -=== Implementation Questions ===
> +Implementation Questions
> +------------------------
>
>    * Do the options --scope={sparse,all} sound good to others?  Are there better
>      options?
> @@ -894,7 +906,8 @@ operate full-tree.
>      is seamless for them.
>
>
> -=== Implementation Goals/Plans ===
> +Implementation Goals/Plans
> +--------------------------
>
>   * Get buy-in on this document in general.
>
> @@ -922,13 +935,14 @@ operate full-tree.
>       commands.  IMPORTANT: make sure diff machinery changes don't mess with
>       format-patch, fast-export, etc.
>
> -=== Known bugs ===
> +Known bugs
> +----------

Everything so far makes sense.

>  This list used to be a lot longer (see e.g. [1,2,3,4,5,6,7,8,9]), but we've
>  been working on it.
>
> -0. Behavior A is not well supported in Git.  (Behavior B didn't used to
> -   be either, but was the easier of the two to implement.)
> +Behavior A is not well supported in Git.  (Behavior B didn't used to
> +be either, but was the easier of the two to implement.)

Why did you remove the numbering on this, though?  If asciidoc doesn't
like starting with 0 (the only guess I can think of for why you'd
change this), shouldn't the series be renumbered starting at 1 rather
than removing this from the list?

>  1. am and apply:
>
> @@ -1052,7 +1066,8 @@ been working on it.
>      https://lore.kernel.org/git/CABPp-BEkJQoKZsQGCYioyga_uoDQ6iBeW+FKr8JhyuuTMK1RDw@mail.gmail.com/
>
>
> -=== Reference Emails ===
> +Reference Emails
> +----------------
>
>  Emails that detail various bugs we've had in sparse-checkout:
>
> --
> gitgitgadget