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

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

[Pavan Kumar Sunkara]

Remove 'footnote:' from git-notes.txt which is responsible
for the warnings surfacing during the generation of git
documentation.
---
 Documentation/git-notes.txt |    9 +++++----
 1 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 6a187f2..2a18894 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -210,10 +210,11 @@ Commit notes are blobs containing extra information about an object
 are taken from notes refs.  A notes ref is usually a branch which
 contains "files" whose paths are the object names for the objects
 they describe, with some directory separators included for performance
-reasons footnote:[Permitted pathnames have the form
-'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory
-names of two hexadecimal digits each followed by a filename with the
-rest of the object ID.].
+reasons.
+
+Permitted pathnames have the form 'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...':
+a sequence of directory names of two hexadecimal digits each
+followed by a filename with the rest of the object ID.
 
 Every notes change creates a new commit at the specified notes ref.
 You can therefore inspect the history of the notes by invoking, e.g.,
-- 
1.7.6.485.gad3dc

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

[Drew Northup]

On Sun, 2011-07-17 at 04:00 +0530, Pavan Kumar Sunkara wrote:
> Remove 'footnote:' from git-notes.txt which is responsible
> for the warnings surfacing during the generation of git
> documentation.
> ---

What version of asciidoc are you using? Perhaps that works just fine
with newer versions?
-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

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

[Pavan Kumar Sunkara]

I am using asciidoc 8.6.3. It is the newest available in ubuntu repository.

On Sun, Jul 17, 2011 at 6:41 PM, Drew Northup <drew.northup@maine.edu> wrote:
>
> On Sun, 2011-07-17 at 04:00 +0530, Pavan Kumar Sunkara wrote:
> > Remove 'footnote:' from git-notes.txt which is responsible
> > for the warnings surfacing during the generation of git
> > documentation.
> > ---
>
> What version of asciidoc are you using? Perhaps that works just fine
> with newer versions?
> --
> -Drew Northup
> ________________________________________________
> "As opposed to vegetable or mineral error?"
> -John Pescatore, SANS NewsBites Vol. 12 Num. 59
>

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

[Jonathan Nieder]

Hi,

Drew Northup wrote:
> On Sun, 2011-07-17 at 04:00 +0530, Pavan Kumar Sunkara wrote:

>> Remove 'footnote:' from git-notes.txt which is responsible
>> for the warnings surfacing during the generation of git
>> documentation.
>
> What version of asciidoc are you using? Perhaps that works just fine
> with newer versions?

Good call.  This was fixed by Docbook XSL 1.76.0:

	Norman Walsh: block.xsl; endnotes.xsl

		Fix bug where simpara in footnote didn't work.

The symptoms are a warning and a little extra vertical space after the
numberal "1." in the output.  I don't know if it is worth working
around or not.

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

[Pavan Kumar Sunkara]

On Mon, Jul 18, 2011 at 3:28 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Hi,
>
> Drew Northup wrote:
>> On Sun, 2011-07-17 at 04:00 +0530, Pavan Kumar Sunkara wrote:
>
>>> Remove 'footnote:' from git-notes.txt which is responsible
>>> for the warnings surfacing during the generation of git
>>> documentation.
>>
>> What version of asciidoc are you using? Perhaps that works just fine
>> with newer versions?
>
> Good call.  This was fixed by Docbook XSL 1.76.0:
>
>        Norman Walsh: block.xsl; endnotes.xsl
>
>                Fix bug where simpara in footnote didn't work.
>
> The symptoms are a warning and a little extra vertical space after the
> numberal "1." in the output.  I don't know if it is worth working
> around or not.
>

So, using newest version will not give us a warning?


-- 
- Pavan Kumar Sunkara

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

[Jonathan Nieder]

Pavan Kumar Sunkara wrote:
> On Mon, Jul 18, 2011 at 3:28 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:

>> Good call.  This was fixed by Docbook XSL 1.76.0:
>>
>>        Norman Walsh: block.xsl; endnotes.xsl
>>
>>                Fix bug where simpara in footnote didn't work.
>>
>> The symptoms are a warning and a little extra vertical space after the
>> numberal "1." in the output.  I don't know if it is worth working
>> around or not.
>
> So, using newest version will not give us a warning?

Yes, when I run "make -C Documentation git-notes.1" I don't get the
warning or spurious blank line.  Sorry for the lack of clarity.
(That's no reason to not to adopt a workaround if it is pleasant, of
course.)

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

[Pavan Kumar Sunkara]

>> So, using newest version will not give us a warning?
>
> Yes, when I run "make -C Documentation git-notes.1" I don't get the
> warning or spurious blank line.  Sorry for the lack of clarity.
> (That's no reason to not to adopt a workaround if it is pleasant, of
> course.)
>

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.
Jonathan, ack the patch if you want to have a workaround.

Thanks
-- 
- Pavan Kumar Sunkara

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

[Jonathan Nieder]

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

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

[Pavan Kumar Sunkara]

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

That is what I did.

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

I agree. So, if the patch is ok, I will rewrite the commit msg and
send it again.

Thanks,
Pavan Kumar Sunkara

-- 
- Pavan Kumar Sunkara

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

[Junio C Hamano]

Pavan Kumar Sunkara <pavan.sss1991@gmail.com> writes:

>> 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
>>
>
> I agree. So, if the patch is ok, I will rewrite the commit msg and
> send it again.
>
> Thanks,
> Pavan Kumar Sunkara

Thanks.