<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!-- header_tag --> <html lang="en"> <head> <title>New markup command definition - GNU LilyPond Notation Reference</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta name="description" content="GNU LilyPond Notation Reference"> <meta name="generator" content="makeinfo 4.11"> <link title="Top" rel="start" href="index.es.html#Top"> <link rel="up" href="Markup-programmer-interface.es.html#Markup-programmer-interface" title="Markup programmer interface"> <link rel="prev" href="How-markups-work-internally.es.html#How-markups-work-internally" title="How markups work internally"> <link rel="next" href="New-markup-list-command-definition.es.html#New-markup-list-command-definition" title="New markup list command definition"> <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> <!-- Copyright (C) 1999--2007 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''. --> <meta http-equiv="Content-Style-Type" content="text/css"> <style type="text/css"><!-- pre.display { font-family:inherit } pre.format { font-family:inherit } pre.smalldisplay { font-family:inherit; font-size:smaller } pre.smallformat { font-family:inherit; font-size:smaller } pre.smallexample { font-size:smaller } pre.smalllisp { font-size:smaller } span.sc { font-variant:small-caps } span.roman { font-family:serif; font-weight:normal; } span.sansserif { font-family:sans-serif; font-weight:normal; } hr { border:0; height:1; color: #000000; background-color: #000000; } /* hr { border: none; height: 1px; color: #666666; background-color: #666666; } body { border-left: 1px solid #666666; border-right: 1px solid #666666; color: #332d28; margin-right: auto; margin-left: auto; width: 60em; list-style-type: square; font-family: Arial,Helvetica,sans-serif; padding-right: 1em; padding-left: 1em; } a { border-bottom: 1px dashed #344242; text-decoration: none; color: #344242; } a:link { text-decoration: none; } a:visited { border-bottom: 1px dashed #666666; color: #666666; } a:active { border-bottom: 1px solid #00cccc; color: #00cccc; } a:hover { border-bottom: 1px solid #1d7b85; color: #1d7b85; } blockquote { border: 1px solid #cccccc; padding: 3px; width: 40em; } .node { border-left: 1px solid #666666; margin: -0.5em 0px 1em; padding: 2px 1px 0px; font-style: italic; } .node a { border: none; text-decoration: underline; font-style: normal; font-weight: bold; } .verbatim { font-family: "Courier New",Courier,monospace; } .unnumberedsubsubsec { font-size: large; color: #1d7b85; } .subsubheading { font-size: large; color: #3b220d; } .contents { border: 1px dashed #339999; margin: 3px 2em; list-style-type: square; padding-right: 1em; width: 40em; background-color: #fcfff9; } .contents a { border-bottom: 1px dashed #423d34; text-decoration: none; color: #423d34; } .contents a:visited { border-bottom: 1px dashed #666666; color: #666666; } .contents a:active { border-bottom: 1px solid #f0d86d; color: #f0d86d; } .contents a:hover { border-bottom: 1px solid #3b220d; color: #3b220d; } .menu { border-left: 1px dashed #339999; margin: 3px 2em 1em; list-style-type: square; padding-left: 1.4em; width: 40em; } .unnumbered { } h2 { font-size: x-large; color: #1d7b85; } */ --></style> </head> <BODY BGCOLOR=WHITE TEXT=BLACK> <div class="node"> <p> <a name="New-markup-command-definition"></a> Next: <a rel="next" accesskey="n" href="New-markup-list-command-definition.es.html#New-markup-list-command-definition">New markup list command definition</a>, Previous: <a rel="previous" accesskey="p" href="How-markups-work-internally.es.html#How-markups-work-internally">How markups work internally</a>, Up: <a rel="up" accesskey="u" href="Markup-programmer-interface.es.html#Markup-programmer-interface">Markup programmer interface</a> <hr> </div> <h4 class="subsection">6.4.3 New markup command definition</h4> <p>New markup commands can be defined with the <code>define-markup-command</code> Scheme macro. <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> <p>The arguments are <dl> <dt><var>argi</var><dd><var>i</var>th command argument <br><dt><var>argi-type?</var><dd>a type predicate for the i<var>th</var> argument <br><dt><var>layout</var><dd>the ‘layout’ definition <br><dt><var>props</var><dd>a list of alists, containing all active properties. </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, <pre class="example">\markup { \override #'(font-shape . caps) Text-in-caps } </pre> <p class="noindent">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>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 <pre class="example">(define-markup-command (smallcaps layout props argument) (markup?) </pre> <p class="noindent">What follows is the content of the command: we should interpret the <code>argument</code> as a markup, i.e., <pre class="example">(interpret-markup layout ... argument) </pre> <p class="noindent">This interpretation should add <code>'(font-shape . caps)</code> to the active properties, so we substitute the following for the <small class="dots">...</small> in the above example: <pre class="example">(cons (list '(font-shape . caps) ) props) </pre> <p class="noindent">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>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: <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> <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>The final result is as follows: <pre class="example">{ c''^\markup \character #"Cleopatra" e'^\markup \character #"Giulio Cesare" } </pre> <blockquote> <p> <a href="../dd/lily-d53ef9a1.ly"> <img align="middle" border="0" src="../dd/lily-d53ef9a1.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: <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> <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>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.es.html#Text-markup-commands">Text markup commands</a>, for details. <p class="noindent"> <h5 class="subsubheading">Known issues and warnings</h5> <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. <dl> <dt>(no argument)<dt><var>list</var><dt><var>markup</var><dt><var>markup markup</var><dt><var>scm</var><dt><var>scm markup</var><dt><var>scm scm</var><dt><var>scm scm markup</var><dt><var>scm scm markup markup</var><dt><var>scm markup markup</var><dt><var>scm scm scm</var><dd></dl> <p class="noindent">In the above table, <var>scm</var> represents native Scheme data types like ‘number’ or ‘string’. <p>As an example, it is not possible to use a markup command <code>foo</code> with four arguments defined as <pre class="example">#(define-markup-command (foo layout props num1 str1 num2 str2) (number? string? number? string?) ...) </pre> <p class="noindent">If you apply it as, say, <pre class="example">\markup \foo #1 #"bar" #2 #"baz" </pre> <p><a name="index-Scheme-signature-2824"></a><a name="index-signature_002c-Scheme-2825"></a><samp><span class="command">lilypond</span></samp> complains that it cannot parse <code>foo</code> due to its unknown Scheme signature. <!-- footer_tag --><br><hr> <div class="node"> <p> Next: <a rel="next" accesskey="n" href="New-markup-list-command-definition.es.html#New-markup-list-command-definition">New markup list command definition</a>, Previous: <a rel="previous" accesskey="p" href="How-markups-work-internally.es.html#How-markups-work-internally">How markups work internally</a>, Up: <a rel="up" accesskey="u" href="Markup-programmer-interface.es.html#Markup-programmer-interface">Markup programmer interface</a> </div> <div style="background-color: #e8ffe8; padding: 2; border: #c0ffc0 1px solid;"> <p> <font size="-1"> Esta página corresponde a LilyPond-2.11.57 (rama de desarrollo). <br> <address> Informe de los fallos a través de la lista en español <a href="http://es.groups.yahoo.com/group/lilypond-es/">lilypond-es</a>, o en inglés a través de <a href="http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs">http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs</a>. </address> <br> Se agradecen las <a href="http://lilypond.org/web/devel/participating/documentation-adding">sugerencias para la documentación</a>. </font> </p> </div> </BODY></html>