LilyPond: manual d'utilització del programa: 1.2 Utilització des de la línia d'ordres

## 1.2 Utilització des de la línia d’ordres

Aquesta secció conté informació addicional sobre l’ús del LilyPond a la línia d’ordres. Aquesta forma pot ser preferible per passar-li al programa algunes opcions addicionals. A més a més, existeixen alguns programes complementaris ‘de suport’ (com ara `midi2ly`) que sols estan disponibles a la línia d’ordres.

En parlar de la ‘línia d’ordres’, ens referim a la consola del sistema operatiu. Els usuaris del Windows possiblement estiguin més familiaritzats amb els termes ‘finestra del MS-DOS’ o ‘línia de comandes’; Els usuaris del MacOS X potser que estiguin més familiaritzats amb els termes ‘terminal’ o ‘consola’. Aquests podrien requerir algunes configuracions addicionals i haurien de consultar també l’apartat MacOS X.

La descripció de l’ús d’aquesta part dels sistemes operatius excedeix l’àmbit d’aquest manual; us preguem que consulteu altres documents sobre aquest tema si no us resulta familiar la línia d’ordres.

### Invocació del `lilypond`

L’executable `lilypond` es pot cridar des d’una línia d’ordres de la manera següent:

>     lilypond [opció]… fitxer…

Quan s’invoca amb un nom de fitxer sense extensió, es prova en primer lloc amb la extensió ‘`.ly`’. Per llegir l’entrada des de stdin, utilitzeu un guió (`-`) en substitució de fitxer.

Quan es processa ‘`archivo.ly`’, la sortida resultant són els fitxers ‘`fitxer.ps`’ i ‘`fitxer.pdf`’. Es poden especificar diversos fitxers; cadascú d’ells es processarà de forma independent1.

Si ‘`fitxer.ly`’ conté més d’un bloc `\score`, la resta de les partitures s’obtindran com a sortida en fitxers numerats, començant per ‘`fitxer-1.pdf`’. A més, el valor de `output-suffix` (sufix de sortida) s’inserirà entre el nom base i el número. Un fitxer de sortida que contingui

>     #(define output-suffix "violí")
>     \score { … }
>     #(define output-suffix "violoncel")
>     \score { … }

produirà com a sortida base‘`-violí.pdf`’ i base‘`-violoncel-1.pdf`’.

#### Instruccions estàndard de la línia d’ordres

Si la vostra terminal (o finestra d’ordres) contempla les redireccions normals, potser us siguin d’utilitat les següents instruccions per redirigir la sortida de la consola d’un fitxer:

- `lilypond fitxer.ly 1>sortidaestandard.log` per redirigir la sortida normal
- `lilypond fitxer.ly 2>sortidaderror.log` per redirigir els missatges d’error
- `lilypond fitxer.ly &>tot.log` per redirigir tota la sortida

Consulteu la documentació del vostre intèrpret d’ordres per veure si contempla aquestes opcions, o si la sintaxi és diferent. Observeu que són instruccions de l’intèrpret d’ordres i que no tenen res a veure amb el LilyPond.

### Opcions bàsiques de la línia d’ordres per al LilyPond

Estan contemplades les opcions següents:

`-d, --define-default=variable=valor`

  Vegeu Opcions avançades de la línia d’ordres per al LilyPond.

`-e, --evaluate=expressió`

  Avalua l’expressió del Scheme abans d’analitzar els fitxers ‘`.ly`’. Es poden passar diverses opcions ‘`-e`’, que s’avaluaran en seqüència.

  L’expressió s’avaluarà al mòdul `guile-user`, de manera que si voleu usar definicions dins d’expressió, heu d’utilitzar

  >     lilypond -e '(define-public a 42)'

  a la línia d’ordres, i incloure

  >     #(use-modules (guile-user))

  al principi del fitxer ‘`.ly`’.

  Nota: Els usuaris de Windows han d’utilitzar cometes dobles en comptes de cometes simples.

