{"thread":{"id":"49177","subject":"[PATCH 0/1] Docs: Add commit-graph tech docs to Makefile","startedAt":"2018-08-21T12:53:03Z","lastAt":"2018-08-22T01:19:29Z","messageCount":9,"participants":["Derrick Stolee via GitGitGadget","Junio C Hamano","Eric Sunshine","Derrick Stolee"],"isPatch":true,"patchVersion":1,"patchTotal":1},"messages":[{"id":"356165","messageId":"pull.22.git.gitgitgadget@gmail.com","threadId":"49177","inReplyTo":null,"subject":"[PATCH 0/1] Docs: Add commit-graph tech docs to Makefile","fromName":"Derrick Stolee via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2018-08-21T12:53:00Z","receivedAt":"2018-08-21T12:53:03Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"Similar to [1], add the commit-graph and commit-graph-format technical docs\nto Documentation/Makefile so they are automatically converted to HTML when\nneeded.\n\nI compiled the docs and inspected the HTML manually in the browser. Nothing\nlooked strange, so I don't think the docs themselves need any editing for\nformat.\n\n[1] \nhttps://public-inbox.org/git/20180814222846.GG142615@aiede.svl.corp.google.com/\n[PATCH] partial-clone: render design doc using asciidoc\n\nDerrick Stolee (1):\n  Docs: Add commit-graph tech docs to Makefile\n\n Documentation/Makefile | 2 ++\n 1 file changed, 2 insertions(+)\n\n\nbase-commit: 53f9a3e157dbbc901a02ac2c73346d375e24978c\nPublished-As: https://github.com/gitgitgadget/git/releases/tags/pr-22%2Fderrickstolee%2Fmake-docs-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-22/derrickstolee/make-docs-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/22\n-- \ngitgitgadget\n"},{"id":"356166","messageId":"ef5af2ccc7ea662a4059d118772cdbe282fc7e43.1534855978.git.gitgitgadget@gmail.com","threadId":"49177","inReplyTo":"pull.22.git.gitgitgadget@gmail.com","subject":"[PATCH 1/1] Docs: Add commit-graph tech docs to Makefile","fromName":"Derrick Stolee via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2018-08-21T12:53:01Z","receivedAt":"2018-08-21T12:53:04Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"From: Derrick Stolee <dstolee@microsoft.com>\n\nEnsure that the commit-graph.txt and commit-graph-format.txt files\nare compiled to HTML using ASCIIDOC.\n\nSigned-off-by: Derrick Stolee <dstolee@microsoft.com>\n---\n Documentation/Makefile | 2 ++\n 1 file changed, 2 insertions(+)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex d079d7c73..841e4f705 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -69,6 +69,8 @@ API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technica\n SP_ARTICLES += $(API_DOCS)\n \n TECH_DOCS += SubmittingPatches\n+TECH_DOCS += technical/commit-graph\n+TECH_DOCS += technical/commit-graph-format\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n TECH_DOCS += technical/index-format\n-- \ngitgitgadget\n"},{"id":"356179","messageId":"xmqqwosj8u5m.fsf@gitster-ct.c.googlers.com","threadId":"49177","inReplyTo":"ef5af2ccc7ea662a4059d118772cdbe282fc7e43.1534855978.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/1] Docs: Add commit-graph tech docs to Makefile","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-08-21T18:13:41Z","receivedAt":"2018-08-21T18:13:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Derrick Stolee via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Derrick Stolee <dstolee@microsoft.com>\n>\n> Ensure that the commit-graph.txt and commit-graph-format.txt files\n> are compiled to HTML using ASCIIDOC.\n>\n> Signed-off-by: Derrick Stolee <dstolee@microsoft.com>\n> ---\n>  Documentation/Makefile | 2 ++\n>  1 file changed, 2 insertions(+)\n>\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index d079d7c73..841e4f705 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -69,6 +69,8 @@ API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technica\n>  SP_ARTICLES += $(API_DOCS)\n>  \n>  TECH_DOCS += SubmittingPatches\n> +TECH_DOCS += technical/commit-graph\n> +TECH_DOCS += technical/commit-graph-format\n>  TECH_DOCS += technical/hash-function-transition\n>  TECH_DOCS += technical/http-protocol\n>  TECH_DOCS += technical/index-format\n\nLooking at what 5641eb94 (\"partial-clone: render design doc using\nasciidoc\", 2018-08-14) had to do to make the straight text usable as\nAsciiDoc input, I do not think a patch to D/Makefile alone is\nsufficient; just quick skim of the source makes a reader notice a\nblock of text like this:\n\n    Equivalently, the generation number of a commit A is one more than the\n    length of a longest path from A to a root commit. The recursive definition\n    is easier to use for computation and observing the following property:\n\n        If A and B are commits with generation numbers N and M, respectively,\n        and N <= M, then A cannot reach B. That is, we know without searching\n        that B is not an ancestor of A because it is further from a root commit\n        than A.\n\n        Conversely, when checking if A is an ancestor of B, then we only need\n        to walk commits until all commits on the walk boundary have generation\n        number at most N. If we walk commits using a priority queue seeded by\n        generation numbers, then we always expand the boundary commit with highest\n        generation number and can easily detect the stopping condition.\n\nwhich would give you two paragraphs that are typeset in monospace,\nwithout giving enough visual cue that these two are the \"following\nproperties\" the previous paragraph talks about, like the original\nplain-text does.\n\nI haven't checked the \"-format\" document, but I suspect both of\nthese are easier to read in text than in HTML formatted without\ntweaking the mark-up a bit.  It's not like we are not shipping the\ntext versions; let's not give readers HTML that is uglier than text.\n"},{"id":"356197","messageId":"pull.22.v2.git.gitgitgadget@gmail.com","threadId":"49177","inReplyTo":"pull.22.git.gitgitgadget@gmail.com","subject":"[PATCH v2 0/2] Docs: Add commit-graph tech docs to Makefile","fromName":"Derrick Stolee via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2018-08-21T19:29:10Z","receivedAt":"2018-08-21T19:29:14Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"Similar to [1], add the commit-graph and commit-graph-format technical docs\nto Documentation/Makefile so they are automatically converted to HTML when\nneeded.\n\nI compiled the docs and inspected the HTML manually in the browser. As\nsuggested, I modified the documents to format a bit better. See the commit\nmessages for details. Since the files had been modified since 'maint', this\nversion is based on 'master'.\n\n[1] \nhttps://public-inbox.org/git/20180814222846.GG142615@aiede.svl.corp.google.com/\n[PATCH] partial-clone: render design doc using asciidoc\n\nDerrick Stolee (2):\n  Docs: Add commit-graph tech docs to Makefile\n  commit-graph.txt: improve formatting for asciidoc\n\n Documentation/Makefile                   |  2 ++\n Documentation/technical/commit-graph.txt | 43 +++++++++++-------------\n 2 files changed, 22 insertions(+), 23 deletions(-)\n\n\nbase-commit: fa03cdc39b951d1cfbfd690fe6f3ac6c57ab6a44\nPublished-As: https://github.com/gitgitgadget/git/releases/tags/pr-22%2Fderrickstolee%2Fmake-docs-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-22/derrickstolee/make-docs-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/22\n\nRange-diff vs v1:\n\n 1:  ef5af2ccc = 1:  4c66af626 Docs: Add commit-graph tech docs to Makefile\n -:  --------- > 2:  6cf253c2a commit-graph.txt: improve formatting for asciidoc\n\n-- \ngitgitgadget\n"},{"id":"356196","messageId":"4c66af6262b17f856f8ea35676f753058d12d6e2.1534879749.git.gitgitgadget@gmail.com","threadId":"49177","inReplyTo":"pull.22.v2.git.gitgitgadget@gmail.com","subject":"[PATCH v2 1/2] Docs: Add commit-graph tech docs to Makefile","fromName":"Derrick Stolee via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2018-08-21T19:29:12Z","receivedAt":"2018-08-21T19:29:15Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"From: Derrick Stolee <dstolee@microsoft.com>\n\nEnsure that the commit-graph.txt and commit-graph-format.txt files\nare compiled to HTML using ASCIIDOC.\n\nSigned-off-by: Derrick Stolee <dstolee@microsoft.com>\n---\n Documentation/Makefile | 2 ++\n 1 file changed, 2 insertions(+)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex d079d7c73..841e4f705 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -69,6 +69,8 @@ API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technica\n SP_ARTICLES += $(API_DOCS)\n \n TECH_DOCS += SubmittingPatches\n+TECH_DOCS += technical/commit-graph\n+TECH_DOCS += technical/commit-graph-format\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\n TECH_DOCS += technical/index-format\n-- \ngitgitgadget\n\n"},{"id":"356198","messageId":"6cf253c2a6a091520e1376839dff8b97869c9808.1534879749.git.gitgitgadget@gmail.com","threadId":"49177","inReplyTo":"pull.22.v2.git.gitgitgadget@gmail.com","subject":"[PATCH v2 2/2] commit-graph.txt: improve formatting for asciidoc","fromName":"Derrick Stolee via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2018-08-21T19:29:13Z","receivedAt":"2018-08-21T19:29:16Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"From: Derrick Stolee <dstolee@microsoft.com>\n\nWhen viewing commit-graph.txt as a plain-text document, it makes\nsense to keep paragraphs left-padded between bullet points.\nHowever, asciidoc converts these left-padded paragraphs as monospace\nfonts, creating an unpleasant document. Remove the padding.\n\nThe \"Future Work\" section includes a bulleted list of items, and one\nitem has sub-items. These do not render properly in asciidoc, so\nremove the sub-list and incorporate them into the paragraph.\n\nSigned-off-by: Derrick Stolee <dstolee@microsoft.com>\n---\n Documentation/technical/commit-graph.txt | 43 +++++++++++-------------\n 1 file changed, 20 insertions(+), 23 deletions(-)\n\ndiff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt\nindex c664acbd7..bdc3eab9e 100644\n--- a/Documentation/technical/commit-graph.txt\n+++ b/Documentation/technical/commit-graph.txt\n@@ -49,23 +49,23 @@ Equivalently, the generation number of a commit A is one more than the\n length of a longest path from A to a root commit. The recursive definition\n is easier to use for computation and observing the following property:\n \n-    If A and B are commits with generation numbers N and M, respectively,\n-    and N <= M, then A cannot reach B. That is, we know without searching\n-    that B is not an ancestor of A because it is further from a root commit\n-    than A.\n+If A and B are commits with generation numbers N and M, respectively,\n+and N <= M, then A cannot reach B. That is, we know without searching\n+that B is not an ancestor of A because it is further from a root commit\n+than A.\n \n-    Conversely, when checking if A is an ancestor of B, then we only need\n-    to walk commits until all commits on the walk boundary have generation\n-    number at most N. If we walk commits using a priority queue seeded by\n-    generation numbers, then we always expand the boundary commit with highest\n-    generation number and can easily detect the stopping condition.\n+Conversely, when checking if A is an ancestor of B, then we only need\n+to walk commits until all commits on the walk boundary have generation\n+number at most N. If we walk commits using a priority queue seeded by\n+generation numbers, then we always expand the boundary commit with highest\n+generation number and can easily detect the stopping condition.\n \n This property can be used to significantly reduce the time it takes to\n walk commits and determine topological relationships. Without generation\n numbers, the general heuristic is the following:\n \n-    If A and B are commits with commit time X and Y, respectively, and\n-    X < Y, then A _probably_ cannot reach B.\n+If A and B are commits with commit time X and Y, respectively, and\n+X < Y, then A _probably_ cannot reach B.\n \n This heuristic is currently used whenever the computation is allowed to\n violate topological relationships due to clock skew (such as \"git log\"\n@@ -121,11 +121,8 @@ Future Work\n - After computing and storing generation numbers, we must make graph\n   walks aware of generation numbers to gain the performance benefits they\n   enable. This will mostly be accomplished by swapping a commit-date-ordered\n-  priority queue with one ordered by generation number. The following\n-  operations are important candidates:\n-\n-    - 'log --topo-order'\n-    - 'tag --merged'\n+  priority queue with one ordered by generation number. Commands that could\n+  improve include 'git log --topo-order' and 'git tag --merged'.\n \n - A server could provide a commit graph file as part of the network protocol\n   to avoid extra calculations by clients. This feature is only of benefit if\n@@ -148,13 +145,13 @@ Related Links\n     More discussion about generation numbers and not storing them inside\n     commit objects. A valuable quote:\n \n-    \"I think we should be moving more in the direction of keeping\n-     repo-local caches for optimizations. Reachability bitmaps have been\n-     a big performance win. I think we should be doing the same with our\n-     properties of commits. Not just generation numbers, but making it\n-     cheap to access the graph structure without zlib-inflating whole\n-     commit objects (i.e., packv4 or something like the \"metapacks\" I\n-     proposed a few years ago).\"\n+\"I think we should be moving more in the direction of keeping\n+ repo-local caches for optimizations. Reachability bitmaps have been\n+ a big performance win. I think we should be doing the same with our\n+ properties of commits. Not just generation numbers, but making it\n+ cheap to access the graph structure without zlib-inflating whole\n+ commit objects (i.e., packv4 or something like the \"metapacks\" I\n+ proposed a few years ago).\"\n \n [4] https://public-inbox.org/git/20180108154822.54829-1-git@jeffhostetler.com/T/#u\n     A patch to remove the ahead-behind calculation from 'status'.\n-- \ngitgitgadget\n"},{"id":"356200","messageId":"CAPig+cR7OuF8LfZFY-b6egCOn0-p1uC5KeerhOig5FAC4rqrrw@mail.gmail.com","threadId":"49177","inReplyTo":"6cf253c2a6a091520e1376839dff8b97869c9808.1534879749.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 2/2] commit-graph.txt: improve formatting for asciidoc","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2018-08-21T19:35:40Z","receivedAt":"2018-08-21T19:35:54Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Tue, Aug 21, 2018 at 3:29 PM Derrick Stolee via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n> When viewing commit-graph.txt as a plain-text document, it makes\n> sense to keep paragraphs left-padded between bullet points.\n> However, asciidoc converts these left-padded paragraphs as monospace\n> fonts, creating an unpleasant document. Remove the padding.\n>\n> The \"Future Work\" section includes a bulleted list of items, and one\n> item has sub-items. These do not render properly in asciidoc, so\n> remove the sub-list and incorporate them into the paragraph.\n\nSee: http://asciidoc.org/userguide.html#_bulleted_lists\n\nAnd...\n\n> diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt\n> @@ -148,13 +145,13 @@ Related Links\n> -    \"I think we should be moving more in the direction of keeping\n> -     repo-local caches for optimizations. Reachability bitmaps have been\n> -     a big performance win. I think we should be doing the same with our\n> -     properties of commits. Not just generation numbers, but making it\n> -     cheap to access the graph structure without zlib-inflating whole\n> -     commit objects (i.e., packv4 or something like the \"metapacks\" I\n> -     proposed a few years ago).\"\n> +\"I think we should be moving more in the direction of keeping\n> + repo-local caches for optimizations. Reachability bitmaps have been\n> + a big performance win. I think we should be doing the same with our\n> + properties of commits. Not just generation numbers, but making it\n> + cheap to access the graph structure without zlib-inflating whole\n> + commit objects (i.e., packv4 or something like the \"metapacks\" I\n> + proposed a few years ago).\"\n\nPerhaps this should be using a quote block:\nhttp://asciidoc.org/userguide.html#_quote_blocks\n"},{"id":"356219","messageId":"xmqqtvnn76i4.fsf@gitster-ct.c.googlers.com","threadId":"49177","inReplyTo":"6cf253c2a6a091520e1376839dff8b97869c9808.1534879749.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 2/2] commit-graph.txt: improve formatting for asciidoc","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-08-21T21:29:55Z","receivedAt":"2018-08-21T21:29:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Derrick Stolee via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Derrick Stolee <dstolee@microsoft.com>\n>\n> When viewing commit-graph.txt as a plain-text document, it makes\n> sense to keep paragraphs left-padded between bullet points.\n> However, asciidoc converts these left-padded paragraphs as monospace\n> fonts, creating an unpleasant document. Remove the padding.\n\nThat's completely backwards.\n\nThese indented two paragraphs that follow \"... the following\nproperty:\" do not fall into the same classes of paragraphs as\nothers.  The way the text version makes them stand out by indenting\nclearly show these two are what \"... the following ...\" refers to.\n\nPerhaps these two would want to become a bulleted list or\nsomething.  \n\n>\n> The \"Future Work\" section includes a bulleted list of items, and one\n> item has sub-items. These do not render properly in asciidoc, so\n> remove the sub-list and incorporate them into the paragraph.\n>\n> Signed-off-by: Derrick Stolee <dstolee@microsoft.com>\n> ---\n>  Documentation/technical/commit-graph.txt | 43 +++++++++++-------------\n\nI said I didn't check if commit-graph-format.txt doc format\ncorrectly, but that does not mean you do not have to ;-).  I suspect\nthat most of the contents would become monospaced wall of text,\nwhich is no better than the original text and because only the\nheadings are typeset in different font, the result actually would be\nharder to read than the original.\n\nWe are not in a hurry to do this during the pre-release period, are\nwe?  My understanding is that the original text documentation files\nwill be shipped and installed, and they are adequately readable\n(correct me if it is not the case).\n\nUnless we are making the result a lot more readable as the original\ntext, let's not distract ourselves by rerolling this in too quick\ncycles without giving us sufficiently big improvements.\n\nThanks.\n"},{"id":"356228","messageId":"b21df6d2-19a4-766f-fea0-778c92785410@gmail.com","threadId":"49177","inReplyTo":"xmqqtvnn76i4.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH v2 2/2] commit-graph.txt: improve formatting for asciidoc","fromName":"Derrick Stolee","fromEmail":"stolee@gmail.com","sentAt":"2018-08-22T01:19:23Z","receivedAt":"2018-08-22T01:19:29Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 8/21/2018 5:29 PM, Junio C Hamano wrote:\n> \"Derrick Stolee via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n>> From: Derrick Stolee <dstolee@microsoft.com>\n>>\n>> When viewing commit-graph.txt as a plain-text document, it makes\n>> sense to keep paragraphs left-padded between bullet points.\n>> However, asciidoc converts these left-padded paragraphs as monospace\n>> fonts, creating an unpleasant document. Remove the padding.\n> That's completely backwards.\n>\n> These indented two paragraphs that follow \"... the following\n> property:\" do not fall into the same classes of paragraphs as\n> others.  The way the text version makes them stand out by indenting\n> clearly show these two are what \"... the following ...\" refers to.\n>\n> Perhaps these two would want to become a bulleted list or\n> something.\n>\n>> The \"Future Work\" section includes a bulleted list of items, and one\n>> item has sub-items. These do not render properly in asciidoc, so\n>> remove the sub-list and incorporate them into the paragraph.\n>>\n>> Signed-off-by: Derrick Stolee <dstolee@microsoft.com>\n>> ---\n>>   Documentation/technical/commit-graph.txt | 43 +++++++++++-------------\n> I said I didn't check if commit-graph-format.txt doc format\n> correctly, but that does not mean you do not have to ;-).  I suspect\n> that most of the contents would become monospaced wall of text,\n> which is no better than the original text and because only the\n> headings are typeset in different font, the result actually would be\n> harder to read than the original.\n\nI compared the results of commit-graph-format.txt to pack-format.txt. \nSince I had based the format of commit-graph-format.txt on that file, \nthe output was remarkably similar (and hence I couldn't find anything to \nchange).\n\n> We are not in a hurry to do this during the pre-release period, are\n> we?  My understanding is that the original text documentation files\n> will be shipped and installed, and they are adequately readable\n> (correct me if it is not the case).\n>\n> Unless we are making the result a lot more readable as the original\n> text, let's not distract ourselves by rerolling this in too quick\n> cycles without giving us sufficiently big improvements.\nNo rush! I'll wait until the release calms down for a v3, and read the \nhelpful docs on asciidoc format that Eric shared earlier.\n\nThanks,\n-Stolee\n"}]}