<!-- header_tag --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd"> <html> <!-- Copyright C 1999-2009 by the authors Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections. A copy of the license is included in the section entitled "GNU Free Documentation License". --> <!-- Created on December 15, 2009 by texi2html 1.82 texi2html was written by: Lionel Cons <Lionel.Cons@cern.ch> (original author) Karl Berry <karl@freefriends.org> Olaf Bachmann <obachman@mathematik.uni-kl.de> and many others. Maintained by: Many creative people. Send bugs and suggestions to <texi2html-bug@nongnu.org> --> <head> <title>GNU LilyPond Notation Reference: 6.4.3 New markup command definition</title> <meta name="description" content="GNU LilyPond Notation Reference: 6.4.3 New markup command definition"> <meta name="keywords" content="GNU LilyPond Notation Reference: 6.4.3 New markup command definition"> <meta name="resource-type" content="document"> <meta name="distribution" content="global"> <meta name="Generator" content="texi2html 1.82"> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <link href="index.fr.html#index" rel="start" title="GNU LilyPond — Notation Reference"> <link href="LilyPond-command-index.fr.html#LilyPond-command-index" rel="index" title="F. LilyPond command index"> <link href="index_toc.fr.html#SEC_Contents" rel="contents" title="Table of Contents"> <link href="index_abt.fr.html#SEC_About" rel="help" title="About This Document"> <link href="Markup-programmer-interface.fr.html#Markup-programmer-interface" rel="up" title="6.4 Markup programmer interface"> <link href="LilyPond-index.fr.html#LilyPond-index" rel="next" title="G. LilyPond index"> <link href="How-markups-work-internally.fr.html#How-markups-work-internally" rel="previous" title="6.4.2 How markups work internally"> <link rel="stylesheet" type="text/css" title="Patrick McCarty's design" href="lilypond-mccarty.css"> <link rel="alternate stylesheet" type="text/css" href="lilypond.css" title="Andrew Hawryluk's design"> <link rel="alternate stylesheet" type="text/css" href="lilypond-blue.css" title="Kurt Kroon's blue design"> <!--[if lte IE 7]> <link href="lilypond-ie-fixes.css" rel="stylesheet" type="text/css"> <![endif]--> </head> <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> <div id="main"> <a name="New-markup-command-definition"></a> <table class="nav_table"> <tr><td valign="middle" align="left" colspan="1">[<a href="Interfaces-for-programmers.fr.html#Interfaces-for-programmers" title="Beginning of this chapter or previous chapter"> << Interfaces for programmers </a>]</td><td valign="middle" align="center" colspan="3">[<a href="index.fr.html#index" title="Cover (top) of document" rel="start">Top</a>][<a href="index_toc.fr.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LilyPond-command-index.fr.html#LilyPond-command-index" title="Index" rel="index">Index</a>][<a href="index_abt.fr.html#SEC_About" title="About (help)" rel="help"> ? </a>]</td><td valign="middle" align="right" colspan="1">[<a href="Literature-list.fr.html#Literature-list" title="Next chapter"> Literature list >> </a>]</td></tr><tr><td valign="middle" align="left" colspan="2">[<a href="How-markups-work-internally.fr.html#How-markups-work-internally" title="Previous section in reading order" accesskey="p" rel="previous"> < How markups work internally </a>]</td><td valign="middle" align="center" colspan="1">[<a href="Markup-programmer-interface.fr.html#Markup-programmer-interface" title="Up section" accesskey="u" rel="up"> Up : Markup programmer interface </a>]</td><td valign="middle" align="right" colspan="2">[<a href="New-markup-list-command-definition.fr.html#New-markup-list-command-definition" title="Next section in reading order" accesskey="n" rel="next"> New markup list command definition > </a>]</td></tr></table> <a name="New-markup-command-definition"></a> <h3 class="subsection">6.4.3 New markup command definition</h3> <p>New markup commands can be defined with the <code>define-markup-command</code> Scheme macro. </p> <table><tr><td> </td><td><pre class="lisp">(define-markup-command (<var>command-name</var> <var>layout</var> <var>props</var> <var>arg1</var> <var>arg2</var> ...) (<var>arg1-type?</var> <var>arg2-type?</var> ...) ..command body..) </pre></td></tr></table> <p>The arguments are </p> <dl compact="compact"> <dt> <var>argi</var></dt> <dd><p><var>i</var>th command argument </p></dd> <dt> <var>argi-type?</var></dt> <dd><p>a type predicate for the i<var>th</var> argument </p></dd> <dt> <var>layout</var></dt> <dd><p>the ‘layout’ definition </p></dd> <dt> <var>props</var></dt> <dd><p>a list of alists, containing all active properties. </p></dd> </dl> <p>As a simple example, we show how to add a <code>\smallcaps</code> command, which selects a small caps font. Normally we could select the small caps font, </p> <blockquote><pre class="example">\markup { \override #'(font-shape . caps) Text-in-caps } </pre></blockquote> <p>This selects the caps font by setting the <code>font-shape</code> property to <code>#'caps</code> for interpreting <code>Text-in-caps</code>. </p> <p>To make the above available as <code>\smallcaps</code> command, we must define a function using <code>define-markup-command</code>. The command should take a single argument of type <code>markup</code>. Therefore the start of the definition should read </p> <blockquote><pre class="example">(define-markup-command (smallcaps layout props argument) (markup?) </pre></blockquote> <p>What follows is the content of the command: we should interpret the <code>argument</code> as a markup, i.e., </p> <blockquote><pre class="example">(interpret-markup layout … argument) </pre></blockquote> <p>This interpretation should add <code>'(font-shape . caps)</code> to the active properties, so we substitute the following for the … in the above example: </p> <blockquote><pre class="example">(cons (list '(font-shape . caps) ) props) </pre></blockquote> <p>The variable <code>props</code> is a list of alists, and we prepend to it by cons’ing a list with the extra setting. </p> <p>Suppose that we are typesetting a recitative in an opera and we would like to define a command that will show character names in a custom manner. Names should be printed with small caps and moved a bit to the left and top. We will define a <code>\character</code> command which takes into account the necessary translation and uses the newly defined <code>\smallcaps</code> command: </p> <blockquote><pre class="example">#(define-markup-command (character layout props name) (string?) "Print the character name in small caps, translated to the left and top. Syntax: \\character #\"name\"" (interpret-markup layout props (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name))) </pre></blockquote> <p>There is one complication that needs explanation: texts above and below the staff are moved vertically to be at a certain distance (the <code>padding</code> property) from the staff and the notes. To make sure that this mechanism does not annihilate the vertical effect of our <code>#:translate</code>, we add an empty string (<code>#:hspace 0</code>) before the translated text. Now the <code>#:hspace 0</code> will be put above the notes, and the <code>name</code> is moved in relation to that empty string. The net effect is that the text is moved to the upper left. </p> <p>The final result is as follows: </p> <blockquote><pre class="example">{ c''^\markup \character #"Cleopatra" e'^\markup \character #"Giulio Cesare" } </pre></blockquote> <blockquote><p> <a href="../27/lily-850aee86.ly"> <img align="middle" border="0" src="../27/lily-850aee86.png" alt="[image of music]"> </a> </p> </blockquote> <p>We have used the <code>caps</code> font shape, but suppose that our font does not have a small-caps variant. In that case we have to fake the small caps font by setting a string in upcase with the first letter a little larger: </p> <blockquote><pre class="example">#(define-markup-command (smallcaps layout props str) (string?) "Print the string argument in small caps." (interpret-markup layout props (make-line-markup (map (lambda (s) (if (= (string-length s) 0) s (markup #:large (string-upcase (substring s 0 1)) #:translate (cons -0.6 0) #:tiny (string-upcase (substring s 1))))) (string-split str #\Space))))) </pre></blockquote> <p>The <code>smallcaps</code> command first splits its string argument into tokens separated by spaces (<code>(string-split str #\Space)</code>); for each token, a markup is built with the first letter made large and upcased (<code>#:large (string-upcase (substring s 0 1))</code>), and a second markup built with the following letters made tiny and upcased (<code>#:tiny (string-upcase (substring s 1))</code>). As LilyPond introduces a space between markups on a line, the second markup is translated to the left (<code>#:translate (cons -0.6 0) ...</code>). Then, the markups built for each token are put in a line by <code>(make-line-markup ...)</code>. Finally, the resulting markup is passed to the <code>interpret-markup</code> function, with the <code>layout</code> and <code>props</code> arguments. </p> <p>Note: there is now an internal command <code>\smallCaps</code> which can be used to set text in small caps. See <a href="Text-markup-commands.fr.html#Text-markup-commands">Text markup commands</a>, for details. </p> <a name="Known-issues-and-warnings-18"></a> <h4 class="subsubheading">Known issues and warnings</h4> <p>Currently, the available combinations of arguments (after the standard <var>layout</var> and <var>props</var> arguments) to a markup command defined with <code>define-markup-command</code> are limited as follows. </p> <dl compact="compact"> <dt> (no argument)</dt> <dt> <var>list</var></dt> <dt> <var>markup</var></dt> <dt> <var>markup markup</var></dt> <dt> <var>scm</var></dt> <dt> <var>scm markup</var></dt> <dt> <var>scm scm</var></dt> <dt> <var>scm scm markup</var></dt> <dt> <var>scm scm markup markup</var></dt> <dt> <var>scm markup markup</var></dt> <dt> <var>scm scm scm</var></dt> </dl> <p>In the above table, <var>scm</var> represents native Scheme data types like ‘number’ or ‘string’. </p> <p>As an example, it is not possible to use a markup command <code>foo</code> with four arguments defined as </p> <blockquote><pre class="example">#(define-markup-command (foo layout props num1 str1 num2 str2) (number? string? number? string?) ...) </pre></blockquote> <p>If you apply it as, say, </p> <blockquote><pre class="example">\markup \foo #1 #"bar" #2 #"baz" </pre></blockquote> <a name="index-Scheme-signature"></a> <a name="index-signature_002c-Scheme"></a> <p><code>lilypond</code> complains that it cannot parse <code>foo</code> due to its unknown Scheme signature. </p> <hr size="6"> <table class="nav_table"> <tr><td valign="middle" align="left" colspan="1">[<a href="Interfaces-for-programmers.fr.html#Interfaces-for-programmers" title="Beginning of this chapter or previous chapter"> << Interfaces for programmers </a>]</td><td valign="middle" align="center" colspan="3">[<a href="index.fr.html#index" title="Cover (top) of document" rel="start">Top</a>][<a href="index_toc.fr.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LilyPond-command-index.fr.html#LilyPond-command-index" title="Index" rel="index">Index</a>][<a href="index_abt.fr.html#SEC_About" title="About (help)" rel="help"> ? </a>]</td><td valign="middle" align="right" colspan="1">[<a href="Literature-list.fr.html#Literature-list" title="Next chapter"> Literature list >> </a>]</td></tr><tr><td valign="middle" align="left" colspan="2">[<a href="How-markups-work-internally.fr.html#How-markups-work-internally" title="Previous section in reading order" accesskey="p" rel="previous"> < How markups work internally </a>]</td><td valign="middle" align="center" colspan="1">[<a href="Markup-programmer-interface.fr.html#Markup-programmer-interface" title="Up section" accesskey="u" rel="up"> Up : Markup programmer interface </a>]</td><td valign="middle" align="right" colspan="2">[<a href="New-markup-list-command-definition.fr.html#New-markup-list-command-definition" title="Next section in reading order" accesskey="n" rel="next"> New markup list command definition > </a>]</td></tr></table> <!-- footer_tag --> <div class="footer"> <p class="footer_version"> This page is for LilyPond-2.12.3 (stable-branch). </p> <p class="footer_report"> Your <a href="http://lilypond.org/web/devel/participating/documentation-adding">suggestions for the documentation</a> are welcome, please report errors to our <a href="http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs">bug list</a>. </p> </div> <p id="languages"> Other languages: <a href="New-markup-command-definition.es.html">espaƱol</a>. <br> </p> <!-- FOOTER --> <!-- end div#main here --> </div> <div id="tocframe"> <p class="toc_uplink"><a href="../index.fr.html" title="Documentation Index"><< Back to Documentation Index</a></p> <h4 class="toc_header"> <a href="index.fr.html#index" title="Start of the manual">Notation Reference</a></h4> <div class="contents"> <ul class="toc"> <li><a name="toc-Musical-notation-1" href="Musical-notation.fr.html#Musical-notation">1. Musical notation</a> <ul class="toc"> <li><a name="toc-Pitches-1" href="Pitches.fr.html#Pitches">1.1 Pitches</a> </li> <li><a name="toc-Rhythms-1" href="Rhythms.fr.html#Rhythms">1.2 Rhythms</a> </li> <li><a name="toc-Expressive-marks-1" href="Expressive-marks.fr.html#Expressive-marks">1.3 Expressive marks</a> </li> <li><a name="toc-Repeats-1" href="Repeats.fr.html#Repeats">1.4 Repeats</a> </li> <li><a name="toc-Simultaneous-notes-1" href="Simultaneous-notes.fr.html#Simultaneous-notes">1.5 Simultaneous notes</a> </li> <li><a name="toc-Staff-notation-1" href="Staff-notation.fr.html#Staff-notation">1.6 Staff notation</a> </li> <li><a name="toc-Editorial-annotations-1" href="Editorial-annotations.fr.html#Editorial-annotations">1.7 Editorial annotations</a> </li> <li><a name="toc-Text-1" href="Text.fr.html#Text">1.8 Text</a> </li> </ul> </li> <li><a name="toc-Specialist-notation-1" href="Specialist-notation.fr.html#Specialist-notation">2. Specialist notation</a> <ul class="toc"> <li><a name="toc-Vocal-music-1" href="Vocal-music.fr.html#Vocal-music">2.1 Vocal music</a> </li> <li><a name="toc-Keyboard-and-other-multi_002dstaff-instruments-1" href="Keyboard-and-other-multi_002dstaff-instruments.fr.html#Keyboard-and-other-multi_002dstaff-instruments">2.2 Keyboard and other multi-staff instruments</a> </li> <li><a name="toc-Unfretted-string-instruments-1" href="Unfretted-string-instruments.fr.html#Unfretted-string-instruments">2.3 Unfretted string instruments</a> </li> <li><a name="toc-Fretted-string-instruments-1" href="Fretted-string-instruments.fr.html#Fretted-string-instruments">2.4 Fretted string instruments</a> </li> <li><a name="toc-Percussion-1" href="Percussion.fr.html#Percussion">2.5 Percussion</a> </li> <li><a name="toc-Wind-instruments-1" href="Wind-instruments.fr.html#Wind-instruments">2.6 Wind instruments</a> </li> <li><a name="toc-Chord-notation-1" href="Chord-notation.fr.html#Chord-notation">2.7 Chord notation</a> </li> <li><a name="toc-Ancient-notation-1" href="Ancient-notation.fr.html#Ancient-notation">2.8 Ancient notation</a> </li> <li><a name="toc-World-music-1" href="World-music.fr.html#World-music">2.9 World music</a> </li> </ul> </li> <li><a name="toc-General-input-and-output-1" href="General-input-and-output.fr.html#General-input-and-output">3. General input and output</a> <ul class="toc"> <li><a name="toc-Input-structure-1" href="Input-structure.fr.html#Input-structure">3.1 Input structure</a> </li> <li><a name="toc-Titles-and-headers-1" href="Titles-and-headers.fr.html#Titles-and-headers">3.2 Titles and headers</a> </li> <li><a name="toc-Working-with-input-files-1" href="Working-with-input-files.fr.html#Working-with-input-files">3.3 Working with input files</a> </li> <li><a name="toc-Controlling-output-1" href="Controlling-output.fr.html#Controlling-output">3.4 Controlling output</a> </li> <li><a name="toc-MIDI-output-1" href="MIDI-output.fr.html#MIDI-output">3.5 MIDI output</a> </li> </ul> </li> <li><a name="toc-Spacing-issues-1" href="Spacing-issues.fr.html#Spacing-issues">4. Spacing issues</a> <ul class="toc"> <li><a name="toc-Paper-and-pages-1" href="Paper-and-pages.fr.html#Paper-and-pages">4.1 Paper and pages</a> </li> <li><a name="toc-Music-layout-1" href="Music-layout.fr.html#Music-layout">4.2 Music layout</a> </li> <li><a name="toc-Breaks-1" href="Breaks.fr.html#Breaks">4.3 Breaks</a> </li> <li><a name="toc-Vertical-spacing-1" href="Vertical-spacing.fr.html#Vertical-spacing">4.4 Vertical spacing</a> </li> <li><a name="toc-Horizontal-spacing-1" href="Horizontal-spacing.fr.html#Horizontal-spacing">4.5 Horizontal spacing</a> </li> <li><a name="toc-Fitting-music-onto-fewer-pages-1" href="Fitting-music-onto-fewer-pages.fr.html#Fitting-music-onto-fewer-pages">4.6 Fitting music onto fewer pages</a> </li> </ul> </li> <li><a name="toc-Changing-defaults-1" href="Changing-defaults.fr.html#Changing-defaults">5. Changing defaults</a> <ul class="toc"> <li><a name="toc-Interpretation-contexts-1" href="Interpretation-contexts.fr.html#Interpretation-contexts">5.1 Interpretation contexts</a> </li> <li><a name="toc-Explaining-the-Internals-Reference-1" href="Explaining-the-Internals-Reference.fr.html#Explaining-the-Internals-Reference">5.2 Explaining the Internals Reference</a> </li> <li><a name="toc-Modifying-properties-1" href="Modifying-properties.fr.html#Modifying-properties">5.3 Modifying properties</a> </li> <li><a name="toc-Useful-concepts-and-properties-1" href="Useful-concepts-and-properties.fr.html#Useful-concepts-and-properties">5.4 Useful concepts and properties</a> </li> <li><a name="toc-Advanced-tweaks-1" href="Advanced-tweaks.fr.html#Advanced-tweaks">5.5 Advanced tweaks</a> </li> </ul> </li> <li class="toc_current"><a name="toc-Interfaces-for-programmers-1" href="Interfaces-for-programmers.fr.html#Interfaces-for-programmers">6. Interfaces for programmers</a> <ul class="toc"> <li><a name="toc-Music-functions-1" href="Music-functions.fr.html#Music-functions">6.1 Music functions</a> </li> <li><a name="toc-Programmer-interfaces-1" href="Programmer-interfaces.fr.html#Programmer-interfaces">6.2 Programmer interfaces</a> </li> <li><a name="toc-Building-complicated-functions-1" href="Building-complicated-functions.fr.html#Building-complicated-functions">6.3 Building complicated functions</a> </li> <li class="toc_current"><a name="toc-Markup-programmer-interface-1" href="Markup-programmer-interface.fr.html#Markup-programmer-interface">6.4 Markup programmer interface</a> <ul class="toc"> <li><a name="toc-Markup-construction-in-Scheme-1" href="Markup-construction-in-Scheme.fr.html#Markup-construction-in-Scheme">6.4.1 Markup construction in Scheme</a> </li> <li><a name="toc-How-markups-work-internally-1" href="How-markups-work-internally.fr.html#How-markups-work-internally">6.4.2 How markups work internally</a> </li> <li class="toc_current"><a name="toc-New-markup-command-definition-1" href="New-markup-command-definition.fr.html#New-markup-command-definition">6.4.3 New markup command definition</a> </li> <li><a name="toc-New-markup-list-command-definition-1" href="New-markup-list-command-definition.fr.html#New-markup-list-command-definition">6.4.4 New markup list command definition</a> </li> </ul> </li> <li><a name="toc-Contexts-for-programmers-1" href="Contexts-for-programmers.fr.html#Contexts-for-programmers">6.5 Contexts for programmers</a> </li> <li><a name="toc-Scheme-procedures-as-properties-1" href="Scheme-procedures-as-properties.fr.html#Scheme-procedures-as-properties">6.6 Scheme procedures as properties</a> </li> <li><a name="toc-Using-Scheme-code-instead-of-_005ctweak-1" href="Using-Scheme-code-instead-of-_005ctweak.fr.html#Using-Scheme-code-instead-of-_005ctweak">6.7 Using Scheme code instead of <code>\tweak</code></a> </li> <li><a name="toc-Difficult-tweaks-1" href="Difficult-tweaks.fr.html#Difficult-tweaks">6.8 Difficult tweaks</a> </li> </ul> </li> <li><a name="toc-Literature-list-1" href="Literature-list.fr.html#Literature-list">A. Literature list</a> </li> <li><a name="toc-Notation-manual-tables-1" href="Notation-manual-tables.fr.html#Notation-manual-tables">B. Notation manual tables</a> <ul class="toc"> <li><a name="toc-Chord-name-chart-1" href="Chord-name-chart.fr.html#Chord-name-chart">B.1 Chord name chart</a> </li> <li><a name="toc-Common-chord-modifiers-1" href="Common-chord-modifiers.fr.html#Common-chord-modifiers">B.2 Common chord modifiers</a> </li> <li><a name="toc-Predefined-fretboard-diagrams-1" href="Predefined-fretboard-diagrams.fr.html#Predefined-fretboard-diagrams">B.3 Predefined fretboard diagrams</a> </li> <li><a name="toc-MIDI-instruments-1" href="MIDI-instruments.fr.html#MIDI-instruments">B.4 MIDI instruments</a> </li> <li><a name="toc-List-of-colors-1" href="List-of-colors.fr.html#List-of-colors">B.5 List of colors</a> </li> <li><a name="toc-The-Feta-font-1" href="The-Feta-font.fr.html#The-Feta-font">B.6 The Feta font</a> </li> <li><a name="toc-Note-head-styles-1" href="Note-head-styles.fr.html#Note-head-styles">B.7 Note head styles</a> </li> <li><a name="toc-Text-markup-commands-1" href="Text-markup-commands.fr.html#Text-markup-commands">B.8 Text markup commands</a> </li> <li><a name="toc-Text-markup-list-commands-1" href="Text-markup-list-commands.fr.html#Text-markup-list-commands">B.9 Text markup list commands</a> </li> <li><a name="toc-List-of-articulations-1" href="List-of-articulations.fr.html#List-of-articulations">B.10 List of articulations</a> </li> <li><a name="toc-Percussion-notes-1" href="Percussion-notes.fr.html#Percussion-notes">B.11 Percussion notes</a> </li> <li><a name="toc-All-context-properties-1" href="All-context-properties.fr.html#All-context-properties">B.12 All context properties</a> </li> <li><a name="toc-Layout-properties-1" href="Layout-properties.fr.html#Layout-properties">B.13 Layout properties</a> </li> <li><a name="toc-Identifiers-1" href="Identifiers.fr.html#Identifiers">B.14 Identifiers</a> </li> <li><a name="toc-Scheme-functions-1" href="Scheme-functions.fr.html#Scheme-functions">B.15 Scheme functions</a> </li> </ul> </li> <li><a name="toc-Cheat-sheet-1" href="Cheat-sheet.fr.html#Cheat-sheet">C. Cheat sheet</a> </li> <li><a name="toc-LilyPond-grammar-1" href="LilyPond-grammar.fr.html#LilyPond-grammar">D. LilyPond grammar</a> </li> <li><a name="toc-GNU-Free-Documentation-License-1" href="GNU-Free-Documentation-License.fr.html#GNU-Free-Documentation-License">E. GNU Free Documentation License</a> </li> <li><a name="toc-LilyPond-command-index-1" href="LilyPond-command-index.fr.html#LilyPond-command-index">F. LilyPond command index</a> </li> <li><a name="toc-LilyPond-index-1" href="LilyPond-index.fr.html#LilyPond-index">G. LilyPond index</a> </li> </ul> </div> </div> </body> </html>