`-f, --format=format`

  quins formats s’han d’escriure. Les opcions per a `format` són `ps`, `pdf`, i `png`.

  Exemple: `lilypond -fpng fitxer.ly`

`-h, --help`

  Mostra un resum de les formes de utilització.

`-H, --header=CAMP`

  Bolca un camp de capçalera al fitxer ‘`NOMBASE.CAMP`’

`-i, --init=archivo`

  Establir el fitxer d’inici a fitxer (predeterminat: ‘`init.ly`’).

`-I, --include=directori`

  Afegir el directori a la ruta de cerca de fitxers d’entrada.

  Es poden escriure diverses opcions -I. La cerca s’inicia al primer directori definit, i si el fitxer que s’ha d’incloure no es troba, la cerca continua als directoris següents.

`-j, --jail=usuari,grup,gàbia,directori`

  Executar `lilypond` a una gàbia de chroot.

  L’opció ‘`--jail`’ (gàbia) proporciona una alternativa més flexible a l’opció ‘`-dsafe`’ quan el procés de tipografia del LilyPond està disponible a un servidor web o quan el LilyPond executa instruccions enviades per fonts externes (vegeu Opcions avançades de la línia d’ordres per al LilyPond).

  L’opció ‘`--jail`’ funciona canviant l’arrel de `lilypond` a gàbia just o abans de començar el procés de compilació en sí. Si es fa això es canvien l’usuari i el grup als que s’han donat a l’opció, i el directori actual es canvia a directori. Aquesta instal·lació garanteix que no és possible, al menys en teoria, escapar a la gàbia. Observeu que perquè funcioni ‘`--jail`’, s’ha d’executar `lilypond` com root, cosa que normalment es pot fer d’una forma segura utilitzant `sudo`.

  La instal·lació d’una gàbia pot ser un assumpte relativament complex, atès que hem d’assegurar-nos que el LilyPond pot trobar dins de la pròpia gàbia tot el que necessita per poder compilar la font. Una típica configuració de gàbia de chroot consta dels següents elements:

  Preparació d’un sistema de fitxers separat

    S’ha de crear un sistema de fitxers separat per al LilyPond, de forma que es pugui muntar amb opcions segures com `noexec`, `nodev` i `nosuid`. D’aquesta forma, és impossible executar programes o escriure directament a un dispositiu des del LilyPond. Si no voleu crear una partició separada, tan sols té que crear un fitxer d’una mida raonable i usar-lo per muntar un dispositiu loop. El sistema de fitxers separat garanteix també que el LilyPond mai no pugui escriure en un espai major del què se li permeti.

  Preparar un usuari separat

    Es pot usar un usuari i grup separats (diguem-ne `lily`/`lily`) amb pocs privilegis per executar el LilyPond dins d’una gàbia. Hauria d’existir un sols directori amb permisos d’escriptura per a aquest usuari, i s’ha de passar el valor directori.

  Preparació de la gàbia

    El LilyPond necessita llegir alguns fitxers mentre s’executa, Tots aquests fitxers s’han de copiar dins de la gàbia, sota la mateixa ruta en la qual apareixen al sistema de fitxers real de root. Tot el contingut de la instal·lació del LilyPond (per exemple ‘`/usr/share/lilypond`’) s’ha de copiar.

    Si sorgeixen problemes, la forma més senzilla de rastrejar-los és executar el LilyPond usant `strace`, cosa que li permetrà determinar quins fitxers falten.

  Execució del LilyPond

    Dins d’una gàbia muntada amb `noexec` és impossible executar cap programa extern. Per tant, el LilyPond s’ha d’executar amb un backend que no necessiti un programa extern. Com ja hem mencionat, s’ha d’executar amb privilegis del superusuari (que per suposat perdrà immediatament), possiblement usant `sudo`. També de CPU que el LilyPond pot usar (per exemple usant `ulimit -t`), i, si el vostre sistema operatiu ho contempla, la mida de la memòria que es pot reservar. Vegeu també El LilyPond a una gàbia de chroot.

