Doc-de: update macros.itely and nitpicks

[lilypond.git] / Documentation / es / user / working.itely

@c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
@c This file is part of lilypond.tely
@ignore
    Translation of GIT committish: d4f58bb3ad4e7fe1967a6b48f25e3addffc8aa14

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  See TRANSLATION for details.
@end ignore

@c \version "2.12.0"

@node Working on LilyPond projects
@chapter Working on LilyPond projects

Esta sección explica cómo resolver o evitar ciertos problemas comunes.
Si tiene experiencia en programación muchos de estos
consejos pueden parecer obvios, pero aún así le recomendamos
que lea este capítulo.


@menu
* Suggestions for writing LilyPond input files::
* When things don't work::
* Scores and parts::
* Make and Makefiles::
@end menu


@node Suggestions for writing LilyPond input files
@section Suggestions for writing LilyPond input files

En este momento está preparado para comenzar a escribir archivos de
LilyPond más grandes -- no sólo los pequeños ejemplos que aparecen en
el tutorial, sino piezas completas --. Pero ¿cómo debe proceder para
hacerlo?

En la medida en que LilyPond entienda sus archivos y produzca la
salida que usted pretendía, realmente no importa mucho qué aspecto
tengan sus archivos.  Sin embargo existen algunas otras cosas a tener
en cuenta cuando se escriben archivos de LilyPond.

@itemize
@item ¿Qué ocurre si comete un fallo?  La estructura de un archivo
de LilyPond puede hacer que ciertos errores se hagan más fáciles (o
más difíciles) de encontrar.

@item ¿Qué ocurre si quiere compartir sus archivos con otras personas?
De hecho, ¿y si quiere alterar sus propios archivos después de algunos
años?  Algunos archivos de LilyPond se comprenden a primera vista;
otros pueden tenerle rascándose la cabeza durante una hora.

@item ¿Qué ocurre si quiere actualizar su archivo de LilyPond para poderlo usar con
una versión más reciente del programa?  La sintaxis de la entrada se
modifica de forma ocasional según LilyPond se va perfeccionando.  Casi
todos los cambios se pueden hacer de forma automática con
@code{convert-ly}, pero algunos podrían necesitar de una ayuda manual.
Los archivos de LilyPond se pueden estructurar para que sean más
fáciles (o más difíciles) de actualizar.

@end itemize

@menu
* General suggestions::
* Typesetting existing music::
* Large projects::
* Saving typing with variables and functions::
* Style sheets::
@end menu


@node General suggestions
@subsection General suggestions

Presentamos algunas sugerencias que le pueden servir de ayuda para evitar
o corregir problemas:

@itemize
@item @strong{Incluya los números de @code{\version} en todos los archivos}.  Dése cuenta de que todas las
plantillas contienen información sobre la @code{\version}.  Le
recomendamos mucho que siempre incluya la @code{\version}, sin
importar cuán pequeño pueda ser su archivo.  Desde la experiencia
personal podemos decirle que es bastante frustrante intentar recordar
el número de versión de LilyPond que estaba usando hace unos años.
@code{convert-ly} requiere que declare qué versión de LilyPond
utilizó.

@item @strong{Incluya comprobaciones}: @ruser{Bar and bar number checks},
@ruser{Octave checks}.  Si incluye comprobaciones de vez en cuando, en
caso de que cometa un error podrá localizarlo mucho más rápidamente.
¿Con qué frecuencia es @q{de vez en cuando}?  Depende de la
complejidad de la música.  Para una música muy sencilla, quizá tan
sólo una o dos veces.  Para una música muy compleja, quizá a cada
compás.

@item @strong{Un compás por cada línea de texto}.  Si hay algo muy complicado, ya sea
en la propia música o en la salida que desea producir, a menudo
conviene escribir un solo compás por cada línea.  El ahorro en espacio
de pantalla que se obtiene al amontonar ocho compases por línea no
merece la pena si luego tiene que @q{depurar} los archivos.

@item @strong{Comente los archivos}.  Utilice o números de compás (de vez en cuando)
o referencias a temas musicales (@q{segundo tema de los violines,}
@q{cuarta variación,} etc.).  Puede que no necesite comentarios cuando
introduce una pieza por vez primera, pero si quiere volver a ella o
modificar algo al cabo de dos o tres años, y también si le pasa la
fuente a un amigo, será todo un desafío determinar sus intenciones o
de qué manera estaba estructurado el archivo si no le añadió los
comentarios.

@item @strong{Aplique márgenes a las llaves}.  Muchos problemas están causados por una
falta de equilibrio en el número de @code{@{} y @code{@}}.

@item @strong{Escriba las duraciones explícitamente} al comienzo de las secciones
e identificadores.  Si especifica @code{c4 d e} al principio de una
frase (en lugar de sólo @code{c d e}) se puede ahorrar problemas si
reelabora la música más tarde.

@item @strong{Separe los trucos} de las definiciones musicales.  Consulte
@ref{Saving typing with variables and functions} y
@ref{Style sheets}.

@end itemize


@node Typesetting existing music
@subsection Typesetting existing music

Si está introduciendo música a partir de una partitura existente (es
decir, tipografiando una hoja de música ya impresa),

@itemize

