threads / patch / 50660

patchDoc: fix misleading asciidoc formating

Subject: [PATCH] Doc: fix misleading asciidoc formating

## tl;dr

10 messages between Mar 5, 2019 and Mar 6, 2019. Diffs are folded; open one to read it.

replies: 9people: 3as markdown or json

Jean-Noël Avila· Mar 5, 2019, 21:44 UTC · lore

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(-)
Show changes to Documentation/technical/directory-rename-detection.txt +2 −2
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
Jeff King· Mar 5, 2019, 22:36 UTC · re: Jean-Noël Avila · lore

Re: [PATCH] Doc: fix misleading asciidoc formating

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
Junio C Hamano· Mar 5, 2019, 22:54 UTC · re: Jeff King · lore

Re: [PATCH] Doc: fix misleading asciidoc formating

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.

Jeff King· Mar 5, 2019, 23:02 UTC · re: Junio C Hamano · lore

Re: [PATCH] Doc: fix misleading asciidoc formating

On Wed, Mar 06, 2019 at 07:54:20AM +0900, Junio C Hamano wrote:
Show 8 quoted lines
> 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
Jeff King· Mar 5, 2019, 23:11 UTC · re: Jeff King · lore

Re: [PATCH] Doc: fix misleading asciidoc formating

On Tue, Mar 05, 2019 at 06:02:27PM -0500, Jeff King wrote:
Show 12 quoted lines
> 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
Junio C Hamano· Mar 5, 2019, 23:44 UTC · re: Jeff King · lore

Re: [PATCH] Doc: fix misleading asciidoc formating

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

Jean-Noël Avila· Mar 6, 2019, 08:07 UTC · re: Junio C Hamano · lore

Re: [PATCH] Doc: fix misleading asciidoc formating

On 2019-03-06, Junio Hamano, Jeff King wrote:> Jeff King <peff@peff.net> writes

Show 13 quoted lines
> 
>> 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.

Jeff King· Mar 6, 2019, 19:06 UTC · re: Jean-Noël Avila · lore

Re: [PATCH] Doc: fix misleading asciidoc formating

On Wed, Mar 06, 2019 at 09:07:11AM +0100, Jean-Noël Avila wrote:
Show 5 quoted lines
> 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
Junio C Hamano· Mar 5, 2019, 22:39 UTC · re: Jean-Noël Avila · lore

Re: [PATCH] Doc: fix misleading asciidoc formating

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

Show 20 quoted lines
> 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.

← back to recent threads