Re: Issue 1567 in lilypond: Add documentation for footnotes

[lilypond]

Updates:
        Labels: -Patch-review Patch-needs_work

Comment #10 on issue 1567 by address@hidden: Add documentation for  
footnotes
http://code.google.com/p/lilypond/issues/detail?id=1567

Actually reading Mikes new documentation outline he sent me for the two new  
commands and the clarification of the existing one I am closing the  
Rietveld issue above and will open a new one with *all* the documentation  
for footnotes in it when is done.

--snipped from 1788 so I have it in the correct place--

AUTOMATIC-FOOTNOTES

In automatic footnotes, there are three pertinent commands
\autoFootnote
\autoFootnoteGrob
\footnote

1) \autoFootnote
\autoFootnote is to be used within the context of a chord.
It accepts two arguments:
  -- a pair showing how the annotation is displaced with respect to the  
original note (ie #'(1 . 1))
  -- a markup containing the footnote that will be typset above

2) \autoFootnoteGrob
\autoFootnoteGrob is to be used before the command that results in the  
creation of the grob you want to footnote
It accepts three arguments:
  -- a symbol showing the name of the grob to footnote
  -- a pair showing how the annotation is displaced with respect to the  
original note (ie #'(1 . 1))
  -- a markup containing the footnote that will be typset above

3) \footnote
\footnote is to be used within the context of a markup.
It accepts two arguments:
  -- a markup that will be automatically annotated
  -- a markup containing the footnote that will be typset above
By "automatically annotated," I mean that the correct annotation will be  
concatenated to the right end of the markup.
So, `\footnote foo bar' will read foo^1 in the actual text if foo is the  
first thing footnoted, and bar will automatically have a 1 pre-pended at  
the bottom of the page.

In the paper block, there are four variables that may be set with respect  
to automatic footnotes:

footnote-auto-numbering (default = ##t)
-- if you set this to false, you can still use the commands \autoFootnote  
and \autoFootnoteGrob, but there will be no annotation added.   
additionally, if you use \footnote, the markup that is footnoted will  
receive no additional annotation.
footnote-number-raise (default = 0.5\mm)
-- this controls how high the annotation numbers are raised at the bottom  
of the page.  try playing with it and look at the bottom of the page:  
you'll see what it does immediately
footnote-numbering-function (default = #numbered-footnotes)
-- a function that takes ONE AND ONLY ONE INPUT, which should be an  
INTEGER, and returns the appropriate markup to be used in numbering the  
current prefabbed functions in output-lib.scm that work with this are  
`numbered-footnotes' and `symbol-footnotes'.  You can create your own w/o  
too much hassle, ie:
         footnote-numbering-function = #(lambda (x) (markup #:tiny "thank  
you james!"))
reset-footnotes-on-new-page (default = ##t)
-- automatic footnote annotations reset on each new page.
All non-automatic paper-block commands apply to automatic footnotes as well.

NON-AUTOMATIC-FOOTNOTES

*** ATTENTION ***
For non-automatic footnotes, the paper block MUST contain  
footnote-auto-number = ##f
Otherwise, LilyPond will spew numbers all over the page.
*** NOITNETTA ***

In non-automatic footnotes, there are three pertinent commands.

\footnote
\footnoteGrob
\footnote (double listing intentional, see below)

1) \footnote
\footnote is to be used within the context of a chord.
It accepts three arguments:
  -- a pair showing how the annotation is displaced with respect to the  
original note (ie #'(1 . 1))
  -- a markup containing the symbol that will refer to the annotation below
  -- a markup containing the footnote that will be typset above

2) \footnoteGrob
\footnoteGrob is to be used before the command that results in the creation  
of the grob you want to footnote
It accepts four arguments:
  -- a symbol showing the name of the grob to footnote
  -- a pair showing how the annotation is displaced with respect to the  
original note (ie #'(1 . 1))
  -- a markup containing the symbol that will refer to the annotation below
  -- a markup containing the footnote that will be typset above

3) \footnote
\footnote is to be used within the context of a markup (hence the double  
listing: it works differently than the footnote within chords).
It accepts two arguments:
  -- a markup that should have its own annotation
  -- a markup containing the footnote that will be typset above
By "own annotation", I mean that the markup should contain its own  
annotation.  So,
So, `\footnote foo bar' will read foo in the actual text and bar will have  
no number typset next to it.  If you want annotation  
numbers/symbols/whatever, you need to roll your own, i.e.  
\footnote "foo*" "*bar".


In the paper block, there are three variables that may be set with respect  
to ALL footnotes (non-automatic and automatic):

footnote-separator-markup (default = \markup \fill-line { \override  
#'(span-factor . 1/2) \draw-hline } )
-- separates the music from the footnotes
footnote-padding (default = 0.5\mm)
-- the padding between each footnote
footnote-footer-padding (default = 0.5\mm)
-- the padding between the bottom-most footnote and the footer