{"thread":{"id":"50660","subject":"[PATCH] Doc: fix misleading asciidoc formating","startedAt":"2019-03-05T21:44:29Z","lastAt":"2019-03-06T23:39:31Z","messageCount":10,"participants":["Jean-Noël Avila","Jeff King","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"370750","messageId":"20190305214423.27820-1-jn.avila@free.fr","threadId":"50660","inReplyTo":null,"subject":"[PATCH] Doc: fix misleading asciidoc formating","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2019-03-05T21:44:23Z","receivedAt":"2019-03-05T21:44:29Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"The end of sentence in \"x.\" at the begining of a line misleads\nascidoctor into interpreting it as the start of numbered sub-list.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/technical/directory-rename-detection.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/technical/directory-rename-detection.txt b/Documentation/technical/directory-rename-detection.txt\nindex 1c0086e287..844629c8c4 100644\n--- a/Documentation/technical/directory-rename-detection.txt\n+++ b/Documentation/technical/directory-rename-detection.txt\n@@ -20,8 +20,8 @@ More interesting possibilities exist, though, such as:\n * one side of history renames x -> z, and the other renames some file to\n x/e, causing the need for the merge to do a transitive rename.\n \n- * one side of history renames x -> z, but also renames all files within\n- x. For example, x/a -> z/alpha, x/b -> z/bravo, etc.\n+ * one side of history renames x -> z, but also renames all files within x.\n+ For example, x/a -> z/alpha, x/b -> z/bravo, etc.\n \n * both 'x' and 'y' being merged into a single directory 'z', with a\n directory rename being detected for both x->z and y->z.\n-- \n2.21.0\n\n"},{"id":"370753","messageId":"20190305223655.GA27535@sigill.intra.peff.net","threadId":"50660","inReplyTo":"20190305214423.27820-1-jn.avila@free.fr","subject":"Re: [PATCH] Doc: fix misleading asciidoc formating","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2019-03-05T22:36:55Z","receivedAt":"2019-03-05T22:36:59Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Mar 05, 2019 at 10:44:23PM +0100, Jean-Noël Avila wrote:\n\n> The end of sentence in \"x.\" at the begining of a line misleads\n> ascidoctor into interpreting it as the start of numbered sub-list.\n\nBecause I'd been wanting to play with doc-diff and asciidoctor, I tried\nlooking at the rendered diff. However, I couldn't see any difference!\n\nDid you notice this when building locally, or on the asciidoctor-built\npages at git-scm.com? If the latter, I wonder if we might need to update\nour version of asciidoctor there (it looks like we're on v1.5.6.1 there,\nbut my local asciidoctor binary is v1.5.8).\n\n-Peff\n"},{"id":"370755","messageId":"xmqqd0n5t07b.fsf@gitster-ct.c.googlers.com","threadId":"50660","inReplyTo":"20190305214423.27820-1-jn.avila@free.fr","subject":"Re: [PATCH] Doc: fix misleading asciidoc formating","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-03-05T22:39:52Z","receivedAt":"2019-03-05T22:39:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël Avila writes:\n\n> The end of sentence in \"x.\" at the begining of a line misleads\n> ascidoctor into interpreting it as the start of numbered sub-list.\n\nWow. That's tricky.\n\nOne thing that makes me wonder is how you found it, as I do not\nthink this file is part of the set of Documentation/technical/ files\nthat are usually touched by \"make doc\".\n\n> Signed-off-by: Jean-Noël Avila \n> ---\n> Documentation/technical/directory-rename-detection.txt | 4 ++--\n> 1 file changed, 2 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/technical/directory-rename-detection.txt b/Documentation/technical/directory-rename-detection.txt\n> index 1c0086e287..844629c8c4 100644\n> --- a/Documentation/technical/directory-rename-detection.txt\n> +++ b/Documentation/technical/directory-rename-detection.txt\n> @@ -20,8 +20,8 @@ More interesting possibilities exist, though, such as:\n> * one side of history renames x -> z, and the other renames some file to\n> x/e, causing the need for the merge to do a transitive rename.\n> \n> - * one side of history renames x -> z, but also renames all files within\n> - x. For example, x/a -> z/alpha, x/b -> z/bravo, etc.\n> + * one side of history renames x -> z, but also renames all files within x.\n> + For example, x/a -> z/alpha, x/b -> z/bravo, etc.\n> \n> * both 'x' and 'y' being merged into a single directory 'z', with a\n> directory rename being detected for both x->z and y->z.\n"},{"id":"370757","messageId":"xmqq4l8hszj7.fsf@gitster-ct.c.googlers.com","threadId":"50660","inReplyTo":"20190305223655.GA27535@sigill.intra.peff.net","subject":"Re: [PATCH] Doc: fix misleading asciidoc formating","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-03-05T22:54:20Z","receivedAt":"2019-03-05T22:54:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> Did you notice this when building locally, or on the asciidoctor-built\n> pages at git-scm.com?\n\nDoes git-scm.com even have this file rendered? I do not think we\nglob for technical/*.txt in any of our Makefiles; instead we have a\nlist of ready-to-be-consumed TECH_DOCS listed explicitly.\n"},{"id":"370759","messageId":"20190305230227.GA22901@sigill.intra.peff.net","threadId":"50660","inReplyTo":"xmqq4l8hszj7.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] Doc: fix misleading asciidoc formating","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2019-03-05T23:02:27Z","receivedAt":"2019-03-05T23:02:30Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Mar 06, 2019 at 07:54:20AM +0900, Junio C Hamano wrote:\n\n> Jeff King writes:\n> \n> > Did you notice this when building locally, or on the asciidoctor-built\n> > pages at git-scm.com?\n> \n> Does git-scm.com even have this file rendered? I do not think we\n> glob for technical/*.txt in any of our Makefiles; instead we have a\n> list of ready-to-be-consumed TECH_DOCS listed explicitly.\n\nIt is rendered, at https://git-scm.com/docs/directory-rename-detection.\n\nHowever, that explains why doc-diff did not find anything; it only looks\nat the results of \"make install-man\", which does not include any\ntechnical docs (let alone this one that is not mentioned in\n$(TECH_DOCS).\n\n-Peff\n"},{"id":"370762","messageId":"20190305231142.GA359@sigill.intra.peff.net","threadId":"50660","inReplyTo":"20190305230227.GA22901@sigill.intra.peff.net","subject":"Re: [PATCH] Doc: fix misleading asciidoc formating","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2019-03-05T23:11:42Z","receivedAt":"2019-03-05T23:11:45Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Mar 05, 2019 at 06:02:27PM -0500, Jeff King wrote:\n\n> On Wed, Mar 06, 2019 at 07:54:20AM +0900, Junio C Hamano wrote:\n> \n> > Jeff King writes:\n> > \n> > > Did you notice this when building locally, or on the asciidoctor-built\n> > > pages at git-scm.com?\n> > \n> > Does git-scm.com even have this file rendered? I do not think we\n> > glob for technical/*.txt in any of our Makefiles; instead we have a\n> > list of ready-to-be-consumed TECH_DOCS listed explicitly.\n> \n> It is rendered, at https://git-scm.com/docs/directory-rename-detection.\n\nBy the way, that rendering shows that the whole document could probably\nuse a few tweaks to make its asciidoc formatting look good (in addition\nto the \"x.\" thing that Jean-Noël fixed here, which can also be seen\nthere).\n\nTBH, I still have mixed feelings on rendering these technical docs with\nasciidoc at all. It seems like few enough people bother to render them\nthat bugs persist for a long time. It kind of seems like make-work\ngetting them to format correctly.\n\n-Peff\n"},{"id":"370768","messageId":"xmqqy35ssx7v.fsf@gitster-ct.c.googlers.com","threadId":"50660","inReplyTo":"20190305231142.GA359@sigill.intra.peff.net","subject":"Re: [PATCH] Doc: fix misleading asciidoc formating","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-03-05T23:44:20Z","receivedAt":"2019-03-05T23:44:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> TBH, I still have mixed feelings on rendering these technical docs with\n> asciidoc at all. It seems like few enough people bother to render them\n> that bugs persist for a long time. It kind of seems like make-work\n> getting them to format correctly.\n\nI thought about resisting when some people started pushing for\nrendering everything under the Sun, but went with the flow as I\nlacked the energy to fight every battle in sight.\n\nGood to see somebody shares a similar sense of trade-off, better\nlate than never ;-).\n"},{"id":"370793","messageId":"43445278-ec9f-f3f4-89bf-cf99906fc617@free.fr","threadId":"50660","inReplyTo":"xmqqy35ssx7v.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] Doc: fix misleading asciidoc formating","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2019-03-06T08:07:11Z","receivedAt":"2019-03-06T08:07:19Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On 2019-03-06, Junio Hamano, Jeff King wrote:> Jeff King \nwrites\n> \n>> TBH, I still have mixed feelings on rendering these technical docs with\n>> asciidoc at all. It seems like few enough people bother to render them\n>> that bugs persist for a long time. It kind of seems like make-work\n>> getting them to format correctly.\n> \n> I thought about resisting when some people started pushing for\n> rendering everything under the Sun, but went with the flow as I\n> lacked the energy to fight every battle in sight.\n> \n> Good to see somebody shares a similar sense of trade-off, better\n> late than never ;-).\n> \n\nTBH, I discovered this while diving into the rendering on manpages for\nthe localized version because asciidoctor issued a warning, and pushed\nthis patch for \"cultural\" knowledge (sometimes, automatic linefeed\ntriggers unintended behaviors). But, as Peff noted, this may not be a\ngood idea to render these documents at all on git-scm.com.\n\nIn this case, there's no point in tracking rendering issues outside\ngenuine manpages.\n\n\n"},{"id":"370820","messageId":"20190306190630.GB18239@sigill.intra.peff.net","threadId":"50660","inReplyTo":"43445278-ec9f-f3f4-89bf-cf99906fc617@free.fr","subject":"Re: [PATCH] Doc: fix misleading asciidoc formating","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2019-03-06T19:06:31Z","receivedAt":"2019-03-06T19:06:34Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Mar 06, 2019 at 09:07:11AM +0100, Jean-Noël Avila wrote:\n\n> TBH, I discovered this while diving into the rendering on manpages for\n> the localized version because asciidoctor issued a warning, and pushed\n> this patch for \"cultural\" knowledge (sometimes, automatic linefeed\n> triggers unintended behaviors). But, as Peff noted, this may not be a\n> good idea to render these documents at all on git-scm.com.\n\nAh, that makes sense. I do think this is an interesting gotcha, and I'm\nglad to have learned about it. So even if we don't apply your patch and\nit serves as an interesting report, I think it was still worth it.\n\n(Though I am also happy to see it applied since you went to the trouble\nto make it).\n\n-Peff\n"},{"id":"370838","messageId":"xmqqtvgfpo7m.fsf@gitster-ct.c.googlers.com","threadId":"50660","inReplyTo":"20190306190630.GB18239@sigill.intra.peff.net","subject":"Re: [PATCH] Doc: fix misleading asciidoc formating","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-03-06T23:39:25Z","receivedAt":"2019-03-06T23:39:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> (Though I am also happy to see it applied since you went to the trouble\n> to make it).\n\nYup.\n"}]}