Docs: Add commit-graph tech docs to Makefile
cover Docs: Add commit-graph tech docs to Makefile
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/[email protected]/
[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
Signature · 1 line
gitgitgadget
PATCH 1/1 Docs: Add commit-graph tech docs to Makefile
From: Derrick Stolee <[email protected]>
Ensure that the commit-graph.txt and commit-graph-format.txt files are compiled to HTML using ASCIIDOC.
--- Documentation/Makefile | 2 ++ 1 file changed, 2 insertions(+)
Documentation/Makefile +2 -0
@@ -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
Signature · 1 line
gitgitgadget
Quoted 15 lines · Derrick Stolee via GitGitGadget
From: Derrick Stolee <[email protected]>
Ensure that the commit-graph.txt and commit-graph-format.txt files are compiled to HTML using ASCIIDOC.
Signed-off-by Derrick Stolee <[email protected]>--- Documentation/Makefile | 2 ++ 1 file changed, 2 insertions(+)Documentation/Makefile +0
-0
Documentation/Makefile API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technica · line 76
Quoted 8 lines
Documentation/Makefile +2
-0@@ -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.
v2 cover Docs: Add commit-graph tech docs to Makefile
In reply to Derrick Stolee via GitGitGadgetSimilar 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/[email protected]/
[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
Signature · 1 line
gitgitgadget
PATCH v2 1/2 Docs: Add commit-graph tech docs to Makefile
From: Derrick Stolee <[email protected]>
Ensure that the commit-graph.txt and commit-graph-format.txt files are compiled to HTML using ASCIIDOC.
--- Documentation/Makefile | 2 ++ 1 file changed, 2 insertions(+)
Documentation/Makefile +2 -0
@@ -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
Signature · 1 line
gitgitgadget
PATCH v2 2/2 commit-graph.txt: improve formatting for asciidoc
In reply to Derrick Stolee via GitGitGadgetFrom: Derrick Stolee <[email protected]>
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.
--- Documentation/technical/commit-graph.txt | 43 +++++++++++------------- 1 file changed, 20 insertions(+), 23 deletions(-)
Documentation/technical/commit-graph.txt +20 -23
@@ -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/[email protected]/T/#u A patch to remove the ahead-behind calculation from 'status'.
Signature · 1 line
gitgitgadget
Re: [PATCH v2 2/2] commit-graph.txt: improve formatting for asciidoc
Quoted 8 lines · Derrick Stolee via GitGitGadget
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...
Quoted 6 lines
Documentation/technical/commit-graph.txt +0
-4@@ -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
Documentation/technical/commit-graph.txt Related Links · line 151
Quoted 10 lines
Documentation/technical/commit-graph.txt +7
-3- 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
In reply to Derrick Stolee via GitGitGadgetQuoted 6 lines · Derrick Stolee via GitGitGadget
From: Derrick Stolee <[email protected]>
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.
Quoted 8 lines
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 <[email protected]>--- 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
Quoted 25 lines · Junio C Hamano
Quoted 6 lines · Derrick Stolee via GitGitGadget
From: Derrick Stolee <[email protected]>
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.
Quoted 7 lines
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 <[email protected]>--- Documentation/technical/commit-graph.txt | 43 +++++++++++-------------
Quoted 6 lines
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).
Quoted 8 lines
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