@item Introduzca un sistema del manuscrito (la copia física) cada vez (pero mantenga
la práctica de escribir un compás por línea de texto), y compruebe
cada sistema cuando lo haya terminado.  Puede usar las instrucciones
@code{showLastLength} o @code{showFirstLength} para acelerar el
proceso -- ver @ruser{Skipping corrected music} -- .

@item Defina @code{mBreak = @{ \break @}} e inserte @code{\mBreak}
dentro del archivo de entrada donde el manuscrito tenga un saldo de
línea.  De esta forma le resultará mucho más fácil comparar la música
de LilyPond con la original.  Cuando haya terminado de revisar su
partitura podrá definir @code{mBreak = @{ @}} para quitar todos esos
saltos de línea.  Así permitirá a LilyPond colocar los saltos donde
éste lo estime más oportuno.

@item Al escribir una parte para un instrumento transpositor dentro de una
variable, se recomienda que las notas estén envueltas dentro de

@example
\transpose c altura-natural @{...@}
@end example
(donde @code{altura-natural} es la afinación natural del instrumento)
de forma que la música dentro de la variable esté realmente en Do
mayor.  Después podemos volver a transportarlas en sentido inverso
cuando se utiliza la variable, si es necesario, pero quizá no queramos
hacerlo (p.ej., al imprimir una partitura en afinación de concierto,
al convertir una parte de trombón de clave de Sol a clave de Fa,
etc.).  Es menos probable cometer errores en los transportes si toda
la música que está dentro de las variables se encuentra en un tono
coherente.

Asimismo, haga los transportes exclusivamente hacia o desde Do mayor.
Esto significa que aparte de ésta, las únicas tonalidades que usaremos
serán los tonos de afinación de los instrumentos transpositores: bes
para una trompeta en Si bemol, aes para un clarinete en La bemol, etc.

@end itemize


@node Large projects
@subsection Large projects

Al trabajar en proyecto grande se hace esencial tener una estructura clara
en los archivos de LilyPond

@itemize

@item @strong{Utilice un identificador para cada voz}, con un mínimo de
estructura dentro de la definición.  La estructura de la sección
@code{\score} es la que cambiará con mayor probabilidad; por contra, es
extremadamente improbable que cambie la definición de @code{violin} en
versiones nuevas de LilyPond.

@example
violin = \relative c'' @{
g4 c'8. e16
@}
...
\score @{
  \new GrandStaff @{
    \new Staff @{
      \violin
    @}
  @}
@}
@end example

@item @strong{Separe los trucos de las definiciones musicales}.
Ya se mencionó con anterioridad, pero para proyectos grandes es vital.
Quizá tengamos que cambiar la definición de @code{fluegop}, pero en ese
caso sólo lo tendremos que hacer una vez, y aún podremos evitar tocar
nada dentro de @code{violin}.

