@c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-

@ignore
    Translation of GIT committish: 557cc9934585a9083c9e4957068889b3f393873c

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore



@c \version "2.19.21"

@node Tutorial
@chapter Tutorial
@translationof Tutorial

Este capítulo ofrece una introducción básica al trabajo con
LilyPond.

@menu
* Compilación del archivo::
* Cómo escribir archivos de entrada::
* Tratar con los errores::
* Cómo leer los manuales::
@end menu

@node Compilación del archivo
@section Compilación del archivo
@translationof Compiling a file

Esta sección presenta el concepto de @qq{compilación}: el
procesamiento de los documentos de entrada de LilyPond (escritos
por uno mismo) para producir archivos de salida.

@cindex compilación
@cindex ejemplo inicial
@cindex inicial, ejemplo
@cindex mayúsculas, sensible a

@qq{Compilación} es una palabra que significa procesar un texto de
entrada en formato de LilyPond para producir un archivo que se
puede imprimir y (de manera opcional) un archivo MIDI que se puede
reproducir.  El primer ejemplo muestra el aspecto de un sencillo
archivo de texto de entrada.

Este ejemplo muestra un archivo de entrada sencillo:

@example
\version "@w{@version{}}"
@{
  c' e' g' e'
@}
@end example

El resultado tiene este aspecto:

@c  in this case we don't want verbatim
@lilypond[quote]
{
  c' e' g' e'
}
@end lilypond

@warning{la música y la letra escrita en el código de entrada de
LilyPond tiene que ir siempre entre @w{@strong{@{ llaves @}}}.
Las llaves deberían también estar rodeadas por espacios a no ser
que se encuentren al principio o al final de una línea, para
evitar ambigüedades.  Es posible que se omitan en algunos ejemplos
del presente manual ¡pero no las omita en su propia música!  Para
ver más información sobre la presentación de los ejemplos del
manual, consulte @ref{Cómo leer los manuales}.}

Además, la entrada de LilyPond es @strong{sensible a las
mayúsculas}.  @w{@samp{ @{ c d e @}}} es una entrada válida;
@w{@samp{@{ C D E @}}} produce un mensaje de error.



@node Cómo escribir archivos de entrada
@section Cómo escribir archivos de entrada
@translationof How to write input files

Esta sección presenta una parte de la sintaxis básica de LilyPond
como ayuda para que se inicie en la escritura de archivos de
entrada.

@menu
* Notación sencilla::
* Trabajar sobre los archivos de entrada::
@end menu


@node Notación sencilla
@subsection Notación sencilla
@translationof Simple notation

@cindex sencilla, notación
@cindex notación sencilla

@menu
* Alturas::
* Duraciones (valores rítmicos)::
* Silencios::
* Indicación de compás::
* Indicaciones de tempo::
* Clave::
* Todo junto::
@end menu

LilyPond añadirá ciertos elementos de notación de manera
automática.  En el siguiente ejemplo hemos especificado solamente
cuatro alturas, pero LilyPond ha añadido la clave, el compás y las
duraciones.

@lilypond[verbatim,quote]
{
  c' e' g' e'
}
@end lilypond

@noindent
Este comportamiento se puede modificar, pero en general estos
valores automáticos son adecuados.


@node Alturas
@unnumberedsubsubsec Alturas
@translationof Pitches

@cindex alturas
@cindex notas
@cindex relativo, modo
@cindex apóstrofo
@cindex comilla simple
@cindex coma
@cindex alteraciones y modo relativo
@cindex relativo, modo, alteraciones y

@funindex \relative
@funindex '
@funindex ,

Glosario musical:
@rglos{pitch},
@rglos{interval},
@rglos{scale},
@rglos{middle C},
@rglos{octave},
@rglos{accidental}.

