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

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

[Derrick Stolee via GitGitGadget]

Similar to [1], add the commit-graph and commit-graph-format technical docs
to Documentation/Makefile so they are automatically converted to HTML when
needed.

I compiled the docs and inspected the HTML manually in the browser. Nothing
looked strange, so I don't think the docs themselves need any editing for
format.

[1] 
https://public-inbox.org/git/20180814222846.GG142615@aiede.svl.corp.google.com/
[PATCH] partial-clone: render design doc using asciidoc

Derrick Stolee (1):
  Docs: Add commit-graph tech docs to Makefile

 Documentation/Makefile | 2 ++
 1 file changed, 2 insertions(+)


base-commit: 53f9a3e157dbbc901a02ac2c73346d375e24978c
Published-As: https://github.com/gitgitgadget/git/releases/tags/pr-22%2Fderrickstolee%2Fmake-docs-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-22/derrickstolee/make-docs-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/22
-- 
gitgitgadget

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

[Derrick Stolee via GitGitGadget]

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
-- 
gitgitgadget

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

[Junio C Hamano]

"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.

[PATCH v2 0/2] Docs: Add commit-graph tech docs to Makefile

[Derrick Stolee via GitGitGadget]

Similar to [1], add the commit-graph and commit-graph-format technical docs
to Documentation/Makefile so they are automatically converted to HTML when
needed.

I compiled the docs and inspected the HTML manually in the browser. As
suggested, I modified the documents to format a bit better. See the commit
messages for details. Since the files had been modified since 'maint', this
version is based on 'master'.

[1] 
https://public-inbox.org/git/20180814222846.GG142615@aiede.svl.corp.google.com/
[PATCH] partial-clone: render design doc using asciidoc

Derrick Stolee (2):
  Docs: Add commit-graph tech docs to Makefile
  commit-graph.txt: improve formatting for asciidoc

 Documentation/Makefile                   |  2 ++
 Documentation/technical/commit-graph.txt | 43 +++++++++++-------------
 2 files changed, 22 insertions(+), 23 deletions(-)


base-commit: fa03cdc39b951d1cfbfd690fe6f3ac6c57ab6a44
Published-As: https://github.com/gitgitgadget/git/releases/tags/pr-22%2Fderrickstolee%2Fmake-docs-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-22/derrickstolee/make-docs-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/22

Range-diff vs v1:

 1:  ef5af2ccc = 1:  4c66af626 Docs: Add commit-graph tech docs to Makefile
 -:  --------- > 2:  6cf253c2a commit-graph.txt: improve formatting for asciidoc

-- 
gitgitgadget

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

[Derrick Stolee via GitGitGadget]

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
-- 
gitgitgadget

[PATCH v2 2/2] commit-graph.txt: improve formatting for asciidoc

[Derrick Stolee via GitGitGadget]

From: Derrick Stolee <dstolee@microsoft.com>

When viewing commit-graph.txt as a plain-text document, it makes
sense to keep paragraphs left-padded between bullet points.
However, asciidoc converts these left-padded paragraphs as monospace
fonts, creating an unpleasant document. Remove the padding.

The "Future Work" section includes a bulleted list of items, and one
item has sub-items. These do not render properly in asciidoc, so
remove the sub-list and incorporate them into the paragraph.

Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
---
 Documentation/technical/commit-graph.txt | 43 +++++++++++-------------
 1 file changed, 20 insertions(+), 23 deletions(-)

diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt
index c664acbd7..bdc3eab9e 100644
--- a/Documentation/technical/commit-graph.txt
+++ b/Documentation/technical/commit-graph.txt
@@ -49,23 +49,23 @@ 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.
+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.
+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.
 
 This property can be used to significantly reduce the time it takes to
 walk commits and determine topological relationships. Without generation
 numbers, the general heuristic is the following:
 
