From 2f9328a294a9317af7fe91ebdb00534e0cba29ea Mon Sep 17 00:00:00 2001 From: David Kastrup Date: Wed, 27 May 2015 17:05:34 +0200 Subject: [PATCH] Issue 4422/7: Documentation fixes and Changelog --- Documentation/changes.tely | 13 +++++++++++ .../extending/programming-interface.itely | 23 ++++--------------- .../notation/changing-defaults.itely | 9 ++------ 3 files changed, 19 insertions(+), 26 deletions(-) diff --git a/Documentation/changes.tely b/Documentation/changes.tely index 906214b6a3..6735a03b08 100644 --- a/Documentation/changes.tely +++ b/Documentation/changes.tely @@ -61,6 +61,19 @@ which scares away people. @end ignore +@item +The definition of LilyPond functions with +@code{define-music-function}, @code{define-event-function}, +@code{define-scheme-function} and @code{define-void-function} no +longer requires specification of @code{parser} and @code{location} +arguments. Current parser and input location are part of the +current dynamic state and can be accessed with the function calls +@code{(*parser*)} and @code{(*location*)} when required. + +LilyPond makes a best-faith attempt of recognizing legacy use of +@code{parser} and @code{location} arguments and will provide +backwards-compatible semantics for some time. + @item In the "english" notename language, the long notenames for pitches with accidentals now contain a hyphen for better readability. You diff --git a/Documentation/extending/programming-interface.itely b/Documentation/extending/programming-interface.itely index c3afc53d94..e8f41a9338 100644 --- a/Documentation/extending/programming-interface.itely +++ b/Documentation/extending/programming-interface.itely @@ -63,11 +63,8 @@ code. The Scheme reader actually is changed for accommodating LilyPond code blocks and can deal with embedded Scheme expressions starting with @code{$} and@w{ }@code{#}. -@cindex parser (function argument) -@cindex location - The reader extracts the LilyPond code block and generates a runtime -call to the LilyPond @code{parser} to interpret the LilyPond code. +call to the LilyPond parser to interpret the LilyPond code. Scheme expressions embedded in the LilyPond code are evaluated in the lexical environment of the LilyPond code block, so all local variables and function parameters available at the point the LilyPond code block @@ -77,10 +74,8 @@ are not accessible as Scheme variables, i.e. prefixed with@tie{}@code{#}, but they are accessible as LilyPond variables, i.e. prefixed with@tie{}@code{\}. -If @code{location} (see @ref{Scheme functions}) refers to a valid -input location (which it usually does inside of music/@/Scheme -functions), all music generated inside the code block has its -@samp{origin} set to @code{location}. +All music generated inside the code block has its +@samp{origin} set to the current input location. A LilyPond code block may contain anything that you can use on the right side of an assignment. In addition, an empty LilyPond block @@ -123,15 +118,6 @@ function = where @multitable @columnfractions .33 .66 -@item @code{parser} -@tab needs to be literally @code{parser} in order to give LilyPond code -blocks (@code{#@{}@dots{}@code{#@}}) access to the parser. - -@item @code{location} -@tab needs to be literally @code{location} in order to provide access -to the input location object, which is used to provide error messages -with file names and line numbers. - @item @code{@var{argN}} @tab @var{n}th argument @@ -148,7 +134,7 @@ don't follow it with a default value, @code{#f} is used as the default. Default values are not verified with @emph{predicate?} at either definition or run time: it is your responsibility to deal with the values you specify. Default values that happen to be music expressions -are copied while setting @code{origin} to the @code{location} parameter. +are copied while setting @code{origin} to the current input location. @item @code{@var{body}} @tab A sequence of Scheme forms evaluated in order, the last one being @@ -1537,4 +1523,3 @@ This chapter covers the various tools provided by LilyPond to help Scheme programmers get information into and out of the music streams. TODO -- figure out what goes in here and how to organize it - diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely index f64396f502..6b9c7410f5 100644 --- a/Documentation/notation/changing-defaults.itely +++ b/Documentation/notation/changing-defaults.itely @@ -4636,13 +4636,8 @@ reference arguments (eg. @samp{#arg1}). @end multitable -The @code{parser} and @code{location} arguments are mandatory, and -are used in some advanced situations as described in the -@q{Extending} manual (see @rextend{Music functions}). For -substitution functions, just be sure to include them. - -The list of type predicates is also required. Some of the most -common type predicates used in music functions are: +The list of type predicates is required. Some of the most common +type predicates used in music functions are: @example boolean? -- 2.39.2