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

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

diff --git a/Documentation/topdocs/NEWS.tely b/Documentation/topdocs/NEWS.tely
index 4a707e3b96941212d3aa63bbb581a80ce5c982dd..d6511260188948a1e1875ae1d78ea94c63872659 100644 (file)
--- a/Documentation/topdocs/NEWS.tely
+++ b/Documentation/topdocs/NEWS.tely
@@ -65,6 +65,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

diff --git a/Documentation/user/non-music.itely b/Documentation/user/non-music.itely
index 52c18dbf70b76cc5b181506a2393e86d48d5bb71..eded3eca1b78a8c60cde0204aaceeb25594a9816 100644 (file)
--- 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 a83df21d8ea4548af874de740b8acffaf2625fce..9f40328cf4ce958691104ba062534783823adcb2 100644 (file)
--- 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 db088a57359ad75246fb9cd1b2f06f035d9d4f69..6ed851243d93809d2a6d226bd73faaf64d6cbb9c 100644 (file)
--- 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 4dba6bbbd58f08784b55e5cbef2e38e96edc8355..1578688925befd5e7eb9de5f68ab3fbfb3954529 100644 (file)
--- 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 ea28ba4a58ccf86fd6995b5d03d6529a9852730b..c88759853991c1f7265c931bd3b37bbf49d64dc7 100644 (file)
--- 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 014481c0ca7ffd195b42b4851fa6e3d914cae1bc..45a2c77e84b34c4211f8ac92b39e0d0afe007d97 100644 (file)
--- 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 57ef143930e1707adce9e71a451d333e1d3fbddc..e3a6e3d9a7911b09770c8524c7bb714fc1227687 100644 (file)
--- 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 54355336d89513d4b263c0c5caab657439e4f6ee..6bd66501e4950e911c9ab1204cca99e4712fda9b 100644 (file)
--- 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)