@example
fluegop = _\markup@{
  \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
violin = \relative c'' @{
g4\fluegop c'8. e16
@}
@end example

@end itemize


@node Saving typing with variables and functions
@subsection Saving typing with variables and functions

@cindex variables
@cindex identificadores

Llegado a este punto, usted ha visto cosas de este tipo:

@lilypond[quote,verbatim,ragged-right]
hornNotes = \relative c'' { c4 b dis c }
\score {
  {
    \hornNotes
  }
}
@end lilypond

Incluso se dará cuenta de que esto puede ser útil en música
minimalista:

@lilypond[quote,verbatim,ragged-right]
fragmentA = \relative c'' { a4 a8. b16 }
fragmentB = \relative c'' { a8. gis16 ees4 }
violin = \new Staff { \fragmentA \fragmentA \fragmentB \fragmentA }
\score {
  {
    \violin
  }
}
@end lilypond

Sin embargo también puede usar estos identificadores (que también se
conocen como variables, macros o instrucciones definidas por el
usuario) para hacer trucos:

@lilypond[quote,verbatim,ragged-right]
dolce = \markup{ \italic \bold dolce }
padText = { \once \override TextScript #'padding = #5.0 }
fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
violin = \relative c'' {
  \repeat volta 2 {
    c4._\dolce b8 a8 g a b |
    \padText
    c4.^"hi there!" d8 e' f g d |
    c,4.\fthenp b8 c4 c-. |
  }
}
\score {
  {
    \violin
  }
\layout{ragged-right=##t}
}
@end lilypond

Obviamente estos identificadores son útiles para ahorrar tecleo.  Pero
son dignos de tener en cuenta incluso si se van a utilizar una sola
vez: reducen la complejidad.  Examinemos el ejemplo anterior reescrito
sin ningún identificador.  Encontrará que es mucho más difícil de
leer, sobre todo la última línea.

@example
violin = \relative c'' @{
  \repeat volta 2 @{
    c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
    \once \override TextScript #'padding = #5.0
    c4.^"hi there!" d8 e' f g d |
    c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
      \hspace #0.1 \dynamic p @} b8 c4 c-. |
  @}
@}
@end example

@c TODO Replace the following with a better example  -td
@c Skylining handles this correctly without padText

Hasta ahora hemos contemplado la sustitución estática: cuando LilyPond
se encuentra con @code{\padText}, lo sustituye con aquello que
hemos definido que sea (es decir, todo lo que está a la derecha de
@code{padtext=}).

LilyPond también puede manejar sustituciones no estáticas (piense en
ellas como en funciones).

@lilypond[quote,verbatim,ragged-right]
padText =
#(define-music-function (parser location padding) (number?)
  #{
    \once \override TextScript #'padding = #$padding
  #})

\relative c''' {
  c4^"piu mosso" b a b
  \padText #1.8
  c4^"piu mosso" d e f
  \padText #2.6
  c4^"piu mosso" fis a g
}
@end lilypond

La utilización de identificadores también es una buena forma de
reducir el trabajo si la sintaxis de entrada de LilyPond cambia (véase
@ref{Updating old files}).  Si tiene una sola definición (como
p.ej. @code{\dolce}) para todos sus archivos (ver @ref{Style sheets}),
y después la sintaxis se modifica, sólo tendrá que actualizar su
definición @code{\dolce} única, en lugar de tener que hacer cambios en
cada uno de los archivos @code{.ly}.


@node Style sheets
@subsection Style sheets

La salida que produce LilyPond se puede modificar profundamente;
consulte @ref{Tweaking output} para leer detalles sobre este asunto.
Pero ¿qué ocurre si tiene muchos archivos a los que les quiere aplicar
sus propios trucos?  O ¿qué ocurre si, sencillamente, quiere separar
los trucos de la propia música?  Todo esto es bastante fácil de
conseguir.

Veamos un ejemplo.  No se preocupe si no entiende
las partes que tienen todos los @code{#()}.  Esto se explicará en
@ref{Advanced tweaks with Scheme}.

@lilypond[quote,verbatim,ragged-right]
mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
  #:line(#:dynamic "mp" #:text #:italic "dolce" )))

inst = #(define-music-function (parser location string) (string?)
  (make-music
    'TextScriptEvent
    'direction UP
    'text (markup #:bold (#:box string))))

\relative c'' {
  \tempo 4=50
  a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
  \inst "Clarinet"
  cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
}
@end lilypond

Existen varios problemas con la salida que se superpone; los
arreglaremos utilizando las técnicas descritas en @ref{Moving
objects}.  Pero también haremos algo respecto a las definiciones
@code{mpdolce} e @code{inst}.  Éstas producen la salida que deseamos,
pero quizá las querríamos utilizar en otra pieza.  Podríamos
simplemente copiarlas y pegarlas al principio de cada archivo, pero
sería bastante molesto.  También hace que se queden las definiciones a
la vista dentro de nuestros archivos de música, y yo personalmente
encuentro todos los @code{#()} bastante poco estéticos.  Los vamos a
esconder dentro de otro archivo:

@example
%%% guardar esto en un archivo de nombre "definiciones.ily"
mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
  #:line(#:dynamic "mp" #:text #:italic "dolce" )))

inst = #(define-music-function (parser location string) (string?)
  (make-music
    'TextScriptEvent
    'direction UP
    'text (markup #:bold (#:box string))))
@end example

Haremos referencia a este archivo utilizando la instrucción
@code{\include} al principio del archivo de música (la extensión
@code{.ily} se utiliza para distinguir este archivo de inclusión --que
se supone que no debe ser procesado de forma independiente-- del
archivo principal).  Ahora modificaremos la música (guardemos este
archivo como @file{"musica.ly"}).

@c  We have to do this awkward example/lilypond-non-verbatim
@c  because we can't do the \include stuff in the manual.

@example
\include "definiciones.ily"

\relative c'' @{
  \tempo 4=50
  a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
  \inst "Clarinete"
  cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
@}
@end example

@lilypond[quote,ragged-right]
mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
  #:line(#:dynamic "mp" #:text #:italic "dolce" )))

inst = #(define-music-function (parser location string) (string?)
  (make-music
    'TextScriptEvent
    'direction UP
    'text (markup #:bold (#:box string))))

\relative c'' {
  \tempo 4=50
  a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
  \inst "Clarinet"
  cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
}
@end lilypond

Eso tiene mejor aspecto, pero haremos algunos cambios más.  El glissando es difícil
de ver, así que lo haremos más grueso y lo acercaremos a las cabezas de las notas.  Pondremos
la indicación metronómica encima de la clave, en lugar de ir encima de la primera
nota.  Y por último, mi profesor de composición odia las indicaciones de compás @q{C},
así que la convertiremos en @q{4/4}.

Sin embargo, no debemos cambiar el archivo @file{musica.ly}.
Sustituyamos nuestro archivo @file{definiciones.ily} con éste:

@example
%%%  definiciones.ily
mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
  #:line( #:dynamic "mp" #:text #:italic "dolce" )))

inst = #(define-music-function (parser location string) (string?)
  (make-music
    'TextScriptEvent
    'direction UP
    'text (markup #:bold (#:box string))))

\layout@{
  \context @{ \Score
    \override MetronomeMark #'extra-offset = #'(-9 . 0)
    \override MetronomeMark #'padding = #'3
  @}
  \context @{ \Staff
    \override TimeSignature #'style = #'numbered
  @}
  \context @{ \Voice
    \override Glissando #'thickness = #3
    \override Glissando #'gap = #0.1
  @}
@}
@end example

@lilypond[quote,ragged-right]
mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
  #:line( #:dynamic "mp" #:text #:italic "dolce" )))

inst = #(define-music-function (parser location string) (string?)
  (make-music
    'TextScriptEvent
    'direction UP
    'text (markup #:bold (#:box string))))

\layout{
  \context { \Score
    \override MetronomeMark #'extra-offset = #'(-9 . 0)
    \override MetronomeMark #'padding = #'3
  }
  \context { \Staff
    \override TimeSignature #'style = #'numbered
  }
  \context { \Voice
    \override Glissando #'thickness = #3
    \override Glissando #'gap = #0.1
  }
}

\relative c'' {
  \tempo 4=50
  a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
  \inst "Clarinet"
  cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
}
@end lilypond

¡Eso tiene un aspecto mucho mejor!  Ahora suponga que quiere publicar esta
pieza.  A mi profesor de composición no le gustan las indicaciones de compás @q{C},
pero yo les tengo cierto cariño.  Copiaremos el archivo
actual @file{definiciones.ily} a @file{publicar-web.ily} y modificaremos
éste.  Como el propósito de esta música es producir un PDF que va a mostrarse
en la pantalla, también vamos a aumentar el
tamaño general de la salida.

@example
%%%  definiciones.ily
mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
  #:line( #:dynamic "mp" #:text #:italic "dolce" )))

inst = #(define-music-function (parser location string) (string?)
  (make-music
    'TextScriptEvent
    'direction UP
    'text (markup #:bold (#:box string))))

#(set-global-staff-size 23)
\layout@{
  \context @{ \Score
    \override MetronomeMark #'extra-offset = #'(-9 . 0)
    \override MetronomeMark #'padding = #'3
  @}
  \context @{ \Staff
  @}
  \context @{ \Voice
    \override Glissando #'thickness = #3
    \override Glissando #'gap = #0.1
  @}
@}
@end example

@lilypond[quote,ragged-right]
mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0)
  #:line( #:dynamic "mp" #:text #:italic "dolce" )))

inst = #(define-music-function (parser location string) (string?)
  (make-music
    'TextScriptEvent
    'direction UP
    'text (markup #:bold (#:box string))))

#(set-global-staff-size 23)
\layout{
  \context { \Score
    \override MetronomeMark #'extra-offset = #'(-9 . 0)
    \override MetronomeMark #'padding = #'3
  }
  \context { \Voice
    \override Glissando #'thickness = #3
    \override Glissando #'gap = #0.1
  }
}

\relative c'' {
  \tempo 4=50
  a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
  \inst "Clarinet"
  cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
}
@end lilypond

Ahora, en la música, simplemente sustituyo @code{\include
"definiciones.ily"} por @code{\include "publicar-web.ily"}.  Por
supuesto, podríamos hacer esto aún más práctico.  Podríamos hacer un
archivo @file{definiciones.ily} que contuviera solamente las
definiciones de @code{mpdolce} y de @code{inst}, un archivo
@file{publicar-web.ily} que contuviera solamente la sección
@code{\layout} que se mostró en el ejemplo, y un archivo
@file{universidad.ily} que contendría solamente los trucos para
producir la salida que le gusta a mi profesor.  El comienzo de
@file{musica.ly} tendría entonces este aspecto:

@example
\include "definiciones.ily"

%%%  ¡Quitar el comentario de una sola de estas líneas!
\include "publicar-web.ily"
%\include "universidad.ily"
@end example

Este enfoque puede ser útil incluso si va a producir sólo un conjunto
de particellas.  Yo utilizo media docena de archivos de @q{hojas de
estilo} para mis proyectos.  Comienzo todos los archivos de música con
@code{\include "../global.ily"}, que contiene

@example
%%%   global.ily
\version @w{"@version{}"}
#(ly:set-option 'point-and-click #f)
\include "../iniciar/iniciar-definiciones.ily"
\include "../iniciar/iniciar-disposicion.ily"
\include "../iniciar/iniciar-cabeceras.ily"
\include "../iniciar/iniciar-papel.ily"
@end example


@node When things don't work
@section When things don't work

@menu
* Updating old files::
* Troubleshooting (taking it all apart)::
* Minimal examples::
@end menu

@node Updating old files
@subsection Updating old files

La sintaxis de la entrada de LilyPond cambia de manera ocasional.  A
medida que el propio LilyPond mejora, la sintaxis (el lenguaje de la
entrada) se modifica en consonancia.  A veces estos cambios se hacen
para conseguir que la entrada sea más fácil de leer y escribir, y
otras veces estos cambios son para dar cabida a nuevas funcionalidades
de LilyPond.

LilyPond lleva incorporado un archivo que facilita esta actualización:
@code{convert-ly}.  Para ver detalles sobre cómo ejecutar este
programa, consulte @rprogram{Updating files with convert-ly}.

Desgraciadamente @code{convert-ly} no puede tratar todos los cambios
en la entrada.  Se ocupa de los cambios sencillos de búsqueda y
sustitución (como @code{raggedright} que se convierte en
@code{ragged-right}), pero algunos cambios son demasiado complicados.
Los cambios de sintaxis que @code{convert-ly} es incapaz de manejar se
relacionan en @rprogram{Updating files with convert-ly}.

Por ejemplo, en la versión 2.4 y anteriores de LilyPond, los acentos y
las letras no inglesas se introducían utilizando LaTeX: por ejemplo,
@code{No\"el} (que significa @q{Navidad} en francés).  En LilyPond 2.6
y siguientes, el carácter especial @code{ë} debe introducirse
directamente en el archivo de LilyPond como un carácter UTF-8.
@code{convert-ly} no puede cambiar todos los caracteres especiales de
LaTeX a caracteres de UTF-8; tendrá que actualizar manualmente sus
archivos de LilyPond antiguos.


@node Troubleshooting (taking it all apart)
@subsection Troubleshooting (taking it all apart)

Antes o después escribirá un archivo que LilyPond no podrá compilar.
Los mensajes que LilyPond proporciona pueden ayudarle a encontrar el
error, pero en muchos casos tendrá que llevar a cabo algún tipo de
investigación para determinar el origen del problema.

Las herramientas más poderosas para este cometido son el comentario de
una sola línea (indicado por @code{%}) y el comentario de bloque
(indicado por @code{%@{ ... %@}}).  Si no sabe dónde está el problema,
comience convirtiendo grandes secciones del archivo de entrada en un
comentario.  Después de eliminar una sección convirtiéndola en un
comentario, pruebe a compilar el archivo otra vez.  Si funciona,
entonces el problema debía estar en la porción que había eliminado.
Si no funciona, continúe eliminando material (transformándolo en
comentarios) hasta que tenga algo que funcione.

En un caso extremo podría terminar con sólo

@example
\score @{
  <<
    % \melodia
    % \armonia
    % \bajo
  >>
  \layout@{@}
@}
@end example

@noindent
(en otras palabras: un archivo sin música)

Si ocurre esto, no abandone.  Descomente un trozo pequeño -- digamos
la parte del bajo -- y observe si funciona.  Si no es así, transforme
en comentarios toda la música del bajo (pero deje el @code{\bajo} de
la sección @code{\score} no comentado.

@example
bajo = \relative c' @{
%@{
  c4 c c c
  d d d d
%@}
@}
@end example

Ahora empiece poco a poco descomentando cada vez más fracciones de la
parte del @code{bajo} hasta que encuentre la línea del problema.

Otra técnica de depuración muy útil es la construcción de
@ref{Minimal examples}.


@node Minimal examples
@subsection Minimal examples

Un ejemplo mínimo es un ejemplo tan pequeño como sea posible.  Estos
ejemplos son mucho más fáciles de comprender que los ejemplos largos.
Los ejemplos mínimos se utilizan para

@itemize
@item Informes de fallo
@item Solicitudes de ayuda a las listas de correo
@item Añadir ejemplos al @uref{http://lsr@/.dsi@/.unimi@/.it/,Repositorio de Fragmentos de Código de LilyPond}
@end itemize


Para construir un ejemplo que sea lo más pequeño posible, la regla es
bastante simple: quite todo lo que no sea necesario.  Al tratar de
quitar partes innecesarias de un archivo, es una buena idea convertir
líneas en comentarios en vez de borrarlas.  De esta forma, si descubre
que en realidad sí @emph{necesitaba} algunas de estas líneas, podrá
descomentarlas y no tendrá que teclearlas de nuevo partiendo de cero.

Existen dos excepciones a la regla del @qq{lo más pequeño posible}:

@itemize
@item Incluya el número de @code{\version}.
@item Si puede, ponga @code{\paper@{ ragged-right=##t @}} al principio del ejemplo.
@end itemize


En resumen, el objetivo de un ejemplo mínimo es que sea fácil de leer:

@itemize
@item Evite usar notas, tonalidades o compases demasiado complicados, a no ser que quiera
demostrar algo sobre el comportamiento de estos elementos precisamente.
@item No use instrucciones @code{\override} a no ser que ése sea el propósito
del ejemplo.
@end itemize


@node Scores and parts
@section Scores and parts

En música orquestal, todas las notas se imprimen dos veces.  Una vez
en las particellas para los músicos, y otra para la partitura del
director.  Los identificadores se pueden usar para evitar la
duplicación del trabajo.  La música se escribe una vez y se almacena
en una variable.  El contenido de dicha variable se usa después para
generar tanto la particella como la partitura del director.

Es muy conveniente definir las notas en un archivo especial.  Por
ejemplo, supongamos que el archivo @file{trompa.ly} contiene la
siguiente parte de un dúo para trompa y fagot:

@example
notasTrompa = \relative c @{
  \time 2/4
  r4 f8 a cis4 f e d
@}
@end example

@noindent
Luego se hace una particella escribiendo en un archivo lo siguiente

@example
\include "trompa.ly"
\header @{
  instrument = "Trompa en Fa"
@}

@{
 \transpose f c' \notasTrompa
@}
@end example

La línea

@example
\include "trompa.ly"
@end example

@noindent
sustituye el contenido de @file{trompa.ly} en esta posición dentro del
archivo, así que @code{notasTrompa} se define con posterioridad.  La
instrucción @code{\transpose f@tie{}c'} indica que el argumento
constituido por @code{\notasTrompa} se debe transponer una quinta
hacia arriba.  Lo que suena como @code{f} se escribe como @code{c'},
lo que corresponde con el tono de afinación de una trompa normal
en@tie{}Fa.  La transposición se puede ver en la siguiente salida

@lilypond[quote,ragged-right]
\transpose f c' \relative c {
  \time 2/4
  r4 f8 a cis4 f e d
}
@end lilypond

En piezas para conjunto, con frecuencia una de las voces no suena
durante muchos compases.  Esto queda denotado por un silencio
especial, el silencio multicompás.  Se introduce con una @code{R}
mayúscula seguida de una duración (@code{1}@tie{}en el caso de la
redonda, @code{2}@tie{}en el caso de una blanca, etc.).  Multiplicando
la duración se pueden construir silencios más largos.  Por ejemplo,
este silencio ocupa 3@tie{}compases de 2/4

@example
R2*3
@end example

Cuando se imprime la particella tienen que comprimirse los silencios
multicompás.  Esto se hace estableciendo una variable en tiempo de
ejecución

@example
\set Score.skipBars = ##t
@end example

@noindent
Esta instrucción establece el valor de la propiedad @code{skipBars} en
el contexto de @code{Score} a verdadero (@code{##t}).  Anteponiendo el
silencio y esta opción a la música anterior, llegamos al siguiente
resultado

@lilypond[quote,ragged-right]
\transpose f c' \relative c {
  \time 2/4
  \set Score.skipBars = ##t
  R2*3
  r4 f8 a cis4 f e d
}
@end lilypond


Esta partitura se hace combinando toda la música junta.  Suponiendo
que la otra voz se encuentra dentro de @code{notasFagot} en el archivo
@file{fagot.ly}, la partitura se hace con

@example
\include "fagot.ly"
\include "trompa.ly"

<<
  \new Staff \notasTrompa
  \new Staff \notasFagot
>>
@end example

@noindent
lo que nos lleva a

@lilypond[quote,ragged-right]
\relative c <<
  \new Staff {
    \time 2/4 R2*3
    r4 f8 a cis4 f e d
  }
  \new Staff {
    \clef bass
    r4 d,8 f | gis4 c | b bes |
    a8 e f4 | g d | gis f
  }
>>
@end lilypond


@node Make and Makefiles
@section Make and Makefiles

@cindex make, archivos de
@cindex make

Posiblemente todas las plataformas en que puede correr LilyPond,
contemplan una posibilidad de software llamada @code{make}. Este
programa lee un archivo especial llamado @code{Makefile} que define
las relaciones de dependencia entre los archivos y qué instrucciones
necesitamos dar al sistema operativo para producir un archivo a partir
de otro.  Por ejemplo, el archivo de make detallaría cómo obtener
@code{balada.pdf} y @code{balada.midi} a partir de @code{balada.ly}
mediante la ejecución de Lilypond.

Existen ocasiones en las que es buena idea crear un @code{Makefile}
para nuestro proyecto, bien sea por nuestra propia comodidad o como
cortesía para otros que posiblemente tengan acceso a nuestros archivos
fuente.  Esto es cierto para proyectos muy grandes con muchos archivos
de inclusión y distintas opciones de salida (p.ej. partitura completa,
particellas, partitura del director, reducción para piano, etc.), o
para proyectos que requieren instrucciones difíciles para montarlas
(como los proyectos de @code{lilypond-book}). La complejidad y
flexibilidad de los Makefiles varía enormemente según las necesidades
y la habilidad de los autores.  El programa GNU Make viene instalado
en las distribuciones de GNU/Linux y en MacOS X, y también existe para
Windows.

Consulte el @strong{Manual de GNU Make} para ver todos los detalles
sobre el uso de @code{make}, pues lo que sigue a continuación ofrece
solamente una pincelada de todo lo que es capaz de hacer.

Las instrucciones que definen las reglas en un archivo de make
difieren en función de la plataforma; por ejemplo, las distintas
formas de Linux y MacOS usan @code{bash}, mientras que Windows usa
@code{cmd}.  Observeque en MacOS X, tenemos que configurar el sistema
para que utilice el intérprete de órdenes. A continuación presentamos
algunos makefiles de ejemplo, con versiones tanto para Linux/MacOS
como para Windows.

El primer ejemplo es para una obra orquestal en cuatro movimientos con
la estructura de directorios siguiente:

@example
Sinfonia/
|-- MIDI/
|-- Makefile
|-- Notas/
|   |-- cello.ily
|   |-- cifras.ily
|   |-- trompa.ily
|   |-- oboe.ily
|   |-- trioCuerdas.ily
|   |-- viola.ily
|   |-- violinUno.ily
|   `-- violinDos.ily
|-- PDF/
|-- Particellas/
|   |-- sinfonia-cello.ly
|   |-- sinfonia-trompa.ly
|   |-- sinfonia-oboes.ly
|   |-- sinfonia-viola.ly
|   |-- sinfonia-violinUno.ly
|   `-- sinfonia-violinDos.ly
|-- Partituras/
|   |-- sinfonia.ly
|   |-- sinfoniaI.ly
|   |-- sinfoniaII.ly
|   |-- sinfoniaIII.ly
|   `-- sinfoniaIV.ly
`-- sinfoniaDefs.ily
@end example

Los archivos @code{.ly} de los directorios @code{Partituras} y
@code{Particellas} obtienen las notas de archivos @code{.ily} que están en
el directorio @code{Notas}:

@example
%%% principio del archivo "sinfonia-cello.ly"
\include ../definiciones.ily
\include ../Notas/cello.ily
@end example

El makefile tendrá los objetivos de @code{partitura} (la pieza
completa en todo su esplendor), @code{movimientos} (partitura completa
de los movimientos individuales) y @code{particellas} (partes
individuales para los atriles). También existe un objetivo
@code{archivo} que produce un tarball de los archivos fuente, adecuado
para compartirlo a través de la web o por correo electrónico.  A
continuación presentamos el makefile para GNU/Linux o MacOS X.  Se
debe guardar con el nombre exacto @code{Makefile} el el directorio
superior del proyecto:

@warning{Cuando se define un objetivo o una regla de patrón, las
líneas siguientes deben comenzar con tabuladores, no con espacios.}

@example
# nombre principal de los archivos de salida
nombre = sinfonia
# determinar cuántos procesadores existen
CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
# La instrucción para ejecutar lilypond
LILY_CMD = lilypond -ddelete-intermediate-files \
                    -dno-point-and-click -djob-count=$(CPU_CORES)

# Los sufijos utilizados en este Makefile.
.SUFFIXES: .ly .ily .pdf .midi

# Los archivos de entrada y salida se buscan dentro de los directorios relacionados en
# la variable VPATH.  Todos esllos son subdirectorios del directorio
# en curso (dado por la variable de GNU make `CURDIR').
VPATH = \
  $(CURDIR)/Partituras \
  $(CURDIR)/PDF \
  $(CURDIR)/Particellas \
  $(CURDIR)/Notas

# La regla de patrón para crear archivos PDF y MIDI a partir de un archivo de entrada LY.
# Los archivos de salida .pdf se colocan en el subdirectorio `PDF', y los archivos
# .midi van al subdirectorio `MIDI'.
%.pdf %.midi: %.ly
        $(LILY_CMD) $<; \           # esta línea comienza con un salto de tabulación
        if test -f "$*.pdf"; then \
            mv "$*.pdf" PDF/; \
        fi; \
        if test -f "$*.midi"; then \
            mv "$*.midi" MIDI/; \
        fi

notas = \
  cello.ily \
  trompa.ily \
  oboe.ily \
  viola.ily \
  violinUno.ily \
  violinDos.ily

# Dependencias de los movimientos.
$(nombre)I.pdf: $(nombre)I.ly $(notas)
$(nombre)II.pdf: $(nombre)II.ly $(notas)
$(nombre)III.pdf: $(nombre)III.ly $(notas)
$(nombre)IV.pdf: $(nombre)IV.ly $(notas)

# Dependencias de la partitura completa.
$(nombre).pdf: $(nombre).ly $(notas)

# Dependencias de las particellas.
$(nombre)-cello.pdf: $(nombre)-cello.ly cello.ily
$(nombre)-trompa.pdf: $(nombre)-trompa.ly trompa.ily
$(nombre)-oboes.pdf: $(nombre)-oboes.ly oboe.ily
$(nombre)-viola.pdf: $(nombre)-viola.ly viola.ily
$(nombre)-violinUno.pdf: $(nombre)-violinUno.ly violinUno.ily
$(nombre)-violinDos.pdf: $(nombre)-violinDos.ly violinDos.ily

# Teclee `make partitura' para generer la partitura completa de los cuatro
# movimientos como un archivo único.
.PHONY: partitura
partitura: $(nombre).pdf

# Teclee `make particellas' para generar todas las particellas.
# Teclee `make fulanito.pdf' para generar la particella del instrumento `fulanito'.
# Ejemplo: `make sinfonia-cello.pdf'.
.PHONY: particellas
particellas: $(nombre)-cello.pdf \
       $(nombre)-violinUno.pdf \
       $(nombre)-violinDos.pdf \
       $(nombre)-viola.pdf \
       $(nombre)-oboes.pdf \
       $(nombre)-trompa.pdf

# Teclee `make movimientos' para generar los archivos de los
# cuatro movimientos de forma separada.
.PHONY: movimientos
movimientos: $(nombre)I.pdf \
           $(nombre)II.pdf \
           $(nombre)III.pdf \
           $(nombre)IV.pdf

all: partitura particellas movimientos

archivo:
        tar -cvvf stamitz.tar \       # esta línea comienza con un salto de tabulación
        --exclude=*pdf --exclude=*~ \
        --exclude=*midi --exclude=*.tar \
        ../Stamitz/*
@end example


Existen ciertas complicaciones en la plataforma Windows. Después de
descargar e instalar el programa GNU Make para Windows, debemos
configurar la ruta adecuada en las variables de entorno del sistema de
forma que el shell del DOS pueda encontrar el programa Make. Para
hacerlo, pulse con el botón derecho sobre "Mi PC", elija
@code{Propiedades} y @code{Avanzadas}. Pulse sobre @code{Variables de
entorno}, y luego en la pestaña @code{Variables del sistema},
seleccione @code{Ruta}, pulse sobre @code{editar} y añada la ruta al
archivo ejecutable de GNU Make, con lo que quedará algo parecido a lo
siguiente:

@example
C:\Archivos de programa\GnuWin32\bin
@end example

El makefile en sí debe modificarse para que maneje distintas
instrucciones del shell y para que pueda tratar con los espacios que
aparecen en el nombre de algunos directorios del sistema
predeterminados. El objetivo @code{archivo} se elimina porque Windows
no tiene la instrucción @code{tar}, y Windows tiene también una
extensión predeterminada distinta para los archivos MIDI.


@example
## VERSIÓN PARA WINDOWS
##
nombre = sinfonia
LILY_CMD = lilypond -ddelete-intermediate-files \
                    -dno-point-and-click \
                    -djob-count=$(NUMBER_OF_PROCESSORS)

#obtener el nombre 8.3 de CURDIR (rodeo para los espacios en PATH)
workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
          do @@echo %%~sb)

.SUFFIXES: .ly .ily .pdf .mid

VPATH = \
  $(workdir)/Partituras \
  $(workdir)/PDF \
  $(workdir)/Particellas \
  $(workdir)/Notas

%.pdf %.mid: %.ly
        $(LILY_CMD) $<      # esta línea comienza con un salto de tabulación
        if exist "$*.pdf"  move /Y "$*.pdf"  PDF/ # comienzo con tab
        if exist "$*.mid" move /Y "$*.mid" MIDI/  # comienzo con tab

notas = \
  cello.ily \
  cifras.ily \
  trompa.ily \
  oboe.ily \
  trioCuerdas.ily \
  viola.ily \
  violinUno.ily \
  violinDos.ily

$(nombre)I.pdf: $(nombre)I.ly $(notas)
$(nombre)II.pdf: $(nombre)II.ly $(notas)
$(nombre)III.pdf: $(nombre)III.ly $(notas)
$(nombre)IV.pdf: $(nombre)IV.ly $(notas)

$(nombre).pdf: $(nombre).ly $(notas)

$(nombre)-cello.pdf: $(nombre)-cello.ly cello.ily
$(nombre)-trompa.pdf: $(nombre)-trompa.ly trompa.ily
$(nombre)-oboes.pdf: $(nombre)-oboes.ly oboe.ily
$(nombre)-viola.pdf: $(nombre)-viola.ly viola.ily
$(nombre)-violinUno.pdf: $(nombre)-violinUno.ly violinUno.ily
$(nombre)-violinDos.pdf: $(nombre)-violinDos.ly violinDos.ily

.PHONY: partitura
partitura: $(nombre).pdf

.PHONY: particellas
particellas: $(nombre)-cello.pdf \
       $(nombre)-violinUno.pdf \
       $(nombre)-violinDos.pdf \
       $(nombre)-viola.pdf \
       $(nombre)-oboes.pdf \
       $(nombre)-trompa.pdf

.PHONY: movimientos
movimientos: $(nombre)I.pdf \
           $(nombre)II.pdf \
           $(nombre)III.pdf \
           $(nombre)IV.pdf

all: partitura particellas movimientos
@end example


El Makefile siguiente es para un documento de @command{lilypond-book}
hecho en LaTeX.  Este proyecto tiene un índice, que requiere ejecutar
la instrucción @command{latex} dos veces para actualizar los enlaces.
Todos los archivos de salida se almacenan en el directorio
@code{salida} para los documentos .pdf y en el directorio
@code{salidahtml} para la salida en formato html.

@example
SHELL=/bin/sh
NOMBRE=miproyecto
DIR_SALIDA=salida
DIR_WEB=salidahtml
VISOR=acroread
NAVEGADOR=firefox
LILYBOOK_PDF=lilypond-book --output=$(DIR_SALIDA) --pdf $(NOMBRE).lytex
LILYBOOK_HTML=lilypond-book --output=$(DIR_WEB) $(NOMBRE).lytex
PDF=cd $(DIR_SALIDA) && pdflatex $(NOMBRE)
HTML=cd $(DIR_WEB) && latex2html $(NOMBRE)
INDICE=cd $(DIR_SALIDA) && makeindex $(NOMBRE)
VISTA_PREVIA=$(VISOR) $(DIR_SALIDA)/$(NOMBRE).pdf &

all: pdf web guardar

pdf:
        $(LILYBOOK_PDF)  # comienza con un tab
        $(PDF)           # comienza con un tab
        $(INDICE)        # comienza con un tab
        $(PDF)           # comienza con un tab
        $(VISTA_PREVIA)  # comienza con un tab

web:
        $(LILYBOOK_HTML) # comienza con un tab
        $(HTML)          # comienza con un tab
        cp -R $(DIR_WEB)/$(NOMBRE)/ ./  # comienza con un tab
        $(NAVEGADOR) $(NOMBRE)/$(NOMBRE).html &  # comienza con un tab

guardar: pdf
        cp $(DIR_SALIDA)/$(NOMBRE).pdf $(NOMBRE).pdf  # comienza con un tab

clean:
        rm -rf $(DIR_SALIDA) # comienza con un tab

web-clean:
        rm -rf $(DIR_WEB) # comienza con un tab

archivo:
        tar -cvvf miproyecto.tar \ # comienza con un tab
        --exclude=salida/* \
        --exclude=salidahtml/* \
        --exclude=miproyecto/* \
        --exclude=*midi \
        --exclude=*pdf \
        --exclude=*~ \
        ../MiProyecto/*
@end example

HACER: conseguir que funcione en Windows

El makefile anterior no funciona en Windows.  Una alternativa para los
usuarios de Windows sería crear un archivo de lotes sencillo que
contenga las instrucciones de montaje.  Esto no rastrea las
dependencias en la manera en que lo hace un makefile, pero al menos
reduce el proceso de construcción a una sola instrucción.  Guarde el
código siguiente como @command{montaje.bat} o @command{montaje.cmd}.
El archivo de lotes se puede ejecutar en la línea de comandos del DOS
o simplemente haciendo doble click sobre su icono.

@example
lilypond-book --output=salida --pdf miproyecto.lytex
cd salida
pdflatex miproyecto
makeindex miproyecto
pdflatex miproyecto
cd ..
copy salida\miproyecto.pdf MiProyecto.pdf
@end example


@seealso
Manual de utilización del programa:
@rprogram{Setup for MacOS X},
@rprogram{Command-line usage},
@rprogram{LilyPond-book}