`-l, --loglevel=NIVELL`

  Fixa el grau en el qual la sortida de consola és neta al nivell NIVELL. Els valors possibles són:

  `NONE`

    Cap sortida en absolut, ni tan sols missatges d’error.

  `ERROR`

    Sols missatges d’error, cap advertiment o indicacions de progrés.

  `WARN`

    Advertiments i missatges d’error, no de progrés.

  `BASIC_PROGRESS`

    Missatges de progrés bàsics (èxit), advertiment i errors.

  `PROGRESS`

    Tots els missatges de progrés, advertiments i errors.

  `INFO (predeterminat)`

    Missatges de progrés, advertiments, errors i informació d’execució addicional.

  `DEBUG`

    Tots els missatges possibles, fins i tot la informació detallada de depuració.

`-o, --output=FITXER o CARPETA`

  Estableix el nom del fitxer de sortida predeterminat a FITXER o, si hi ha una carpeta amb aquest nom, dirigeix la sortida cap a CARPETA, agafant el nom de fitxer del document d’entrada. S’afegeix el sufix corresponent (per exemple, `.pdf` per a PDF) als dos casos.

`--ps`

  Generar PostScript.

`--png`

  Genera imatges de les pàgines en format PNG. Això implica ‘`--ps`’. La resolució en PPP de la imatge es pot establir amb

  >     -dresolution=110

`--pdf`

  Genera PDF. Implica ‘`--ps`’.

`-v, --version`

  Mostra la informació de la versió.

`-V, --verbose`

  Sigues detallat: mostra les rutes completes de tots els fitxers que se llegeixen, i dóna informació cronomètrica.

`-w, --warranty`

  Mostra la garantia del GNU LilyPond (no ve amb CAP GARANTIA!).

### Opcions avançades de la línia d’ordres per al LilyPond

`-d[nom-de-opció]=[valor], --define-default=[nom-de-opció]=[valor]`

  Estableix la funció del Scheme interna equivalent a valor.

  >     -dbackend=svg

  Si no es proporciona cap valor, s’usa el valor predeterminat Per desactivar una opció es pot anteposar `no-` a la variable, per exemple:

  >     -dno-point-and-click

  és el mateix que

  >     -dpoint-and-click=#f

Estan contemplades les següents opcions junt als seus respectius valors predeterminats:

