From: Junio C Hamano <gitster@pobox.com>
To: "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, Derrick Stolee <dstolee@microsoft.com>
Subject: Re: [PATCH 1/1] Docs: Add commit-graph tech docs to Makefile
Date: Tue, 21 Aug 2018 11:13:41 -0700 [thread overview]
Message-ID: <xmqqwosj8u5m.fsf@gitster-ct.c.googlers.com> (raw)
In-Reply-To: <ef5af2ccc7ea662a4059d118772cdbe282fc7e43.1534855978.git.gitgitgadget@gmail.com> (Derrick Stolee via GitGitGadget's message of "Tue, 21 Aug 2018 05:53:01 -0700 (PDT)")
"Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 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.
next prev parent reply other threads:[~2018-08-21 18:13 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-08-21 12:53 [PATCH 0/1] Docs: Add commit-graph tech docs to Makefile Derrick Stolee via GitGitGadget
2018-08-21 12:53 ` [PATCH 1/1] " Derrick Stolee via GitGitGadget
2018-08-21 18:13 ` Junio C Hamano [this message]
2018-08-21 19:29 ` [PATCH v2 0/2] " Derrick Stolee via GitGitGadget
2018-08-21 19:29 ` [PATCH v2 1/2] " Derrick Stolee via GitGitGadget
2018-08-21 19:29 ` [PATCH v2 2/2] commit-graph.txt: improve formatting for asciidoc Derrick Stolee via GitGitGadget
2018-08-21 19:35 ` Eric Sunshine
2018-08-21 21:29 ` Junio C Hamano
2018-08-22 1:19 ` Derrick Stolee
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqwosj8u5m.fsf@gitster-ct.c.googlers.com \
--to=gitster@pobox.com \
--cc=dstolee@microsoft.com \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).