\label and \page-ref documentation and news item.

Add "labels" grob property and "page-label" (iso. "label") music
property definitions.

9 files changed, 98 insertions, 6 deletions

diff --git a/Documentation/topdocs/NEWS.tely b/Documentation/topdocs/NEWS.tely
index 4a707e3b96..d651126018 100644
--- a/Documentation/topdocs/NEWS.tely
+++ b/Documentation/topdocs/NEWS.tely
@@ -66,6 +66,11 @@ which scares away people.
 @end ignore
 
 @item
+Particular points of a book may be marked with the @code{\label}
+command. Then, the page where these points are placed can be refered to
+using the @code{\page-ref} markup command.
+
+@item
 Page breaking and page turning commands (@code{\pageBreak},
 @code{\noPageBreak}, etc) can be used at top-level, between scores and
 top-level markups.
diff --git a/Documentation/user/non-music.itely b/Documentation/user/non-music.itely
index 52c18dbf70..eded3eca1b 100644
--- a/Documentation/user/non-music.itely
+++ b/Documentation/user/non-music.itely
@@ -481,6 +481,7 @@ some pieces include a lot more information.
 @menu
 * Creating titles::             
 * Custom titles::               
+* Table of contents::                
 @end menu
 
 
@@ -733,7 +734,90 @@ composer flush right on a single line.
 }
 @end verbatim
 
+@node Table of contents
+@subsection Table of contents
 