Símbol | Valor | Explicació/Opcions
`anti-alias-factor` (factor d’antiàlies) | `1` | Renderitza a una major resolució (utilitzant el factor donat) i redueix l’escala del resultat per així evitar ‘escales’ a les imatges `PNG`.
`aux-files` (fitxers auxiliars) | `#t` | Crea fitxeres `.tex`, `.texi`, `.count` al ‘back-end’ `EPS`.
`backend` | `ps` | Selecciona un ‘rerefons’. Els fitxers (l’opció predeterminada) inclouen els tipus tipogràfics de lletra `TTF`, `Type1` i `OTF`. No es fa cap subconjunt d’aquests tipus de lletra. L’ús de conjunts de caràcters ‘orientals’ pot produir fitxers molts grans.
| `svg` | Gràfics vectorials escalables. Crea un únic fitxer `SVG`, sense tipus tipogràfics de lletra incrustats, per a cada pàgina de sortida. Es recomana instal·lar el tipus de lletra Century Schoolbook, que està inclòs a la instal·lació del LilyPond, per a un renderitzat òptim. Sota l’UNIX, bastarà amb que copieu aquests fitxers de tipus de lletra del directori del Lilypond (normalment ‘`/usr/share/lilypond/VERSION/fonts/otf/`’) al directori ‘`~/.fonts/`’. La sortida `SVG` hauria de ser compatible amb qualsevol editor o client de SVG. També hi ha una opció `svg-woff` (vegeu més avall) per usar els fitxers de tipus de lletra woff al ‘rerefons’ SVG.
`clip-systems` (retalla els sistemes de pentagrames) | `#f` | Genera framents d’imatge retallats d’una partitura.
`datadir` (directori de dades) |  | Prefix dels fitxers de dades (sols lectura).
`debug-skylines` | `#f` | Depuració de les línies de horitzó.
`delete-intermediate-files` | `#t` | Elimina els fitxers intermedis `.ps` inútils que es creen durant la compilació.
`eps-box-padding` | `#f` | Omple la vora esquerra de la capsa contenidora de l’EPS de sortida en la quantitat donada (en mm).
`gs-load-fonts` | `#f` | Carrega els tipus tipogràfics de lletra a través del Ghostscript.
`gs-load-lily-fonts` | `#f` | Carrega sols els tipus de lletra del LilyPond per mitjà del Ghostscript.
`help` | `#f` | Mostra aquesta ajuda
`include-book-title-preview` | `#t` | Inclou els títols de llibre a les imatges de vista prèvia.
`include-eps-fonts` | `#t` | Incloure els tipus tipogràfics de fonts als fitxers EPS de cadascú dels sistemes.
`include-settings` | `#f` | Inclou el fitxer dels ajustos globals, s’inclou abans que la partitura es processi.
`job-count` | `#f` | Processa en paral·lel, usant el nombre de tasques donat.
`log-file` | `#f [fitxer]` | Si es dóna a una cadena `fitxer` como a segon argument, redirigeix la sortida al fitxer de registre `fitxer.log`.
`max-markup-depth` | `1024` | Profunditat màxima de l’arbre de l’etiquetatge. Si un etiquetatge té més nivells, suposa que no acabarà per sí mateix, imprimint un advertiment i retornant en el seu lloc un element d’etiquetatge nul.
`midi-extension` | `"midi"` | Fixa l’extensió de fitxer predeterminat per al fitxer de sortida MIDI a la cadena donada.
`music-strings-to-paths` | `#f` | Converteix les cadenes de text a rutes quan els glifs pertanyen a un tipus de lletra de tipografia musical.
`paper-size` | `\"a4\"` | Estableix la mida predeterminada del paper. Observeu que la cadena ha d’anar tancada entre cometes dobles.
`pixmap-format` | `png16m` | Fixa el format de sortida del Ghostsript per a les imatges de píxels.
`point-and-click` | `#f` | Afegeix enllaços d’‘apuntar i clicar’ a la sortida `PDF`. Vegeu Point and click.
`preview` | `#f` | Crea imatges de vista prèvia a més de la sortida normal.

Aquesta opció està contemplada per tots els ‘rerefons’: `pdf`, `png`, `ps`, `eps` i `svg`, però no per `scm`. Genera un fitxer de sortida, en la forma `elmeuFitxer.preview.extensió`, que conté els títols i el primer sistema de la música. Si s’estan utilitzant blocs `\book` o `\bookpart`, apareixen a la sortida els títols de `\book`, `\bookpart` o `\score`, inclòs el primer sistema de cada bloc `\score` si la variable de `\paper` `print-all-headers` està fixada al valor `#t`.

Per suprimir la sortida actual, utilitzeu les opcions ‘`-dprint-pages`’ o ‘`-dno-print-pages`’ segons les vostres necessitats.

`print-pages` | `#t` | Genera pàgines completes (és l’opció predeterminada). És útil ‘`-dno-print-pages`’ en combinació amb ‘`-dpreview`’.
`protected-scheme-parsing` | `#t` | Continua quan es capten a l’analitzador sintàctic errors del Scheme encastat. Si es fixa a `#f`, detenir-se quan hi hagi errors i imprimir un registre de traça de pila.
`relative-includes` | `#f` | Quan es processa una instrucció `\include`, cerca el fitxer inclòs de forma relativa al fitxer actual (enlloc del fitxer principal).
`resolution` | `101` | Fixa la resolució per generar imatges de píxels `PNG` al valor donat (en ppp).
`safe` | `#f` | No confiïs en l’entrada `.ly`.

Quan el servei de tipografia està disponible a través d’un servidor web, S’HAN DE passar les opcions ‘`--safe`’ o ‘`--jail`’. L’opció ‘`--safe`’ evita que el codi del Scheme faci un desastre, per exemple:

