Re: [PATCH] doc: fix merge-base ASCII art tab spacing

From: Philip Oakley <philipoakley@iee.org>
Date: Oct 21, 2016, 21:26 UTC
Message-ID: <D861234B3E78496DBA70EE63B2BCDB96@PhilipOakley>
In-Reply-To: <xmqqa8dyeebj.fsf@gitster.mtv.corp.google.com>

From: "Junio C Hamano" <gitster@pobox.com>

Show 14 quoted lines

> Philip Oakley <philipoakley@iee.org> writes:
>
>> The doc-tool stack does not always respect the 'tab = 8 spaces' rule,
>> particularly the git-scm doc pages 
>> https://git-scm.com/docs/git-merge-base
>> and the Git generated html pages.
>
> Sorry, but I do not understand this change.
>
> https://git.github.io/htmldocs/git-merge-base.html is "Git generated
> HTML page" and I do not see any breakage around the drawings this
> patch touches, and the fp-path series does not touch these drawings,
> either.
>

I'd been looking the Git for Windows output, which has the same breakage, rather than yours. Apologies for failing to check there.

> If a broken "doc-tool stack" breaks the formatting, I'd prefer to
> see that "doc-tool stack" fixed, instead of working around by

The doc-tool stack is question is asciidoctor. It looks like it is an explicit decision that the the 8 space tab substitution is deprecated in these case (see http://asciidoctor.org/docs/user-manual/#migrate-deprecated #96.3)

It appears that acciidoctor sees the art as being a separated mono-spaced block, with border/background as locally appropriate. While the asciidoc looks to simply change to mono-spaced text.

> updating the source they work on.  Otherwise, the broken "doc-tool
> stack" will keep producing broken output next time a source that
> respects "tab is to skip to the next multiple of 8" rule is fed to
> it, no?

By avoiding tabs *within the art* we would also be tolerant of those who may not have a set their tab spacing to 8 when viewing the raw text.

It's particularly the criss-cross diagram that needs fixed one way or another (for the doc/doctor differences).

The update of the asciidoctor version for git-scm, as reported by peff isn't sufficient for this case.

also cc'ing dscho as this breakage shows in GfW (issue 923)

Philip