From 6d451df53791b15dc4707694deb3622b33299997 Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Wed, 26 Jan 2011 10:06:17 +0100 Subject: [PATCH 1/1] [scm] Improve formatting of `define-public' functions. --- scm/backend-library.scm | 16 +-- scm/chord-entry.scm | 9 +- scm/chord-generic-names.scm | 11 +-- scm/chord-name.scm | 9 +- scm/clip-region.scm | 4 +- scm/define-grob-properties.scm | 4 +- scm/define-music-display-methods.scm | 9 +- scm/define-stencil-commands.scm | 4 +- scm/define-woodwind-diagrams.scm | 15 +-- scm/display-lily.scm | 2 +- scm/encoding.scm | 2 +- scm/flag-styles.scm | 76 +++++++------- scm/font.scm | 32 ++++-- scm/framework-ps.scm | 6 +- scm/lily-library.scm | 77 ++++++++------- scm/lily.scm | 2 +- scm/markup.scm | 34 ++++--- scm/midi.scm | 6 +- scm/music-functions.scm | 142 ++++++++++++++------------- scm/output-lib.scm | 5 +- scm/output-svg.scm | 2 +- scm/paper.scm | 8 +- scm/parser-clef.scm | 8 +- scm/parser-ly-from-scheme.scm | 10 +- scm/part-combiner.scm | 7 +- scm/predefined-fretboards.scm | 13 +-- scm/song-util.scm | 26 ++--- scm/stencil.scm | 48 ++++----- scm/time-signature-settings.scm | 17 ++-- scm/titling.scm | 17 ++-- scm/to-xml.scm | 4 +- scm/translation-functions.scm | 16 +-- 32 files changed, 342 insertions(+), 299 deletions(-) diff --git a/scm/backend-library.scm b/scm/backend-library.scm index f21decd96b..706bccb2de 100644 --- a/scm/backend-library.scm +++ b/scm/backend-library.scm @@ -37,7 +37,7 @@ (throw 'ly-file-failed))))) (define-public (sanitize-command-option str) - "Kill dubious shell quoting" + "Kill dubious shell quoting." (string-append "\"" @@ -212,7 +212,8 @@ (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)) @@ -221,13 +222,13 @@ ;; 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) @@ -237,8 +238,9 @@ ""))) (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)) diff --git a/scm/chord-entry.scm b/scm/chord-entry.scm index c1238b78da..06cc077ce4 100644 --- a/scm/chord-entry.scm +++ b/scm/chord-entry.scm @@ -16,13 +16,12 @@ ;;;; along with LilyPond. If not, see . (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 '()) diff --git a/scm/chord-generic-names.scm b/scm/chord-generic-names.scm index 40482cdd00..a30036d1af 100644 --- a/scm/chord-generic-names.scm +++ b/scm/chord-generic-names.scm @@ -47,14 +47,13 @@ (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)) diff --git a/scm/chord-name.scm b/scm/chord-name.scm index 06b1178459..79b018992a 100644 --- a/scm/chord-name.scm +++ b/scm/chord-name.scm @@ -60,7 +60,7 @@ )))) (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 @@ -107,9 +107,10 @@ (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 diff --git a/scm/clip-region.scm b/scm/clip-region.scm index 3c52329fa7..8718f56104 100644 --- a/scm/clip-region.scm +++ b/scm/clip-region.scm @@ -50,8 +50,8 @@ ;; 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)) diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm index e6eb6a8c8d..cbe0058318 100644 --- a/scm/define-grob-properties.scm +++ b/scm/define-grob-properties.scm @@ -25,9 +25,7 @@ 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)) diff --git a/scm/define-music-display-methods.scm b/scm/define-music-display-methods.scm index 0d7e3c451b..4676747896 100644 --- a/scm/define-music-display-methods.scm +++ b/scm/define-music-display-methods.scm @@ -37,7 +37,8 @@ ;;; (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) @@ -968,7 +969,7 @@ Otherwise, return #f." ;;; \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) @@ -977,8 +978,8 @@ Otherwise, return #f." 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 diff --git a/scm/define-stencil-commands.scm b/scm/define-stencil-commands.scm index 8a86ce6439..eb7f85ddc1 100644 --- a/scm/define-stencil-commands.scm +++ b/scm/define-stencil-commands.scm @@ -20,7 +20,7 @@ (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 @@ -63,7 +63,7 @@ defined in the output modules (output-*.scm)" (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 diff --git a/scm/define-woodwind-diagrams.scm b/scm/define-woodwind-diagrams.scm index 944d9c67a9..501e63779a 100644 --- a/scm/define-woodwind-diagrams.scm +++ b/scm/define-woodwind-diagrams.scm @@ -22,16 +22,17 @@ ;; 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 diff --git a/scm/display-lily.scm b/scm/display-lily.scm index a144e8b398..51b13eb259 100644 --- a/scm/display-lily.scm +++ b/scm/display-lily.scm @@ -82,7 +82,7 @@ display method will be called." (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 diff --git a/scm/encoding.scm b/scm/encoding.scm index 9b65fa75cc..a35be6c391 100644 --- a/scm/encoding.scm +++ b/scm/encoding.scm @@ -59,7 +59,7 @@ (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))) diff --git a/scm/flag-styles.scm b/scm/flag-styles.scm index d390d5e884..9e1a268e4d 100644 --- a/scm/flag-styles.scm +++ b/scm/flag-styles.scm @@ -20,7 +20,7 @@ (define-public (no-flag stem-grob) - "No flag: Simply return empty stencil" + "No flag: Simply return empty stencil." empty-stencil) @@ -29,13 +29,16 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(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)))) @@ -53,12 +56,15 @@ 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)) @@ -101,13 +107,13 @@ (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)) @@ -126,7 +132,7 @@ (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 @@ -145,7 +151,7 @@ (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))) @@ -156,7 +162,7 @@ (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))) @@ -168,12 +174,12 @@ (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)))) @@ -185,25 +191,27 @@ (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 diff --git a/scm/font.scm b/scm/font.scm index 03926cbea5..84646d6c3f 100644 --- a/scm/font.scm +++ b/scm/font.scm @@ -151,16 +151,28 @@ "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}-.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 diff --git a/scm/framework-ps.scm b/scm/framework-ps.scm index da7119901e..18038a61af 100644 --- a/scm/framework-ps.scm +++ b/scm/framework-ps.scm @@ -462,9 +462,9 @@ (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)) diff --git a/scm/lily-library.scm b/scm/lily-library.scm index 6fb605b250..0e2c810da9 100644 --- a/scm/lily-library.scm +++ b/scm/lily-library.scm @@ -84,7 +84,7 @@ ;; 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 @@ -131,21 +131,21 @@ (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))) @@ -269,14 +269,15 @@ bookoutput function" (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))) @@ -301,10 +302,14 @@ bookoutput function" (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) @@ -383,7 +388,8 @@ bookoutput function" (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) @@ -394,7 +400,7 @@ bookoutput function" (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) @@ -420,7 +426,8 @@ bookoutput function" (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) @@ -445,9 +452,10 @@ bookoutput function" (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 @@ -483,7 +491,7 @@ bookoutput function" (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) @@ -494,14 +502,15 @@ bookoutput function" ((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))) @@ -599,7 +608,7 @@ bookoutput function" (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) @@ -607,17 +616,17 @@ bookoutput function" 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) @@ -630,8 +639,9 @@ bookoutput function" (* (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)))) @@ -676,14 +686,15 @@ bookoutput function" (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) @@ -705,7 +716,7 @@ possibly turned off." (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) @@ -745,7 +756,7 @@ possibly turned off." (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 @@ -771,9 +782,9 @@ applied to function @var{getter}.") (stringstring (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) diff --git a/scm/lily.scm b/scm/lily.scm index 10573e29a7..7384d56f9e 100644 --- a/scm/lily.scm +++ b/scm/lily.scm @@ -228,7 +228,7 @@ messages into errors.") 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)))) diff --git a/scm/markup.scm b/scm/markup.scm index a8068eb894..108751e22f 100644 --- a/scm/markup.scm +++ b/scm/markup.scm @@ -210,9 +210,9 @@ interpreted, returns a list of stencils instead of a single one" ,(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)) @@ -367,11 +367,12 @@ Use `markup*' in a \\notemode context." ;;; (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) @@ -401,13 +402,16 @@ Use `markup*' in a \\notemode context." ;;;;;;;;;;;;;;;;;;;;;; ;;; 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) @@ -428,12 +432,12 @@ eg: ((italic) (raise 4) (bold)), maps the commands on each markup argument, eg: (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))) diff --git a/scm/midi.scm b/scm/midi.scm index c6d2d43023..7f26bea0dc 100644 --- a/scm/midi.scm +++ b/scm/midi.scm @@ -262,14 +262,14 @@ 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))) @@ -282,7 +282,7 @@ (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)) diff --git a/scm/music-functions.scm b/scm/music-functions.scm index e3f70121f5..b015c536a6 100644 --- a/scm/music-functions.scm +++ b/scm/music-functions.scm @@ -55,8 +55,8 @@ (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) @@ -67,7 +67,7 @@ First it recurses over the children, then the function is applied to MUSIC. (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." @@ -96,7 +96,8 @@ First it recurses over the children, then the function is applied to MUSIC. (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 ": { ") @@ -147,8 +148,9 @@ For instance, `(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)) @@ -227,9 +229,9 @@ Returns `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)) @@ -245,7 +247,8 @@ a dot to any note encountered. This scales the music up by a factor 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." @@ -302,7 +305,7 @@ 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) @@ -316,7 +319,7 @@ through MUSIC." ;; 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))) @@ -360,8 +363,8 @@ through MUSIC." ;; 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 @@ -369,14 +372,15 @@ i.e., this is not an override." '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)) @@ -441,7 +445,7 @@ i.e., this is not an override." 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)) @@ -493,7 +497,7 @@ i.e., this is not an override." ;;; 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 @@ -501,9 +505,8 @@ i.e., this is not an override." ;;; 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 @@ -559,14 +562,14 @@ inside of and outside of chord construct." (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))) @@ -596,7 +599,7 @@ NUMBER is 0-base, i.e., Voice=1 (upstems) has number 0. 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)) @@ -625,11 +628,8 @@ NUMBER is 0-base, i.e., Voice=1 (upstems) has number 0. (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)))) @@ -637,8 +637,7 @@ NUMBER is 0-base, i.e., Voice=1 (upstems) has number 0. ;; (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))) @@ -653,9 +652,8 @@ NUMBER is 0-base, i.e., Voice=1 (upstems) has number 0. (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)) @@ -714,7 +712,7 @@ SkipEvent. Useful for extracting parts from crowded scores." (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)) @@ -724,7 +722,7 @@ SkipEvent. Useful for extracting parts from crowded scores." (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) @@ -778,7 +776,7 @@ Syntax: ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (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)) @@ -865,7 +863,7 @@ Syntax: 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))) @@ -1088,18 +1086,22 @@ specifies whether accidentals should be canceled in different octaves." (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) @@ -1131,10 +1133,10 @@ A positive integer means that the accidental lasts over that many bar lines. (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)) @@ -1149,10 +1151,10 @@ A positive integer means that the accidental lasts over that many bar lines. #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) @@ -1168,9 +1170,9 @@ A positive integer means that the accidental lasts over that many bar lines. (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) @@ -1198,9 +1200,10 @@ A positive integer means that the accidental lasts over that many bar lines. 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) @@ -1364,7 +1367,7 @@ use GrandStaff as a context." ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (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 @@ -1373,7 +1376,7 @@ use GrandStaff as a context." (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 @@ -1394,8 +1397,7 @@ use GrandStaff as a context." ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (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) @@ -1413,12 +1415,12 @@ from @code{music}." (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))) diff --git a/scm/output-lib.scm b/scm/output-lib.scm index 400506a8a5..219a287cd1 100644 --- a/scm/output-lib.scm +++ b/scm/output-lib.scm @@ -27,15 +27,14 @@ (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 diff --git a/scm/output-svg.scm b/scm/output-svg.scm index 0a60cf4ffd..3132175414 100644 --- a/scm/output-svg.scm +++ b/scm/output-svg.scm @@ -63,7 +63,7 @@ (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) diff --git a/scm/paper.scm b/scm/paper.scm index 8b877024f6..bc6e2e1944 100644 --- a/scm/paper.scm +++ b/scm/paper.scm @@ -86,13 +86,13 @@ )) (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))) diff --git a/scm/parser-clef.scm b/scm/parser-clef.scm index 88c5d2a5d5..f668ab78e6 100644 --- a/scm/parser-clef.scm +++ b/scm/parser-clef.scm @@ -105,7 +105,7 @@ ("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) @@ -144,7 +144,8 @@ (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) @@ -204,7 +205,8 @@ ;; 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 diff --git a/scm/parser-ly-from-scheme.scm b/scm/parser-ly-from-scheme.scm index 2998a07e7f..b86392623f 100644 --- a/scm/parser-ly-from-scheme.scm +++ b/scm/parser-ly-from-scheme.scm @@ -29,7 +29,7 @@ (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 @@ -37,10 +37,10 @@ (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) diff --git a/scm/part-combiner.scm b/scm/part-combiner.scm index 6df192d56f..0e72ebe2a0 100644 --- a/scm/part-combiner.scm +++ b/scm/part-combiner.scm @@ -200,8 +200,9 @@ Voice-state objects ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (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)) @@ -259,7 +260,7 @@ list, similar to the Recording_group_engraver in 2.8 and earlier" 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)) diff --git a/scm/predefined-fretboards.scm b/scm/predefined-fretboards.scm index e310ece1d2..ff0200729d 100644 --- a/scm/predefined-fretboards.scm +++ b/scm/predefined-fretboards.scm @@ -17,13 +17,13 @@ (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 @@ -31,8 +31,9 @@ return a marking list, which can be used with a fretboard grob." '()))) (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) diff --git a/scm/song-util.scm b/scm/song-util.scm index 2eb61adb98..9a65d44c8e 100644 --- a/scm/song-util.scm +++ b/scm/song-util.scm @@ -129,33 +129,35 @@ (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)) @@ -163,7 +165,7 @@ If it unsets the property, return #f." 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 @@ -174,13 +176,13 @@ If it unsets the property, return #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)) diff --git a/scm/stencil.scm b/scm/stencil.scm index c934e4c429..64f48cc89d 100644 --- a/scm/stencil.scm +++ b/scm/stencil.scm @@ -16,7 +16,8 @@ ;;;; along with LilyPond. If not, see . (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)) @@ -25,7 +26,8 @@ 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)) @@ -36,11 +38,11 @@ (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 @@ -70,7 +72,7 @@ (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)) @@ -160,7 +162,7 @@ the more angular the shape of the parenthesis." 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 @@ -180,7 +182,7 @@ the more angular the shape of the parenthesis." 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)))) @@ -190,9 +192,9 @@ the more angular the shape of the parenthesis." (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))) ) @@ -411,8 +413,9 @@ respectively." `(,(/ 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))) ) @@ -424,8 +427,7 @@ respectively." (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)) @@ -438,7 +440,7 @@ encloses the contents. ;; 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)) @@ -451,7 +453,7 @@ encloses the contents. 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) @@ -468,7 +470,7 @@ encloses the contents. (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)) @@ -485,8 +487,8 @@ encloses the contents. (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)) @@ -507,7 +509,7 @@ encloses the contents. (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)) @@ -544,9 +546,9 @@ encloses the contents. )) (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) diff --git a/scm/time-signature-settings.scm b/scm/time-signature-settings.scm index 907b84ffc7..1b20103ee6 100644 --- a/scm/time-signature-settings.scm +++ b/scm/time-signature-settings.scm @@ -195,8 +195,8 @@ (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))) @@ -205,9 +205,8 @@ 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)))) @@ -232,8 +231,8 @@ for @code{time-signature} from 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)) @@ -282,8 +281,8 @@ a fresh copy of the list-head is made." (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 diff --git a/scm/titling.scm b/scm/titling.scm index d14b8c919f..d0dde63bdf 100644 --- a/scm/titling.scm +++ b/scm/titling.scm @@ -25,11 +25,11 @@ (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)) @@ -73,10 +73,9 @@ and page:page-number" (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))) diff --git a/scm/to-xml.scm b/scm/to-xml.scm index d3f5fc4f02..f1d2e76d2e 100644 --- a/scm/to-xml.scm +++ b/scm/to-xml.scm @@ -231,7 +231,7 @@ is then separated. (string-append "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. ;; @@ -242,7 +242,7 @@ is then separated. (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. ;; diff --git a/scm/translation-functions.scm b/scm/translation-functions.scm index 87cdbd4c2e..f6f24734e4 100644 --- a/scm/translation-functions.scm +++ b/scm/translation-functions.scm @@ -209,18 +209,18 @@ (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 -- 2.39.2