(throw 'ly-file-failed)))))
(define-public (sanitize-command-option str)
- "Kill dubious shell quoting"
+ "Kill dubious shell quoting."
(string-append
"\""
(filter (lambda (x) (not (pred? x))) lst))
(define-public (font-name-split font-name)
- "Return (FONT-NAME . DESIGN-SIZE) from FONT-NAME string or #f."
+ "Return @code{(FONT-NAME . DESIGN-SIZE)} from @var{font-name} string
+or @code{#f}."
(let ((match (regexp-exec (make-regexp "(.*)-([0-9]*)") font-name)))
(if (regexp-match? match)
(cons (match:substring match 1) (match:substring match 2))
;; Example of a pango-physical-font
;; ("Emmentaler-11" "/home/janneke/vc/lilypond/out/share/lilypond/current/fonts/otf/emmentaler-11.otf" 0)
(define-public (pango-pf-font-name pango-pf)
- "Return the font-name of the pango physical font PANGO-PF."
+ "Return the font-name of the pango physical font @var{pango-pf}."
(list-ref pango-pf 0))
(define-public (pango-pf-file-name pango-pf)
- "Return the file-name of the pango physical font PANGO-PF."
+ "Return the file-name of the pango physical font @var{pango-pf}."
(list-ref pango-pf 1))
(define-public (pango-pf-fontindex pango-pf)
- "Return the fontindex of the pango physical font PANGO-PF."
+ "Return the fontindex of the pango physical font @var{pango-pf}."
(list-ref pango-pf 2))
(define (pango-font-name pango-font)
"")))
(define-public (define-fonts paper define-font define-pango-pf)
- "Return a string of all fonts used in PAPER, invoking the functions
-DEFINE-FONT DEFINE-PANGO-PF for producing the actual font definition."
+ "Return a string of all fonts used in @var{paper}, invoking the functions
+@var{define-font} and @var{define-pango-pf} for producing the actual font
+definition."
(let* ((font-list (ly:paper-fonts paper))
(pango-fonts (filter ly:pango-font? font-list))
;;;; along with LilyPond. If not, see <http://www.gnu.org/licenses/>.
(define-public (construct-chord-elements root duration modifications)
- " Build a chord on root using modifiers in MODIFICATIONS. NoteEvents
-have duration DURATION.
+ "Build a chord on root using modifiers in @var{modifications}.
+@code{NoteEvents} have duration @var{duration}.
-Notes: natural 11 is left from chord if not explicitly specified.
+Notes: Natural 11 is left from chord if not explicitly specified.
-Entry point for the parser.
-"
+Entry point for the parser."
(let* ((flat-mods (flatten-list modifications))
(base-chord (stack-thirds (ly:make-pitch 0 4 0) the-canonical-chord))
(complete-chord '())
(define-public (ugh-compat-double-plus-new-chord->markup
style pitches bass inversion context options)
- "Entry point for New_chord_name_engraver.
+ "Entry point for @code{New_chord_name_engraver}.
FIXME: func, options/context have changed
- See
-double-plus-new-chord-name.scm for the signature of STYLE. PITCHES,
-BASS and INVERSION are lily pitches. OPTIONS is an alist-alist (see
-input/test/dpncnt.ly).
- "
+
+See @file{double-plus-new-chord-name.scm} for the signature of @var{style}.
+@var{pitches}, @var{bass}, and @var{inversion} are lily pitches.
+@var{options} is an alist-alist (see @file{input/test/dpncnt.ly})."
(define (step-nr pitch)
(let* ((pitch-nr (+ (* 7 (ly:pitch-octave pitch))
))))
(define-public (note-name->markup pitch lowercase?)
- "Return pitch markup for PITCH."
+ "Return pitch markup for @var{pitch}."
(make-line-markup
(list
(make-simple-markup
(list-ref '("eses" "es" "" "is" "isis") (+ 2 (cdr n-a)))))))))
(define-public ((chord-name->italian-markup re-with-eacute) pitch lowercase?)
- "Return pitch markup for PITCH, using italian/french note names.
- If re-with-eacute is set to #t, french 'ré' is returned for D instead of 're'
-"
+ "Return pitch markup for @var{pitch}, using italian/french note names.
+If @var{re-with-eacute} is set to @code{#t}, french `ré' is returned for
+pitch@tie{}D instead of `re'."
+
(let* ((name (ly:pitch-notename pitch))
(alt (ly:pitch-alteration pitch)))
(make-line-markup
;; but let's leave that for future extensions.
;;
(define-public (system-clipped-x-extent system-grob clip-region)
- "Return the X-extent of the SYSTEM-GROB when clipped with
-CLIP-REGION. Return #f if not appropriate."
+ "Return the X-extent of @var{system-grob} when clipped with
+@var{clip-region}. Return @code{#f} if not appropriate."
(let*
((region-start (car clip-region))
symbol)
;; put this in an alist?
-(define-public
- all-user-grob-properties
-
+(define-public all-user-grob-properties
(map
(lambda (x)
(apply define-grob-property x))
;;;
(define-public (markup->lily-string markup-expr)
- "Return a string describing, in LilyPond syntax, the given markup expression."
+ "Return a string describing, in LilyPond syntax, the given markup
+expression."
(define (proc->command proc)
(let ((cmd-markup (symbol->string (procedure-name proc))))
(substring cmd-markup 0 (- (string-length cmd-markup)
;;; \clef
(define clef-name-alist #f)
(define-public (memoize-clef-names clefs)
- "Initialize `clef-name-alist', if not already set."
+ "Initialize @code{clef-name-alist}, if not already set."
(if (not clef-name-alist)
(set! clef-name-alist
(map (lambda (name+vals)
clefs))))
(define-extra-display-method ContextSpeccedMusic (expr parser)
- "If `expr' is a clef change, return \"\\clef ...\"
-Otherwise, return #f."
+ "If @var{expr} is a clef change, return \"\\clef ...\".
+Otherwise, return @code{#f}."
(with-music-match (expr (music 'ContextSpeccedMusic
context-type 'Staff
element (music 'SequentialMusic
(define-public (ly:all-stencil-commands)
"Return the list of stencil commands that can be
-defined in the output modules (output-*.scm)"
+defined in the output modules (@file{output-*.scm})."
'(beam
bezier-sandwich
blank
(define-public (ly:all-output-backend-commands)
"Return the list of extra output backend commands that
-are used internally in lily/stencil-interpret.cc."
+are used internally in @file{lily/stencil-interpret.cc}."
'(color
combine-stencil
delay-stencil-evaluation
;; Utility functions
(define-public (symbol-concatenate . names)
- "Like string-concatenate, but for symbols"
+ "Like @code{string-concatenate}, but for symbols."
(string->symbol (apply string-append (map symbol->string names))))
(define-public (function-chain arg function-list)
- "Applies a list of functions in function list to arg.
- Each element of function list is structured (cons function '(arg2 arg3 ...))
- If function takes arguments besides arg, they are provided in function list.
- For example:
- @code{guile> (function-chain 1 `((,+ 1) (,- 2) (,+ 3) (,/)))}
- @code{1/3}"
+ "Applies a list of functions in @var{function-list} to @var{arg}.
+Each element of @var{function-list} is structured @code{(cons function
+'(arg2 arg3 ...))}. If function takes arguments besides @var{arg}, they
+are provided in @var{function-list}.
+
+Example: Executing @samp{(function-chain 1 `((,+ 1) (,- 2) (,+ 3) (,/)))}
+returns @samp{1/3}."
(if (null? function-list)
arg
(function-chain
(ly:music-property expr 'tags))))
(define-public (music->lily-string expr parser)
- "Print expr, a music expression, in LilyPond syntax"
+ "Print @var{expr}, a music expression, in LilyPond syntax."
(if (ly:music? expr)
(let* ((music-type (ly:music-property expr 'name))
(procs (assoc-ref (hashq-ref music-name-to-property-table
(define-public (decode-byte-string str)
"Return vector of glyphname symbols that correspond to string,
-assuming that STR is byte-coded using ENCODING-NAME."
+assuming that @var{str} is byte-coded using latin-1 encoding."
(let* ((len (string-length str))
(output-vector (make-vector len '.notdef)))
(define-public (no-flag stem-grob)
- "No flag: Simply return empty stencil"
+ "No flag: Simply return empty stencil."
empty-stencil)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-(define-public (add-stroke-straight stencil stem-grob dir log stroke-style offset length thickness stroke-thickness)
+(define-public (add-stroke-straight stencil stem-grob dir log stroke-style
+ offset length thickness stroke-thickness)
"Add the stroke for acciaccatura to the given flag stencil.
- The stroke starts for up-flags at upper-end-of-flag+(0,length/2) and
- ends at (0, vertical-center-of-flag-end) - (flag-x-width/2, flag-x-width + flag-thickness).
- Here length is the whole length, while flag-x-width is just the
- x-extent and thus depends on the angle! Other combinations don't look as
- good... For down-stems the y-coordinates are simply mirrored."
+The stroke starts for up-flags at `upper-end-of-flag + (0,length/2)'
+and ends at `(0, vertical-center-of-flag-end) -
+(flag-x-width/2, flag-x-width + flag-thickness)'. Here `length' is the
+whole length, while `flag-x-width' is just the x-extent and thus depends on
+the angle! Other combinations don't look as good.
+
+For down-stems the y-coordinates are simply mirrored."
(let* ((start (offset-add offset (cons 0 (* (/ length 2) dir))))
(end (offset-add (cons 0 (cdr offset))
(cons (- (/ (car offset) 2)) (* (- (+ thickness (car offset))) dir))))
flag-stencil))
(define-public (straight-flag flag-thickness flag-spacing
- upflag-angle upflag-length
- downflag-angle downflag-length)
- "Create a stencil for a straight flag.
- flag-thickness, -spacing are given in staff spaces,
- *flag-angle is given in degree, *flag-length is given in staff spaces.
- All lengths will be scaled according to the font size of the note."
+ upflag-angle upflag-length
+ downflag-angle downflag-length)
+ "Create a stencil for a straight flag. @var{flag-thickness} and
+@var{flag-spacing} are given in staff spaces, @var{upflag-angle} and
+@var{downflag-angle} are given in degrees, and @var{upflag-length} and
+@var{downflag-length} are given in staff spaces.
+
+All lengths are scaled according to the font size of the note."
+
(lambda (stem-grob)
(let* ((log (ly:grob-property stem-grob 'duration-log))
(dir (ly:grob-property stem-grob 'direction))
(define-public (modern-straight-flag stem-grob)
"Modern straight flag style (for composers like Stockhausen, Boulez, etc.).
- The angles are 18 and 22 degrees and thus smaller than for the ancient style
- of Bach etc."
+The angles are 18 and 22 degrees and thus smaller than for the ancient style
+of Bach, etc."
((straight-flag 0.55 1 -18 1.1 22 1.2) stem-grob))
(define-public (old-straight-flag stem-grob)
- "Old straight flag style (for composers like Bach). The angles of the flags
- are both 45 degrees."
+ "Old straight flag style (for composers like Bach). The angles of the
+flags are both 45 degrees."
((straight-flag 0.55 1 -45 1.2 45 1.4) stem-grob))
(define-public (add-stroke-glyph stencil stem-grob dir stroke-style flag-style)
"Load and add a stroke (represented by a glyph in the font) to the given
- flag stencil"
+flag stencil."
(if (not (string? stroke-style))
stencil
; Otherwise: look up the stroke glyph and combine it with the flag
(define-public (retrieve-glyph-flag flag-style dir dir-modifier stem-grob)
- "Load the correct flag glyph from the font"
+ "Load the correct flag glyph from the font."
(let* ((log (ly:grob-property stem-grob 'duration-log))
(font (ly:grob-default-font stem-grob))
(font-char (string-append "flags." flag-style dir dir-modifier (number->string log)))
(define-public (create-glyph-flag flag-style dir-modifier stem-grob)
- "Create a flag stencil by looking up the glyph from the font"
+ "Create a flag stencil by looking up the glyph from the font."
(let* ((dir (if (eqv? (ly:grob-property stem-grob 'direction) UP) "u" "d"))
(flag (retrieve-glyph-flag flag-style dir dir-modifier stem-grob))
(stroke-style (ly:grob-property stem-grob 'stroke-style)))
(define-public (mensural-flag stem-grob)
"Mensural flags: Create the flag stencil by loading the glyph from the font.
- Flags are always aligned with staff lines, so we need to check the end point
- of the stem: For stems ending on staff lines, use different flags than for
- notes between staff lines. The idea is that flags are always vertically
- aligned with the staff lines, regardless of whether the note head is on a
- staff line or between two staff lines. In other words, the inner end of
- a flag always touches a staff line."
+Flags are always aligned with staff lines, so we need to check the end point
+of the stem: For stems ending on staff lines, use different flags than for
+notes between staff lines. The idea is that flags are always vertically
+aligned with the staff lines, regardless of whether the note head is on a
+staff line or between two staff lines. In other words, the inner end of
+a flag always touches a staff line."
(let* ((adjust #t)
(stem-end (inexact->exact (round (ly:grob-property stem-grob 'stem-end-position))))
(define-public ((glyph-flag flag-style) stem-grob)
- "Simulates the default way of generating flags: look up glyphs
- flags.style[ud][1234] from the feta font and use it for the flag stencil."
+ "Simulatesthe default way of generating flags: Look up glyphs
+@code{flags.style[ud][1234]} from the feta font and use it for the flag
+stencil."
(create-glyph-flag flag-style "" stem-grob))
(define-public (normal-flag stem-grob)
- "Create a default flag"
+ "Create a default flag."
(create-glyph-flag "" "" stem-grob))
(define-public (default-flag stem-grob)
"Create a flag stencil for the stem. Its style will be derived from the
- @code{'flag-style} Stem property. By default, @code{lilypond} uses a
- C++ Function (which is slightly faster) to do exactly the same as this
- function. However, if one wants to modify the default flags, this function
- can be used to obtain the default flag stencil, which can then be modified
- at will. The correct way to do this is:
+@code{'flag-style} Stem property. By default, @code{lilypond} uses a
+C++ Function (which is slightly faster) to do exactly the same as this
+function. However, if one wants to modify the default flags, this function
+can be used to obtain the default flag stencil, which can then be modified
+at will. The correct way to do this is:
+
@example
\\override Stem #'flag = #default-flag
\\override Stem #'flag-style = #'mensural
"Set up music fonts.
Arguments:
- NODE the font tree to modify.
- NAME is the basename for the music font. NAME-DESIGNSIZE.otf should be the music font,
- NAME-brace.otf should have piano braces.
- DESIGN-SIZE-ALIST is a list of (ROUNDED . DESIGN-SIZE). ROUNDED is
- a suffix for font filenames, while DESIGN-SIZE should be the actual
- design size. The latter is used for text fonts loaded through
- pango/fontconfig
- FACTOR is a size factor relative to the default size that is being used.
- This is used to select the proper design size for the text fonts.
-"
+@itemize
+@item
+@var{node} is the font tree to modify.
+
+@item
+@var{name} is the basename for the music font.
+@file{@var{name}-<designsize>.otf} should be the music font,
+@file{@var{name}-brace.otf} should have piano braces.
+
+@item
+@var{family} is the family name of the music font.
+
+@item
+@var{design-size-alist} is a list of @code{(rounded . designsize)}.
+@code{rounded} is a suffix for font filenames, while @code{designsize}
+should be the actual design size. The latter is used for text fonts
+loaded through pango/fontconfig.
+
+@item
+@var{factor} is a size factor relative to the default size that is being
+used. This is used to select the proper design size for the text fonts.
+@end itemize"
(for-each
(lambda (x)
(add-font node
(define-public (dump-stencil-as-EPS-with-bbox paper dump-me filename
load-fonts
bbox)
- "Create an EPS file from stencil DUMP-ME to FILENAME. BBOX has
-format (left-x, lower-y, right x, up-y). If LOAD-FONTS set, include
-fonts inline."
+ "Create an EPS file from stencil @var{dump-me} to @var{filename}.
+@var{bbox} has format @code{(left-x, lower-y, right-x, upper-y)}. If
+@var{load-fonts} set, include fonts inline."
(define (to-rounded-bp-box box)
"Convert box to 1/72 inch with rounding to enlarge the box."
(let* ((scale (ly:output-def-lookup paper 'output-scale))
;; parser <-> output hooks.
(define-public (collect-bookpart-for-book parser book-part)
- "Toplevel book-part handler"
+ "Toplevel book-part handler."
(define (add-bookpart book-part)
(ly:parser-define!
parser 'toplevel-bookparts
(score-handler (scorify-music music parser)))))
(define-public (collect-music-for-book parser music)
- "Top-level music handler"
+ "Top-level music handler."
(collect-music-aux (lambda (score)
(collect-scores-for-book parser score))
parser
music))
(define-public (collect-book-music-for-book parser book music)
- "Book music handler"
+ "Book music handler."
(collect-music-aux (lambda (score)
(ly:book-add-score! book score))
parser
music))
(define-public (scorify-music music parser)
- "Preprocess MUSIC."
+ "Preprocess @var{music}."
(for-each (lambda (func)
(set! music (func music parser)))
(map-alist-keys func (cdr list)))))
(define-public (first-member members lst)
- "Return first successful MEMBER of member from MEMBERS in LST."
+ "Return first successful member (of member) from @var{members} in
+@var{lst}."
(if (null? members)
#f
(let ((m (member (car members) lst)))
(if m m (first-member (cdr members) lst)))))
(define-public (first-assoc keys lst)
- "Return first successful ASSOC of key from KEYS in LST."
+ "Return first successful assoc of key from @var{keys} in @var{lst}."
(if (null? keys)
#f
(let ((k (assoc (car keys) lst)))
(assoc-crawler key '() alist))
(define-public (map-selected-alist-keys function keys alist)
- "Returns alist with function applied to all of the values in list keys.
- For example:
- @code{guile> (map-selected-alist-keys - '(a b) '((a . 1) (b . -2) (c . 3) (d . 4)))}
- @code{((a . -1) (b . 2) (c . 3) (d . 4))}"
+ "Return @var{alist} with @var{function} applied to all of the values
+in list @var{keys}.
+
+For example:
+@example
+@code{guile> (map-selected-alist-keys - '(a b) '((a . 1) (b . -2) (c . 3) (d . 4)))}
+@code{((a . -1) (b . 2) (c . 3) (d . 4)}
+@end example"
(define (map-selected-alist-keys-helper function key alist)
(map
(lambda (pair)
(helper lst 0))
(define-public (count-list lst)
- "Given lst (E1 E2 .. ), return ((E1 . 1) (E2 . 2) ... )."
+ "Given @var{lst} as @code{(E1 E2 .. )}, return
+@code{((E1 . 1) (E2 . 2) ... )}."
(define (helper l acc count)
(if (pair? l)
(reverse (helper lst '() 1)))
(define-public (list-join lst intermediate)
- "put INTERMEDIATE between all elts of LST."
+ "Put @var{intermediate} between all elts of @var{lst}."
(fold-right
(lambda (elem prev)
(lset-difference eq? a b))
(define-public (uniq-list lst)
- "Uniq LST, assuming that it is sorted. Uses equal? for comparisons."
+ "Uniq @var{lst}, assuming that it is sorted. Uses @code{equal?}
+for comparisons."
(reverse!
(fold (lambda (x acc)
(list lst)))))
(define-public (split-list-by-separator lst pred)
- "Split LST at each element that satisfies PRED, and return the parts
- (with the separators removed) as a list of lists. Example:
- (split-list-by-separator '(a 0 b c 1 d) number?) ==> ((a) (b c) (d))"
+ "Split @var{lst} at each element that satisfies @var{pred}, and return
+the parts (with the separators removed) as a list of lists. For example,
+executing @samp{(split-list-by-separator '(a 0 b c 1 d) number?)} returns
+@samp{((a) (b c) (d))}."
(let loop ((result '()) (lst lst))
(if (and lst (not (null? lst)))
(loop
(cons (- expr) expr))
(define-public (interval-length x)
- "Length of the number-pair X, when an interval"
+ "Length of the number-pair @var{x}, if an interval."
(max 0 (- (cdr x) (car x))))
(define-public (ordered-cons a b)
((if (= dir RIGHT) cdr car) interval))
(define-public (interval-index interval dir)
- "Interpolate INTERVAL between between left (DIR=-1) and right (DIR=+1)"
+ "Interpolate @var{interval} between between left (@var{dir}=-1) and
+right (@var{dir}=+1)."
(* (+ (interval-start interval) (interval-end interval)
(* dir (- (interval-end interval) (interval-start interval))))
0.5))
(define-public (interval-center x)
- "Center the number-pair X, when an interval"
+ "Center the number-pair @var{x}, if an interval."
(if (interval-empty? x)
0.0
(/ (+ (car x) (cdr x)) 2)))
(define-public THREE-PI-OVER-TWO (* 3 PI-OVER-TWO))
(define-public (cyclic-base-value value cycle)
- "Takes a value and modulo-maps it between 0 and base."
+ "Take @var{value} and modulo-maps it between 0 and base @var{cycle}."
(if (< value 0)
(cyclic-base-value (+ value cycle) cycle)
(if (>= value cycle)
value)))
(define-public (angle-0-2pi angle)
- "Takes an angle in radians and maps it between 0 and 2pi."
+ "Take @var{angle} (in radians) and maps it between 0 and 2pi."
(cyclic-base-value angle TWO-PI))
(define-public (angle-0-360 angle)
- "Takes an angle in radians and maps it between 0 and 2pi."
+ "Take @var{angle} (in degrees) and maps it between 0 and 360 degrees."
(cyclic-base-value angle 360.0))
(define-public PI-OVER-180 (/ PI 180))
(define-public (degrees->radians angle-degrees)
- "Convert the given angle from degrees to radians"
+ "Convert the given angle from degrees to radians."
(* angle-degrees PI-OVER-180))
(define-public (ellipse-radius x-radius y-radius angle)
(* (sin angle) (sin angle)))))))
(define-public (polar->rectangular radius angle-in-degrees)
- "Convert polar coordinate @code{radius} and @code{angle-in-degrees}
- to (x-length . y-length)"
+ "Return polar coordinates (@var{radius}, @var{angle-in-degrees})
+as rectangular coordinates @ode{(x-length . y-length)}."
+
(let ((complex (make-polar
radius
(degrees->radians angle-in-degrees))))
(ly:number->string (cdr c))))
(define-public (dir-basename file . rest)
- "Strip suffixes in REST, but leave directory component for FILE."
+ "Strip suffixes in @var{rest}, but leave directory component for
+@var{file}."
(define (inverse-basename x y) (basename y x))
(simple-format #f "~a/~a" (dirname file)
(fold inverse-basename file rest)))
(define-public (write-me message x)
- "Return X. Display MESSAGE and write X. Handy for debugging,
-possibly turned off."
+ "Return @var{x}. Display @var{message} and write @var{x}.
+Handy for debugging, possibly turned off."
(display message) (write x) (newline) x)
;; x)
(cons (f (car x)) (f (cdr x))))
(define-public (list-insert-separator lst between)
- "Create new list, inserting BETWEEN between elements of LIST"
+ "Create new list, inserting @var{between} between elements of @var{lst}."
(define (conc x y )
(if (eq? y #f)
(list x)
(define-public (binary-search start end getter target-val)
(_i "Find the index between @var{start} and @var{end} (an integer)
-which will produce the closest match to @var{target-val} when
+which produces the closest match to @var{target-val} if
applied to function @var{getter}.")
(if (<= end start)
start
(string<? (symbol->string (car lst)) (symbol->string (car r))))
(define-public (eval-carefully symbol module . default)
- "Check if all symbols in expr SYMBOL are reachable
-in module MODULE. In that case evaluate, otherwise
-print a warning and set an optional DEFAULT."
+ "Check whether all symbols in expr @var{symbol} are reachable
+in module @var{module}. In that case evaluate, otherwise
+print a warning and set an optional @var{default}."
(let* ((unavailable? (lambda (sym)
(not (module-defined? module sym))))
(sym-unavailable (if (pair? symbol)
format)
(define-public (ergonomic-simple-format dest . rest)
- "Like ice-9 format, but without the memory consumption."
+ "Like ice-9's @code{format}, but without the memory consumption."
(if (string? dest)
(apply simple-format (cons #f (cons dest rest)))
(apply simple-format (cons dest rest))))
,(symbol->string make-markup-name) sig args)))))))
(define-public (make-markup markup-function make-name signature args)
- " Construct a markup object from MARKUP-FUNCTION and ARGS. Typecheck
-against SIGNATURE, reporting MAKE-NAME as the user-invoked function.
-"
+ "Construct a markup object from @var{markup-function} and @var{args}.
+Typecheck against @var{signature}, reporting @var{make-name} as the
+user-invoked function."
(let* ((arglen (length args))
(siglen (length signature))
(error-msg (if (and (> siglen 0) (> arglen 0))
;;;
(define-public (markup-command-signature-ref markup-command)
- "Return markup-command's signature (the 'markup-signature object property)"
+ "Return @var{markup-command}'s signature (the @code{'markup-signature}
+object property)."
(object-property markup-command 'markup-signature))
(define-public (markup-command-signature-set! markup-command signature)
- "Set markup-command's signature (as object property)"
+ "Set @var{markup-command}'s signature (as object property)."
(set-object-property! markup-command 'markup-signature signature)
signature)
;;;;;;;;;;;;;;;;;;;;;;
;;; used in parser.yy to map a list of markup commands on markup arguments
(define-public (map-markup-command-list commands markups)
- "`markups' being a list of markups, eg (markup1 markup2 markup3),
-and `commands' a list of commands with their scheme arguments, in reverse order,
-eg: ((italic) (raise 4) (bold)), maps the commands on each markup argument, eg:
- ((bold (raise 4 (italic markup1)))
- (bold (raise 4 (italic markup2)))
- (bold (raise 4 (italic markup3))))
-"
+ "@var{markups} being a list of markups, for example
+@code{(markup1 markup2 markup3)}, and @var{commands} a list of commands with
+their scheme arguments, in reverse order, for example
+@code{((italic) (raise 4) (bold))}, map the commands on each markup argument,
+for example
+@example
+((bold (raise 4 (italic markup1)))
+ (bold (raise 4 (italic markup2)))
+ (bold (raise 4 (italic markup3))))
+@end example"
(map-in-order (lambda (arg)
(let ((result arg))
(for-each (lambda (cmd)
(object-property x 'markup-list-command)))
(define-public (markup-command-list? x)
- "Determine if `x' is a markup command list, ie. a list composed of
-a markup list function and its arguments."
+ "Determine whether @var{x} is a markup command list, i.e. a list
+composed of a markup list function and its arguments."
(and (pair? x) (markup-list-function? (car x))))
(define-public (markup-list? arg)
- "Return a true value if `x' is a list of markups or markup command lists."
+ "Return @code{#t} if @var{x} is a list of markups or markup command lists."
(define (markup-list-inner? lst)
(or (null? lst)
(and (or (markup? (car lst)) (markup-command-list? (car lst)))
instrument-names-alist))
(define-public (percussion? instrument)
- "returns whether the instrument should use midi channel 9"
+ "Return @code{#t} if the instrument should use MIDI channel 9."
(let* ((inst (symbol->string instrument))
(entry (assoc-get inst instrument-names-alist)))
(and entry (>= entry 32768))))
(define-public (midi-program instrument)
- "returns the program of the instrument"
+ "Return the program of the instrument."
(let* ((inst (symbol->string instrument))
(entry (assoc-get inst instrument-names-alist)))
(define-public dynamic-default-volume 0.71)
(define-public (alterations-in-key pitch-list)
- "Count number of sharps minus number of flats"
+ "Count number of sharps minus number of flats."
(* (apply + (map cdr pitch-list)) 2))
(define-public (music-map function music)
"Apply @var{function} to @var{music} and all of the music it contains.
-First it recurses over the children, then the function is applied to MUSIC.
-"
+First it recurses over the children, then the function is applied to
+@var{music}."
(let ((es (ly:music-property music 'elements))
(e (ly:music-property music 'element)))
(set! (ly:music-property music 'elements)
(function music)))
(define-public (music-filter pred? music)
- "Filter out music expressions that do not satisfy PRED."
+ "Filter out music expressions that do not satisfy @var{pred?}."
(define (inner-music-filter pred? music)
"Recursive function."
(make-music 'Music))) ;must return music.
(define-public (display-music music)
- "Display music, not done with music-map for clarity of presentation."
+ "Display music, not done with @code{music-map} for clarity of
+presentation."
(display music)
(display ": { ")
`(markup ,@(inner-markup->make-markup markup-expression))))
(define-public (music->make-music obj)
- "Generate a expression that, once evaluated, may return an object equivalent to `obj',
-that is, for a music expression, a (make-music ...) form."
+ "Generate an expression that, once evaluated, may return an object
+equivalent to @var{obj}, that is, for a music expression, a
+@code{(make-music ...)} form."
(cond (;; markup expression
(markup? obj)
(markup-expression->make-markup obj))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(define-public (shift-one-duration-log music shift dot)
- "Add SHIFT to duration-log of 'duration in music and optionally
-a dot to any note encountered. This scales the music up by a factor
-2^shift * (2 - (1/2)^dot)."
+ "Add @var{shift} to @code{duration-log} of @code{'duration} in
+@var{music} and optionally @var{dot} to any note encountered. This
+scales the music up by a factor `2^@var{shift} * (2 - (1/2)^@var{dot})'."
(let ((d (ly:music-property music 'duration)))
(if (ly:duration? d)
(let* ((cp (ly:duration-factor d))
music))
(define-public (make-repeat name times main alts)
- "create a repeat music expression, with all properties initialized properly"
+ "Create a repeat music expression, with all properties initialized
+properly."
(define (first-note-duration music)
"Finds the duration of the first NoteEvent by searching depth-first
through MUSIC."
;; clusters.
(define-public (note-to-cluster music)
- "Replace NoteEvents by ClusterNoteEvents."
+ "Replace @code{NoteEvents} by @code{ClusterNoteEvents}."
(if (eq? (ly:music-property music 'name) 'NoteEvent)
(make-music 'ClusterNoteEvent
'pitch (ly:music-property music 'pitch)
;; repeats.
(define-public (unfold-repeats music)
- "This function replaces all repeats with unfolded repeats."
+ "Replace all repeats with unfolded repeats."
(let ((es (ly:music-property music 'elements))
(e (ly:music-property music 'element)))
;; property setting music objs.
(define-public (make-grob-property-set grob gprop val)
- "Make a Music expression that sets GPROP to VAL in GROB. Does a pop first,
-i.e., this is not an override."
+ "Make a @code{Music} expression that sets @var{gprop} to @var{val} in
+@var{grob}. Does a pop first, i.e., this is not an override."
(make-music 'OverrideProperty
'symbol grob
'grob-property gprop
'pop-first #t))
(define-public (make-grob-property-override grob gprop val)
- "Make a Music expression that overrides GPROP to VAL in GROB."
+ "Make a @code{Music} expression that overrides @var{gprop} to @var{val}
+in @var{grob}."
(make-music 'OverrideProperty
'symbol grob
'grob-property gprop
'grob-value val))
(define-public (make-grob-property-revert grob gprop)
- "Revert the grob property GPROP for GROB."
+ "Revert the grob property @var{gprop} for @var{grob}."
(make-music 'RevertProperty
'symbol grob
'grob-property gprop))
cm))
(define-public (descend-to-context m context)
- "Like context-spec-music, but only descending."
+ "Like @code{context-spec-music}, but only descending."
(let ((cm (context-spec-music m context)))
(ly:music-set-property! cm 'descend-only #t)
cm))
;;; Need to keep this definition for \time calls from parser
(define-public (make-time-signature-set num den)
- "Set properties for time signature NUM/DEN."
+ "Set properties for time signature @var{num}/@var{den}."
(make-music 'TimeSignatureMusic
'numerator num
'denominator den
;;; Used for calls that include beat-grouping setting
(define-public (set-time-signature num den . rest)
- "Set properties for time signature @var{num/den}.
-If @var{rest} is present, it is used to set
-@code{beatStructure}."
+ "Set properties for time signature @var{num}/@var{den}.
+If @var{rest} is present, it is used to set @code{beatStructure}."
(ly:export
(make-music 'TimeSignatureMusic
'numerator num
(revert-head-style heads)))))
(define-public (set-mus-properties! m alist)
- "Set all of ALIST as properties of M."
+ "Set all of @var{alist} as properties of @var{m}."
(if (pair? alist)
(begin
(set! (ly:music-property m (caar alist)) (cdar alist))
(set-mus-properties! m (cdr alist)))))
(define-public (music-separator? m)
- "Is M a separator?"
+ "Is @var{m} a separator?"
(let ((ts (ly:music-property m 'types)))
(memq 'separator ts)))
ch))
(define-public (voicify-music m)
- "Recursively split chords that are separated with \\ "
+ "Recursively split chords that are separated with @code{\\\\}."
(if (not (ly:music? m))
(ly:error (_ "music expected: ~S") m))
(let ((es (ly:music-property m 'elements))
(define-public ((set-output-property grob-name symbol val) grob grob-c context)
- "Usage:
-
-\\applyoutput #(set-output-property 'Clef 'extra-offset '(0 . 1))
-
-"
+ "Usage example:
+@code{\\applyoutput #(set-output-property 'Clef 'extra-offset '(0 . 1))}"
(let ((meta (ly:grob-property grob 'meta)))
(if (equal? (assoc-get 'name meta) grob-name)
(set! (ly:grob-property grob symbol) val))))
;;
(define-public (smart-bar-check n)
- "Make a bar check that checks for a specific bar number.
-"
+ "Make a bar check that checks for a specific bar number."
(let ((m (make-music 'ApplyContext)))
(define (checker tr)
(let* ((bn (ly:context-property tr 'currentBarNumber)))
(define-public (skip->rest mus)
-
- "Replace MUS by RestEvent of the same duration if it is a
-SkipEvent. Useful for extracting parts from crowded scores."
+ "Replace @var{mus} by @code{RestEvent} of the same duration if it is a
+@code{SkipEvent}. Useful for extracting parts from crowded scores."
(if (memq (ly:music-property mus 'name) '(SkipEvent SkipMusic))
(make-music 'RestEvent 'duration (ly:music-property mus 'duration))
(f (vector-ref v i))))
(define-public (add-grace-property context-name grob sym val)
- "Set SYM=VAL for GROB in CONTEXT-NAME."
+ "Set @var{sym}=@var{val} for @var{grob} in @var{context-name}."
(define (set-prop context)
(let* ((where (ly:context-property-where-defined context 'graceSettings))
(current (ly:context-property where 'graceSettings))
(ly:export (context-spec-music (make-apply-context set-prop) 'Voice)))
(define-public (remove-grace-property context-name grob sym)
- "Remove all SYM for GROB in CONTEXT-NAME."
+ "Remove all @var{sym} for @var{grob} in @var{context-name}."
(define (sym-grob-context? property sym grob context-name)
(and (eq? (car property) context-name)
(eq? (cadr property) grob)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(define-public (cue-substitute quote-music)
- "Must happen after quote-substitute."
+ "Must happen after @code{quote-substitute}."
(if (vector? (ly:music-property quote-music 'quoted-events))
(let* ((dir (ly:music-property quote-music 'quoted-voice-direction))
music)
(define-public (make-duration-of-length moment)
- "Make duration of the given MOMENT length."
+ "Make duration of the given @code{moment} length."
(ly:make-duration 0 0
(ly:moment-main-numerator moment)
(ly:moment-main-denominator moment)))
(cons need-restore need-accidental)))
(define-public ((make-accidental-rule octaveness laziness) context pitch barnum measurepos)
- "Creates an accidental rule that makes its decision based on the octave of the note
-and a laziness value.
-octaveness is either 'same-octave or 'any-octave and defines whether the rule should
-respond to accidental changes in other octaves than the current. 'same-octave is the
-normal way to typeset accidentals - an accidental is made if the alteration is different
-from the last active pitch in the same octave. 'any-octave looks at the last active pitch
-in any octave.
-laziness states over how many bars an accidental should be remembered.
-0 is default - accidental lasts over 0 bar lines, that is, to the end of current measure.
-A positive integer means that the accidental lasts over that many bar lines.
--1 is 'forget immediately', that is, only look at key signature.
-#t is forever."
+ "Create an accidental rule that makes its decision based on the octave of
+the note and a laziness value.
+
+@var{octaveness} is either @code{'same-octave} or @code{'any-octave} and
+defines whether the rule should respond to accidental changes in other
+octaves than the current. @code{'same-octave} is the normal way to typeset
+accidentals -- an accidental is made if the alteration is different from the
+last active pitch in the same octave. @code{'any-octave} looks at the last
+active pitch in any octave.
+
+@var{laziness} states over how many bars an accidental should be remembered.
+@code{0}@tie{}is the default -- accidental lasts over 0@tie{}bar lines, that
+is, to the end of current measure. A positive integer means that the
+accidental lasts over that many bar lines. @code{-1} is `forget
+immediately', that is, only look at key signature. @code{#t} is `forever'."
+
(check-pitch-against-signature context pitch barnum laziness octaveness))
(define (key-entry-notename entry)
(cadr entry)))
(define-public (find-pitch-entry keysig pitch accept-global accept-local)
- "Return the first entry in keysig that matches the pitch.
- accept-global states whether key signature entries should be included.
- accept-local states whether local accidentals should be included.
- if no matching entry is found, #f is returned."
+ "Return the first entry in @var{keysig} that matches @var{pitch}.
+@var{accept-global} states whether key signature entries should be included.
+@var{accept-local} states whether local accidentals should be included.
+If no matching entry is found, @var{#f} is returned."
(if (pair? keysig)
(let* ((entry (car keysig))
(entryoct (key-entry-octave entry))
#f))
(define-public (neo-modern-accidental-rule context pitch barnum measurepos)
- "an accidental rule that typesets an accidental if it differs from the key signature
- AND does not directly follow a note on the same staff-line.
- This rule should not be used alone because it does neither look at bar lines
- nor different accidentals at the same notename"
+ "An accidental rule that typesets an accidental if it differs from the
+key signature @emph{and} does not directly follow a note on the same
+staff line. This rule should not be used alone because it does neither
+look at bar lines nor different accidentals at the same note name."
(let* ((keysig (ly:context-property context 'localKeySignature))
(entry (find-pitch-entry keysig pitch #t #t)))
(if (equal? #f entry)
(and (equal? entrybn barnum) (equal? entrymp measurepos)))))))))
(define-public (teaching-accidental-rule context pitch barnum measurepos)
- "an accidental rule that typesets a cautionary accidental
- if it is included in the key signature AND does not directly follow
- a note on the same staff-line."
+ "An accidental rule that typesets a cautionary accidental if it is
+included in the key signature @emph{and} does not directly follow a note
+on the same staff line."
(let* ((keysig (ly:context-property context 'localKeySignature))
(entry (find-pitch-entry keysig pitch #t #t)))
(if (equal? #f entry)
context))
(define-public (set-accidental-style style . rest)
- "Set accidental style to STYLE. Optionally takes a context argument,
-e.g. 'Staff or 'Voice. The context defaults to Staff, except for piano styles, which
-use GrandStaff as a context."
+ "Set accidental style to @var{style}. Optionally take a context
+argument, e.g. @code{'Staff} or @code{'Voice}. The context defaults
+to @code{Staff}, except for piano styles, which use @code{GrandStaff}
+as a context."
(let ((context (if (pair? rest)
(car rest) 'Staff))
(pcontext (if (pair? rest)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(define-public (skip-of-length mus)
- "Create a skip of exactly the same length as MUS."
+ "Create a skip of exactly the same length as @var{mus}."
(let* ((skip
(make-music
'SkipEvent
(make-event-chord (list (ly:music-compress skip (ly:music-length mus))))))
(define-public (mmrest-of-length mus)
- "Create a mmrest of exactly the same length as MUS."
+ "Create a multi-measure rest of exactly the same length as @var{mus}."
(let* ((skip
(make-multi-measure-rest
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(define-public (extract-named-music music music-name)
-"Return a flat list of all music named @code{music-name}
-from @code{music}."
+ "Return a flat list of all music named @var{music-name} from @var{music}."
(let ((extracted-list
(if (ly:music? music)
(if (eq? (ly:music-property music 'name) music-name)
(flatten-list extracted-list)))
(define-public (event-chord-notes event-chord)
-"Return a list of all notes from @{event-chord}."
+ "Return a list of all notes from @var{event-chord}."
(filter
(lambda (m) (eq? 'NoteEvent (ly:music-property m 'name)))
(ly:music-property event-chord 'elements)))
(define-public (event-chord-pitches event-chord)
-"Return a list of all pitches from @{event-chord}."
+ "Return a list of all pitches from @var{event-chord}."
(map (lambda (x) (ly:music-property x 'pitch))
(event-chord-notes event-chord)))
(pair? (ly:grob-basic-properties grob)))
(define-public (make-stencil-boxer thickness padding callback)
-
"Return function that adds a box around the grob passed as argument."
(lambda (grob)
(box-stencil (callback grob) thickness padding)))
(define-public (make-stencil-circler thickness padding callback)
"Return function that adds a circle around the grob passed as argument."
-
- (lambda (grob) (circle-stencil (callback grob) thickness padding)))
+ (lambda (grob)
+ (circle-stencil (callback grob) thickness padding)))
(define-public (print-circled-text-callback grob)
(grob-interpret-markup grob (make-circle-markup
(format "<~S~a>\n" entity (attributes attributes-alist)))
(define-public (eoc entity . attributes-alist)
- " oc = open/close"
+ "oc = open/close"
(format "<~S~a/>\n" entity (attributes attributes-alist)))
(define-public (ec entity)
))
(define-public (layout-set-absolute-staff-size sz)
- "Function to be called inside a \\layout{} block to set the staff
-size. SZ is in points"
+ "Set the absolute staff size inside of a @code{\\layout@{@}} block.
+@var{sz} is in points."
(layout-set-absolute-staff-size-in-module (current-module) sz))
(define-public (layout-set-staff-size sz)
- "Function to be called inside a \\layout{} block to set the staff
-size. SZ is in points"
+ "Set the staff size inside of a @code{\\layout@{@}} block.
+@var{sz} is in points."
(layout-set-absolute-staff-size (* (eval 'pt (current-module)) sz)))
("clefs.petrucci.g" . -4)))
(define-public (make-clef-set clef-name)
- "Generate the clef setting commands for a clef with name CLEF-NAME."
+ "Generate the clef setting commands for a clef with name @var{clef-name}."
(define (make-prop-set props)
(let ((m (make-music 'PropertySet)))
(map (lambda (x) (set! (ly:music-property m (car x)) (cdr x))) props)
(make-music 'Music)))))
(define-public (make-cue-clef-set clef-name)
- "Generate the clef setting commands for a cue clef with name CLEF-NAME."
+ "Generate the clef setting commands for a cue clef with name
+@var{clef-name}."
(define (make-prop-set props)
(let ((m (make-music 'PropertySet)))
(map (lambda (x) (set! (ly:music-property m (car x)) (cdr x))) props)
;; a function to add new clefs at runtime
(define-public (add-new-clef clef-name clef-glyph clef-position octavation c0-position)
- "Append the entries for a clef symbol to supported clefs and c0-pitch-alist"
+ "Append the entries for a clef symbol to supported clefs and
+@code{c0-pitch-alist}."
(set! supported-clefs
(acons clef-name (list clef-glyph clef-position octavation) supported-clefs))
(set! c0-pitch-alist
(string->list (number->string var-idx)))))))))
(define-public (parse-string-result str parser)
- "Parse `str', which is supposed to contain a music expression."
+ "Parse @var{str}, which is supposed to contain a music expression."
(ly:parser-parse-string
parser
(ly:parser-lookup parser 'parseStringResult))
(define-public (read-lily-expression chr port)
- "Read a #{ lily music expression #} from port and return
-the scheme music expression. The $ character may be used to introduce
-scheme forms, typically symbols. $$ may be used to simply write a `$'
-character."
+ "Read a lilypond music expression enclosed within @code{#@}} and @code{#@}}
+from @var{port} and return the corresponding Scheme music expression.
+The @samp{$} character may be used to introduce Scheme forms, typically
+symbols. @code{$$} may be used to simply write a @samp{$} character itself."
(let ((bindings '()))
(define (create-binding! val)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(define-public (recording-group-emulate music odef)
- "Interprets music according to odef, but stores all events in a chronological
-list, similar to the Recording_group_engraver in 2.8 and earlier"
+ "Interpret @var{music} according to @var{odef}, but store all events
+in a chronological list, similar to the @code{Recording_group_engraver} in
+LilyPond version 2.8 and earlier."
(let*
((context-list '())
(now-mom (ly:make-moment 0 0))
m))
(define-public (determine-split-list evl1 evl2)
- "EVL1 and EVL2 should be ascending"
+ "@var{evl1} and @var{evl2} should be ascending."
(let* ((pc-debug #f)
(chord-threshold 8)
(voice-state-vec1 (make-voice-states evl1))
(define-public (parse-terse-string terse-definition)
-"Parse a fret-diagram-terse definition string @code{terse-definition} and
-return a marking list, which can be used with a fretboard grob."
+ "Parse a @code{fret-diagram-terse} definition string @var{terse-definition}
+and return a marking list, which can be used with a fretboard grob."
(cdr (fret-parse-terse-definition-string (list '()) terse-definition)))
(define-public (get-chord-shape shape-code tuning base-chord-shapes)
-"Return the chord shape associated with @code{shape-code} and
-@code{tuning} in the hash-table @code{base-chord-shapes}."
+ "Return the chord shape associated with @var{shape-code} and
+@var{tuning} in the hash-table @var{base-chord-shapes}."
(let ((hash-handle (hash-get-handle base-chord-shapes
(cons shape-code tuning))))
(if hash-handle
'())))
(define-public (offset-fret fret-offset diagram-definition)
-"Add @code{fret-offset} to each fret indication in @code{diagram-definition}
-and return the resulting verbose fret-diagram-definition."
+ "Add @var{fret-offset} to each fret indication in
+@var{diagram-definition} and return the resulting verbose
+@code{fret-diagram-definition}."
(let ((verbose-definition
(if (string? diagram-definition)
(parse-terse-string diagram-definition)
(define-public (music-property-value? music property value)
- "Return true iff MUSIC's PROPERTY is equal to VALUE."
+ "Return @code{#t} iff @var{music}'s @var{property} is equal to
+@var{value}."
(equal? (ly:music-property music property) value))
(define-public (music-name? music name)
- "Return true iff MUSIC's name is NAME."
+ "Return @code{#t} iff @var{music}'s name is @var{name}."
(if (list? name)
(member (ly:music-property music 'name) name)
(music-property-value? music 'name name)))
(define-public (music-property? music property)
- "Return true iff MUSIC is a property setter and sets or unsets PROPERTY."
+ "Return @code{#t} iff @var{music} is a property setter and sets
+or unsets @var{property}."
(and (music-name? music '(PropertySet PropertyUnset))
(music-property-value? music 'symbol property)))
(define-public (music-has-property? music property)
- "Return true iff MUSIC contains PROPERTY."
+ "Return @code{#t} iff @var{music} contains @var{property}."
(not (eq? (ly:music-property music property) '())))
(define-public (property-value music)
- "Return value of a property setter MUSIC.
-If it unsets the property, return #f."
+ "Return value of a property setter @var{music}.
+If it unsets the property, return @code{#f}."
(if (music-name? music 'PropertyUnset)
#f
(ly:music-property music 'value)))
(define-public (music-elements music)
- "Return list of all MUSIC's top-level children."
+ "Return list of all @var{music}'s top-level children."
(let ((elt (ly:music-property music 'element))
(elts (ly:music-property music 'elements)))
(if (not (null? elt))
elts)))
(define-public (find-child music predicate)
- "Find the first node in MUSIC that satisfies PREDICATE."
+ "Find the first node in @var{music} that satisfies @var{predicate}."
(define (find-child queue)
(if (null? queue)
#f
(find-child (list music)))
(define-public (find-child-named music name)
- "Return the first child in MUSIC that is named NAME."
+ "Return the first child in @var{music} that is named @var{name}."
(find-child music (lambda (elt) (music-name? elt name))))
(define-public (process-music music function)
- "Process all nodes of MUSIC (including MUSIC) in the DFS order.
-Apply FUNCTION on each of the nodes.
-If FUNCTION applied on a node returns true, don't process the node's subtree."
+ "Process all nodes of @var{music} (including @var{music}) in the DFS order.
+Apply @var{function} on each of the nodes. If @var{function} applied on a
+node returns @code{#t}, don't process the node's subtree."
(define (process-music queue)
(if (not (null? queue))
(let* ((elt (car queue))
;;;; along with LilyPond. If not, see <http://www.gnu.org/licenses/>.
(define-public (stack-stencils axis dir padding stils)
- "Stack stencils STILS in direction AXIS, DIR, using PADDING."
+ "Stack stencils @var{stils} in direction @var{axis}, @var{dir}, using
+@var{padding}."
(cond
((null? stils) empty-stencil)
((null? (cdr stils)) (car stils))
padding))))
(define-public (stack-stencils-padding-list axis dir padding stils)
- "Stack stencils STILS in direction AXIS, DIR, using a list of PADDING."
+ "Stack stencils @var{stils} in direction @var{axis}, @var{dir}, using
+a list of @var{padding}."
(cond
((null? stils) empty-stencil)
((null? (cdr stils)) (car stils))
(car padding)))))
(define-public (centered-stencil stencil)
- "Center stencil @var{stencil} in both the X and Y directions"
+ "Center stencil @var{stencil} in both the X and Y directions."
(ly:stencil-aligned-to (ly:stencil-aligned-to stencil X CENTER) Y CENTER))
(define-public (stack-lines dir padding baseline stils)
- "Stack vertically with a baseline-skip."
+ "Stack vertically with a baseline skip."
(define result empty-stencil)
(define last-y #f)
(do
(define-public (bracketify-stencil stil axis thick protrusion padding)
- "Add brackets around STIL, producing a new stencil."
+ "Add brackets around @var{stil}, producing a new stencil."
(let* ((ext (ly:stencil-extent stil axis))
(lb (ly:bracket axis ext thick protrusion))
stencil))
(define-public (make-line-stencil width startx starty endx endy)
- "Make a line stencil of given linewidth and set its extents accordingly"
+ "Make a line stencil of given linewidth and set its extents accordingly."
(let ((xext (cons (min startx endx) (max startx endx)))
(yext (cons (min starty endy) (max starty endy))))
(ly:make-stencil
xext yext))
(define-public (make-circle-stencil radius thickness fill)
- "Make a circle of radius @var{radius} and thickness @var{thickness}"
+ "Make a circle of radius @var{radius} and thickness @var{thickness}."
(let*
((out-radius (+ radius (/ thickness 2.0))))
(cons (- out-radius) out-radius))))
(define-public (make-oval-stencil x-radius y-radius thickness fill)
- "Make an oval from two Bezier curves, of x radius @var{x-radius},
- y radius @code{y-radius},
- and thickness @var{thickness} with fill defined by @code{fill}."
+ "Make an oval from two Bezier curves, of x@tie{}radius @var{x-radius},
+y@tie{}radius @code{y-radius}, and thickness @var{thickness} with fill
+defined by @code{fill}."
(let*
((x-out-radius (+ x-radius (/ thickness 2.0)))
(y-out-radius (+ y-radius (/ thickness 2.0))) )
`(,(/ thickness -2) . ,(/ thickness 2))))))
(define-public (make-ellipse-stencil x-radius y-radius thickness fill)
- "Make an ellipse of x radius @var{x-radius}, y radius @code{y-radius},
- and thickness @var{thickness} with fill defined by @code{fill}."
+ "Make an ellipse of x@tie{}radius @var{x-radius}, y@tie{}radius
+@code{y-radius}, and thickness @var{thickness} with fill defined by
+@code{fill}."
(let*
((x-out-radius (+ x-radius (/ thickness 2.0)))
(y-out-radius (+ y-radius (/ thickness 2.0))) )
(define-public (box-grob-stencil grob)
"Make a box of exactly the extents of the grob. The box precisely
-encloses the contents.
-"
+encloses the contents."
(let* ((xext (ly:grob-extent grob grob 0))
(yext (ly:grob-extent grob grob 1))
(thick 0.01))
;; TODO merge this and prev function.
(define-public (box-stencil stencil thickness padding)
- "Add a box around STENCIL, producing a new stencil."
+ "Add a box around @var{stencil}, producing a new stencil."
(let* ((x-ext (interval-widen (ly:stencil-extent stencil 0) padding))
(y-ext (interval-widen (ly:stencil-extent stencil 1) padding))
(y-rule (make-filled-box-stencil (cons 0 thickness) y-ext))
stencil))
(define-public (circle-stencil stencil thickness padding)
- "Add a circle around STENCIL, producing a new stencil."
+ "Add a circle around @var{stencil}, producing a new stencil."
(let* ((x-ext (ly:stencil-extent stencil X))
(y-ext (ly:stencil-extent stencil Y))
(diameter (max (interval-length x-ext)
(define-public (oval-stencil stencil thickness x-padding y-padding)
"Add an oval around @code{stencil}, padded by the padding pair,
- producing a new stencil."
+producing a new stencil."
(let* ((x-ext (ly:stencil-extent stencil X))
(y-ext (ly:stencil-extent stencil Y))
(x-length (+ (interval-length x-ext) x-padding thickness))
(interval-center y-ext))))))
(define-public (ellipse-stencil stencil thickness x-padding y-padding)
- "Add an ellipse around STENCIL, padded by the padding pair,
- producing a new stencil."
+ "Add an ellipse around @var{stencil}, padded by the padding pair,
+producing a new stencil."
(let* ((x-ext (ly:stencil-extent stencil X))
(y-ext (ly:stencil-extent stencil Y))
(x-length (+ (interval-length x-ext) x-padding thickness))
(interval-center y-ext))))))
(define-public (rounded-box-stencil stencil thickness padding blot)
- "Add a rounded box around STENCIL, producing a new stencil."
+ "Add a rounded box around @var{stencil}, producing a new stencil."
(let* ((xext (interval-widen (ly:stencil-extent stencil 0) padding))
(yext (interval-widen (ly:stencil-extent stencil 1) padding))
))
(define-public (arrow-stencil-maker start? end?)
- "Returns a function drawing a line from current point to @var{destination},
- with optional arrows of @var{max-size} on start and end controlled by
- @var{start?} and @var{end?}."
+ "Return a function drawing a line from current point to @code{destination},
+with optional arrows of @code{max-size} on start and end controlled by
+@var{start?} and @var{end?}."
(lambda (destination max-size)
(let*
((e_x 1+0i)
(cons 'beamExceptions beam-exceptions)))
(define-public (base-fraction time-signature time-signature-settings)
- "Get @code{baseMoment} fraction value for @code{time-signature} from
-@code{time-signature-settings}."
+ "Get @code{baseMoment} fraction value for @var{time-signature} from
+@var{time-signature-settings}."
(let ((return-value (get-setting 'baseMoment
time-signature
time-signature-settings)))
return-value)))
(define-public (beat-structure base-fraction time-signature time-signature-settings)
- "Get beatStructure value in @code{base-fraction} units
-for @code{time-signature} from
-@code{time-signature-settings}."
+ "Get @code{beatStructure} value in @var{base-fraction} units
+for @var{time-signature} from @var{time-signature-settings}."
(define (fraction-divide numerator denominator)
(/ (* (car numerator) (cdr denominator))
(* (cdr numerator) (car denominator))))
return-value)))
(define-public (beam-exceptions time-signature time-signature-settings)
- "Get beamExceptions value for @code{time-signature} from
-@code{time-signature-settings}."
+ "Get @code{beamExceptions} value for @var{time-signature} from
+@var{time-signature-settings}."
(get-setting 'beamExceptions time-signature time-signature-settings))
(revert-member current-value setting)))))
(define-public (override-time-signature-setting time-signature setting)
- "Override the time signature settings for the context in @var{rest},
-with the new setting alist @var{setting}."
+ "Override the time signature settings for the context in
+@var{time-signature}, with the new setting alist @var{setting}."
(context-spec-music
(make-apply-context
(lambda (c) (override-property-setting
(define-public ((marked-up-headfoot what-odd what-even)
layout scopes page-number is-last-bookpart is-bookpart-last-page)
-
- "Read variables WHAT-ODD, WHAT-EVEN from LAYOUT, and interpret them
-as markup. The PROPS argument will include variables set in SCOPES and
-page:is-bookpart-last-page, page:is-last-bookpart, page:page-number-string
-and page:page-number"
+ "Read variables @var{what-odd}, @var{what-even} from @var{layout},
+and interpret them as markup. The @var{props} argument will include
+variables set in @var{scopes} and @code{page:is-bookpart-last-page},
+@code{page:is-last-bookpart}, @code{page:page-number-string}, and
+@code{page:page-number}."
(define (get sym)
(ly:output-def-lookup layout sym))
(get what-odd))))
(define-public ((marked-up-title what) layout scopes)
- "Read variables WHAT from SCOPES, and interpret it as markup. The
-PROPS argument will include variables set in SCOPES (prefixed with
-`header:'
-"
+ "Read variables @var{what} from @var{scopes}, and interpret it as markup.
+The @var{props} argument will include variables set in @var{scopes} (prefixed
+with `header:'."
(define (get sym)
(let ((x (ly:modules-lookup scopes sym)))
(string-append "</" (symbol->string name) ">"))
(define-public (music-to-xml music port)
- "Dump XML-ish stuff to PORT."
+ "Dump XML-ish stuff to @var{port}."
;; dtd contains # -- This confuses tex during make doc.
;;
(display (close-tag 'music) port))
(define-public (music-to-musicxml music port)
- "Dump MusicXML-ish stuff to PORT."
+ "Dump MusicXML-ish stuff to @var{port}."
;; dtd contains # -- This confuses tex during make doc.
;;
(define-public
(determine-frets context notes specified-info . rest)
"Determine string numbers and frets for playing @var{notes}
-as a chord, given specified information @var{specified-info}.
+as a chord, given specified information @var{specified-info}.
@var{specified-info} is a list with two list elements,
-specified strings @var{defined-strings} and
-specified fingerings @var{defined-fingers}. Only a fingering of
-0 will affect the fret selection, as it specifies an open string.
-If @var{defined-strings} is @code{'()}, the context property
+specified strings @code{defined-strings} and
+specified fingerings @code{defined-fingers}. Only a fingering of@tie{}0
+will affect the fret selection, as it specifies an open string.
+If @code{defined-strings} is @code{'()}, the context property
@code{defaultStrings} will be used as a list of defined strings.
Will look for predefined fretboards if @code{predefinedFretboardTable}
is not @code {#f}. If @var{rest} is present, it contains the
-FretBoard grob, and a fretboard will be
-created. Otherwise, a list of (string fret finger) lists will
-be returned)."
+@code{FretBoard} grob, and a fretboard will be
+created. Otherwise, a list of @code{(string fret finger)} lists will
+be returned."
;; helper functions
projects / lilypond.git / commitdiff