From 33f71ee2c062b4e377e146920ef48ea8c41d6fe8 Mon Sep 17 00:00:00 2001
From: Neil Puttock <n.puttock@gmail.com>
Date: Fri, 22 Jul 2011 00:01:31 +0100
Subject: [PATCH] Add Notation appendix for context mod identifiers.

* Documentation/notation/notation-appendices.itely:

  add node for context modifications

* lily/context-mod.cc:

  add type predicate ly:context-mod?

* ly/context-mods-init.ly (RemoveEmptyStaves):

  add docstring via \description

* scm/document-context-mods.scm:

  new file for generating context-mod documentation

* scm/document-identifiers.scm (identifier<?):

  move to documentation-lib.scm

* scm/documentation-generate.scm:

  load document-context-mods.scm and output documentation to
  context-mod-identifiers.tely

* scm/documentation-lib.scm (identifier<?):

  moved from document-identifiers.scm so it can be used in
  document-context-mods.scm too

* scripts/auxiliar/ref_check.tely:

  exclude context-mod-identifiers.tely

* scripts/build/website-known-missing-files.txt:

  add context-mod-identifiers.tely
---
 .../notation/notation-appendices.itely        |   8 ++
 lily/context-mod.cc                           |   1 +
 ly/context-mods-init.ly                       |   2 +
 scm/document-context-mods.scm                 | 100 ++++++++++++++++++
 scm/document-identifiers.scm                  |   7 --
 scm/documentation-generate.scm                |   4 +
 scm/documentation-lib.scm                     |   4 +
 scripts/auxiliar/ref_check.tely               |   1 +
 scripts/build/website-known-missing-files.txt |   1 +
 9 files changed, 121 insertions(+), 7 deletions(-)
 create mode 100644 scm/document-context-mods.scm

diff --git a/Documentation/notation/notation-appendices.itely b/Documentation/notation/notation-appendices.itely
index 66a907f709..ded7f6e624 100644
--- a/Documentation/notation/notation-appendices.itely
+++ b/Documentation/notation/notation-appendices.itely
@@ -30,6 +30,7 @@
 * All context properties::
 * Layout properties::
 * Available music functions::
+* Context modification identifiers::
 * Predefined type predicates::
 * Scheme functions::
 @end menu
@@ -1375,6 +1376,13 @@ Internals Reference:
 
 @include identifiers.tely
 
+@node Context modification identifiers
+@appendixsec Context modification identifiers
+
+The following commands are defined for use as context modifications
+within a @code{\layout} or @code{\with} block.
+
+@include context-mod-identifiers.tely
 
 @node Predefined type predicates
 @appendixsec Predefined type predicates
diff --git a/lily/context-mod.cc b/lily/context-mod.cc
index 200ba7c6dc..5fccf6c4d2 100644
--- a/lily/context-mod.cc
+++ b/lily/context-mod.cc
@@ -32,6 +32,7 @@ Context_mod::Context_mod (Context_mod const &s)
 #include "ly-smobs.icc"
 IMPLEMENT_SIMPLE_SMOBS (Context_mod);
 IMPLEMENT_DEFAULT_EQUAL_P (Context_mod);
+IMPLEMENT_TYPE_P (Context_mod, "ly:context-mod?");
 
 int
 Context_mod::print_smob (SCM smob, SCM port, scm_print_state *)
diff --git a/ly/context-mods-init.ly b/ly/context-mods-init.ly
index be3ade7e04..6d942d7e93 100644
--- a/ly/context-mods-init.ly
+++ b/ly/context-mods-init.ly
@@ -28,4 +28,6 @@ RemoveEmptyStaves = \with {
   \remove "Hara_kiri_engraver"
   \consists "Hara_kiri_engraver"
   \override VerticalAxisGroup #'remove-empty = ##t
+  \description "Remove staves which are considered to be empty according
+to the list of interfaces set by @code{keepAliveInterfaces}."
 }
