patchDocs: 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/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

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(+)

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

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.

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

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(+)

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(-)

On Tue, Aug 21, 2018 at 3:29 PM Derrick Stolee via GitGitGadget <gitgitgadget@gmail.com> wrote:

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

And...

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

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

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.

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.

On 8/21/2018 5:29 PM, Junio C Hamano wrote:

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

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