| Message ID | 20190305214423.27820-1-jn.avila@free.fr (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Doc: fix misleading asciidoc formating | expand |
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
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.
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.
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
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
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 ;-).
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.
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
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.
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.
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(-)