Re: [PATCH] Documentation/Notes: Remove 'footnote:' warning

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Jul 18, 2011, 07:13 UTC
Message-ID: <20110718071308.GA4745@elie.gateway.2wire.net>
In-Reply-To: <CAK9CXBV=OMRVzEjUmb6JP8nM9bQ4DqM0D7xCywxs0TUD5+scrw@mail.gmail.com>

Pavan Kumar Sunkara wrote:

> Currently the documentation at
> http://www.kernel.org/pub/software/scm/git/docs/git-notes.html is
> showing the footnote wrongly. This workaround will solve that.

(For reference, the linked-to page was generated with asciidoc 8.4.5 and renders the footnote as

	<br />[Permitted pathnames have the
[...]
	rest of the object ID.]<br />.

inline instead of a nicely labelled link like "[1]" that one might expect.)

Weird. That's not the Docbook XSL bug I pointed to --- the HTML documentation is generated by asciidoc directly, without any help from Docbook XSL. And I can't reproduce it locally, either. *digs around in asciidoc changelog* Ah, Asciidoc 8.5.1 introduced styling of footnotes:

     * Styled HTML footnotes.
     * Added links to HTML footnote refs.

Until the kernel.org toolchain gains that feature, wouldn't a simpler workaround be to put the footnote after the period, so it renders there as a simple line in brackets?

Barring that, it should be possible to put this information in the discussion section without disrupting the flow of the text so much, for example by putting it in parentheses or making it the last paragraph of the discussion section. A patch with such a change and mentioning in the commit message the two bugs you're working around would seem sane to me.

Thanks, Jonathan