[PATCH] Doc: fix misleading asciidoc formating

[PATCH] Doc: fix misleading asciidoc formating

[Jean-Noël Avila]

The end of sentence in "x." at the begining of a line misleads
ascidoctor into interpreting it as the start of numbered sub-list.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/technical/directory-rename-detection.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/technical/directory-rename-detection.txt b/Documentation/technical/directory-rename-detection.txt
index 1c0086e287..844629c8c4 100644
--- a/Documentation/technical/directory-rename-detection.txt
+++ b/Documentation/technical/directory-rename-detection.txt
@@ -20,8 +20,8 @@ More interesting possibilities exist, though, such as:
   * one side of history renames x -> z, and the other renames some file to
     x/e, causing the need for the merge to do a transitive rename.
 
-  * one side of history renames x -> z, but also renames all files within
-    x.  For example, x/a -> z/alpha, x/b -> z/bravo, etc.
+  * one side of history renames x -> z, but also renames all files within x.
+    For example, x/a -> z/alpha, x/b -> z/bravo, etc.
 
   * both 'x' and 'y' being merged into a single directory 'z', with a
     directory rename being detected for both x->z and y->z.
-- 
2.21.0

Re: [PATCH] Doc: fix misleading asciidoc formating

[Jeff King]

On Tue, Mar 05, 2019 at 10:44:23PM +0100, Jean-Noël Avila wrote:

> The end of sentence in "x." at the begining of a line misleads
> ascidoctor into interpreting it as the start of numbered sub-list.

Because I'd been wanting to play with doc-diff and asciidoctor, I tried
looking at the rendered diff. However, I couldn't see any difference!

Did you notice this when building locally, or on the asciidoctor-built
pages at git-scm.com? If the latter, I wonder if we might need to update
our version of asciidoctor there (it looks like we're on v1.5.6.1 there,
but my local asciidoctor binary is v1.5.8).

-Peff

Re: [PATCH] Doc: fix misleading asciidoc formating

[Junio C Hamano]

Jean-Noël Avila <jn.avila@free.fr> writes:

> The end of sentence in "x." at the begining of a line misleads
> ascidoctor into interpreting it as the start of numbered sub-list.

Wow.  That's tricky.

One thing that makes me wonder is how you found it, as I do not
think this file is part of the set of Documentation/technical/ files
that are usually touched by "make doc".

> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
>  Documentation/technical/directory-rename-detection.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/technical/directory-rename-detection.txt b/Documentation/technical/directory-rename-detection.txt
> index 1c0086e287..844629c8c4 100644
> --- a/Documentation/technical/directory-rename-detection.txt
> +++ b/Documentation/technical/directory-rename-detection.txt
> @@ -20,8 +20,8 @@ More interesting possibilities exist, though, such as:
>    * one side of history renames x -> z, and the other renames some file to
>      x/e, causing the need for the merge to do a transitive rename.
>  
> -  * one side of history renames x -> z, but also renames all files within
> -    x.  For example, x/a -> z/alpha, x/b -> z/bravo, etc.
> +  * one side of history renames x -> z, but also renames all files within x.
> +    For example, x/a -> z/alpha, x/b -> z/bravo, etc.
>  
>    * both 'x' and 'y' being merged into a single directory 'z', with a
>      directory rename being detected for both x->z and y->z.

Re: [PATCH] Doc: fix misleading asciidoc formating

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> Did you notice this when building locally, or on the asciidoctor-built
> pages at git-scm.com?