+A particular place of a score can be marked using the @code{\label}
+command, either at top-level or inside music.  This label can then be
+refered to in a markup, to get the number of the page where the marked
+point is placed, using the @code{\page-ref} markup command.
+
+@verbatim
+\score {
+  {
+    c'1
+    \mark A \label #'markA
+    c'
+  }
+} \label #'firstScore
+
+\markup { The first score is on page \page-ref #'firstScore "0" "?" }
+\markup { Mark A is on page \page-ref #'markA "0" "?" }
+@end verbatim
+
+The @code{\page-ref} markup command takes three arguments:
+@enumerate
+@item the label, a scheme symbol, eg. #'firstScore
+@item a markup that will be used as a gauge to estimate the dimensions
+of the markup
+@item a markup that will be used if the label is not known
+@end enumerate
+
+The reason why a gauge is needed is that, at the time markups are
+interpreted, the page breaking has not yet occured, so the page numbers
+are not yet known.  To work around this issue, the actual markup
+interpretation is delayed to a later time; however, the dimensions of
+the markup have to be known before, so a gauge is used to decide these
+dimensions.  If the book has between 10 and 99 pages, it may be "00",
+ie. a two digit number.
+
+@code{\label} and @code{\page-ref} can be used to build a table of contents:
+
+@verbatim
+#(set-default-paper-size "a6")
+
+#(define-markup-command (toc-line layout props label text) (symbol? markup?)
+  (interpret-markup layout props
+   (markup #:fill-line (text #:page-ref label "8" "?"))))
+
+\markup \column {
+  \large \fill-line { \null "Table of contents" \null }
+  \hspace #1
+  \toc-line #'toc "Table of contents"
+  \toc-line #'scoreI "First Score"
+  \toc-line #'markA \line { \hspace #3 Mark A }
+  \toc-line #'scoreII "Second Score"
+} \label #'toc
+
+\pageBreak
+
+\score {
+  { 
+    c'1 \break
+    \mark A \label #'markA
+    c'1
+  }
+  \header { piece = "First score" }
+} \label #'scoreI
+
+\pageBreak
+
+\score {
+  { d' }
+  \header { piece = "Second score" }
+} \label #'scoreII
+@end verbatim
+
+In this example, a @code{\toc-line} markup command is defined to build
+the table of content items. As this example has less than 10 pages, the
+gauge used by @code{\page-ref} has a single digit.
+
+@refcommands
+
+@funindex \label
+@code{\label}
+@funindex \page-ref
+@code{\page-ref}
 
 @node MIDI output
 @section MIDI output
diff --git a/input/regression/page-label.ly b/input/regression/page-label.ly
index a83df21d8e..9f40328cf4 100644
--- a/input/regression/page-label.ly
+++ b/input/regression/page-label.ly
@@ -1,4 +1,4 @@
-\version "2.11.24"
+\version "2.11.25"
 
 \header {
   texidoc = "Page labels may be placed inside music or at top-level,
diff --git a/lily/paper-column-engraver.cc b/lily/paper-column-engraver.cc
index db088a5735..6ed851243d 100644
--- a/lily/paper-column-engraver.cc
+++ b/lily/paper-column-engraver.cc
@@ -159,7 +159,7 @@ Paper_column_engraver::process_music ()
 
   for (vsize i = 0 ; i < label_events_.size () ; i ++)
     {
-      SCM label = label_events_[i]->get_property ("label");
+      SCM label = label_events_[i]->get_property ("page-label");
       SCM labels = command_column_->get_property ("labels");
       command_column_->set_property ("labels", scm_cons (label, labels));
     }
diff --git a/lily/paper-column.cc b/lily/paper-column.cc
index 4dba6bbbd5..1578688925 100644
--- a/lily/paper-column.cc
+++ b/lily/paper-column.cc
@@ -289,7 +289,8 @@ ADD_INTERFACE (Paper_column,
 	       /* properties */
 	       "between-cols "
 	       "bounded-by-me "
-	       "grace-spacing " 
+	       "grace-spacing "
+	       "labels "
 	       "line-break-system-details "
 	       "line-break-penalty "
 	       "line-break-permission "
diff --git a/ly/music-functions-init.ly b/ly/music-functions-init.ly
index ea28ba4a58..c887598539 100644
--- a/ly/music-functions-init.ly
+++ b/ly/music-functions-init.ly
@@ -304,9 +304,9 @@ label =
    (_i "Place a bookmarking label, either at top-level or inside music.")
    (make-music 'EventChord
 	       'page-marker #t
-	       'label label
+	       'page-label label
 	       'elements (list (make-music 'LabelEvent
-					   'label label)))) 
+					   'page-label label)))) 
 
 makeClusters =
 #(define-music-function
diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm
index 014481c0ca..45a2c77e84 100644
--- a/scm/define-grob-properties.scm
+++ b/scm/define-grob-properties.scm
@@ -282,6 +282,7 @@ bar lines, this is the amount of space after a thick line.")
 correction amount for kneed beams.  Set between @code{0} for no
 correction and @code{1} for full correction.")
 
+     (labels ,list? "List of labels (symbols) placed on a column")
      (label-dir ,ly:dir? "Side to which a label is attached.
 @code{-1} for left, @code{1}@tie{}for right.")
      (layer ,number? "The output layer (a value between 0 and@tie{}2:
diff --git a/scm/define-music-properties.scm b/scm/define-music-properties.scm
index 57ef143930..e3a6e3d9a7 100644
--- a/scm/define-music-properties.scm
+++ b/scm/define-music-properties.scm
@@ -78,6 +78,7 @@ here. TODO: use SpanEvents?")
      (octavation ,integer? "This pitch was octavated by how many octaves? For chord inversions, this is negative.")
      (origin ,ly:input-location? "where was this piece of music defined?")
      (page-break-permission ,symbol? "When the music is at top-level, whether to allow, forbid or force a page break.")
+     (page-label ,symbol? "The label of a page marker")
      (page-marker ,boolean? "If true, and the music expression is found at top-level, a page marker object is instanciated instead of a score.")
      (page-turn-permission ,symbol? "When the music is at top-level, whether to allow, forbid or force a page turn.")
      (part-combine-status ,symbol?
diff --git a/scm/lily-library.scm b/scm/lily-library.scm
index 54355336d8..6bd66501e4 100644
--- a/scm/lily-library.scm
+++ b/scm/lily-library.scm
@@ -72,7 +72,7 @@
   (cond ((music-property 'page-marker)
 	 ;; a page marker: set page break/turn permissions or label
 	 (begin
-	   (let ((label (music-property 'label)))
+	   (let ((label (music-property 'page-label)))
 	     (if (symbol? label)
 		 (score-handler (ly:make-page-label-marker label))))
 	   (for-each (lambda (symbol)