>     #(system "rm -rf /")
>     {
>       c4^$(ly:gulp-file "/etc/passwd")
>     }

L’opció ‘`-dsafe`’ funciona avaluant les expressions del Scheme en línia dins d’un mòdul segur especial. Deriva del mòdul ‘`safe-r5rs`’ del GUILE, però a més afegeix unes quantes funcions de l’API del LilyPond que estan relacionades en ‘`scm/safe-lily.scm`’.

A més, el mode segur prohibeix les directives `\include` i desactiva la utilització de barres invertides a les cadene de TeX. A més, no és possible importar variables del LilyPond dins del Scheme quan s’està em mode segur.

‘`-dsafe`’ no detecta la sobreutilitizació de recursos, per la qual cosa encara és possible fer que el programa es pengi indefinidament, per exemple subministrant estructures de dades cícliques en el rerefons. Per això, si esteu usant el LilyPond en un servidor web accessible públicament, el procés s’ha de limitar tant en l’ús de memòria com de CPU.

El mode segur evita que es puguin compilar molts fragments de codi útils.

L’opció ‘`--jail`’ és una alternativa encara més segura, però requereix més feina per a la seva configuració. Vegeu Opcions bàsiques de la línia d’ordres per al LilyPond.

`separate-log-files` | `#f` | Per als fitxers d’entrada `FITXER1.ly`, `FITXER2.ly`, etc., treu les dades de registre cap als fitxers `FITXER1.log`, `FITXER2.log`…
`show-available-fonts` | `#f` | Llista tots els noms dels tipus tipogràfics de lletra disponibles.
`strip-output-dir` | `#t` | No usis els directoris dels fitxers d’entrada en construir els noms dels fitxers de sortida.
`strokeadjust` | `#f` | Força l’ajust dels traços de PostScript. Aquesta opció és rellevant principalment quan es genera un `PDF` a partir de la sortida de PostScript (l’ajust del traç està en general activat automàticament per a dispositius de mapa de punts de baixa resolució). Sense aquesta opció, els visors de `PDF` tendeixen a produir amplades de plica molt poc consistents a les resolucions típiques de les pantalles d’ordinador. L’opció no afecta de forma molt significativa a la qualitat de la impressió i causa grans increments a la mida del fitxer `PDF`.
`svg-woff` | `#f` | Usar fitxers de tipus tipogràfic de lletra de woff al rerefons SVG.
`verbose` | `#f` | Sortida detallada, és a dir el nivell de registre en DEBUT (sols lectura).
`warning-as-error` | `#f` | Canvia tots els missatges d’advertiment i de ‘error de programació’ a errors.

### Variables d’entorn

`lilypond` reconeix les següents variables d’entorn:

`LILYPOND_DATADIR`

  Especifica un directori en el qual els missatges de localització i de dades es buscaran de forma predeterminada. El directori ha de contenir subdirectoris anomenats ‘`ly/`’, ‘`ps/`’, ‘`tex/`’, etc.

`LANG`

  Selecciona l’idioma dels missatges d’advertiment.

`LILYPOND_LOGLEVEL`

  Nivell de registre predeterminat. Si el LilyPond es crida sense cap nivell de registre explícit (és a dir, sense opció de línia d’ordres ‘`--loglevel`’), s’usa aquest valor.

`LILYPOND_GC_YIELD`

  Una variable, com a percentatge, que ajusta el comportament de l’administració de memòria. Amb valors més alts, el programa usa més memòria; amb valors més baixos, usa més temps de CPU. El valor predeterminat és `70`.

### El LilyPond a una gàbia de chroot

La preparació del servidor perquè executi el LilyPond a una gàbia de chroot és una tasca molt complicada. Els passos estan relacionats més avall. Els exemples que apareixen en cadascú dels passos son vàlids per a Ubuntu GNU/Linux, i poden requerir l’ús de `sudo` segons correspongui.

