Merge branch 'lilypond/translation'

[lilypond.git] / Documentation / es / learning / tutorial.itely

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

@ignore
    Translation of GIT committish: cec6b24809cf3ffbb594f70c9823365501ccc2b4

    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

@include included/generating-output.itexi

@c \version "2.12.0"

@node Tutorial
@chapter Tutorial
@translationof Tutorial

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

@menu
* Compilación del archivo::
* Escritura del código 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.

@menu
* Escritura del código de entrada::
* MacOS X::
* Windows::
* Línea de órdenes::
@end menu

@node Escritura del código de entrada
@subsection Escritura del código de entrada
@translationof Entering input

@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.

@smallspace

@subheading Generar el resultado

@cindex PDF, archivo
@cindex ver la música
@cindex editores de texto

El método para producir un resultado impreso depende de snuestro
sistema operativo y del programa o programas que utilicemos.


@itemize

@item
@ref{MacOS X, @sourceimage{logo-macosx,,,}}
@ref{MacOS X, MacOS X} (gráfico)

@item
@ref{Windows, @sourceimage{logo-windows,,,}}
@ref{Windows, Microsoft Windows} (gráfico)

@item
@ref{Línea de órdenes, @sourceimage{logo-linux,,,}
@sourceimage{logo-freebsd,,,}
@sourceimage{logo-macosx,,,}
@sourceimage{logo-windows,,,}
}
@ref{Línea de órdenes, Todos los sistemas operativos} (consola)

@end itemize

Existen varios otros editores de texto con un apoyo específico a la
edición de texto de LilyPond.  Para ver más información, consulte
@rweb{Entornos mejorados}.

@warning{La primera vez que ejecute LilyPond, tardará un minuto o dos
porque todas las tipografías del sistema han de ser analizadas
previamente.  ¡Después de esto, LilyPond será mucho más rápido!}


@node MacOS X
@subsection MacOS X

@cindex ejecución de LilyPond bajo MacOS X
@cindex MacOS X, ejecución de LilyPond

@lilypadOSX


@node Windows
@subsection Windows

@cindex ejecutar LilyPond bajo Windows
@cindex Windows, ejecutar LilyPond

@lilypadWindows


@node Línea de órdenes
@subsection Línea de órdenes
@translationof Command-line

@cindex ejecución de  LilyPond bajo Unix
@cindex Unix, ejecución de LilyPond

@lilypadCommandLine

@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

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.


@subheading Alturas

@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 relative
@funindex '
@funindex ,

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

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]
% set the starting point to middle C
\relative c' {
  c d e f
  g a b c
}
@end lilypond

La nota inicial 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 c' {
  d f a g
  c b f d
}
@end lilypond

@noindent
No es necesario que la primera nota de la melodía comience exactamente
en aquella que especifica la altura de inicio.  En el ejemplo
anterior, la primera nota (@code{d}) es el Re más cercano al Do
central.

Añadiendo (o eliminando) comillas simples @code{'} o comas @code{,} a
la instrucción @q{@w{@code{@bs{}\relative c'}}}, podemos cambiar la octava
de inicio:

@c KEEP LY
@lilypond[verbatim,quote]
% una octava por encima del Do central
\relative c'' {
  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 c'' {
  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 c'' {
  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

@subheading Duraciones (valores rítmicos)

@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 c'' {
  a1
  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 c'' {
  a a a4. a8
  a8. a16 a a8. a8 a4.
}
@end lilypond


@subheading Silencios

@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 c'' {
  a r r2
  r8 a r4 r4. r8
}
@end lilypond


@subheading Indicación de compás

@cindex compás, indicación de

@funindex \time
@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 c'' {
  \time 3/4
  a4 a a
  \time 6/8
  a4. a
  \time 4/4
  a4 a a a
}
@end lilypond


@subheading Clave

@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
@funindex clef

Glosario musical:
@rglos{clef}.

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

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


@subheading Todo junto

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

@lilypond[verbatim,quote]
\relative c, {
  \time 3/4
  \clef bass
  c2 e8 c' g'2.
  f4 e d c4 c, r4
}
@end lilypond


@seealso
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{@{ c d e @}}}
significa lo mismo que @w{@samp{@{ c @tie{} @tie{} @tie{} d e @}}} y
que

@example
@{ c                        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
@{
  c 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{@bs{}relative c' @{ @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.

  f 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{@bs{}relative c'' @{ @dots{} @}}}}.  Durante el resto del presente
manual, la mayor parte de los ejemplos omitirán las llaves.  Para
reproducir los ejemplos, deberá copiar y pegar la entrada que se
muestra, pero @strong{deberá} escribir el @q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}},
de la siguiente forma:

@example
\relative c'' @{
  @dots{}aquí va el ejemplo@dots{}
@}
@end example

¿Por qué omitir las llaves? Casi todos los ejemplos del presente
manual se pueden insertar en medio de un fragmento mayor de música.
Para estos ejemplos no tiene ningún sentido añadir
@q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}}
(¡no debería poner un @code{\relative} dentro de otro
@code{\relative}!); si hubiésemos incluido
@q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}}
rodeando a cada uno de los ejemplos, usted no podría copiar un
ejemplo pequeño procedente de la documentación y pegarlo dentro de su
propia pieza.  La mayoría querrá insertar el código dentro de una
pieza más grande, por eso hemos formateado el manual de esta manera.

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'' {
  c-\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
@translationof 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