Does git-scm.com even have this file rendered?  I do not think we
glob for technical/*.txt in any of our Makefiles; instead we have a
list of ready-to-be-consumed TECH_DOCS listed explicitly.

Re: [PATCH] Doc: fix misleading asciidoc formating

[Jeff King]

On Wed, Mar 06, 2019 at 07:54:20AM +0900, Junio C Hamano wrote:

> Jeff King <peff@peff.net> writes:
> 
> > Did you notice this when building locally, or on the asciidoctor-built
> > pages at git-scm.com?
> 
> Does git-scm.com even have this file rendered?  I do not think we
> glob for technical/*.txt in any of our Makefiles; instead we have a
> list of ready-to-be-consumed TECH_DOCS listed explicitly.

It is rendered, at https://git-scm.com/docs/directory-rename-detection.

However, that explains why doc-diff did not find anything; it only looks
at the results of "make install-man", which does not include any
technical docs (let alone this one that is not mentioned in
$(TECH_DOCS).

-Peff

Re: [PATCH] Doc: fix misleading asciidoc formating

[Jeff King]

On Tue, Mar 05, 2019 at 06:02:27PM -0500, Jeff King wrote:

> On Wed, Mar 06, 2019 at 07:54:20AM +0900, Junio C Hamano wrote:
> 
> > Jeff King <peff@peff.net> writes:
> > 
> > > Did you notice this when building locally, or on the asciidoctor-built
> > > pages at git-scm.com?
> > 
> > Does git-scm.com even have this file rendered?  I do not think we
> > glob for technical/*.txt in any of our Makefiles; instead we have a
> > list of ready-to-be-consumed TECH_DOCS listed explicitly.
> 
> It is rendered, at https://git-scm.com/docs/directory-rename-detection.

By the way, that rendering shows that the whole document could probably
use a few tweaks to make its asciidoc formatting look good (in addition
to the "x." thing that Jean-Noël fixed here, which can also be seen
there).

TBH, I still have mixed feelings on rendering these technical docs with
asciidoc at all. It seems like few enough people bother to render them
that bugs persist for a long time. It kind of seems like make-work
getting them to format correctly.

-Peff

Re: [PATCH] Doc: fix misleading asciidoc formating

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> TBH, I still have mixed feelings on rendering these technical docs with
> asciidoc at all. It seems like few enough people bother to render them
> that bugs persist for a long time. It kind of seems like make-work
> getting them to format correctly.

I thought about resisting when some people started pushing for
rendering everything under the Sun, but went with the flow as I
lacked the energy to fight every battle in sight.

Good to see somebody shares a similar sense of trade-off, better
late than never ;-).

Re: [PATCH] Doc: fix misleading asciidoc formating

[Jean-Noël Avila]

On 2019-03-06, Junio Hamano, Jeff King wrote:> Jeff King <peff@peff.net>
writes
> 
>> TBH, I still have mixed feelings on rendering these technical docs with
>> asciidoc at all. It seems like few enough people bother to render them
>> that bugs persist for a long time. It kind of seems like make-work
>> getting them to format correctly.
> 
> I thought about resisting when some people started pushing for
> rendering everything under the Sun, but went with the flow as I
> lacked the energy to fight every battle in sight.
> 
> Good to see somebody shares a similar sense of trade-off, better
> late than never ;-).
> 

TBH, I discovered this while diving into the rendering on manpages for
the localized version because asciidoctor issued a warning, and pushed
this patch for "cultural" knowledge (sometimes, automatic linefeed
triggers unintended behaviors). But, as Peff noted, this may not be a
good idea to render these documents at all on git-scm.com.

In this case, there's no point in tracking rendering issues outside
genuine manpages.

Re: [PATCH] Doc: fix misleading asciidoc formating

[Jeff King]

On Wed, Mar 06, 2019 at 09:07:11AM +0100, Jean-Noël Avila wrote:

> TBH, I discovered this while diving into the rendering on manpages for
> the localized version because asciidoctor issued a warning, and pushed
> this patch for "cultural" knowledge (sometimes, automatic linefeed
> triggers unintended behaviors). But, as Peff noted, this may not be a
> good idea to render these documents at all on git-scm.com.

Ah, that makes sense. I do think this is an interesting gotcha, and I'm
glad to have learned about it. So even if we don't apply your patch and
it serves as an interesting report, I think it was still worth it.

(Though I am also happy to see it applied since you went to the trouble
to make it).

-Peff

Re: [PATCH] Doc: fix misleading asciidoc formating

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> (Though I am also happy to see it applied since you went to the trouble
> to make it).

Yup.