- Instal·leu els paquets necessaris: el LilyPond, el Ghostscript i l’ImageMagick.
- Creeu un usuari nou amb el nom de `lily`:

  >     adduser lily

  Això també crearà un nou grup per a l’usuari `lily`, i una carpeta personal, `/home/lily`

- A la carpeta personal de l’usuari `lily`, creeu un fitxer per usar-lo com a sistema de fitxers separat:

  >     dd if=/dev/zero of=/home/lily/loopfile bs=1k count= 200000

  Aquest exemple crea un fitxer de 200MB per al seu ús com el sistema de fitxers de la gàbia.

- Creeu un dispositiu loop, feu un sistema de fitxers i munteu-lo, després creeu una carpeta que es pugui escriure per l’usuari `lily`:

  >     mkdir /mnt/lilyloop
  >     losetup /dev/loop0 /home/lily/loopfile
  >     mkfs -t ext3 /dev/loop0 200000
  >     mount -t ext3 /dev/loop0 /mnt/lilyloop
  >     mkdir /mnt/lilyloop/lilyhome
  >     chown lily /mnt/lilyloop/lilyhome

- En la configuració dels servidors, JAIL serà `/mnt/lilyloop` i DIR serà `/lilyhome`.
- Creeu un gran arbre de directoris dins de la gàbia copiant els fitxers necessaris, com es mostra en el guió d’exemple que apareix més avall.

  Podeu usar `sed` per crear els fitxeres de còpia necessaris per a un executable donat:

  >     for i in "/usr/local/lilypond/usr/bin/lilypond" "/bin/sh" "/usr/bin/;  \
  >       do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\&  \
  >         cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p  \
  >           \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done

### Guió d’exemple per a l’Ubuntu 8.04 de 32 bits

>     #!/bin/sh
>     ## aquí es fixen els valors predeterminats

>     username=lily
>     home=/home
>     loopdevice=/dev/loop0
>     jaildir=/mnt/lilyloop
>     # prefix (sense la barra inicial!)
>     lilyprefix=usr/local
>     # el directori en el qual el LilyPond es troba instal·lat en el sistema
>     lilydir=/$lilyprefix/lilypond/

>     userhome=$home/$username
>     loopfile=$userhome/loopfile
>     adduser $username
>     dd if=/dev/zero of=$loopfile bs=1k count=200000
>     mkdir $jaildir
>     losetup $loopdevice $loopfile
>     mkfs -t ext3 $loopdevice 200000
>     mount -t ext3 $loopdevice $jaildir
>     mkdir $jaildir/lilyhome
>     chown $username $jaildir/lilyhome
>     cd $jaildir

>     mkdir -p bin usr/bin usr/share usr/lib usr/share/fonts $lilyprefix tmp
>     chmod a+w tmp

>     cp -r -L $lilydir $lilyprefix
>     cp -L /bin/sh /bin/rm bin
>     cp -L /usr/bin/convert /usr/bin/gs usr/bin
>     cp -L /usr/share/fonts/truetype usr/share/fonts

>     # Ara la màgia de copiar les biblioteques
>     for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh"  \
>       "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=>  \
>         \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed  \
>           's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/'  \
>             | sed '/.*=>.*/d'; done | sh -s

>     # Els fitxers compartits per al ghostcript...
>           cp -L -r /usr/share/ghostscript usr/share
>     # Els fitxers compartits per a l'ImageMagick
>           cp -L -r /usr/lib/ImageMagick* usr/lib

>     ### Ara, suposant que tenim test.ly a /mnt/lilyloop/lilyhome,
>     ### hauríem de poder executar:
>     ### Observeu que /$lilyprefix/bin/lilypond és un guió, que estableix
>     ### un valor per a LD_LIBRARY_PATH : això és crucial
>           /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly

### Notes a peu de pàgina

[1] L’estat del GUILE no es restableix després de processar un fitxer `.ly`, per la qual cosa heu de tenir cura de no modificar cap valor predeterminat des de dins del Scheme.

#### LilyPond — Utilització v2.24.4 (branca estable).