Re: [PATCH 1/1] Docs: Add commit-graph tech docs to Makefile

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 21, 2018, 18:13 UTC
Message-ID: <xmqqwosj8u5m.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <ef5af2ccc7ea662a4059d118772cdbe282fc7e43.1534855978.git.gitgitgadget@gmail.com>

"Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 23 quoted lines

> From: Derrick Stolee <dstolee@microsoft.com>
>
> Ensure that the commit-graph.txt and commit-graph-format.txt files
> are compiled to HTML using ASCIIDOC.
>
> Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
> ---
>  Documentation/Makefile | 2 ++
>  1 file changed, 2 insertions(+)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index d079d7c73..841e4f705 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -69,6 +69,8 @@ API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technica
>  SP_ARTICLES += $(API_DOCS)
>  
>  TECH_DOCS += SubmittingPatches
> +TECH_DOCS += technical/commit-graph
> +TECH_DOCS += technical/commit-graph-format
>  TECH_DOCS += technical/hash-function-transition
>  TECH_DOCS += technical/http-protocol
>  TECH_DOCS += technical/index-format

Looking at what 5641eb94 ("partial-clone: render design doc using asciidoc", 2018-08-14) had to do to make the straight text usable as AsciiDoc input, I do not think a patch to D/Makefile alone is sufficient; just quick skim of the source makes a reader notice a block of text like this:

    Equivalently, the generation number of a commit A is one more than the
    length of a longest path from A to a root commit. The recursive definition
    is easier to use for computation and observing the following property:

        If A and B are commits with generation numbers N and M, respectively,
        and N <= M, then A cannot reach B. That is, we know without searching
        that B is not an ancestor of A because it is further from a root commit
        than A.

        Conversely, when checking if A is an ancestor of B, then we only need
        to walk commits until all commits on the walk boundary have generation
        number at most N. If we walk commits using a priority queue seeded by
        generation numbers, then we always expand the boundary commit with highest
        generation number and can easily detect the stopping condition.

which would give you two paragraphs that are typeset in monospace, without giving enough visual cue that these two are the "following properties" the previous paragraph talks about, like the original plain-text does.

I haven't checked the "-format" document, but I suspect both of these are easier to read in text than in HTML formatted without tweaking the mark-up a bit. It's not like we are not shipping the text versions; let's not give readers HTML that is uglier than text.