-    If A and B are commits with commit time X and Y, respectively, and
-    X < Y, then A _probably_ cannot reach B.
+If A and B are commits with commit time X and Y, respectively, and
+X < Y, then A _probably_ cannot reach B.
 
 This heuristic is currently used whenever the computation is allowed to
 violate topological relationships due to clock skew (such as "git log"
@@ -121,11 +121,8 @@ Future Work
 - After computing and storing generation numbers, we must make graph
   walks aware of generation numbers to gain the performance benefits they
   enable. This will mostly be accomplished by swapping a commit-date-ordered
-  priority queue with one ordered by generation number. The following
-  operations are important candidates:
-
-    - 'log --topo-order'
-    - 'tag --merged'
+  priority queue with one ordered by generation number. Commands that could
+  improve include 'git log --topo-order' and 'git tag --merged'.
 
 - A server could provide a commit graph file as part of the network protocol
   to avoid extra calculations by clients. This feature is only of benefit if
@@ -148,13 +145,13 @@ Related Links
     More discussion about generation numbers and not storing them inside
     commit objects. A valuable quote:
 
-    "I think we should be moving more in the direction of keeping
-     repo-local caches for optimizations. Reachability bitmaps have been
-     a big performance win. I think we should be doing the same with our
-     properties of commits. Not just generation numbers, but making it
-     cheap to access the graph structure without zlib-inflating whole
-     commit objects (i.e., packv4 or something like the "metapacks" I
-     proposed a few years ago)."
+"I think we should be moving more in the direction of keeping
+ repo-local caches for optimizations. Reachability bitmaps have been
+ a big performance win. I think we should be doing the same with our
+ properties of commits. Not just generation numbers, but making it
+ cheap to access the graph structure without zlib-inflating whole
+ commit objects (i.e., packv4 or something like the "metapacks" I
+ proposed a few years ago)."
 
 [4] https://public-inbox.org/git/20180108154822.54829-1-git@jeffhostetler.com/T/#u
     A patch to remove the ahead-behind calculation from 'status'.
-- 
gitgitgadget

Re: [PATCH v2 2/2] commit-graph.txt: improve formatting for asciidoc

[Eric Sunshine]

On Tue, Aug 21, 2018 at 3:29 PM Derrick Stolee via GitGitGadget
<gitgitgadget@gmail.com> wrote:
> When viewing commit-graph.txt as a plain-text document, it makes
> sense to keep paragraphs left-padded between bullet points.
> However, asciidoc converts these left-padded paragraphs as monospace
> fonts, creating an unpleasant document. Remove the padding.
>
> The "Future Work" section includes a bulleted list of items, and one
> item has sub-items. These do not render properly in asciidoc, so
> remove the sub-list and incorporate them into the paragraph.

See: http://asciidoc.org/userguide.html#_bulleted_lists

And...

> diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt
> @@ -148,13 +145,13 @@ Related Links
> -    "I think we should be moving more in the direction of keeping
> -     repo-local caches for optimizations. Reachability bitmaps have been
> -     a big performance win. I think we should be doing the same with our
> -     properties of commits. Not just generation numbers, but making it
> -     cheap to access the graph structure without zlib-inflating whole
> -     commit objects (i.e., packv4 or something like the "metapacks" I
> -     proposed a few years ago)."
> +"I think we should be moving more in the direction of keeping
> + repo-local caches for optimizations. Reachability bitmaps have been
> + a big performance win. I think we should be doing the same with our
> + properties of commits. Not just generation numbers, but making it
> + cheap to access the graph structure without zlib-inflating whole
> + commit objects (i.e., packv4 or something like the "metapacks" I
> + proposed a few years ago)."

Perhaps this should be using a quote block:
http://asciidoc.org/userguide.html#_quote_blocks

Re: [PATCH v2 2/2] commit-graph.txt: improve formatting for asciidoc

[Junio C Hamano]

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

> From: Derrick Stolee <dstolee@microsoft.com>
>
> When viewing commit-graph.txt as a plain-text document, it makes
> sense to keep paragraphs left-padded between bullet points.
> However, asciidoc converts these left-padded paragraphs as monospace
> fonts, creating an unpleasant document. Remove the padding.

That's completely backwards.

These indented two paragraphs that follow "... the following
property:" do not fall into the same classes of paragraphs as
others.  The way the text version makes them stand out by indenting
clearly show these two are what "... the following ..." refers to.

Perhaps these two would want to become a bulleted list or
something.  

>
> The "Future Work" section includes a bulleted list of items, and one
> item has sub-items. These do not render properly in asciidoc, so
> remove the sub-list and incorporate them into the paragraph.
>
> Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
> ---
>  Documentation/technical/commit-graph.txt | 43 +++++++++++-------------

I said I didn't check if commit-graph-format.txt doc format
correctly, but that does not mean you do not have to ;-).  I suspect
that most of the contents would become monospaced wall of text,
which is no better than the original text and because only the
headings are typeset in different font, the result actually would be
harder to read than the original.

We are not in a hurry to do this during the pre-release period, are
we?  My understanding is that the original text documentation files
will be shipped and installed, and they are adequately readable
(correct me if it is not the case).

Unless we are making the result a lot more readable as the original
text, let's not distract ourselves by rerolling this in too quick
cycles without giving us sufficiently big improvements.

Thanks.

Re: [PATCH v2 2/2] commit-graph.txt: improve formatting for asciidoc

[Derrick Stolee]

On 8/21/2018 5:29 PM, Junio C Hamano wrote:
> "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Derrick Stolee <dstolee@microsoft.com>
>>
>> When viewing commit-graph.txt as a plain-text document, it makes
>> sense to keep paragraphs left-padded between bullet points.
>> However, asciidoc converts these left-padded paragraphs as monospace
>> fonts, creating an unpleasant document. Remove the padding.
> That's completely backwards.
>
> These indented two paragraphs that follow "... the following
> property:" do not fall into the same classes of paragraphs as
> others.  The way the text version makes them stand out by indenting
> clearly show these two are what "... the following ..." refers to.
>
> Perhaps these two would want to become a bulleted list or
> something.
>
>> The "Future Work" section includes a bulleted list of items, and one
>> item has sub-items. These do not render properly in asciidoc, so
>> remove the sub-list and incorporate them into the paragraph.
>>
>> Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
>> ---
>>   Documentation/technical/commit-graph.txt | 43 +++++++++++-------------
> I said I didn't check if commit-graph-format.txt doc format
> correctly, but that does not mean you do not have to ;-).  I suspect
> that most of the contents would become monospaced wall of text,
> which is no better than the original text and because only the
> headings are typeset in different font, the result actually would be
> harder to read than the original.

I compared the results of commit-graph-format.txt to pack-format.txt. 
Since I had based the format of commit-graph-format.txt on that file, 
the output was remarkably similar (and hence I couldn't find anything to 
change).

> We are not in a hurry to do this during the pre-release period, are
> we?  My understanding is that the original text documentation files
> will be shipped and installed, and they are adequately readable
> (correct me if it is not the case).
>
> Unless we are making the result a lot more readable as the original
> text, let's not distract ourselves by rerolling this in too quick
> cycles without giving us sufficiently big improvements.
No rush! I'll wait until the release calms down for a v3, and read the 
helpful docs on asciidoc format that Eric shared earlier.

Thanks,
-Stolee