LilyPond emplea letras minúsculas para las alturas.  Los nombres
de nota en todos los ejemplos de esta sección usan la nomenclatura
holandesa, en que las teclas blancas del piano van desde la c (Do)
hasta la b (Si).  Sin embargo, LilyPond contempla muchos otros
sistemas para los nombres de las notas, como el inglés o el @q{Do
fijo} (do-re-mi-...).  Véase @ruser{Nombres de las notas en otros
idiomas}.  Las letras desde @code{c} hasta@tie{}@code{b} denotan
las alturas de las notas de la @q{octava corta} por debajo del
@notation{Do central}.  Los sufijos @code{'} (apóstrofo)
o@tie{}@code{,} (coma) se añaden para indicar octavas más agudas o
más graves.  A continuación se muestra una escala que comienza en
el @notation{Do central}, y un arpegio:

@lilypond[verbatim,quote]
{ c' d' e' f' g' a' b' c'' g c' e' g' c'' e'' g'' c''' }
@end lilypond

La manera más sencilla de introducir las notas es mediante la
utilización del modo @code{\relative} (relativo).  En este modo,
se elige la octava automáticamente bajo la suposición de que la
siguiente nota se colocará siempre lo más cerca de la nota actual,
es decir, se colocará en la octava comprendida dentro de hasta
tres espacios de pentagrama a partir de la nota anterior.
Comenzaremos por introducir el fragmento musical más elemental:
una @notation{escala}, donde cada nota está comprendida dentro de
tan sólo un espacio de pentagrama desde la nota anterior.

@lilypond[verbatim,quote]
\relative {
  c' d e f
  g a b c
}
@end lilypond

La nota inicial, escrita como @code{c'}, es el @notation{Do
central}.  Cada nota sucesiva se coloca lo más cerca posible de la
nota previa (en otras palabras: la primera @samp{c} es el Do más
cercano al Do central; a éste le sigue el Re más cercano a la nota
previa, y así sucesivamente).  Podemos crear melodías con
intervalos mayores, aún sin dejar de utilizar el modo relativo:

@lilypond[verbatim,quote]
\relative {
  d' f a g
  c b f d
}
@end lilypond

@noindent
En el ejemplo anterior, la primera nota (@code{d'}, con un
apóstrofo) es el Re que está en la octava que va del Do central al
Si por encima de él.

Añadiendo (o eliminando) comillas simples @code{'} o comas
@code{,} a la primera nota, podemos cambiar la octava de inicio:

@lilypond[verbatim,quote]
\relative {
  e'' c a c
}
@end lilypond

Al principio, el modo relativo puede resultar algo confuso, pero
es la forma más sencilla de introducir la mayor parte de las
melodías.  Veamos cómo funciona en la práctica este cálculo
relativo.  Comenzando por Si, que está situado en la línea central
en clave de Sol, podemos alcanzar Do, Re y Mi dentro de los tres
espacios de pentagrama hacia arriba, y La, Sol y Fa dentro de los
tres espacios hacia abajo.  Por tanto, si la nota siguiente a Si
es Do, Re o Mi se supondrá que está por encima del Si, mientras
que La, Sol o Fa se entenderán situados por debajo.

@c KEEP LY
@lilypond[verbatim,quote]
\relative {
  b' c  % el Do está un espacio por encima, es el Do de arriba
  b d  % el Re está dos por encima ó 5 por debajo, es el Re de arriba
  b e  % el Mi está 3 por encima ó 4 por debajo, es el Mi de arriba
  b a  % el La está 6 por encima ó 1 por debajo, es el La de abajo
  b g  % el Sol está 5 por encima ó 2 por debajo, es el Sol de abajo
  b f  % el Fa está 4 por encima ó 3 por debajo, es el Fa de abajo
}
@end lilypond

Lo mismo exactamente ocurre cuando cualquiera de esas notas llevan
un sostenido o un bemol.  Las @notation{Alteraciones accidentales}
se @strong{ignoran totalmente} en el cálculo de la posición
relativa.  Exactamente la misma cuenta de espacios de pentagrama
se hace a partir de una nota situada en cualquier otro lugar del
mismo.

Para añadir intervalos mayores de tres espacios de pentagrama,
podemos elevar la @notation{octava} añadiendo una comilla simple
@code{'} (o apóstrofo) a continuación del nombre de la nota.
También podemos bajar la octava escribiendo una coma @code{,} a
continuación del nombre de la nota.

@lilypond[verbatim,quote]
\relative {
  a' a, c' f,
  g g'' a,, f'
}
@end lilypond

@noindent
Para subir o bajar una nota en dos (¡o más!) octavas, utilizamos
varias @code{''} ó @code{,,} (pero tenga cuidado de utilizar dos
comillas simples @code{''} ¡y no una comilla doble
@code{"}@tie{}!)
@c " - keeps quotes in order for context-sensitive editor -td

@node Duraciones (valores rítmicos)
@unnumberedsubsubsec Duraciones (valores rítmicos)
@translationof Durations (rhythms)

@cindex duraciones de las notas
@cindex notas, duraciones de
@cindex ritmos
@cindex redonda
@cindex blanca
@cindex negra
@cindex figura con puntillo
@cindex puntillo
@cindex notación de las duraciones

Glosario musical:
@rglos{beam},
@rglos{duration},
@rglos{whole note},
@rglos{half note},
@rglos{quarter note},
@rglos{dotted note}.

La @notation{duración} de una nota se especifica mediante un
número después del nombre de la nota: @code{1} significa
@notation{redonda}, @code{2} significa @notation{blanca}, @code{4}
significa @notation{negra} y así sucesivamente.  Las
@notation{barras de corchea} se añaden automáticamente.

Si no especifica una duración, se utiliza la duración previa para
la nota siguiente.  La figura por omisión de la primera nota es
una negra.

@lilypond[verbatim,quote]
\relative {
  a'1
  a2 a4 a8 a
  a16 a a a a32 a a a a64 a a a a a a a a2
}
@end lilypond

Para crear @notation{notas con puntillo}, añada un punto @code{.}
al número de la duración.  La duración de una nota con puntillo se
debe especificar de forma explícita (es decir: mediante un
número).

@lilypond[verbatim,quote]
\relative {
  a'4 a a4. a8
  a8. a16 a a8. a8 a4.
}
@end lilypond

@node Silencios
@unnumberedsubsubsec Silencios
@translationof Rests

@cindex silencio
@cindex notación de los silencios

Glosario musical:
@rglos{rest}.

Un @notation{silencio} se introduce igual que si fuera una nota
con el nombre @code{r}@tie{}:

@lilypond[verbatim,quote]
\relative {
  a'4 r r2
  r8 a r4 r4. r8
}
@end lilypond


@node Indicación de compás
@unnumberedsubsubsec Indicación de compás
@translationof Time signature

@cindex compás, indicación de

@funindex \time

Glosario musical:
@rglos{time signature}.

La @notation{indicación de compás} se puede establecer con la
orden @code{\time} :

@lilypond[verbatim,quote]
\relative {
  \time 3/4
  a'4 a a
  \time 6/8
  a4. a
  \time 4/4
  a4 a a a
}
@end lilypond

@node Indicaciones de tempo
@unnumberedsubsubsec Indicaciones de tempo
@translationof Tempo marks

@cindex tempo, indicaciones de
@cindex metronómicas, indicaciones

@funindex \tempo

Glosario musical:
@rglos{tempo indication},
@rglos{metronome}.

La @notation{indicación de tempo} y la @notation{indicación
metronómica} pueden establecerse con la instrucción @code{\tempo}:

@lilypond[verbatim,quote]
\relative {
  \time 3/4
  \tempo "Andante"
  a'4 a a
  \time 6/8
  \tempo 4. = 96
  a4. a
  \time 4/4
  \tempo  "Presto" 4 = 120
  a4 a a a
}
@end lilypond


@node Clave
@unnumberedsubsubsec Clave
@translationof Clef

@cindex clave
@cindex sol, clave de
@cindex do en tercera, clave de
@cindex do en cuarta, clave de
@cindex fa, clave de
@cindex soprano
@cindex alto
@cindex tenor
@cindex bajo

@funindex \clef

Glosario musical:
@rglos{clef}.

La @notation{clave} se puede establecer utilizando la orden
@code{\clef} :

@lilypond[verbatim,quote]
\relative {
  \clef "treble"
  c'1
  \clef "alto"
  c1
  \clef "tenor"
  c1
  \clef "bass"
  c1
}
@end lilypond


@node Todo junto
@unnumberedsubsubsec Todo junto
@translationof All together

He aquí un pequeño ejemplo que muestra todos los elementos
anteriores juntos:

@lilypond[verbatim,quote]
\relative {
  \clef "bass"
  \time 3/4
  \tempo "Andante" 4 = 120
  c,2 e8 c'
  g'2.
  f4 e d
  c4 c, r
}
@end lilypond


@morerefs
Referencia de la notación:
@ruser{Escritura de notas},
@ruser{Escritura de las duraciones (valores rítmicos)},
@ruser{Escritura de silencios},
@ruser{Indicación de compás},
@ruser{Clave}.


@node Trabajar sobre los archivos de entrada
@subsection Trabajar sobre los archivos de entrada
@translationof Working on input files

@cindex llaves
@cindex comentarios
@cindex línea, comentario de
@cindex comentario de línea
@cindex bloque, comentario de
@cindex mayúsculas, sensible a
@cindex espacios, insensible a
@cindex expresiones
@cindex versiones
@cindex versión
@cindex número de versión


@funindex \version
@funindex { ... }
@funindex %
@funindex %@{ ... %@}

Los archivos de entrada de LilyPond son como los archivos fuente
de muchos lenguajes de programación corrientes.  Contienen un
enunciado de versión, son sensibles a las mayúsculas y
generalmente los espacios se ignoran.  Las expresiones se forman
con llaves @w{@code{@{ @}}} y los comentarios se denotan por un
signo de porcentaje (@code{%}) o por @w{@code{%@{ @dots{}
%@}}}@tie{}.

Si la frase anterior no tiene sentido para usted ¡no se preocupe!
A continuación explicaremos el significado de todos estos
términos:

@itemize

@item
@strong{Enunciado de la versión}: Todo archivo de LilyPond debe
contener un enunciado de versión.  Un enunciado de versión es una
línea que describe la versión de LilyPond para la que se escribió
este archivo, como en el ejemplo siguiente:

@example
\version "@w{@version{}}"
@end example

Por convenio, el enunciado de versión se coloca al principio del
archivo de LilyPond.

El enunciado de versión es importante por dos motivos como mínimo.
En primer lugar, permite la actualización automática del código de
entrada conforme se va modificando la sintaxis de LilyPond.  En
segundo lugar, indica la versión de LilyPond que se necesita para
compilar el archivo.

Si no se escribe ningún enunciado de versión en el archivo de
entrada, LilyPond imprime una advertencia durante la compilación
del mismo.

@item
@strong{Sensible a las mayúsculas}: tiene importancia el hecho de
que introduzca una letra en minúsculas (p.ej. @w{@code{a, b, s, t}})
o en mayúsculas (p.ej.  @w{@code{A, B, S, T}}).  Las notas son
minúsculas: @w{@samp{@{ c d e @}}} es una entrada válida;
@w{@samp{@{ C D E @}}} produciría un mensaje de error.

@item
@strong{Insensible al número de espacios}: no importa cuántos
espacios (o saltos de línea o de tabulación) añada.
@w{@samp{@{ c4 d e @}}} significa lo mismo que
@w{@samp{@{ c4 @tie{} @tie{} @tie{} d e @}}} y que

@example
@{ c4                       d
                   e   @}
@end example

@noindent
Por supuesto, el ejemplo anterior es difícil de leer.  Una regla
práctica es sangrar los bloques de código con un carácter de
tabulación, o bien con dos espacios:

@example
@{
  c4 d e
@}
@end example

Sin embargo, @emph{sí} se necesitan espacios para separar muchos
elementos sintácticos unos de otros.  En otras palabras, los
espacios se pueden siempre @emph{añadir}, pero no siempre
@emph{eliminar}.  Dado que la falta de espacios puede dar lugar a
extraños errores, recomendamos insertar espacios siempre antes y
después de cualquier elemento sintáctico, por ejemplo, antes y
después de las llaves.

@item
@strong{Expresiones:} Todo fragmento de código de entrada para
LilyPond ha de llevar @strong{@{@tie{}llaves@tie{}@}} antes y
después de la entrada.  Estas llaves le dicen a LilyPond que la
entrada es una expresión musical unitaria, igual que los
paréntesis @samp{()} de las matemáticas.  Las llaves deben ir
rodeadas de un espacio a no ser que se encuentren al comienzo o al
final de una línea, para evitar cualquier ambigüedad.

Una instrucción de LilyPond seguida de una expresión simple entre
llaves (como por ejemplo @q{@w{@code{\relative @{ @dots{}
@}}}}) también es una expresión musical unitaria.

@cindex comentarios
@cindex comentario de línea
@cindex comentario de bloque
@item
@strong{Comentarios}: Un comentario es una nota para el lector
humano de la entrada musical; se ignora cuando esta entrada se
analiza, de manera que no tiene ningún efecto sobre la salida
impresa.  Existen dos tipos de comentarios.  El símbolo de
porcentaje @samp{%} introduce un comentario de línea; todo lo que
se encuentra después de @samp{%} en esa línea se ignora.  Por
convenio, una línea de comentario se coloca @emph{por encima} del
código a que se refiere el comentario.

@example
a4 a a a
% este comentario se refiere a las notas Si
b2 b
@end example

Un comentario de bloque marca una sección entera de entrada
musical como comentario.  Todo lo que está encerrado dentro de
@code{%@{} y @code{%@}} se ignora (pero los comentarios no pueden
anidarse, lo que significa que un comentario de bloque no puede
incluir otros comentarios de bloque).  Si lo hiciera, el primer
@code{%@}} daría por terminado @emph{los dos} comentarios de
bloque.  El siguiente fragmento muestra algunos posibles usos para
los comentarios:

@example
% a continuación van las notas de campanitas del lugar
  c4 c g' g a a g2

%@{
  Esta línea y las notas que aparecen más abajo
  se ignoran, por estar dentro de un
  comentario de bloque.

  f4 f e e d d c2
%@}
@end example

@end itemize


@node Tratar con los errores
@section Tratar con los errores
@translationof Dealing with errors

@cindex depuración de errores

A veces, LilyPond no produce el resultado esperado.  Esta sección
aporta algunos enlaces para ayudarle a resolver los problemas que
pudiera encontrar.

@menu
* Consejos generales de solución de problemas::
* Algunos errores comunes::
@end menu

@node Consejos generales de solución de problemas
@subsection Consejos generales de solución de problemas
@translationof General troubleshooting tips

La solución de problemas en LilyPond puede ser un desafío para las
personas acostumbradas a los interfaces gráficos, porque es
posible crear archivos de entrada inválidos.  Cuando esto ocurre,
la mejor forma de identificar y resolver el problema es aplicar un
enfoque lógico.  Se dan algunas guías para ayudarle a aprender a
hacerlo, en @rprogram{Solución de problemas}.


@node Algunos errores comunes
@subsection Algunos errores comunes
@translationof Some common errors

@cindex comunes, errores
@cindex errores comunes

Existen algunos errores comunes que son difíciles de solucionar si
nos basamos solamente en los mensajes de error que se nos
presentan.  Éstos se describen en @rprogram{Errores comunes}.


@node Cómo leer los manuales
@section Cómo leer los manuales
@translationof How to read the manuals

Esta sección muestra cómo leer la documentación de forma
eficiente, y presenta algunas interesantes funcionalidades
interactivas de la versión en línea.

@menu
* Material omitido::
* Ejemplos con enlace::
* Panorámica de los manuales::
@end menu


@node Material omitido
@subsection Material omitido
@translationof Omitted material


@cindex cómo leer el manual
@cindex manual, lectura del
@cindex leer el manual
@cindex ejemplos, pulsar
@cindex pulsar sobre los ejemplos
@cindex consejos para construir archivos
@cindex plantillas
@cindex construir archivos, consejos
@cindex archivos, consejos para construir

Como ya vimos en @ref{Trabajar sobre los archivos de entrada}, el
código de entrada de LilyPond debe estar rodeado de llaves
@code{@{ @}} o de @q{@w{@code{\relative @{ @dots{} @}}}}.
Durante el resto del presente manual, ciertos ejemplos breves
omitirán las llaves.  Para reproducir estos ejemplos puede copiar
la entrada que se muestra, pero debe pegarla entre @code{@{} y
@code{@}} dentro del archivo de entrada.

@example
@{
  @dots{}aquí va el ejemplo@dots{}
@}
@end example

Asimismo, recuerde que todo archivo de LilyPond debe llevar un
enunciado @code{\version}.  Dado que los ejemplos de los manuales
son fragmentos de código y no archivos completos, el enunciado
@code{\version} se omite.  De todas formas, debemos acostumbrarnos
a incluirlo en nuestros documentos.

@node Ejemplos con enlace
@subsection Ejemplos con enlace
@translationof Clickable examples

@warning{Esta funcionalidad sólo está disponible en los manuales
en HTML.}

Muchas personas aprenden a utilizar programas probando y enredando
con ellos.  Esto también puede hacerse con LilyPond.  Si hace clic
sobre una imagen en la versión en HTML de este manual, podrá ver
la entrada exacta de LilyPond que se utilizó para generar esa
imagen.  Pruébelo sobre esta imagen:

@c no verbatim here
@c KEEP LY
@lilypond[quote]
\relative {
  c''4-\markup { \bold \huge { Haga clic aquí. } }
}
@end lilypond

Cortando y pegando todo lo que se encuentra dentro de la sección
@qq{ly snippet} (fragmento de tipo ly), tendrá una plantilla
inicial para sus experimentos. Para poder ver exactamente el mismo
resultado (con igual anchura de línea y todo), copie todo lo que
está desde @qq{Start cut-&-pastable section} hasta el final del
archivo.


@ignore
This is item 825

@n ode Navegación con el teclado
@s ubsection Navegación con el teclado
@t ranslationof Keyboard navigation

@warning{Esta posibilidad sólo está disponible en los manuales en
HTML.}

@c TODO: once this is figured out, insert it here.

Estamos trabajando sobre esta funcionalidad.
@end ignore

@node Panorámica de los manuales
@subsection Panorámica de los manuales
@translationof Overview of manuals

Existe abundantísima documentación sobre LilyPond.  Con
frecuencia, los nuevos usuarios se encuentran desorientados
respecto a qué parte o partes deben leer, y ocasionalmente pasan
por alto la lectura de partes de importancia vital.

@warning{Por favor: no se salte las partes importantes de la
documentación.  Le resultará mucho más difícil comprender las
secciones subsiguientes.}

@itemize

@item
@strong{Antes de intentar hacer @emph{cualquier cosa}}: lea el
@ref{Tutorial} del manual de Aprendizaje, y la sección
@ref{Notación corriente}.  Si encuentra términos musicales que no
reconoce, búsquelos en el @rglosnamed{Top, Glosario}.

@item
@strong{Antes de tratar de escribir una pieza completa de música}:
lea la sección @ref{Conceptos fundamentales} del manual de
Aprendizaje.  Después, le vendrá bien consultar las secciones
correspondientes de la @rusernamed{Top, Referencia de la
notación}.

@item
@strong{Antes de tratar de modificar los resultados
predeterminados}: lea la sección @ref{Trucar la salida} del manual
de Aprendizaje.

@item
@strong{Antes de afrontar un proyecto grande}: lea la sección
@rprogramnamed{Suggestions for writing files,Sugerencias para
escribir archivos de entrada de LilyPond} del manual de
Utilización del programa.

@end itemize