diff --git a/scm/document-context-mods.scm b/scm/document-context-mods.scm
new file mode 100644
index 0000000000..85f46de406
--- /dev/null
+++ b/scm/document-context-mods.scm
@@ -0,0 +1,100 @@
+;;;; This file is part of LilyPond, the GNU music typesetter.
+;;;;
+;;;; Copyright (C) 2011 Neil Puttock <n.puttock@gmail.com>
+;;;;
+;;;; LilyPond is free software: you can redistribute it and/or modify
+;;;; it under the terms of the GNU General Public License as published by
+;;;; the Free Software Foundation, either version 3 of the License, or
+;;;; (at your option) any later version.
+;;;;
+;;;; LilyPond is distributed in the hope that it will be useful,
+;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;;;; GNU General Public License for more details.
+;;;;
+;;;; You should have received a copy of the GNU General Public License
+;;;; along with LilyPond.  If not, see <http://www.gnu.org/licenses/>.
+
+(use-modules (ice-9 format))
+
+(define (grob-property-path path)
+  (string-join (map symbol->string path) " "))
+
+(define (document-mod-list op)
+  (let ((tag (car op))
+        (name-sym (cadr op))
+        (args (cddr op)))
+    (case tag
+      ((push)
+       (let ((value (car args))
+             (path (cdr args)))
+         (string-append
+          "@item Sets "
+          (format "grob property @code{~a} "
+                  (grob-property-path path))
+          (format "in @code{@rinternals{~a}} to ~a."
+                  name-sym
+                  (scm->texi value))
+          "\n")))
+      ((pop)
+       (string-append
+        "@item Reverts "
+        (format "grob property @code{~a} "
+                (grob-property-path (car args)))
+        (format "in @code{@rinternals{~a}}."
+                name-sym)
+        "\n"))
+      ((assign)
+       (format "@item Sets translator property @code{~a} to ~a.\n"
+               name-sym
+               (scm->texi (car args))))
+      ((unset)
+       (format "@item Unsets translator property @code{~a}.\n"
+               name-sym))
+      ((consists)
+       (format "@item Adds @code{@rinternals{~a}}.\n" name-sym))
+      ((remove)
+       (format "@item Removes @code{@rinternals{~a}}.\n" name-sym))
+      (else ""))))
+
+(define (document-context-mod context-mod-pair)
+  (let* ((name-sym (car context-mod-pair))
+         (mod-list (ly:get-context-mods (cdr context-mod-pair)))
+         (docstring (filter (lambda (mod)
+                              (eq? (car mod) 'description))
+                            mod-list)))
+    (format
+     "@item @code{~a}
+@findex ~a
+~a
+@itemize
+~{~a ~}
+@end itemize
+"
+     name-sym
+     name-sym
+     (if (pair? docstring) (cadar docstring) "(undocumented; fixme)")
+     (map document-mod-list mod-list))))
+
+(define (document-mod obj-pair)
+  (cond
+   ((ly:context-mod? (cdr obj-pair))
+    (document-context-mod obj-pair))
+   (else
+    #f)))
+
+(define context-mods-doc-string
+  (format
+   "@table @asis
+~a
+@end table
+"
+   (string-join
+    (filter
+     identity
+     (map
+      document-mod
+      (sort
+       (ly:module->alist (current-module))
+       identifier<?)))
+    "")))
diff --git a/scm/document-identifiers.scm b/scm/document-identifiers.scm
index b456acf334..838de55e55 100644
--- a/scm/document-identifiers.scm
+++ b/scm/document-identifiers.scm
@@ -52,13 +52,6 @@
    (else
     #f)))
 
-
-(define (identifier<? a b)
-  (ly:string-ci<?
-   (symbol->string (car a))
-   (symbol->string (car b))))
-
-
 (define-public (identifiers-doc-string)
   (format #f
    "@table @asis
diff --git a/scm/documentation-generate.scm b/scm/documentation-generate.scm
index b1d9fcda2d..b2aa9637b6 100644
--- a/scm/documentation-generate.scm
+++ b/scm/documentation-generate.scm
@@ -34,6 +34,7 @@
 	       "document-music.scm"
 	       "document-type-predicates.scm"
 	       "document-identifiers.scm"
+	       "document-context-mods.scm"
 	       "document-backend.scm"
 	       "document-markup.scm"))
 
@@ -72,6 +73,9 @@
  (identifiers-doc-string)
  (open-output-file "identifiers.tely"))
 
+(display
+ context-mods-doc-string
+ (open-output-file "context-mod-identifiers.tely"))
 
 (display
  (backend-properties-doc-string all-user-grob-properties)
diff --git a/scm/documentation-lib.scm b/scm/documentation-lib.scm
index af48e55c6b..013cc2a437 100644
--- a/scm/documentation-lib.scm
+++ b/scm/documentation-lib.scm
@@ -175,6 +175,10 @@ string-to-use).  If QUOTE? is #t, embed table in a @quotation environment."
 (define (writing-wip x)
   (ly:message (_ "Writing ~S...") x))
 
+(define (identifier<? a b)
+  (ly:string-ci<?
+   (symbol->string (car a))
+   (symbol->string (car b))))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; property  stuff.
diff --git a/scripts/auxiliar/ref_check.tely b/scripts/auxiliar/ref_check.tely
index 5d795eedfb..ed7363148e 100644
--- a/scripts/auxiliar/ref_check.tely
+++ b/scripts/auxiliar/ref_check.tely
@@ -15,6 +15,7 @@ Manual names and reference keywords:
 Files to be excluded (not available in git):
 @exclude colorado.itexi
 @exclude computer-notation.itexi
+@exclude context-mod-identifiers.tely
 @exclude context-properties.tely
 @exclude engravingbib.itexi
 @exclude identifiers.tely
diff --git a/scripts/build/website-known-missing-files.txt b/scripts/build/website-known-missing-files.txt
index 4f4cd85bb0..941aa8cd11 100644
--- a/scripts/build/website-known-missing-files.txt
+++ b/scripts/build/website-known-missing-files.txt
@@ -2,6 +2,7 @@ ancient-notation.itely
 chords.itely
 colorado.itexi
 computer-notation.itexi
+context-mod-identifiers.tely
 context-properties.tely
 contexts-and-engravers.itely
 editorial-annotations.itely
-- 
2.39.2