Manual de usuario de calibre

Transcripción

1 Manual de usuario de calibre Publicación Kovid Goyal June 19, 2015

2

3 Índice general 1. Secciones La interfaz gráfica de usuario Añadir su sitio de noticias favorito El visor de libros electrónicos Conversión de libros Modificar libros electrónicos Comparar libros electrónicos Modificar metadatos de libros electrónicos Preguntas frecuentes Cursillos Personalizar calibre Interfaz de línea de órdenes Configurar un entorno de desarrollo de calibre Glosario Índice de Módulos Python 361 Índice 363 I

4 II

5 calibre es un gestor de biblioteca de libros electrónicos. Con calibre puede leer, convertir y catalogar libros electrónicos en la mayoría de los principales formatos. También puede comunicarse con muchos dispositivos de lectura de libros electrónicos. Puede obtener metadatos para los libros de Internet. Puede descargar periódicos y convertirlos en libros electrónicos para una lectura más cómoda. Es multiplataforma, funciona en Linux, Windows y OS X. Acaba de iniciar calibre. Y ahora qué? Antes de que calibre pueda hacer nada con sus libros electrónicos, tiene que saber de ellos. Arrastre y suelte algunos archivos de libro electrónico en calibre o pulse el botón «Añadir libros» y seleccione los libros con los que quiere trabajar. Una vez que haya añadido los libros, aparecerán en la ventana principal de manera parecida a ésta: Cuando haya admirado la lista de los libros que acaba de añadir durante un tiempo suficiente, probablemente quiera leer alguno. Para ello tendrá que convertir el libro a un formato que su lector entienda. La primera vez que ejecute calibre, el Asistente de bienvenida se iniciará y configurará calibre para su dispositivo lector. La conversión es muy sencilla, no tiene más que seleccionar el libro que quiere convertir y pulsar el botón «Convertir libros». Ignore todas las opciones por ahora y pulse «Aceptar». El pequeño icono en la esquina inferior derecha empezará a girar. Cuando deje de girar, el libro convertido está listo. Pulse el botón «Mostrar» para leer el libro. Si quiere leer el libro en el lector, conéctelo al equipo, espere a que calibre lo detecte (10-20 segundos) y pulse el botón «Enviar al dispositivo». Cuando el icono deje de girar de nuevo, desconecte el lector y ya puede leer! Si no convirtió el libro en el paso anterior, calibre lo convertirá automáticamente al formato que necesite el dispositivo lector. Para iniciarse en un uso más avanzado, debería leer sobre La interfaz gráfica de usuario (Página 3). Si quiere aún más potencia y versatilidad, aprenda generated/en/cli-index. También puede encontrar útil la lista de Preguntas frecuentes (Página 102). Índice general 1

6 2 Índice general

7 CAPÍTULO 1 Secciones 1.1 La interfaz gráfica de usuario La interfaz gráfica de usuario (GUI) da acceso a todas las funciones de gestión de biblioteca y conversión de formatos de libro electrónico. El proceso básico para usar calibre comienza añadiendo libros a la biblioteca desde el disco duro. calibre intentará leer automáticamente los metadatos de los libros y los añadirá a la base de datos interna. Una vez que están en la base de datos, puede realizar distintas Acciones (Página 3) sobre ellos, incluidas la conversión de un formato a otro, la transferecencia a un dispositivo de lectura, la visualización en el equipo y la modificación de metadatos. Esta última acción incluye la modificación de la portada, descripción y etiquetas entre otros detalles. Tenga en cuenta que calibre crea copias de los archivos que añada. Los archivos originales no se alteran. La interfaz se divide en varias secciones: Acciones (Página 3) Preferencias (Página 10) Catálogos (Página 10) Buscar y ordenar (Página 11) La interfaz de búsqueda (Página 11) Guardar búsquedas (Página 14) Bibliotecas virtuales (Página 14) Extraer metadata de los nombres de archivo (Página 14) Detalles del libro (Página 15) Explorador de etiquetas (Página 16) Cuadro de portadas (Página 18) Explorador de portadas (Página 19) Vista rápida (Página 19) Tareas (Página 20) Atajos de teclado (Página 20) Acciones La barra de herramientas de acciones ofrece un acceso inmediato a algunas acciones usuales. Si pulsa con el botón derecho sobre los botones puede realizar variaciones de la acción predeterminada. Tenga en cuenta que la barra de 3

8 herramientas de acciones puede tener un aspecto distinto dependiendo de si hay algún dispositivo de lectura conectado al equipo. Añadir libros (Página 4) Editar metadatos (Página 5) Convertir libros (Página 5) Mostrar (Página 6) Enviar al dispositivo (Página 6) Descargar noticias (Página 7) Biblioteca (Página 7) Dispositivo (Página 8) Guardar en el disco (Página 8) Conectar y compartir (Página 9) Eliminar libros (Página 9) Añadir libros La acción Añadir libros tiene siete variantes accesibles pulsando con el botón derecho sobre el botón. 1. Añadir libros desde un único directorio: Abre un diálogo de selección de archivo y le permite especificar qué libros de un directorio añadir. Esta acción es sensible al contexto, es decir, depende de qué catálogo (Página 10) esté seleccionado. Si está seleccionada la Biblioteca, los libros se añadirán a la biblioteca. Si está seleccionado el dispositivo de lectura, los libros se copiarán al dispositivo, etc. 2. Añadir libros de directorios, incluyendo subdirectorios. (Un libro por directorio, se asume que cada archivo de libro electrónico es el mismo libro en un formato diferente): Le permite elegir un directorio. Se buscará en el directorio y todos sus subdirectorios de manera recursiva y todos los libros que se encuentren se añadirán a la biblioteca. calibre asume que cada directorio contiene un único libro y que todos los archivos de libro en el directorio corresponden al mismo libro en distintos formatos. Esta acción es la inversa de la acción Guardar en el disco (Página 8), es decir, puede Guardar en el disco, eliminar los libros y volver a añadirlos sin pérdida de información excepto por la fecha (suponiendo que no haya modificado ninguna configuración de la acción Guardar en el disco). 3. Añadir libros de directorios, incluyendo subdirectorios. (Múltiples libros por directorio, se asume que cada archivo de libro electrónico es un libro diferente): Le permite elegir un directorio donde se buscará recursivamente, incluyendo todos sus subdirectorios, y todos los libros electrónicos encontrados se añadirán a la biblioteca. calibre asume que cada directorio contiene varios libros. Se supone que todos los archivos de libro electrónico con el mismo nombre en un directorio corresponden al mismo libro en distinto formato. Los archivos con nombres distintos se añadirán como libros distintos. 4. Añadir varios libros desde un archivo (ZIP/RAR): Le permite añadir múltiples libros que estén almacenados en los archivos ZIP o RAR seleccionados. Es una vía rápida para evitar tener que descomprimir los archivos primero y luego añadir los libros con alguna de las dos opciones anteriores. 5. Añadir libro en blanco. (Entrada de libro sin ningún formato): Le permite añadir un registro de libro en blanco. Esto se puede usar para después rellenar manualmente la información de un libro que quizá aún no tenga en la colección. 6. Añadir a partir del ISBN: Le permite añadir uno o más libros introduciendo sus ISBN. 4 Capítulo 1. Secciones

9 7. Añadir archivos a los registros de libros seleccionados: Le permite añadir o actualizar los archivos asociados con un libro existente en la biblioteca. La acción Añadir libros puede leer metadatos de una amplia variedad de formatos de libro electrónico. Además, intenta extraer metadatos a partir del nombre de archivo. Vea la sección Extraer metadata de los nombres de archivo (Página 14) para saber cómo configurar esto. Para añadir un formato adicional a un libro existente, puede hacer cualquiera de estas tres cosas: 1. Arrastrar y soltar un archivo en el panel de detalles del libro, en la parte derecha de la ventana principal. 2. Pulse con el botón derecho sobre Añadir libros y elija Añadir archivos a los registros de libros seleccionados. 3. Pulsar sobr el botón rojo para añadir libros en la parte superior derecha del diálogo Modificar metadatos, accesible mediante la acción Editar metadatos (Página 5). Editar metadatos La acción Modificar metadatos tiene cuatro variantes accesibles pulsando con el botón derecho sobre el botón de la acción. 1. Modificar metadatos por separado: Le permite modificar los metadatos de los libros uno a uno, con la opción de obtener los metadatos, incluidas las portadas, de Internet. También le permite añadir o eliminar formatos específicos de un libro. 2. Modificar metadatos en masa: Le permite modificar campos de metadatos comunes a un gran número de libros simultáneamente. La operación se realiza sobre todos los libros que estén seleccionados en la Vista de biblioteca (Página 11). 3. Descargar metadatos y portadas: Descarga metadatos y portadas (si están disponibles) para los libros seleccionados en la lista de libros. 4. Unir registros de libros: Le ofrece la posibilidad de unir los metadatos y formatos de dos o más registros de libros. Puede elegir borrar o mantener los registros distintos del primero seleccionado. Para más detalles vea Modificar metadatos de libros electrónicos (Página 99). Convertir libros Los libros electrónicos pueden convertirse de una variedad de formatos al formato que su lector de libros electrónicos prefiera. Muchos libros electrónicos a la venta estarán protegidos por tecnología de gestión digital de derechos 1 (DRM). calibre no convertirá estos libros. Es sencillo eliminar la DRM de muchos formatos, pero como esto puede ser ilegal, es su responsabilidad encontrar las herramientas para liberar sus libros y luego usar calibre para convertirlos. Para la mayoría de los usuarios, la conversión es cuestión de una sola pulsación. Si quiere saber más sobre el proceso de conversión, vea Conversión de libros (Página 53). La acción Convertir libros tiene tres variantes accesibles pulsando con el botón derecho sobre el botón de la acción La interfaz gráfica de usuario 5

10 1. Convertir por separado: Le permite especificar opciones de conversión para personalizarla conversión de cada libro seleccionado. 2. Convertir en masa: Le permite especificar opciones una sola vez y convertir un número de libros en masa. 3. Crear un catálogo de los libros en la biblioteca de calibre: Le permite generar un listado completo de los libros en la biblioteca, incluyendo todos los metadatos, en formatos como XML, CSV, BiBTeX, EPUB y MOBI. El catálogo contendrá todos los libros que se muestren actualmente en la vista de biblioteca. Esto le permite usar las funciones de búsqueda para limitar los libros catalogados. Además, si selecciona varios libros con el ratón, sólo se incluirán esos libros. Si genera el catálogo en un formato de libro electrónico como EPUB, MOBI o AZW3, la próxima vez que conecte un dispositivo de lectura el catálogo se enviará automáticamente al dispositivo. Para más información sobre cómo funcionan los catálogos, lea Crear catálogos AZW3 EPUB MOBI Catalogs (Página 229). Mostrar La acción Mostrar abre el libro en un programa visualizador de libros electrónicos. calibre tiene un visor incorporado para muchos formatos de libro electrónico. Para otros formatos usa la aplicación predeterminada del sistema operativo. Puede configurar qué formatos se abren con el visor interno en Preferencias > Comportamiento. Si un libro tiene más de un formato, puede abrir un formato específico pulsando con el botón derecho sobre el botón de la acción. Enviar al dispositivo La acción Enviar al dispositivo tiene ocho variantes accesibles pulsando con el botón derecho sobre el botón de la acción. 1. Enviar a la memoria principal: Los libros seleccionados se copian en la memoria principal del dispositivo de lectura. 2. Enviar a la tarjeta de memoria A: Los libros seleccionados se copian a la tarjeta de memoria (A) en el dispositivo de lectura. 3. Enviar a la tarjeta de memoria B: Los libros seleccionados se copian a la tarjeta de memoria (B) en el dispositivo de lectura. 4. Enviar formato específico a: Los libros seleccionados se copian al lugar de almacenamiento seleccionado en el dispositivo, en el formato que especifique. 5. Desconectar dispositivo. Desconecta el dispositivo de calibre. 6. Asignar acción predeterminada de enviar al dispositivo: Le permite especificar cuál de las acciones (1 a 5, o 7) será la acción predeterminada cuando se pulsa el botón principal. 7. Enviar y eliminar de la biblioteca: Los libros seleccionados se copian al lugar de almacenamiento seleccionado en el dispositivo y despues se borran de la biblioteca. 8. Obtener anotaciones (experimental): Copia las anotaciones que pueda haber en un libro del dispositivo al campo de comentarios en los metadatos del libro en la biblioteca de calibre. 6 Capítulo 1. Secciones

11 Puede controlar el nombre de archivo y la estructura de carpetas de los archivos que se envían al dispositivo estableciendo una plantilla en Preferencias > Importar y exportar > Enviar libros a dispositivos. Véase también El lenguaje de plantillas de calibre (Página 159). Descargar noticias La acción:obtener noticias descarga noticias de distintos sitios web y las convierte en un libro electrónico que pued leer en un dispositivo de lectura. Normalmente, el libro electrónico creado se añade a la biblioteca, pero si tiene un dispositivo conectado cuando termina la descarga, el libro también se copia al lector automáticamente. La acción Obtener noticias usa fórmulas simples (10-15 líneas de código) por cada sitio de noticias. Para saber cómo crear fórmulas para sus fuentes de noticias preferidas, vea Añadir su sitio de noticias favorito (Página 124). La acción Obtener noticias tiene tres variantes accesibles pulsando con el botón derecho sobre el botón de la acción. 1. Planificar descarga de noticias: Le permite planificar la descarga de las fuentes de noticias seleccionadas de los cientos disponibles. La planificación puede establecerse de manera individual para cada fuente de noticias seleccionada y permite seleccionar días de la semana específicos o un número de días de intervalo entre descargas. 2. Añadir una nueva fuente de noticias: Le permite crear una fórmula simple para descargar noticias de un sitio de noticias personalizado al que quiera acceder. Crear una fórmula puede ser tan simple como especificar la dirección URL de un canal RSS, o puede ser más detallado, creando un código basado en python para la tarea. Para más información véase Añadir su sitio de noticias favorito (Página 124). 3. Descargar todas las fuentes de noticias planificadas: Hace que calibre empiece inmediatamente a descargar todas las fuentes de noticias que tenga planificadas. Biblioteca La acción Biblioteca le permite crear, eliminar o cambiar el nombre a una biblioteca, o cambiar de una biblioteca a otra. calibre le permite crear tantas bibliotecas como desee. Puede, por ejemplo, crear una biblioteca de ficción, una de no ficción, una de idiomas extranjeros, una de proyectos, o cualquier estructura que le convenga. Las bibliotecas son la estructura de organización de mayor nivel dentro de calibre. Cada biblioteca tiene su propio conjunto de etiquetas, categorías y ubicación de almacenamiento base. 1. Cambiar o crear biblioteca...: Le permite: a) conectar con una biblioteca de calibre existente en otra ubicación, b) crear una biblioteca vacía en una nueva ubicación o c) mover la biblioteca actual a una nueva ubicación. 2. Cambio rápido: Le permite cambiar de una biblioteca a otra si han sido registradas o creadas con calibre. 3. Cambiar el nombre a la biblioteca: Le permite cambiar el nombre a una biblioteca. 4. Eliminar biblioteca: Le permite dar de baja una biblioteca en calibre. 5. <nombre de biblioteca>: Las acciones 5, 6, etc. le dan acceso inmediato a las bibliotecas que haya creado o registrado. Esta lista contiene sólo las 5 bibliotecas más usadas. Para tener la lista completa, use el menú Cambio rápido La interfaz gráfica de usuario 7

12 6. Mantenimiento de la biblioteca: Le permite comprobar la coherencia de los datos en la biblioteca actual, detectar problemas y restaurar la base de datos de la biblioteca a partir de copias de respaldo. Nota: Los metadatos de los libros, como el título, autor y etiquetas, se almacenan en un único archivo en la carpeta de la biblioteca de calibre, llamado metadata.db. Si este archivo se corrompe (un suceso muy infrecuente) pueden perderse los metadatos. Por suerte, calibre copia automáticamente los metadatos de cada libro en su correspondiente carpeta como un archivo OPF. Mediante la acción Restaurar base de datos bajo Mantenimiento de la biblioteca, descrita anteriormente, puede hacer que calibre reconstruya el archivo metadata.db a partir de los archivos OPF individuales. Puede copiar o mover libros entre diferentes bibliotecas (una vez que haya configurado más de una biblioteca) pulsando con el botón derecho sobre un libro y seleccionando la acción Copiar a biblioteca. Dispositivo La acción Dispositivo le permite ver los libros en la memoria principal o en las tarjetas de almacenamiento de un dispositivo o desconectarlo de calibre. Este icono aparece automáticamente en la barra de herramientas principal de calibre cuando se conecta un dispositivo soportado. Puede pulsar sobre él para ver los libros en el dispositivo. También puede arrastrar y soltar libros de la biblioteca de calibre sobre el icono para copiarlos al dispositivo. Análogamente, puede arrastrar y soltar libros del dispositivo sobre el icono de la biblioteca en la barra de herramientas para copiarlos del dispositivo a la biblioteca de calibre. Guardar en el disco La acción Guardar en el disco tiene cinco variantes, accesibles pulsando con el botón derecho sobre el botón de la acción. 1. Guardar en el disco: Guarda los libros seleccionados en el disco, organizados por directorios. La estructura de directorios es algo así: Author_(sort) Title Book Files Puede controlar el nombre de archivo y la estructura de carpetas de los libros guardados en el disco estableciendo una plantilla en Preferencias > Importar y exportar > Guardar libros en disco. Véase también El lenguaje de plantillas de calibre (Página 159). 2. Guardar en el disco, en un único directorio: Guarda los libros seleccionados en el disco, en un único directorio. Con las opciones 1 y 2 se guardan en el disco todos los formatos, incluidos los metadatos, de cada libro seleccionado. Los metadatos se almacenan en un archivo OPF. Los libros guardados pueden volver a ser importados a la biblioteca sin pérdida de información usando la acción Añadir libros (Página 4). 3. Guardar solamente el formato *<principal>* en disco: Guarda los libros seleccionados en el disco con la estructura de directorios mostrada en (1), pero sólo en el formato principal. Puede establecer el formato preferido en Preferencias > Comportamiento > Formato de salida principal. 8 Capítulo 1. Secciones

13 4. Guardar sólo el formato *<principal>* en un único directorio: Guarda los libros seleccionados en el disco, en un único directorio, pero sólo en el formato principal. 5. Guardar un solo formato en disco...: Guarda los libros seleccionados en el disco con la estructura de directorios mostrada en (1), pero sólo en el formato que seleccione en la lista emergente. Conectar y compartir La acción Conectar y compartir le permite conectar manualmente con un dispositivo o carpeta en el equipo. También le permite configurar la biblioteca de calibre para que pueda accederse a través de un navegador web o por correo electrónico. La acción Conectar y compartir tiene cuatro variantes accesibles pulsando con el botón derecho sobre el botón de la acción. 1. Conectar a carpeta: Le permite conectar con cualquier carpeta en el equipo como si fuera un dispositivo y usar las funciones que calibre ofrece para los dispositivos con esa carpeta. Esto es útil si tiene un dispositivo que no está soportado por calibre pero que está disponible como un disco USB. 2. Conectar a itunes: Le permite conectar con la base de datos de itunes como si fuera un dispositivo. Una vez que los libros se han enviado a itunes, puede usar itunes para copiarlos en los dispositivos de Apple. 3. Iniciar servidor de contenidos: Inicia el servidor web incorporado en calibre. Cuando se ha iniciado, la biblioteca de calibre será accesible mediante un navegador web a través de Internet (si quiere que así sea). Puede configurar cómo se accede al servidor web en Preferencias > Compartir > Compartir por la red. 4. Configurar el intercambio de libros por correo electrónico: Le permite compartir libros y canales de noticias por correo electrónico. Después de configurar las direcciones de correo para esta opción, calibre enviará actualizaciones de noticias y de libros a las direcciones suministradas. Puede configurar cómo se envían los correos electrónicos en Preferencias > Compartir > Compartir libros por correo electrónico. Una vez que haya configurado una o varias direcciones de correo, esta entrada del menú se sustituirá por entradas para enviar libros a las direcciones configuradas. Eliminar libros La acción Eliminar libros elimina libros permanentemente, así que úsela con cuidado. Es sensible al contexto, es decir, su comportamiento depende de qué catálogo (Página 10) tenga seleccionado. Si tiene seleccionada la Biblioteca, los libros se eliminarán de la biblioteca. Si tiene seleccionado el dispositivo de lectura, los libros se eliminarán del dispositivo. Para eliminar un formato específico de un libro use la acción Editar metadatos (Página 5). Eliminar libros también tiene seis variantes accesibles pulsando con el botón derecho sobre el menú de la acción. 1. Eliminar libros seleccionados: Le permite eliminar permanentemente todos los libros seleccionados en la lista de libros 2. Eliminar archivos de un formato específico de los libros seleccionados...: Le permite eliminar permanentemente archivos de un formato determinado de los libros seleccionados en la lista de libros La interfaz gráfica de usuario 9

14 3. Eliminar todos los formatos de los libros seleccionados, excepto...: Le permite eliminar permanentemente los archivos de libro de cualquier formato excepto el especificado de los libros seleccionados en la lista de libros. 4. Eliminar todos los formatos de los libros seleccionados: Le permite eliminar permanentemente todos los archivos de libro de los libros seleccionados en la lista de libros. Sólo quedarán los metadatos. 5. Eliminar portadas de los libros seleccionados: Le permite eliminar permanentemente los archivos de imagen de portada de los libros seleccionados en la lista de libros. 6. Eliminar los libros correspondientes del dispositivo: Le permite eliminar de un dispositivo conectado los archivos de libro que correspondan a los libros seleccionados en la lista de libros. Nota: Tenga en cuenta que al usar Eliminar libros para eliminar libros de la biblioteca de calibre, el registro del libro se borra permanentemente, pero en Windows y OS X los archivos se mueven a la papelera de reciclaje. Esto le permite recuperarlos si cambia de opinión Preferencias La acción Preferencias le permite cambiar la manera en que funcionan distintos aspectos de calibre. Tiene cuatro variantes accesibles pulsando con el botón derecho sobre el botón de la acción. 1. Preferencias: Le permite cambiar la manera en que funcionan los distintos aspectos de calibre. Esta acción también se activa simplemente pulsando sobre el botón. 2. Ejecutar el asistente de bienvenida: Le permite iniciar el asistente de bienvenida, que apareció la primera vez que se ejectuó calibre. 3. Obtener complementos para mejorar calibre: Abre una nueva ventana que muestra complementos para calibre. Estos complementos están desarrollados por terceros para extender las funciones de calibre. 4. Reiniciar en el modo de depuración: Le permite activar un modo de depuración, que puede ayudar a los desarrolladores de calibre a resolver los problemas que pueda encontrar con el programa. Para la mayoría de los usuarios esta opción debe permanecer desactivada, a menos que un desarrollador le indique que la active Catálogos Un catálogo es una colección de libros. calibre puede gestionar dos tipos diferences de catálogos: 1. Biblioteca: Es una colección de libros almacenados en la biblioteca de calibre en el equipo. 2. Dispositivo: Es una colección de libros almacenados en un dispositivo de lectura. Estará disponible cuando conecte el dispositivo al equipo. Muchas operaciones, como añadir o eliminar libros, visualizarlos, etc., son sensibles al contexto. Así, por ejemplo, si pulsa el botón Mostrar cuando tiene el catálogo Dipositivo seleccionado, calibre abrirá los archivos en el dispositivo para mostrarlos. Si tiene el catálogo Biblioteca seleccionado, se abrirán los archivos en la biblioteca de calibre. 10 Capítulo 1. Secciones

15 1.1.4 Buscar y ordenar La sección de búsqueda y ordenación le permite realizar varias acciones muy útiles sobre las colecciones de libros. Puede ordenarlas por título, autor, fecha, calificación, etc. pulsando sobre los títulos de las columnas. También puede ordenar por varias columnas (ordenación secundaria). Por ejemplo, si pulsa sobre la columna título y luego sobre la columna autor, los libros se ordenarán por autor y todas las entradas del mismo autor estarán ordenadas por título. Puede buscar un libro determinado o un conjunto de libros usando la barra de búsqueda. Más adelante hay más información sobre búsquedas. Puede modificar metadatos de manera rápida y cómoda pulsando dos veces sobre la entrada que quiere modificar en la lista. Puede realizar Acciones (Página 3) sobre conjuntos de libros. Para seleccionar varios libros tiene varias opciones: Mantener pulsada la tecla Ctrl y pulsar sobre los libros que quiera seleccionar. Mantener pulsada la tecla Mayús y pulsar sobre el primer y último libro de un grupo que quiera seleccionar. Puede configurar qué campos se muestran usando el diálogo Preferencias (Página 10) La interfaz de búsqueda Puede buscar en todos los metadatos introduciendo los términos de búsqueda en la barra de búsqueda. Las búsquedas no distinguen entre mayúsculas y minúsculas. Por ejemplo: Asimov Foundation format:lrf Esto encontrará todos los libros en la biblioteca que tengan «Asimov» y «Foundation» en los metadatos y que estén disponibles en formato LRF. Otros ejemplos: author:asimov and not series:foundation title:"the Ring" or "This book is about a ring" format:epub publisher:feedbooks.com 1.1. La interfaz gráfica de usuario 11

16 De manera predeterminada las búsquedas son de tipo «contiene». Un elemento coincide si el texto de búsqueda aparece en cualquier lugar en los metadatos indicados. Hay otros dos tipos de búsqueda disponibles: búsquedas de igualdad y búsquedas usando expresiones regulares 2. Las búsquedas de igualdad se indican precediendo el texto de búsqueda con el signo igual (=). Por ejemplo, la búsqueda tag:"=ciencia" encontrará «ciencia» pero no «ciencia ficción» o «historia de la ciencia». Las búsquedas por expresión regular se indican precediendo el texto de búsqueda con una tilde (~). Puede usarse cualquier expresión regular compatible con python 3. Tenga en cuenta que las barras invertidas usadas para incluir caracteres especiales en las expresiones regulares deben duplicarse, porque las barras invertidas aisladas se eliminan al procesar las búsquedas. Por ejemplo, para encontrar un paréntesis literal debe introducir \\(. Las búsquedas con expresiones regulares son de tipo «contiene» a no ser que la expresión contenga puntos de anclaje. En caso de que necesite buscar un texto que empiece por un signo igual o una tilde, incluya una barra invertida al principio. Escriba los textos de búsqueda entre comillas ( ) si el texto contiene paréntesis o espacios. Por ejemplo, para buscar la etiqueta Ciencia ficción deberá escribir tag:"=ciencia ficción". Si escribe tag:=ciencia ficción encontrará todos los libros con la etiqueta «ciencia» y que contengan la palabra «ficción» en cualquier metadato. Puede construir búsquedas avanzadas de manera sencilla usando el diálogo de Búsqueda avanzada, al que se accede pulsando el botón. Los campos disponibles para búsquedas son: tag, title, author, publisher, series, series_index, rating, cover, comments, format, identifiers, date, pubdate, search, size y las columnas personalizadas. Si está conectado algún dispositivo, el campo ondevice está también disponible para buscar en la vista de biblioteca de calibre. Para conocer el nombre de búsqueda de una columna personalizada, ponga el cursor del ratón sobre el encabezado de la columna en la vista de biblioteca. La sintaxis para buscar fechas es: pubdate:> Will find all books published after Jan, 2000 date:<= Will find all books added to calibre before 3 Jan, 2000 pubdate:=2009 Will find all books published in 2009 Si la fecha es ambigua, la configuración local actual se usa para la comparación de fechas. Por ejemplo, con una configuración mm/dd/yyyy, 2/1/2009 se interpreta como 1 Feb 2009; con una configuración dd/mm/yyyy, se interpreta como 2 Ene Hay algunas palabras especiales disponibles. El texto hoy significa la fecha de hoy, sea la que sea. Los textos ayer y estemes (o sus equivalentes traducidos al idioma actual) también funcionan. Además, el texto díasatrás (también traducido) puede usarse para indicar una fecha de hace un cierto número de días. Por ejemplo: date:>10daysago date:<=45daysago Para evitar problemas potenciales con textos traducidos al usar versiones de calibre en idiomas distintos del inglés, los textos _today, _yesterday, _thismonth y _daysago están siempre disponibles. No están traducidos. Puede buscar libros que tengan un formato de cierto tamaño de esta manera: size:>1.1m Will find books with a format larger than 1.1MB size:<=1k Will find books with a format smaller than 1KB Los campos numéricos y de fecha permiten usar los operadores de relación = (igual), > (mayor), >= (mayor o igual), < (menor), <= (menor o igual) y!= (distinto). Los campos de calificación se consideran numéricos. Por ejemplo, la búsqueda rating:>=3 encontrará todos los libros con una calificación de 3 o más. Puede realizar una búsqueda por el número de elementos en campos de valor múltiple, como las etiquetas. Estas búsquedas empiezan por el carácter #, y después se usa la misma sintaxis que en los campos numéricos. Por ejemplo, 2 %C3 %B3n_regular Capítulo 1. Secciones

17 para buscar todos los libros con más de cuatro etiquetas, use tags:#>4. Para buscar todos los libros con exactamente diez etiquetas, use tags:#=10. Los números de serie se pueden buscar. Para las series normales, el nombre de búsqueda es «series_index». Para columnas personalizadas de serie, use el nombre de búsqueda de la columna seguido de «_index». Por ejemplo, para buscar los números de una columna personalizada de serie llamada #mi_serie, se usaría el nombre de búsqueda #mi_serie_index. Los números de serie son números, por lo que se pueden usar los operadores de relación descritos anteriormente. El campo especial search se usa para las búsquedas guardadas. Si guarda una búsqueda con el nombre «Los libros de mi cónyuge», puede introducir search:"los libros de mi cónyuge" en la barra de búsqueda para reutilizar la búsqueda guardada. Más adelante hay más información sobre el guardado de búsquedas. Puede buscar libros que contengan o no un campo usando los valores especiales «true» y «false». Por ejemplo: cover:false will give you all books without a cover series:true will give you all books that belong to a series comments:false will give you all books with an empty comment format:false will give you all books with no actual files (empty records) Las columnas personalizadas de sí/no se pueden buscar. Si busca «false», «vacío» o «blanco» se encontrarán todos los libros con valor indefinido en la columna. Si busca «true» se encontrarán todos los libros que no tengan un valor indefinido. Si busca «sí» o «marcado» se encontrarán todos los libros con Sí en la columna. Si busca «no» o «desmarcado» se encontrarán todos los libros con No en la columna. Tenga en cuenta que las palabras sí, no, blanco, vacío, marcado y desmarcado están traducidas; puede usar tanto el equivalente en el idioma actual o la palabra inglesa. Las palabras true y false y los valores especiales _yes, _no y _empty no están traducidos. Los elementos jerárquicos (por ejemplo A.B.C) emplean una sintaxis extendida para indicar las partes iniciales de la jerarquía. Esto se hace añadiendo un punto entre el operador de coincidencia exacta (=) y el texto. Por ejemplo, la búsqueda tags:=.a encontrará las etiquetas A y A.B, pero no las etiquetas AA o AA.B. La búsqueda tags:=.a.b encontrará las etiquetas A.B y A.B.C, pero no la etiqueta A. Los identificadores (isbn, doi, lccn, etc.) también usan una sintaxis extendida. En primer lugar, tenga en cuenta que un identificador tiene la forma tipo:valor, como en isbn: La sintaxis extendida le permite especificar de manera independiente qué tipo y valor buscar. Tanto la parte del tipo como la del valor pueden usar los tipos de búsqueda de igualdad, expresiones regulares o «contiene». Ejemplos: identifiers:true encontrará libros con cualquier identificador. identifiers:false encontrará libros sin identificador. identifiers:123 encontrará libros con cualquier tipo de identificador cuyo valor contenga 123. identifiers:= encontrará libros con cualquier tipo de identificador cuyo valor sea igual a identifiers:=isbn: e identifiers:isbn:true encontrarán libros con identificador de tipo isbn y cualquier valor. identifiers:=isbn:false encontrará libros sin identificador de tipo isbn. identifiers:=isbn:123 encontrará libros con identificador de tipo isbn cuyo valor contenga 123. identifiers:=isbn:= encontrará libros con identificador de tipo isbn cuyo valor sea igual a identifier:i:1 encontrará libros con identificadores cuyo tipo contenga una i y cuyo valor contenga un La interfaz gráfica de usuario 13

18 Figura 1.1: Diálogo de búsqueda avanzada Guardar búsquedas calibre le permite guardar una búsqueda usada frecuentemente con un nombre especial, y luego usar dicha búsqueda con una sola pulsación. Para ello, cree la búsqueda escribiendo en la barra de búsqueda o con el explorador de etiquetas. Después escriba el nombre que desee darle a la búsqueda en el cuadro de búsquedas guardadas junto a la barra de búsqueda. Pulse el icono con el signo más junto al cuadro de búsquedas guardadas para guardar la búsqueda. A partir de ahora podrá acceder a la búsqueda guardada en el explorador de etiquetas, bajo «Búsquedas». Una sola pulsación le permite volver a usar fácilmente búsquedas de cualquier complejidad, sin tener que crearlas de nuevo Bibliotecas virtuales La opción Biblioteca virtual es una manera de que calibre muestre sólo algunos libros en vez de contener la biblioteca completa. Ésta es una manera excelente de dividir la biblioteca completa en pequeñas secciones fáciles de manejar. Para aprender cómo crear y usar bibliotecas virtuales, vea el cursillo Bibliotecas virtuales (Página 234) Extraer metadata de los nombres de archivo Normalmente, calibre lee los metadatos a partir del contenido del archivo del libro. Sin embargo, puede configurarse para leer los metadatos a partir del nombre de archivo, por medio de Preferencias > Añadir libros > Leer metadatos desde el contenido del archivo. También puede controlar cómo se leen los metadatos desde el nombre del archivo utilizando expresiones regulares (ver Todo acerca de cómo utilizar expresiones regulares en calibre (Página 204)). En la sección Añadir libros del cuadro de diálogo de configuración, puede especificar una expresión regular que calibre utilizará para tratar de adivinar los metadatos a partir de los nombres de los archivos de libro electrónico que se añaden a la biblioteca. La expresión regular predeterminada es: 14 Capítulo 1. Secciones

19 title - author es decir, asume que todos los caracteres hasta el primer - son el título del libro y los caracteres subsiguientes son el autor del libro. Por ejemplo, el nombre de archivo: Foundation and Earth - Isaac Asimov.txt será interpretado con el título: «Foundation and Earth» y autor: «Isaac Asimov» Truco: Si el nombre del archivo no contiene ningún guión, la expresión regular anterior fallará Detalles del libro El panel de detalles del libro muestra la portada y los metadatos para el libro que se encuentre seleccionado. Estos datos pueden ocultarse pulsando en el botón que se encuentra en la esquina inferior derecha de la ventana principal de 1.1. La interfaz gráfica de usuario 15

20 calibre. Se puede pulsar sobre los nombres de autor en el panel de detalles del libro, y al hacerlo el sistema abrirá el artículo de Wikipedia del respectivo autor. Esta opción se puede personalizar pulsando con el botón derecho sobre el nombre del autor y seleccionando la opción Administrar este autor. De manera similar, si se descargan metadatos del libro, el panel de detalles del libro mostrará automáticamente enlaces a las páginas del libro en Amazon, Worldcat, etc. desde donde se descargaron los metadatos. Puede pulsar con el botón derecho individualmente en los formatos de libro electrónico en el panel Detalles del libro para eliminarlos, compararlos con sus versiones originales, guardarlos en un disco, abrirlos con un programa externo, etc. Puede cambiar la portada del libro arrastrando y soltando una imagen en el panel de detalles del libro. Si desea modificar la imagen de portada en un programa externo, pulse con el botón derecho sobre la imagen y elija Abrir portada con... También puede añadir archivos de libro electrónico para el libro actual simplemente arrastrando y soltando los archivos en el panel de detalles del libro. Al pulsar dos veces en el panel de detalles del libro la información se desplegará en una nueva ventana. Finalmente, puede personalizar qué información se mostrará en el panel de detalles del libro en Preferencias > Apariencia > Detalles del libro Explorador de etiquetas El explorador de etiquetas le permite navegar en la colección por autor, etiquetas, serie, etc. Si pulsa en cualquiera de los elementos del explorador de etiquetas, por ejemplo el nombre del autor Isaac Asimov, la lista de libros a la derecha 16 Capítulo 1. Secciones

21 mostrará solamente los libros de ese autor. Puede pulsar también en las diversas categorías. Por ejemplo, pulsando «Serie» obtendrá una lista de los libros en cualquier serie. La primera pulsación sobre un elemento restringe la lista de libros a aquellos que contienen o coinciden con un elemento. Siguiendo con el ejemplo anterior, si pulsamos sobre «Isaac Asimov» se mostrarán los libros de este autor. Al pulsar otra vez sobre el elemento se cambia lo que se muestra, dependiendo de si el elemento tiene descendientes (ver subcategorías y elementos jerárquicos más adelante). En el mismo ejemplo, si pulsamos otra vez sobre «Isaac Asimov» se restringe la lista de libros a los que no son de Isaac Asimov. Una tercera pulsación elimina la restricción y muestra todos los libros. Si mantiene pulsada la tecla Ctrl o Mayús y pulsa en varios elementos, se crearán restricciones basadas en varios elementos. Por ejemplo, puede mantener pulsada la tecla Ctrl y pulsar en las etiquetas «Historia» y «Europa» para buscar libros sobre historia europea. El explorador de etiquetas construye expresiones de búsqueda que se introducen automáticamente en la barra de búsqueda. Examinar lo que genera el explorador de etiquetas es una buena manera de aprender cómo construir expresiones básicas. Los iconos de los elementos del explorador de etiquetas están coloreados parcialmente. La cantidad de color depende de la calificación promedio de los libros en la categoría. Por ejemplo, si los libros de Isaac Asimov tienen una calificación media de cuatro estrellas, el icono para Isaac Asimov en el explorador de etiquetas está coloreado en 4/5. Puede colocar el cursor del ratón sobre el icono para ver la calificación promedio. Los elementos más externos del explorador de etiquetas, como Autores y Series, se llaman categorías. Puede crear nuevas categorías, llamadas categorías de usuario, que resultan útiles para organizar los libros. Por ejemplo, puede usar el editor de categorías de usuario (pulse en Modificar el explorador de etiquetas > Administrar autores, etiquetas, etc. > Administrar categorías de usuario) para crear una categoría llamada «Autores favoritos» y luego asignar los elementos de sus autores favoritos a la categoría. Las categorías de usuario pueden tener subcategorías. Por ejemplo, la categoría de usuario «Favoritos.Autores» es una subcategoría de «Favoritos». Podría tener también «Favoritos.Series», y entonces habría dos subcategorías dentro de «Favoritos». Puede crear subcategorías pulsando con el botón derecho sobre una categoría de usuario, eligiendo «Añadir una subcategoría a...» e introduciendo el nombre de la subcategoría; o usando el editor de categorías de usuario e introduciendo nombres como en el ejemplo anterior de «Favoritos». Puede buscar categorías de usuario de la misma manera que las categorías predefinidas, pulsando sobre ellas. Hay cuatro tipos d 1. «todo lo que coincida con un elemento de la categoría», indicado por un solo signo más verde. 2. «todo lo que coincida con un elemento de la categoría o sus subcategorías», indicado por dos signos más verdes. 3. «todo lo que no coincida con ningún elemento de la categoría», indicado por un signo menos rojo. 4. «todo lo que no coincida con ningún elemento de la categoría o sus subcategorías», indicado por dos signos menos rojos. También es posible crear jerarquías dentro de algunas categorías de texto como las etiquetas, series y columnas de texto. Estas jerarquías se muestran como un pequeño triángulo, permitiendo ocultar los subelementos. Para usar jerarquías de elementos en una categoría debe ir a Preferencias > Apariencia e introducir el nombre de la(s) categoría(s) en el cuadro «Categorías con elementos jerárquicos». Una vez hecho esto, los elementos en dicha categoría que contengan puntos se mostrarán usando el pequeño triángulo. Por ejemplo, supongamos que crea una columna personalizada llamada «Género» e indica que contiene elementos jerárquicos. Los elementos tales como «Misterio.Intriga» y «Misterio.Español» se mostrarán como «Misterio» con el triángulo al lado. Al pulsar sobre el triángulo se mostrarán «Intriga» y «Español» como subelementos. Véase Gestionar subgrupos de libros, por ejemplo «género» (Página 152) para más información. Los elementos jerárquicos (elementos que tienen descendientes) usan las mismas cuatro búsquedas al pulsar que las categorías de usuario. Los elementos sin descendientes usan dos de las búsquedas: «todo lo que coincida» y «todo lo que no coincida». Puede arrastrar y soltar elementos del explorador de etiquetas sobre las categorías de usuario para añadirlos a la categoría. Si el origen es una categoría de usuario y se mantiene pulsada la tecla Mayús mientras se arrastra, se moverá el elemento a la nueva categoría. También puede arrastrar y soltar libros de la lista de libros sobre elementos en el 1.1. La interfaz gráfica de usuario 17

22 explorador de etiquetas; al soltar un libro sobre un elemento, éste se aplicará sobre el libro soltado. Por ejemplo, si se arrastra un libro sobre «Isaac Asimov» se establecerá el autor de dicho libro en «Isaac Asimov». Si se arrastra sobre la etiqueta «Historia» se añadirá la etiqueta «Historia» a las etiquetas del libro. There is a search bar at the top of the Tag Browser that allows you to easily find any item in the Tag Browser. In addition, you can right click on any item and choose one of several operations. Some examples are to hide it, rename it, or open a Manage x dialog that allows you to manage items of that kind. For example, the Manage Authors dialog allows you to rename authors and control how their names are sorted. Puede controlar cómo se ordenan los elementos del explorador de etiquetas por medio del botón Modificar el explorador de etiquetas en la parte inferior del explorador de etiquetas. Puede elegir entre ordenar por nombre, calificación promedio o popularidad (popularidad es el número de libros con un elemento en la biblioteca; por ejemplo, la popularidad de Isaac Asimov es el número de libros de Isaac Asimov en la biblioteca) Cuadro de portadas Puede hacer que calibre muestre un cuadro de portadas en lugar de una lista de libros, si prefiere ver la biblioteca como portadas en lugar de nombres. El Cuadro de portadas se activa pulsando en el botón de parrilla en la esquina inferior derecha de la ventana principal de calibre. Puede personalizar los tamaños de las portadas y el fondo del cuadro de portadas en Preferencias > Apariencia > Cuadro de portadas. Puede también mostrar cualquier campo especificado bajo las portadas, como el título, autores o calificación, o una columna personalizada de diseño propio. 18 Capítulo 1. Secciones

23 Explorador de portadas Además del cuadro de portadas descrito anteriormente, puede hacer que calibre muestre las portadas en una sola fila. Esto se activa por medio de un botón en la esquina inferior derecha de la ventana principal. En Preferencias > Apariencia > Explorador de portadas puede cambiar el número de portadas que se muestran o hacer que el explorador de portadas se abra en una ventana aparte Vista rápida Sometimes you want to select a book and quickly get a list of books with the same value in some category (authors, tags, publisher, series, etc) as the currently selected book, but without changing the current view of the library. You can do this with Quickview. Quickview opens a second window showing the list of books matching the value of interest. Por ejemplo, supongamos que quiere ver una lista de todos los libros con el mismo autor que el libro actualmente seleccionado. Pulse en la celda del autor en el que está interesado y pulse la tecla «Q». Se abrirá una ventana con todos los autores del libro a la izquierda y todos los libros del autor seleccionado a la derecha. Algunos ejemplos de uso de la vista rápida: ver rápidamente qué otros libros: tienen alguna etiqueta que el libro actualmente seleccionado tiene aplicada, están en la misma serie que el libro actual tienen los mismos valores en una columna personalizada que el libro actual están escrtos por alguno de los autores del libro actual sin cambiar los contenidos de la vista de la biblioteca. La ventana de vista rápida se abre sobre la ventana de calibre y se mantendrá abierta hasta que la cierre explícitamente. Puede usar la vista rápida y la vista de biblioteca de calibre simultáneamente. Por ejemplo, si en la vista de biblioteca de calibre pulsa sobre una columna de categoría (etiquetas, serie, editorial, autores, etc.) para un libro, el contenido de la ventana de vista rápida cambiará para mostrar en el panel izquierdo los elementos de dicha categoría para el libro seleccionado (por ejemplo, las etiquetas para el libro). El primer elemento de la lista será seleccionado y la vista rápida mostrará en el panel derecho todos los libros de la biblioteca que hacen referencia a ese elemento. Pulse en otro elemento del panel izquierdo para ver los libros con ese otro elemento La interfaz gráfica de usuario 19

24 Pulse dos veces sobre un libro en la ventana de vista rápida para seleccionar ese libro en la vista de biblioteca. Esto también cambiará los elementos que se muestran en la ventana de vista rápida (el panel izquierdo) para mostrar los elementos en el nuevo libro seleccionado. Pulse dos veces manteniendo pulsada la tecla Mayús (o Ctrl) sobre un libro en la ventana de vista rápida para abrir el cuadro de modificación de metadatos para dicho libro en la ventana de calibre. Puede ver si una columna puede ser objeto de la vista rápida colocando el cursor del ratón sobre el encabezado de la columna y mirando la ayuda emergente de dicho encabezado. También puede pulsar con el botón derecho sobre el encabezado de la columna para ver si la opción «Vista rápida» se muestra en el menú, en cuyo caso elegir la opción Vista rápida es equivalente a pulsar «Q» en la celda actual. La vista rápida respeta la configuración de biblioteca virtual, mostrando sólo los libros en la biblioteca virtual actual Tareas El panel de tareas muestra el número de tareas actualmente en ejecución. Las tareas son procesos que se ejecutan de manera separada. Incluyen la conversión de libros y la comunicación con el dispositivo lector. Puede pulsar sobre el panel de tareas para acceder a la lista de tareas. Una vez completada una tarea puede ver un registro detallado de dicha tarea pulsando dos veces sobre ella en la lista. Esto es útil para depurar tareas que no se hayan completado con éxito Atajos de teclado calibre tiene varios atajos de teclado que pueden ahorrarle tiempo y movimientos de ratón. Estos atajos están activos en la vista de lista de libros (mientras no se estén modificando los detalles de un libro particular), y la mayoría de ellos afecta al libro que esté seleccionado. El visor de libros de calibre tiene sus propios atajos que pueden personalizarse pulsando en el botón Preferencias del visor. Nota: Nota: Los atajos de teclado de calibre no requieren una tecla modificadora (Alt, Opción, Control, etc.), a no ser que se especifique lo contrario. Sólo necesita presionar tecla correspondiente, por ejemplo E para editar. Tabla 1.1: Atajos de teclado Atajo de teclado F2 (Tecla Intro en OS X) A Mayús+A C D Supr E G I K M Alt+M O P S Acción Modificar los metadatos del campo actualmente seleccionado en la lista de libros Añadir libros Añadir archivos a los registros de libros seleccionados Convertir los libros seleccionados Enviar al dispositivo Eliminar los libros seleccionados Modificar metadatos de los libros seleccionados Obtener libros Mostrar detalles del libro Modificar índice Unir los registros de libros seleccionados Unir los registros seleccionados, mantener los originales Abrir carpeta contenedora Pulir libros Guardar en el disco Conti 20 Capítulo 1. Secciones

25 Tabla 1.1 proviene de la página anterior Atajo de teclado Acción T Modificar libro V Mostrar Alt+V (Cmd+V en OS X) Mostrar un formato específico Alt+Mayús+J Conmutar lista de tareas Alt+Mayús+B Conmutar explorador de portadas Alt+Mayús+D Conmutar detalles del libro Alt+Mayús+T Conmutar explorador de etiquetas Alt+Mayús+G Conmutar cuadro de portadas Alt+A Mostrar libros del mismo autor que el libro actual Alt+T Mostrar libros con las mismas etiquetas que el libro actual Alt+P Mostrar libros de la misma editorial que el libro actual Alt+Mayús+S Mostrar libros de la misma serie que el libro actual /, Ctrl+F Activar la barra de búsqueda Ctrl+Mayús+F Abrir el cuadro de diálogo de búsqueda avanzada Esc Limpiar la búsqueda actual Mayús+Esc Llevar el foco a la lista de libros Ctrl+Esc Limpiar la biblioteca virtual Alt+Esc Limpiar la restricción adicional Ctrl+* Crear una biblioteca virtual temporal basada en la búsqueda actual Ctrl+Derecha Seleccionar la siguiente pestaña de biblioteca virtual Ctrl+Izquierda Seleccionar la pestaña de biblioteca virtual anterior N, F3 Find the next book that matches the current search (only works if search highlighting is turned Mayús+N, Mayús+F3 Find the previous book that matches the current search (only works if search highlighting is tur Ctrl+D Download metadata and covers Ctrl+R Reiniciar calibre Ctrl+Mayús+R Reiniciar calibre en modo de depuración Ctrl+Mayús+E Añadir libros vacíos a calibre Q Abrir la ventana de vista rápida para ver libros relacionados por serie, etiquetas, etc. Mayús+Q Llevar el foco al panel de vista rápida abierto Mayús+S Buscar en el panel de vista rápida Ctrl+Q Salir de calibre 1.2 Añadir su sitio de noticias favorito calibre tiene un estructura potente, flexible y fácil de usar para descargar noticias de Internet y convertirlas en un libro electrónico. A continuación se le mostrará, a través de ejemplos, cómo acceder a las noticias de varios sitios de Internet. Para comprender mejor cómo utilizar la estructura, siga los ejemplos en el orden indicado a continuación: 1.2. Añadir su sitio de noticias favorito 21

26 Recopilación totalmente automática (Página 124) El blog de calibre (Página 125) bbc.co.uk (Página 126) Personalizar el proceso de obtención (Página 126) Usar la versión para imprimir de bbc.co.uk (Página 126) Sustituir los estilos de los artículos (Página 127) Dividir y reordenar (Página 128) Ejemplo de la vida real (Página 140) Consejos para desarrollar nuevas fórmulas (Página 142) Lecturas adicionales (Página 143) Documentación de la API (Página 143) Recopilación totalmente automática Si la fuente de noticias es suficientemente simple, es posible que calibre sea capaz de obtener las noticias de forma totalmente automática, todo lo que tiene que hacer es proporcionar el URL. calibre reúne toda la información necesaria para descargar una fuente de noticias en una fórmula. Si quiere añadir una fuente de noticias en calibre, debe crear una fórmula para ello. Veamos algunos ejemplos: El blog de calibre El blog de calibre es un blog de mensajes que describen varias características útiles de calibre de una manera sencilla y accesible para los nuevos usuarios de calibre. Para descargar este blog en un libro electrónico, nos basamos en el RSS del blog: Obtenemos la dirección URL del RSS de la sección «Subscribe to» al final de la página del blog, eligiendo «Posts > Atom». Para hacer que calibre descargue los canales y los convierta en un libro electrónico, debe pulsar con el botón derecho en el botón Obtener noticias y luego el elemento del menú Añadir una nueva fuente de noticias y el botón Nueva fórmula. Se abrirá un cuadro de diálogo similar al que se muestra a continuación. 22 Capítulo 1. Secciones

27 Primero introduzca Blog de calibre dentro del campo Título de la fórmula. Éste será el título del libro electrónico que se creará a partir de los artículos provenientes de los canales anteriores. Los dos campos siguientes (Artículo más antiguo y Número máximo de artículos por canal) le permiten controlar cuántos artículos se descargan desde cada canal, ambos son suficientemente explícitos. Para añadir los canales a la fórmula, introduzca el título y dirección URL del canal y pulse en el botón Añadir canal. Una vez añadido el canal, simplemente pulse en el botón Añadir o actualizar fórmula y ya está! Cierre el cuadro de diálogo. Para probar la nueva fórmula, pulse en el botón Obtener noticias, en el submenú Personalizado, y en Blog de calibre. En un par de minutos, el nuevo libro electrónico descargado con las entradas al blog aparecerá en la biblioteca principal (si tiene conectado un dispositivo de lectura, aparecerá en él en vez de la biblioteca). Selecciónelo y pulse en el botón Mostrar para leerlo. La razón por la que esto funcionó tan bien, con tan poco esfuerzo, es que el blog proporciona una fuente RSS con el contenido completo, es decir, el contenido del artículo está incrustado en el propio canal de información. Para la mayoría de las fuentes de noticias que proporcionan noticias de esta manera, con un canal RSS con el contenido completo, no necesitará mayores esfuerzos para convertirlas en libros electrónicos. Ahora veremos en una fuente de noticias que no proporciona un canal de noticias RSS con el contenido completo. En dichos canales, el artículo completo es una página de Internet y el canal de información RSS sólo contiene un enlace a la página con un breve resumen del artículo Añadir su sitio de noticias favorito 23

28 bbc.co.uk Vamos a probar los siguentes dos canales de The BBC: 1. Portal de noticias: 2. Ciencia y naturaleza: Siga el procedimiento descrito anteriormente en El blog de calibre (Página 125) para crear una fórmula para La BBC (usando los canales RSS mencionados más arriba). Al examinar el libro electrónico descargado, vemos que calibre ha hecho un trabajo encomiable al extraer sólo el contenido que significativo de la página de Internet de cada artículo. Sin embargo, el proceso de extracción no es perfecto. A veces quedan contenidos no deseados como los menús y las ayudas a la navegación o se elimina contenido que debería haber sido mantenido, como las cabeceras de los artículos. Para que la extracción de contenido sea perfecta, tendremos que personalizar el proceso de Obtención, como se describe en la siguiente sección Personalizar el proceso de obtención Cuando desea perfeccionar el proceso de descarga, o descargar el contenido de un sitio de Internet particularmente complejo, puede servirse de toda la potencia y flexibilidad de la estructura de una fórmula. Con ese fin, en el cuadro de diálogo Añadir nueva fuente de noticias, simplemente pulse en el botón Cambiar a modo avanzado. La personalización más fácil y a menudo más productiva es el uso de la versión para imprimir de los artículos en línea. La versión para imprimir normalmente tiene mucho menos contenido superfluo y se transforma de maner más fluida en un libro electrónico. Vamos a tratar de utilizar la versión impresa de los artículos de La BBC. Usar la versión para imprimir de bbc.co.uk El primer paso es buscar en el libro electrónico que descargamos previamente de bbc.co.uk (Página 126). Al final de cada artículo, en el libro electrónico, hay una pequeña reseña que dice desde dónde ha sido descargado el artículo. Copie y pegue la dirección URL en un navegador. Ahora en la página de Internet del artículo, busque un enlace que apunta a la «Versión para imprimir». Pulse en él para ver la versión para imprimir del artículo. Es mucho más limpia! Ahora compare ambas direcciones URL. En mi caso eran: URL del artículo URL de la versión para imprimir Así que parece que para obtener la versión para imprimir, tenemos que poner delante de cada URL de artículo: newsvote.bbc.co.uk/mpapps/pagetools/print/ Ahora en el Modo avanzado cuadro de diálogo de nuevas fuentes de noticias, debería ver algo así (recuerde seleccionar la fórmula La BBC antes de cambiar al modo avanzado): 24 Capítulo 1. Secciones

29 Se puede ver que los campos del Modo básico han sido traducidos a código python de una manera directa. Necesitamos añadir instrucciones para que esta fórmula utilice la versión para imprimir de los artículos. Todo lo que se necesita es añadir las siguientes dos líneas: def print_version(self, url): return url.replace(' ' Esto es python, por lo que la sangría es importante. Después de añadir las líneas, debe ser algo así: En lo anterior, def print_version(self, url) define un método que es utilizado por calibre para cada artículo. url es la dirección URL del artículo original. Lo que hace print_version es tomar la dirección URL y sustituirla por la nueva dirección URL que apunta a la versión para imprimir del artículo. Para aprender sobre python 4 vea el cursillo 5 (en inglés). Ahora, pulse en el botón Añadir o actualizar fórmula y se guardarán los cambios. Vuelva a descargar el libro electrónico. Ahora debe tener un libro electrónico muy mejorado. Uno de los problemas con la nueva versión es que los tipos de letra en la página de Internet de la versión impresa son demasiado pequeños. Esto es corregido automáticamente cuando se convierte a un libro electrónico, pero incluso después del proceso de corrección, el tamaño de la letra de los menús y barra de navegación pueden llegar a ser demasiado grande en relación con el texto del artículo. Para solucionar esto, vamos a personalizar un poco más, en la siguiente sección. Sustituir los estilos de los artículos En la sección anterior, hemos visto que el tamaño de letra para los artículos de la versión impresa de La BBC era demasiado pequeño. En la mayoría de sitios de Internet, incluido La BBC, el tamaño de letra se establece por medio de las hojas de estilo CSS. Podemos desactivar la obtención de dichas hojas de estilo añadiendo esta línea: no_stylesheets = True Añadir su sitio de noticias favorito 25

30 La fórmula queda ahora como: La nueva versión está bastante bien. Si es usted perfeccionista, querrá leer la siguiente sección, que trata de hacer cambios en el contenido descargado. Dividir y reordenar calibre contiene funciones muy poderosas y flexibles a la hora de manipular el contenido descargado. Para mostrar un par de ellas, echemos un nuevo vistazo a nuestra vieja amiga, la fórmula La BBC (Página 128). Mirando el código fuente (HTML) de un par de artículos (versiones para imprimir), vemos que tienen un pie de página que no contiene ninguna información útil, que figura en <div class="footer">... </div> Esto se puede quitar agregando: remove_tags = [dict(name='div', attrs={'class':'footer'})] a la fórmula. Finalmente, reemplacemos parte del CSS que deshabilitamos anteriormente, con nuestro propio CSS, más adecuado para la conversión en un libro electrónico: extra_css = '.headline {font-size: x-large;} \n.fact { padding-top: 10pt }' Con estas adiciones, nuestra fórmula ha alcanzado «calidad de producción», de hecho, está muy cerca de la fórmula real utilizada por calibre para la BBC, mostrada a continuación: ## ## Title: BBC News, Sport, and Blog Calibre Recipe ## Contact: mattst - jmstanfield@gmail.com ## ## License: GNU General Public License v3 - ## Copyright: mattst - jmstanfield@gmail.com ## ## Written: November 2011 ## Last Edited: ## license copyright = 'GNU General Public License v3 - = 'mattst - jmstanfield@gmail.com' 26 Capítulo 1. Secciones

31 ''' BBC News, Sport, and Blog Calibre Recipe ''' # Import the regular expressions module. import re # Import the BasicNewsRecipe class which this class extends. from calibre.web.feeds.recipes import BasicNewsRecipe class BBCNewsSportBlog(BasicNewsRecipe): # # **** IMPORTANT USERS READ ME **** # # First select the feeds you want then scroll down below the feeds list # and select the values you want for the other user preferences, like # oldest_article and such like. # # # Select the BBC rss feeds which you want in your ebook. # Selected feed have NO '#' at their start, de-selected feeds begin with a '#'. # # Eg. ("News Home", " - include feed. # Eg. #("News Home", " - do not include feed. # # There are 68 feeds below which constitute the bulk of the available rss # feeds on the BBC web site. These include 5 blogs by editors and # correspondants, 16 sports feeds, 15 'sub' regional feeds (Eg. North West # Wales, Scotland Business), and 7 Welsh language feeds. # # Some of the feeds are low volume (Eg. blogs), or very low volume (Eg. Click) # so if "oldest_article = 1.5" (only articles published in the last 36 hours) # you may get some 'empty feeds' which will not then be included in the ebook. # # The 15 feeds currently selected below are simply my default ones. # # Note: With all 68 feeds selected, oldest_article set to 2, # max_articles_per_feed set to 100, and simultaneous_downloads set to 10, # the ebook creation took 29 minutes on my speedy 100 mbps net connection, # fairly high-end desktop PC running Linux (Ubuntu Lucid-Lynx). # More realistically with 15 feeds selected, oldest_article set to 1.5, # max_articles_per_feed set to 100, and simultaneous_downloads set to 20, # it took 6 minutes. If that's too slow increase 'simultaneous_downloads'. # # Select / de-select the feeds you want in your ebook. # feeds = [ ("News Home", " ("UK", " ("World", " #("England", " #("Scotland", " #("Wales", " #("N. Ireland", " #("Africa", " #("Asia", " #("Europe", " Añadir su sitio de noticias favorito 27

32 #("Latin America", " #("Middle East", " ("US & Canada", " ("Politics", " ("Science/Environment", " ("Technology", " ("Magazine", " ("Entertainment/Arts", " #("Health", " #("Education/Family", " ("Business", " ("Special Reports", " ("Also in the News", " #("Newsbeat", " #("Click", " ("Blog: Nick Robinson (Political Editor)", " #("Blog: Mark D'Arcy (Parliamentary Correspondent)", " #("Blog: Robert Peston (Business Editor)", " #("Blog: Stephanie Flanders (Economics Editor)", " ("Blog: Rory Cellan-Jones (Technology correspondent)", " ("Sport Front Page", " #("Football", " #("Cricket", " #("Rugby Union", " #("Rugby League", " #("Tennis", " #("Golf", " #("Motorsport", " #("Boxing", " #("Athletics", " #("Snooker", " #("Horse Racing", " #("Cycling", " #("Disability Sport", " #("Other Sport", " #("Olympics 2012", " #("N. Ireland Politics", " #("Scotland Politics", " #("Scotland Business", " #("E. Scotland, Edinburgh & Fife", " #("W. Scotland & Glasgow", " #("Highlands & Islands", " #("NE. Scotland, Orkney & Shetland", " #("South Scotland", " #("Central Scotland & Tayside", " #("Wales Politics", " #("NW. Wales", " #("NE. Wales", " #("Mid. Wales", " #("SW. Wales", " #("SE. Wales", " #("Newyddion - News in Welsh", " #("Gwleidyddiaeth", " #("Gogledd-Ddwyrain", " #("Gogledd-Orllewin", " #("Canolbarth", " #("De-Ddwyrain", " #("De-Orllewin", " 28 Capítulo 1. Secciones

33 ] # **** SELECT YOUR USER PREFERENCES **** # Title to use for the ebook. # title = 'BBC News' # A brief description for the ebook. # description = u'bbc web site ebook created using rss feeds.' # The max number of articles which may be downloaded from each feed. # I've never seen more than about 70 articles in a single feed in the # BBC feeds. # max_articles_per_feed = 100 # The max age of articles which may be downloaded from each feed. This is # specified in days - note fractions of days are allowed, Eg. 2.5 (2 and a # half days). My default of 1.5 days is the last 36 hours, the point at # which I've decided 'news' becomes 'old news', but be warned this is not # so good for the blogs, technology, magazine, etc., and sports feeds. # You may wish to extend this to 2-5 but watch out ebook creation time will # increase as well. Setting this to 30 will get everything (AFAICT) as long # as max_articles_per_feed remains set high (except for 'Click' which is # v. low volume and its currently oldest article is 4th Feb 2011). # oldest_article = 1.5 # Number of simultaneous downloads. 20 is consistantly working fine on the # BBC News feeds with no problems. Speeds things up from the defualt of 5. # If you have a lot of feeds and/or have increased oldest_article above 2 # then you may wish to try increasing simultaneous_downloads to 25-30, # Or, of course, if you are in a hurry. [I've not tried beyond 20.] # simultaneous_downloads = 20 # Timeout for fetching files from the server in seconds. The default of # 120 seconds, seems somewhat excessive. # timeout = 30 # The format string for the date shown on the ebook's first page. # List of all values: # Default in news.py has a leading space so that's mirrored here. # As with 'feeds' select/de-select by adding/removing the initial '#', # only one timefmt should be selected, here's a few to choose from. # timefmt = ' [%a, %d %b %Y]' # [Fri, 14 Nov 2011] (Calibre default) #timefmt = ' [%a, %d %b %Y %H:%M]' # [Fri, 14 Nov :30] #timefmt = ' [%a, %d %b %Y %I:%M %p]' # [Fri, 14 Nov :30 PM] #timefmt = ' [%d %b %Y]' # [14 Nov 2011] #timefmt = ' [%d %b %Y %H:%M]' # [14 Nov ] #timefmt = ' [%Y-%m-%d]' # [ ] #timefmt = ' [%Y-%m-%d-%H-%M]' # [ ] 1.2. Añadir su sitio de noticias favorito 29

34 # # **** IMPORTANT **** # # DO NOT EDIT BELOW HERE UNLESS YOU KNOW WHAT YOU ARE DOING. # # DO NOT EDIT BELOW HERE UNLESS YOU KNOW WHAT YOU ARE DOING. # # I MEAN IT, YES I DO, ABSOLUTELY, AT YOU OWN RISK. :) # # **** IMPORTANT **** # # Author of this recipe. author = 'mattst' # Specify English as the language of the RSS feeds (ISO-639 code). language = 'en_gb' # Set tags. tags = 'news, sport, blog' # Set publisher and publication type. publisher = 'BBC' publication_type = 'newspaper' # Disable stylesheets from site. no_stylesheets = True # Specifies an override encoding for sites that have an incorrect charset # specified. Default of 'None' says to auto-detect. Some other BBC recipes # use 'utf8', which works fine (so use that if necessary) but auto-detecting # with None is working fine, so stick with that for robustness. encoding = None # Sets whether a feed has full articles embedded in it. The BBC feeds do not. use_embedded_content = False # Removes empty feeds - why keep them!? remove_empty_feeds = True # Create a custom title which fits nicely in the Kindle title list. # Requires "import time" above class declaration, and replacing # title with custom_title in conversion_options (right column only). # Example of string below: "BBC News - 14 Nov 2011" # # custom_title = "BBC News - " + time.strftime('%d %b %Y') ''' # Conversion options for advanced users, but don't forget to comment out the # current conversion_options below. Avoid setting 'linearize_tables' as that # plays havoc with the 'old style' table based pages. # conversion_options = { 'title' : title, 'comments' : description, 'tags' : tags, 30 Capítulo 1. Secciones

35 ''' } 'language' : language, 'publisher' : publisher, 'authors' : publisher, 'smarten_punctuation' : True conversion_options = { 'smarten_punctuation' : True } # Specify extra CSS - overrides ALL other CSS (IE. Added last). extra_css = 'body { font-family: verdana, helvetica, sans-serif; } \.introduction,.first { font-weight: bold; } \.cross-head { font-weight: bold; font-size: 125%; } \.cap,.caption { display: block; font-size: 80%; font-style: italic; } \.cap,.caption,.caption img,.caption span { display: block; text-align: center; ma.byl,.byd,.byline img,.byline-name,.byline-title,.author-name,.author-position.correspondent-portrait img,.byline-lead-in,.name,.bbc-role { display: block; text-align: center; font-size: 80%; font-style: italic; margin: 1px auto; } \.story-date,.published { font-size: 80%; } \ table { width: 100%; } \ td img { display: block; margin: 5px auto; } \ ul { padding-top: 10px; } \ ol { padding-top: 10px; } \ li { padding-top: 5px; padding-bottom: 5px; } \ h1 { text-align: center; font-size: 175%; font-weight: bold; } \ h2 { text-align: center; font-size: 150%; font-weight: bold; } \ h3 { text-align: center; font-size: 125%; font-weight: bold; } \ h4, h5, h6 { text-align: center; font-size: 100%; font-weight: bold; }' # Remove various tag attributes to improve the look of the ebook pages. remove_attributes = [ 'border', 'cellspacing', 'align', 'cellpadding', 'colspan', 'valign', 'vspace', 'hspace', 'alt', 'width', 'height' ] # Remove the (admittedly rarely used) line breaks, "<br />", which sometimes # cause a section of the ebook to start in an unsightly fashion or, more # frequently, a "<br />" will muck up the formatting of a correspondant's byline. # "<br />" and "<br clear/>" are far more frequently used on the table formatted # style of pages, and really spoil the look of the ebook pages. preprocess_regexps = [(re.compile(r'<br[ ]*/>', re.ignorecase), lambda m: ''), (re.compile(r'<br[ ]*clear.*/>', re.ignorecase), lambda m: '')] # Create regular expressions for tag keeping and removal to make the matches more # robust against minor changes and errors in the HTML, Eg. double spaces, leading # and trailing spaces, missing hyphens, and such like. # Python regular expression ('re' class) page: # *************************************** # Regular expressions for keep_only_tags: # *************************************** # The BBC News HTML pages use variants of 'storybody' to denote the section of a HTML # page which contains the main text of the article. Match storybody variants: 'storybody', # 'story-body', 'story body','storybody ', etc. storybody_reg_exp = '^.*story[_ -]*body.*$' # The BBC sport and 'newsbeat' (features) HTML pages use 'blq_content' to hold the title # and published date. This is one level above the usual news pages which have the title 1.2. Añadir su sitio de noticias favorito 31

36 # and date within 'story-body'. This is annoying since 'blq_content' must also be kept, # resulting in a lot of extra things to be removed by remove_tags. blq_content_reg_exp = '^.*blq[_ -]*content.*$' # The BBC has an alternative page design structure, which I suspect is an out-of-date # design but which is still used in some articles, Eg. 'Click' (technology), 'FastTrack' # (travel), and in some sport pages. These alternative pages are table based (which is # why I think they are an out-of-date design) and account for -I'm guesstimaking- less # than 1% of all articles. They use a table class 'storycontent' to hold the article # and like blq_content (above) have required lots of extra removal by remove_tags. story_content_reg_exp = '^.*story[_ -]*content.*$' # Keep the sections of the HTML which match the list below. The HTML page created by # Calibre will fill <body> with those sections which are matched. Note that the # blq_content_reg_exp must be listed before storybody_reg_exp in keep_only_tags due to # it being the parent of storybody_reg_exp, that is to say the div class/id 'story-body' # will be inside div class/id 'blq_content' in the HTML (if 'blq_content' is there at # all). If they are the other way around in keep_only_tags then blq_content_reg_exp # will end up being discarded. keep_only_tags = [ dict(name='table', attrs={'class':re.compile(story_content_reg_exp, re.ignorec dict(name='div', attrs={'class':re.compile(blq_content_reg_exp, re.ignorecas dict(name='div', attrs={'id':re.compile(blq_content_reg_exp, re.ignorecase)} dict(name='div', attrs={'class':re.compile(storybody_reg_exp, re.ignorecase) dict(name='div', attrs={'id':re.compile(storybody_reg_exp, re.ignorecase)}) # ************************************ # Regular expressions for remove_tags: # ************************************ # Regular expression to remove share-help and variant tags. The share-help class # is used by the site for a variety of 'sharing' type links, Eg. Facebook, delicious, # twitter, . Removed to avoid page clutter. share_help_reg_exp = '^.*share[_ -]*help.*$' # Regular expression to remove embedded-hyper and variant tags. This class is used to # display links to other BBC News articles on the same/similar subject. embedded_hyper_reg_exp = '^.*embed*ed[_ -]*hyper.*$' # Regular expression to remove hypertabs and variant tags. This class is used to # display a tab bar at the top of an article which allows the user to switch to # an article (viewed on the same page) providing further info., 'in depth' analysis, # an editorial, a correspondant's blog entry, and such like. The ability to handle # a tab bar of this nature is currently beyond the scope of this recipe and # possibly of Calibre itself (not sure about that - TO DO - check!). hypertabs_reg_exp = '^.*hyper[_ -]*tabs.*$' # Regular expression to remove story-feature and variant tags. Eg. 'story-feature', # 'story-feature related narrow', 'story-feature wide', 'story-feature narrow'. # This class is used to add additional info. boxes, or small lists, outside of # the main story. TO DO: Work out a way to incorporate these neatly. story_feature_reg_exp = '^.*story[_ -]*feature.*$' # Regular expression to remove video and variant tags, Eg. 'videoinstoryb', # 'videoinstoryc'. This class is used to embed video. video_reg_exp = '^.*video.*$' # Regular expression to remove audio and variant tags, Eg. 'audioinstoryd'. # This class is used to embed audio. 32 Capítulo 1. Secciones

37 audio_reg_exp = '^.*audio.*$' # Regular expression to remove picturegallery and variant tags, Eg. 'picturegallery'. # This class is used to embed a photo slideshow. See also 'slideshow' below. picture_gallery_reg_exp = '^.*picture.*$' # Regular expression to remove slideshow and variant tags, Eg. 'dslideshow-enclosure'. # This class is used to embed a slideshow (not necessarily photo) but both # 'slideshow' and 'picturegallery' are used for slideshows. slideshow_reg_exp = '^.*slide[_ -]*show.*$' # Regular expression to remove social-links and variant tags. This class is used to # display links to a BBC bloggers main page, used in various columnist's blogs # (Eg. Nick Robinson, Robert Preston). social_links_reg_exp = '^.*social[_ -]*links.*$' # Regular expression to remove quote and (multi) variant tags, Eg. 'quote', # 'endquote', 'quote-credit', 'quote-credit-title', etc. These are usually # removed by 'story-feature' removal (as they are usually within them), but # not always. The quotation removed is always (AFAICT) in the article text # as well but a 2nd copy is placed in a quote tag to draw attention to it. # The quote class tags may or may not appear in div's. quote_reg_exp = '^.*quote.*$' # Regular expression to remove hidden and variant tags, Eg. 'hidden'. # The purpose of these is unclear, they seem to be an internal link to a # section within the article, but the text of the link (Eg. 'Continue reading # the main story') never seems to be displayed anyway. Removed to avoid clutter. # The hidden class tags may or may not appear in div's. hidden_reg_exp = '^.*hidden.*$' # Regular expression to remove comment and variant tags, Eg. 'comment-introduction'. # Used on the site to display text about registered users entering comments. comment_reg_exp = '^.*comment.*$' # Regular expression to remove form and variant tags, Eg. 'comment-form'. # Used on the site to allow registered BBC users to fill in forms, typically # for entering comments about an article. form_reg_exp = '^.*form.*$' # Extra things to remove due to the addition of 'blq_content' in keep_only_tags. #<div class="story-actions"> Used on sports pages for ' ' and 'print'. story_actions_reg_exp = '^.*story[_ -]*actions.*$' #<div class="bookmark-list"> Used on sports pages instead of 'share-help' (for # social networking links). bookmark_list_reg_exp = '^.*bookmark[_ -]*list.*$' #<div id="secondary-content" class="content-group"> # NOTE: Don't remove class="content-group" that is needed. # Used on sports pages to link to 'similar stories'. secondary_content_reg_exp = '^.*secondary[_ -]*content.*$' #<div id="featured-content" class="content-group"> # NOTE: Don't remove class="content-group" that is needed. # Used on sports pages to link to pages like 'tables', 'fixtures', etc. featured_content_reg_exp = '^.*featured[_ -]*content.*$' 1.2. Añadir su sitio de noticias favorito 33

38 #<div id="navigation"> # Used on sports pages to link to pages like 'tables', 'fixtures', etc. # Used sometimes instead of "featured-content" above. navigation_reg_exp = '^.*navigation.*$' #<a class="skip" href="#blq-container-inner">skip to top</a> # Used on sports pages to link to the top of the page. skip_reg_exp = '^.*skip.*$' # Extra things to remove due to the addition of 'storycontent' in keep_only_tags, # which are the alterative table design based pages. The purpose of some of these # is not entirely clear from the pages (which are a total mess!). # Remove mapping based tags, Eg. <map id="world_map"> # The dynamic maps don't seem to work during ebook creation. TO DO: Investigate. map_reg_exp = '^.*map.*$' # Remove social bookmarking variation, called 'socialbookmarks'. social_bookmarks_reg_exp = '^.*social[_ -]*bookmarks.*$' # Remove page navigation tools, like 'search', ' ', 'print', called 'blq-mast'. blq_mast_reg_exp = '^.*blq[_ -]*mast.*$' # Remove 'sharesb', I think this is a generic 'sharing' class. It seems to appear # alongside 'socialbookmarks' whenever that appears. I am removing it as well # under the assumption that it can appear alone as well. sharesb_reg_exp = '^.*sharesb.*$' # Remove class 'o'. The worst named user created css class of all time. The creator # should immediately be fired. I've seen it used to hold nothing at all but with # 20 or so empty lines in it. Also to hold a single link to another article. # Whatever it was designed to do it is not wanted by this recipe. Exact match only. o_reg_exp = '^o$' # Remove 'promotopbg' and 'promobottombg', link lists. Have decided to # use two reg expressions to make removing this (and variants) robust. promo_top_reg_exp = '^.*promotopbg.*$' promo_bottom_reg_exp = '^.*promobottombg.*$' # Remove 'nlp', provides heading for link lists. Requires an exact match due to # risk of matching those letters in something needed, unless I see a variation # of 'nlp' used at a later date. nlp_reg_exp = '^nlp$' # Remove 'mva', provides embedded floating content of various types. Variant 'mvb' # has also now been seen. Requires an exact match of 'mva' or 'mvb' due to risk of # matching those letters in something needed. mva_or_mvb_reg_exp = '^mv[ab]$' # Remove 'mvtb', seems to be page navigation tools, like 'blq-mast'. mvtb_reg_exp = '^mvtb$' # Remove 'blq-toplink', class to provide a link to the top of the page. blq_toplink_reg_exp = '^.*blq[_ -]*top[_ -]*link.*$' # Remove 'products and services' links, Eg. desktop tools, alerts, and so on. # Eg. Class="servicev4 ukfs_services" - what a mess of a name. Have decided to # use two reg expressions to make removing this (and variants) robust. 34 Capítulo 1. Secciones

39 prods_services_01_reg_exp = '^.*servicev4.*$' prods_services_02_reg_exp = '^.*ukfs[_ -]*services.*$' # Remove -what I think is- some kind of navigation tools helper class, though I am # not sure, it's called: 'blq-rst blq-new-nav'. What I do know is it pops up # frequently and it is not wanted. Have decided to use two reg expressions to make # removing this (and variants) robust. blq_misc_01_reg_exp = '^.*blq[_ -]*rst.*$' blq_misc_02_reg_exp = '^.*blq[_ -]*new[_ -]*nav.*$' # Remove 'puffbox' - this may only appear inside 'storyextra', so it may not # need removing - I have no clue what it does other than it contains links. # Whatever it is - it is not part of the article and is not wanted. puffbox_reg_exp = '^.*puffbox.*$' # Remove 'sibtbg' and 'sibtbgf' - some kind of table formatting classes. sibtbg_reg_exp = '^.*sibtbg.*$' # Remove 'storyextra' - links to relevant articles and external sites. storyextra_reg_exp = '^.*story[_ -]*extra.*$' dict(name='div', attrs={'id':re.compile(social_bookmarks_reg_exp, re.ignorecase)} remove_tags = [ dict(name='div', attrs={'class':re.compile(story_feature_reg_exp, re.ignorecase) dict(name='div', attrs={'class':re.compile(share_help_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(embedded_hyper_reg_exp, re.ignorecase dict(name='div', attrs={'class':re.compile(hypertabs_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(video_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(audio_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(picture_gallery_reg_exp, re.ignorecas dict(name='div', attrs={'class':re.compile(slideshow_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(quote_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(hidden_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(comment_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(story_actions_reg_exp, re.ignorecase) dict(name='div', attrs={'class':re.compile(bookmark_list_reg_exp, re.ignorecase) dict(name='div', attrs={'id':re.compile(secondary_content_reg_exp, re.ignorecase dict(name='div', attrs={'id':re.compile(featured_content_reg_exp, re.ignorecase) dict(name='div', attrs={'id':re.compile(navigation_reg_exp, re.ignorecase)}), dict(name='form', attrs={'id':re.compile(form_reg_exp, re.ignorecase)}), dict(attrs={'class':re.compile(quote_reg_exp, re.ignorecase)}), dict(attrs={'class':re.compile(hidden_reg_exp, re.ignorecase)}), dict(attrs={'class':re.compile(social_links_reg_exp, re.ignorecase)}), dict(attrs={'class':re.compile(comment_reg_exp, re.ignorecase)}), dict(attrs={'class':re.compile(skip_reg_exp, re.ignorecase)}), dict(name='map', attrs={'id':re.compile(map_reg_exp, re.ignorecase)}), dict(name='map', attrs={'name':re.compile(map_reg_exp, re.ignorecase)}), dict(name='div', attrs={'id':re.compile(blq_mast_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(sharesb_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(o_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(promo_top_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(promo_bottom_reg_exp, re.ignorecase)} dict(name='div', attrs={'class':re.compile(nlp_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(mva_or_mvb_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(mvtb_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(blq_toplink_reg_exp, re.ignorecase)}) dict(name='div', attrs={'class':re.compile(prods_services_01_reg_exp, re.ignorec dict(name='div', attrs={'class':re.compile(prods_services_02_reg_exp, re.ignorec 1.2. Añadir su sitio de noticias favorito 35

40 dict(name='div', attrs={'class':re.compile(blq_misc_01_reg_exp, re.ignorecase)}) dict(name='div', attrs={'class':re.compile(blq_misc_02_reg_exp, re.ignorecase)}) dict(name='div', attrs={'class':re.compile(puffbox_reg_exp, re.ignorecase)}), dict(attrs={'class':re.compile(sibtbg_reg_exp, re.ignorecase)}), dict(attrs={'class':re.compile(storyextra_reg_exp, re.ignorecase)}) ] # Uses url to create and return the 'printer friendly' version of the url. # In other words the 'print this page' address of the page. # # There are 3 types of urls used in the BBC site's rss feeds. There is just # 1 type for the standard news while there are 2 used for sports feed urls. # Note: Sports urls are linked from regular news feeds (Eg. 'News Home') when # there is a major story of interest to 'everyone'. So even if no BBC sports # feeds are added to 'feeds' the logic of this method is still needed to avoid # blank / missing / empty articles which have an index title and then no body. def print_version(self, url): # Handle sports page urls type 01: if (url.find("go/rss/-/sport1/")!= -1): temp_url = url.replace("go/rss/-/", "") # Handle sports page urls type 02: elif (url.find("go/rss/int/news/-/sport1/")!= -1): temp_url = url.replace("go/rss/int/news/-/", "") # Handle regular news page urls: else: temp_url = url.replace("go/rss/int/news/-/", "") # Always add "?print=true" to the end of the url. print_url = temp_url + "?print=true" return print_url # Remove articles in feeds based on a string in the article title or url. # # Code logic written by: Starson17 - posted in: "Recipes - Re-usable code" # thread, in post with title: "Remove articles from feed", see url: # # Many thanks and all credit to Starson17. # # Starson17's code has obviously been altered to suite my requirements. def parse_feeds(self): # Call parent's method. feeds = BasicNewsRecipe.parse_feeds(self) # Loop through all feeds. for feed in feeds: # Loop through all articles in feed. for article in feed.articles[:]: # Match key words and remove article if there's a match. # Most BBC rss feed video only 'articles' use upper case 'VIDEO' 36 Capítulo 1. Secciones

41 return feeds # End of class and file. # as a title prefix. Just match upper case 'VIDEO', so that # articles like 'Video game banned' won't be matched and removed. if 'VIDEO' in article.title: feed.articles.remove(article) # Most BBC rss feed audio only 'articles' use upper case 'AUDIO' # as a title prefix. Just match upper case 'AUDIO', so that # articles like 'Hi-Def audio...' won't be matched and removed. elif 'AUDIO' in article.title: feed.articles.remove(article) # Most BBC rss feed photo slideshow 'articles' use 'In Pictures', # 'In pictures', and 'in pictures', somewhere in their title. # Match any case of that phrase. elif 'IN PICTURES' in article.title.upper(): feed.articles.remove(article) # As above, but user contributed pictures. Match any case. elif 'YOUR PICTURES' in article.title.upper(): feed.articles.remove(article) # 'Sportsday Live' are articles which contain a constantly and # dynamically updated 'running commentary' during a live sporting # event. Match any case. elif 'SPORTSDAY LIVE' in article.title.upper(): feed.articles.remove(article) # Sometimes 'Sportsday Live' (above) becomes 'Live - Sport Name'. # These are being matched below using 'Live - ' because removing all # articles with 'live' in their titles would remove some articles # that are in fact not live sports pages. Match any case. elif 'LIVE - ' in article.title.upper(): feed.articles.remove(article) # 'Quiz of the week' is a Flash player weekly news quiz. Match only # the 'Quiz of the' part in anticipation of monthly and yearly # variants. Match any case. elif 'QUIZ OF THE' in article.title.upper(): feed.articles.remove(article) # Remove articles with 'scorecards' in the url. These are BBC sports # pages which just display a cricket scorecard. The pages have a mass # of table and css entries to display the scorecards nicely. Probably # could make them work with this recipe, but might take a whole day # of work to sort out all the css - basically a formatting nightmare. elif 'scorecards' in article.url: feed.articles.remove(article) Esta fórmula muestra sólo la punta del iceberg en lo que se refiere a la potencia de calibre. Para explorar más sobre las capacidades de calibre, examinaremos un ejemplo de la vida real más complejo en la siguiente sección Añadir su sitio de noticias favorito 37

42 Ejemplo de la vida real Un ejemplo real bastante complejo que expone más partes de la API de BasicNewsRecipe es la fórmula de The New York Times import string, re from calibre import strftime from calibre.web.feeds.recipes import BasicNewsRecipe from calibre.ebooks.beautifulsoup import BeautifulSoup class NYTimes(BasicNewsRecipe): title = 'The New York Times' author = 'Kovid Goyal' description = 'Daily news from the New York Times' timefmt = ' [%a, %d %b, %Y]' needs_subscription = True remove_tags_before = dict(id='article') remove_tags_after = dict(id='article') remove_tags = [dict(attrs={'class':['articletools', 'post-tools', 'side_tool', 'nextarticlelink c dict(id=['footer', 'toolsright', 'articleinline', 'navigation', 'archive', 'side_sear dict(name=['script', 'noscript', 'style'])] encoding = 'cp1252' no_stylesheets = True extra_css = 'h1 {font: sans-serif large;}\n.byline {font:monospace;}' def get_browser(self): br = BasicNewsRecipe.get_browser() if self.username is not None and self.password is not None: br.open(' br.select_form(name='login') br['userid'] = self.username br['password'] = self.password br.submit() return br def parse_index(self): soup = self.index_to_soup(' def feed_title(div): return ''.join(div.findall(text=true, recursive=false)).strip() articles = {} key = None ans = [] for div in soup.findall(true, attrs={'class':['section-headline', 'story', 'story headline']}): if div['class'] == 'section-headline': key = string.capwords(feed_title(div)) articles[key] = [] ans.append(key) elif div['class'] in ['story', 'story headline']: a = div.find('a', href=true) if not a: continue url = re.sub(r'\?.*', '', a['href']) 38 Capítulo 1. Secciones

43 url += '?pagewanted=all' title = self.tag_to_string(a, use_alt=true).strip() description = '' pubdate = strftime('%a, %d %b') summary = div.find(true, attrs={'class':'summary'}) if summary: description = self.tag_to_string(summary, use_alt=false) feed = key if key is not None else 'Uncategorized' if not articles.has_key(feed): articles[feed] = [] if not 'podcasts' in url: articles[feed].append( dict(title=title, url=url, date=pubdate, description=description, content='')) ans = self.sort_index_by(ans, {'The Front Page':-1, 'Dining In, Dining Out':1, 'Obituaries':2 ans = [(key, articles[key]) for key in ans if articles.has_key(key)] return ans def preprocess_html(self, soup): refresh = soup.find('meta', {'http-equiv':'refresh'}) if refresh is None: return soup content = refresh.get('content').partition('=')[2] raw = self.browser.open(' return BeautifulSoup(raw.decode('cp1252', 'replace')) Vemos varias características nuevas en esta fórmula. En primer lugar, tenemos: timefmt = ' [%a, %d %b, %Y]' Esto hace que la fecha que aparece en la primera página del libro electrónico creado se muestre en este formato, Día, Número de día Mes, Año. Vea: attr:timefmt <calibre.web.feeds.news.basicnewsrecipe.timefmt>. Después vemos un grupo de directivas para depurar el HTML descargado: remove_tags_before = dict(name='h1') remove_tags_after = dict(id='footer') remove_tags =... Éstas eliminan todo lo que hay antes de la primera etiqueta <h1> y todo lo que hay después de la primera etiqueta cuyo id es footer. Véanse remove_tags (Página 318), remove_tags_before (Página 318), remove_tags_after (Página 318). La siguiente función interesante es: needs_subscription = True... def get_browser(self):... needs_subscription = True le comunica a calibre que esta fórmula necesita un nombre de usuario y contraseña para poder acceder al contenido. Esto hace que calibre pida un nombre de usuario y contraseña cada vez que intente utilizar esta fórmula. El código en calibre.web.feeds.news.basicnewsrecipe.get_browser() (Página 311) es el que realmente inicia la sesión en el sitio de Internet del New York Times. Una vez iniciada la sesión, calibre utilizará esta misma sesión para obtener todo el contenido. Véase mechanize 6 para entender el código en get_browser Añadir su sitio de noticias favorito 39

44 La siguiente nueva función es el método calibre.web.feeds.news.basicnewsrecipe.parse_index() (Página 313). Su trabajo consiste en ir a a buscar la lista de los artículos que aparecen en el número de hoy. Aunque es más compleja que simplemente usar el RSS, la fórmula crea un libro electrónico que se corresponde muy de cerca con el periódico del día. parse_index hace un uso intensivo de BeautifulSoup 7 para analizar la página del diario. También puede utilizar otros programas de análisis, más modernos, si no le gusta BeatifulSoup. calibre incluye lxml 8 y html5lib 9, que son los programas de análisis recomendados. Para usarlos, sustituya la llamada a index_to_soup() por lo siguiente: raw = self.index_to_soup(url, raw=true) # For html5lib import html5lib root = html5lib.parse(raw, namespacehtmlelements=false, treebuilder='lxml') # For the lxml html 4 parser from lxml import html root = html.fromstring(raw) La última nueva característica es el método calibre.web.feeds.news.basicnewsrecipe.preprocess_html() (Página 314). Se puede utilizar para realizar transformaciones arbitrarias en cada página HTML descargada. Aquí se usa para evitar la publicidad que nytimes muestra antes de cada artículo Consejos para desarrollar nuevas fórmulas La mejor manera de desarrollar nuevas fórmulas es utilizar la interfaz de línea de órdenes. Cree la fórmula usando su editor de python favorito y guárdela en un archivo, digamos mifórmula.recipe. La extensión.recipe es necesaria. Puede descargar contenido usando esta fórmula con la orden: ebook-convert myrecipe.recipe.epub --test -vv --debug-pipeline debug La orden ebook-convert descargará todas las páginas de Internet y las guardará en el archivo EPUB mifórmula.epub. -vv hace que ebook-convert muestre una gran cantidad de información acerca de lo que está haciendo. --test hace que se descargue sólo un par de artículos de un máximo de dos canales RSS. Además, ebook-convert pondrá el HTML descargado en el directorio debug/input, donde debug es el directorio que haya especificado en la opción :option: debug-pipeline. Una vez que la descarga está completa, puede ver el HTML descargado abriendo el archivo debug/input/index.html en un navegador. Cuando que esté satisfecho con la descarga y el procesado previo, puede generar libros electrónicos en diferentes formatos, como se muestra a continuación: ebook-convert myrecipe.recipe myrecipe.epub ebook-convert myrecipe.recipe myrecipe.mobi... Si está satisfecho con fórmula y cree que existe suficiente demanda para justificar su inclusión en el conjunto de fórmulas incorporadas, compártala en el Foro de fórmulas de calibre 10 (en inglés). Nota: En OS X, las herramientas de línea de órdenes están dentro del paquete calibre, por ejemplo, si ha instalado calibre en /Aplicaciones las herramientas de línea de órdenes están en /Aplicaciones/calibre.app/Contents/console.app/Contents/MacOS Ver también: generated/en/ebook-convert La interfaz de la línea de órdenes para todas las conversiones de libros electrónicos Capítulo 1. Secciones

45 1.2.4 Lecturas adicionales Para obtener más información acerca de cómo escribir fórmulas avanzadas usando algunas de las opciones disponibles en BasicNewsRecipe debe consultar las siguientes fuentes: Documentación de la API (Página 310) La documentación de la clase BasicNewsRecipe y todos sus métodos y campos importantes. BasicNewsRecipe 11 Fórmulas predefinidas 12 El código fuente de BasicNewsRecipe El código fuente de las fórmulas predefinidas que incluye calibre El foro de fórmulas de calibre 13 (en inglés) Un buen número de creadores de fórmulas de calibre pasan el rato aquí Documentación de la API Documentación de la API para fórmulas La API para crear fórmulas está definida por la clase BasicNewsRecipe (Página 310) class calibre.web.feeds.news.basicnewsrecipe(options, log, progress_reporter) La clase base que contiene la lógica necesaria para todas las fórmulas. Reemplazando progresivamente las distintas funciones de esta clase, puede generar fórmulas cada vez más personalizadas y potentes. Para un cursillo introductorio a la creación de fórmulas, véase Añadir su sitio de noticias favorito (Página 124). abort_article(msg=none) Ejecute este método dentro de cualquiera de los métodos de preprocesado para cancelar la descarga del artículo actual. Es útil para evitar la descarga de artículos con contenido no adecuado, como artículos que sólo contienen vídeos. abort_recipe_processing(msg) Hace que el sistema de descarga de fórmulas cancele la descarga de esta fórmula, mostrando al usuario un mensaje de información sencillo. add_toc_thumbnail(article, src) Utilice este método desde populate_article_metadata con el atributo src de una etiqueta <img> del artículo que quiera usar como la miniatura que representa el artículo en el índice. Si la miniatura se usa realmente o no dependerá del dispositivo (actualmente sólo la usan los Kindles). Tenga en cuenta que la imagen a que se hace referencia debe haber sido descargada con éxito, de lo contrario se ignorará. classmethod adeify_images(soup) Si la fórmula, al ser convertida a EPUB, tiene problemas con las imágenes cuando se muestra en Adobe Digital Editions, utilice este método desde postprocess_html() (Página 314). canonicalize_internal_url(url, is_link=true) Devuelve un conjunto de representaciones canónicas de url. La implementación predeterminada usa el nombre del servidor y la ruta de acceso del URL, descartando parámetros de consulta, fragmentos, etc. Las representaciones canónicas deben ser únicas para todos los URL de esta fuente de noticias. Si no lo son, los enlaces internos pueden ser incorrectos. Parámetros is_link Es True si el URL viene de un enlace interno en un archivo HTML. False si el URL es el URL usado para descargar un artículo. cleanup() Usado cuando todos los artículos han sido descargados. Úselo para hacer limpieza, como cerrar sesiones en los sitios que requieren suscripción, etc Añadir su sitio de noticias favorito 41

46 clone_browser(br) Clonar el navegador br. Los navegadores clonados se utilizan para las descargas multihilo, ya que mechanize no es seguro. Las rutinas de clonación predeterminadas deberían reconocer la mayoría de las personalizaciones del navegador, pero si se hace algo exótico en una fórmula, debe sustituir este método en la fórmula y clonarlo de forma manual. Los navegadores clonados usan el mismo CookieJar seguro en varios hilos, de manera predeterminada, a menos que haya personalizado el manejo de las cookies. default_cover(cover_file) Crear una portada genérica para las fórmulas que no poseen una. download() Descargar y preprocesar todos los artículos de los canales RSS en esta fórmula. Este método debe utilizarse una sola vez en cada fórmula. Si se usa más de una vez se obtendrá un comportamiento indefinido. :return: Ruta de acceso al index.html extract_readable_article(html, url) Extrae el contenido del artículo principal desde «html», lo depura y lo devuelve como una tupla (html_artículo, título_extraído). Basado en el algoritmo original de legilibilidad de Arc90. get_article_url(article) Sustituir en una subclase para personalizar la extracción del URL que apunta al contenido de cada artículo. Devuelve el URL del artículo. Se ejecuta con article, un objeto que representa un artículo analizado de un canal. Véase feedparser 14. De manera predeterminada busca el enlace original (para canales agregados mediante un servicio como feedburner o pheedo) y, si se encuentra, devuelve dicho enlace o article.link 15 en caso contrario. get_browser(*args, **kwargs) Devuelve un navegador utilizado para obtener documentos desde Internet. De manera predeterminada devuelve un navegador mechanize< _ que soporta cookies, ignora robots.txt, tiene en cuenta los refrescos y tiene un agente de usuario de tipo mozilla firefox. Si la fórmula requiere un inicio de sesión, reemplace este método en la subclase. Por ejemplo, el siguiente código se usa en la fórmula del New York Times para iniciar la sesión y tener acceso total: def get_browser(self): br = BasicNewsRecipe.get_browser(self) if self.username is not None and self.password is not None: br.open(' br.select_form(name='login') br['userid'] = self.username br['password'] = self.password br.submit() return br get_cover_url() Devuelve un URL para la imagen de portada de este número o None. De manera predeterminada, devuelve el valor del miembro self.cover_url que es normalmente None. Si quiere que la fórmula descargue una portada para el libro electrónico reemplace este método en la subclase, o establezca la variable miembro self.cover_url antes de utilizar este método. get_feeds() Devuelve una lista de canales RSS para obtener en este perfil. Cada elemento de la lista debe ser una tupla de 2 elementos de la forma (título, url). Si el título es None o un texto vacío, se utiliza el título del canal RSS. Este método es útil si la fórmula tiene que hacer algún tipo de procesado para obtener la lista de canales RSS para descargar. Si es así, reemplácelo en la subclase Capítulo 1. Secciones

47 get_masthead_title() Reemplácelo en la subclase para usar algo distinto del título de la fórmula get_masthead_url() Devuelve un URL a la imagen de cabecera de este número o None. De manera predeterminada, devuelve el valor del miembro self.masthead_url que es normalmente None. Si quiere que la fórmula descargue una imagen de cabecera para el libro electrónico reemplace este método en la subclase, o establezca la variable miembro self.masthead_url antes de utilizar este método. Las imágenes de cabecera se usan en los archivos MOBI de Kindle. get_obfuscated_article(url) Si establece articles_are_obfuscated este método se usa con cada URL de artículo. Debe devolver la ruta de acceso a un archivo en el sistema que contenga el código HTML del artículo. Este archivo es procesado por el motor de recolección de HTML recursivo, por lo que puede contener enlaces a páginas o imágenes en Internet. Este método es normalmente útil para sitios que tratan de dificultar el acceso automático al contenido de los artículos. classmethod image_url_processor(baseurl, url) Realiza algún procesado sobre las direcciones URL de las imágenes (tal vez eliminando restricciones de tamaño para imágenes generadas dinámicamente, etc.) y devuelve la dirección URL procesada. index_to_soup(url_or_raw, raw=false, as_tree=false) Método práctico que toma el URL de una página de índice y devuelve un objeto BeautifulSoup 16 que lo representa. url_or_raw: Un URL o la página de índice descargada como texto is_link_wanted(url, tag) Devuelve True si el enlace debe seguirse o False en caso contrario. De manera predeterminada, presenta NotImplementedError, que hace que el programa de descarga lo ignore. Parámetros url La dirección URL que debe seguirse tag La etiqueta de la que se extrajo la dirección URL javascript_login(browser, username, password) Este método se usa para iniciar una sesión en un sitio de Internet que emplee javascript en el correspondiente formulario. Una vez que la conexión se completa, las cookies devueltas por el sitio se copian en un navegador normal (sin javascript) y la descarga continúa con esas cookies. Un ejemplo de implementación: def javascript_login(self, browser, username, password): browser.visit(' form = browser.select_form(nr=0) # Select the first form on the page form['username'] = username form['password'] = password browser.submit(timeout=120) # Submit the form and wait at most two minutes for loading t Tenga en cuenta que también puede seleccionar formularios con selectores CSS2, de esta forma: browser.select_form('form#login_form') browser.select_from('form[name="someform"]') Añadir su sitio de noticias favorito 43

48 parse_feeds() Crea una lista de artículos desde la lista de canales devuelta por BasicNewsRecipe.get_feeds() (Página 312). Devuelve una lista objetos Feed. parse_index() Este método debe implementarse en las fórmulas que analizan una página de Internet en lugar de canales RSS para generar una lista de artículos. Los usos típicos son fuentes de noticias que tienen una página del tipo «edición impresa» que enumera todos los artículos de la edición impresa actual. Si se implementa esta función, se usará con prioridad sobre BasicNewsRecipe.parse_feeds() (Página 313). Debe devolver una lista. Cada elemento de la lista debe ser una tupla de 2 elementos de la forma ( título del canal, lista de artículos). Cada lista de artículos deben contener diccionarios del tipo: { 'title' : article title, 'url' : URL of print version, 'date' : The publication date of the article as a string, 'description' : A summary of the article 'content' : The full article (can be an empty string). Obsolete do not use, instead save the content to a temporary file and pass a file:///path/to/temp/file.html as the URL. } Como ejemplo, véase la fórmula para descargar The Atlantic. Además, puede añadir «author» para el autor del artículo. Si desea cancelar el proceso por alguna razón y hacer que calibre muestre al usuario un simple mensaje en lugar de un error, use abort_recipe_processing() (Página 310). populate_article_metadata(article, soup, first) Utilizada al descargar cada página HTML perteneciente al artículo. Pensada para obtener los metadatos del artículo, como autor, resumen, etc. a partir del HTML analizado (el argumento soup). :param article: Un objeto de la clase calibre.web.feeds.article. Si cambia el resumen, recuerde que debe cambiar también el text_summary :param soup: HTML analizado perteneciente a este artículo :param first: es True si y sólo si el HTML analizado es la primera página del artículo. postprocess_book(oeb, opts, log) Ejecutar cualquier procesado posterior necesario sobre el libro electrónico descargado. Parámetros oeb Un objeto OEBBook opts Opciones de conversión postprocess_html(soup, first_fetch) Este método se ejecuta con el código fuente de cada archivo HTML, después de analizar sus imágenes y enlaces. Puede usarse para efectuar un procesado arbitrario sobre el HTML. Debe devolver soup después del procesado. Parámetros soup Un objeto BeautifulSoup 17 que contiene el HTML descargado. first_fetch True si ésta es la primera página de un artículo. preprocess_html(soup) Este método se ejecuta con el código fuente de cada archivo HTML, antes de analizar sus imágenes y Capítulo 1. Secciones

49 enlaces. Se ejecuta después de la limpieza especificada por remove_tags, etc. Puede usarse para efectuar un preprocesado arbitrario sobre el HTML. Debe devolver soup después del procesado. soup: Un objeto BeautifulSoup 18 que contiene el HTML descargado. preprocess_raw_html(raw_html, url) Este método se ejecuta con el código fuente de cada archivo HTML, antes de convertirlo en un árbol de objetos. raw_html es un texto unicode que representa el HTML en bruto descargado de Internet. url es la dirección URL desde donde se descargó el HTML. Tenga en cuenta que este método actúa antes de preprocess_regexps. Este método debe devolver el archivo raw_html procesado como un objeto unicode. classmethod print_version(url) Tomar un url que apunta a la página de Internet con el contenido del artículo y devuelve el URL de la versión para imprimir del artículo. De manera predeterminada no hace nada. Por ejemplo: def print_version(self, url): return url + '?&pagewanted=print' skip_ad_pages(soup) Este método se ejecuta con el código fuente de cada archivo HTML descargado, antes de aplicar ningún atributo de limpieza como remove_tags o keep_only_tags. Tenga en cuenta que preprocess_regexps ya se habrá aplicado. Está pensado para permitir que la fórmula evite las páginas de publicidad. Si soup representa una página de publicidad, devuelve el HTML de la página real. De lo contrario devuelve None. soup: Un objeto BeautifulSoup 19 que contiene el HTML descargado. sort_index_by(index, weights) Método práctico para ordenar los títulos en index según weights. index se ordena en su lugar. Devuelve index. index: Una lista de títulos. weights: Un diccionario que asigna pesos a los títulos. Si un título del índice no está en weights, se asume que tiene un peso de 0. classmethod tag_to_string(tag, use_alt=true, normalize_whitespace=true) Método práctico que toma un objeto Tag de BeautifulSoup 20 y extrae el texto recursivamente, incluyendo secciones CDATA y atributos «alt». Devuelve un texto unicode posiblemente vacío. use_alt: Si es True intenta usar el atributo «alt» para las etiquetas que no poseen contenido textual tag: Un objeto Tag de BeautifulSoup 21 articles_are_obfuscated = False Establézcalo a True e implemente get_obfuscated_article() (Página 312) para manejar sitios de Internet que tratan de dificultar la obtención de contenido. auto_cleanup = False Extrae automáticamente todo el texto de las páginas de artículos descargadas. Utiliza los algoritmos del proyecto legibilidad. Si se establece en True, no hay necesidad de preocuparse de limpiar el código HTML manualmente (aunque la limpieza manual siempre será mejor). auto_cleanup_keep = None Especifica los elementos que el algoritmo de limpieza automática no debe eliminar nunca. La sintaxis es una expresión XPath. Por ejemplo: Añadir su sitio de noticias favorito 45

50 auto_cleanup_keep = '//div[@id="article-image"]' will keep all divs with id="article-image" auto_cleanup_keep = '//*[@class="important"]' will keep all elements with class="important" auto_cleanup_keep = '//div[@id="article-image"] //span[@class="important"]' will keep all divs with id="article-image" and spans with class="important" center_navbar = True Si es True la barra de navegación se alinea al centro, en caso contrario se alinea a la izquierda compress_news_images = False Si es False, se descartan todos los parámetros de escala y compresión y se dejan las imágenes sin modificar. Si es True y los otros parámetros de compresión se dejan en sus valores predeterminados, las imágenes jpeg se redimensionarán para adaptarse al tamaño de la pantalla establecido por el perfil de salida y se comprimen a un tamaño máximo de (w h)/16, donde «w» y «h» son la anchura y altura redimensionadas de la imagen. compress_news_images_auto_size = 16 El factor utilizado cuando se comprimen automáticamente las imágenes jpeg. Si se establece en None, la compresión automática se desactiva. De lo contrario, las imágenes se reducirán a un tamaño en bytes de (w h)/compress_news_images_auto_size, si es posible, reduciendo el nivel de calidad, donde «w» y «h» son la anchura y la altura de la imagen en píxeles. La calidad mínima del jpeg mínima será 5/100 por lo que es posible que no pueda cumplirse con esta restricción. Este parámetro se puede anular con el parámetro compress_news_images_max_size, que proporciona un tamaño máximo fijo para las imágenes. Tenga en cuenta que si se habilita scale_news_images_to_device entonces la imagen se ampliará primero y luego su calidad se reducirá hasta que su tamaño sea menor que (w h)/factor donde «w» y «h» son ahora las dimensiones de imagen redimensionada. En otras palabras, esta compresión ocurre después del redimensionado. compress_news_images_max_size = None Establece la calidad de los archivos jpeg para que las imágenes no excedan el tamaño dado (en kbytes). Si se establece este parámetro, la compresión automática vía compress_news_images_auto_size no tiene lugar. La calidad mínima del jpeg será 5/100 por lo que es posible que no pueda cumplirse con esta restricción. conversion_options = {} Opciones específicas de la fórmula para controlar la conversión del contenido descargado en un libro electrónico. Éstas tienen prioridad sobre cualquier valor especificado por el usuario o un complemento, por lo que deben utilizarse sólo si es absolutamente necesario. Por ejemplo: conversion_options = { 'base_font_size' : 16, 'tags' : 'mytag1,mytag2', 'title' : 'My Title', 'linearize_tables' : True, } cover_margins = (0, 0, #ffffff ) De manera predeterminada, la imagen de portada devuelta por get_cover_url() se utilizará como portada para la publicación. Si se establece un valor para esta variable en una fórmula, calibre colocará la portada descargada dentro de un marco cuya anchura y altura se expresan como un porcentaje de la portada descargada. cover_margins = (10, 15, #ffffff ) rellena la portada con un margen blanco de 10px a la izquierda y derecha, 15px en la parte superior e inferior. Los nombres de los colores están definidos en Tenga en cuenta que, por alguna razón, «white» no siempre funciona en Windows. Utilice «#ffffff» en su lugar. delay = 0 46 Capítulo 1. Secciones

51 Tiempo de espera, en segundos, entre descargas consecutivas. El argumento puede ser un número decimal para indicar un tiempo más preciso. description = u Un par de líneas que describen el contenido que descarga esta fórmula. Se usará principalmente en una interfaz gráfica que presenta una lista de fórmulas. encoding = None Especifica una codificación para los sitios que tienen una especificación de conjunto de caracteres incorrecta. El error más común es declarar latin1 y usar cp1252. Si es None, trata de detectar la codificación. Si es un método ejecutable, se usará con dos argumentos: el objeto de la fórmula y el código fuente para descodificar. Debe devolver el código descodificado. extra_css = None Especifica cualquier CSS extra que deba añadirse a los archivos HTML descargados. Se insertará en etiquetas <style>, justo antes de la etiqueta de cierre </head> con prioridad sobre todo CSS excepto el que se declara con el atributo «style» en etiquetas HTML individuales. Por ejemplo: extra_css = '.heading { font: serif x-large }' feeds = None Lista de canales para descargar. Puede ser [url1, url2,...] o [( título1, url1), ( título2, url2),...] filter_regexps = [] Lista de expresiones regulares que determina qué enlaces ignorar. Si está vacía no se tiene en cuenta. Usado sólo si is_link_wanted no está implementado. Por ejemplo: filter_regexps = [r'ads\.doubleclick\.net'] eliminará todos los URL que contengan ads.doubleclick.net. Sólo uno de entre BasicNewsRecipe.match_regexps (Página 317) y BasicNewsRecipe.filter_regexps (Página 316) deben definirse. ignore_duplicate_articles = None Ignorar duplicados de los artículos que están presentes en más de una sección. Un artículo duplicado es un artículo que tiene el mismo título o dirección URL. Para ignorar artículos con el mismo título, establézcalo como: ignore_duplicate_articles = {'title'} En cambio, para utilizar las direcciones URL, establézcalo como: ignore_duplicate_articles = {'url'} Para hacer que coincida el título o URL, establézcalo como: ignore_duplicate_articles = {'title', 'url'} keep_only_tags = [] Mantiene sólo las etiquetas especificadas y sus descendientes. El formato para especificar una etiqueta está definido en BasicNewsRecipe.remove_tags (Página 318). Si la lista no está vacía, entonces la etiqueta <body> se vaciará y se volverá a llenar con las etiquetas que coincidan con las entradas en esta lista. Por ejemplo: keep_only_tags = [dict(id=['content', 'heading'])] mantendrá sólo las etiquetas que posean un atributo id igual a content o heading Añadir su sitio de noticias favorito 47

52 language = und El idioma en que están las noticias. Debe ser un código ISO-639 de dos o tres letras masthead_url = None De manera predeterminada, calibre usará la imagen predeterminada para la cabecera (sólo en Kindle). Dé un valor a esta variable en la fórmula para proporcionar un URL para usar como cabecera. match_regexps = [] Lista de expresiones regulares que determina qué enlaces seguir. Si está vacía, no se tiene en cuenta. Se usa sólo si is_link_wanted no está implementado. Por ejemplo: match_regexps = [r'page=[0-9]+'] coincidirá con todas las direcciones URLs que posean page=algún número. Sólo uno de entre BasicNewsRecipe.match_regexps (Página 317) y BasicNewsRecipe.filter_regexps (Página 316) deben definirse. max_articles_per_feed = 100 Número máximo de artículos para descargar de cada canal. Esto es útil sobre todo para los canales que no tienen fechas en los artículos. Para la mayoría de los canales, debe usar BasicNewsRecipe.oldest_article (Página 317) needs_subscription = False Si es True, la interfaz gráfica pedirá al usuario un nombre y una contraseña para utilizar en la descarga. Si se establece en "optional" el nombre y contraseña serán opcionales. no_stylesheets = False Opción útil para desactivar la carga de hojas de estilo en los sitios de Internet que tienen hojas de estilo excesivamente complejas, poco apropiadas para la conversión a formatos de libro electrónico. Si es True, las hojas de estilo no se descargan ni procesan oldest_article = 7.0 Artículo más antiguo para descargar desde la fuente de noticias. En días. preprocess_regexps = [] Lista de reglas de sustitución regexp para ejecutar sobre los HTML descargados. Cada elemento de la lista debe ser una tupla de dos elementos. El primer elemento de la tupla debe ser una expresión regular compilada y el segundo un método ejecutable que toma un objeto de coincidencia único y devuelve un texto para sustituir a la coincidencia. Por ejemplo: preprocess_regexps = [ (re.compile(r'<!--article ends here-->.*</body>', re.dotall re.ignorecase), lambda match: '</body>'), ] eliminará todo lo que haya entre <! Article ends here > y </body>. publication_type = unknown Tipo de publicación. Establecer como «newspaper», «magazine» o «blog». Si se establece en None, no se escribirá el metadato de tipo de publicación en el archivo opf. recipe_disabled = None Establecer a un texto no vacío para desactivar esta fórmula. El texto se utilizará como el mensaje de desactivación. recursions = 0 Número de niveles de enlaces para seguir en las páginas web de los artículos remove_attributes = [] Lista de atributos para quitar de todas las etiquetas. Por ejemplo: 48 Capítulo 1. Secciones

53 remove_attributes = ['style', 'font'] remove_empty_feeds = False Si es True los canales vacíos se eliminan de la salida. Esta opción no tiene efecto si parse_index se reemplaza en la subclase. Está pensado sólo para las fórmulas que devuelven una lista de canales que utilizan feeds o get_feeds() (Página 312). También se utiliza si se emplea la opción ignore_duplicate_articles. remove_javascript = True Opción útil para eliminar todas las etiquetas javascript del archivo HTML descargado remove_tags = [] Lista de etiquetas para ser eliminadas. Las etiquetas especificadas se eliminan del HTML descargado. Cada etiqueta se especifica como un diccionario de la forma: { name : 'tag name', #e.g. 'div' attrs : a dictionary, #e.g. {class: 'advertisment'} } Todas las claves son opcionales. Para una explicación completa de los criterios de búsqueda, véase Beautiful Soup 22 (en inglés). Un ejemplo frecuente: remove_tags = [dict(name='div', attrs={'class':'advert'})] Esto eliminará todas las etiquetas <div class= advert > y todos sus elementos descendientes del HTML descargado. remove_tags_after = None Elimina todas las etiquetas que se aparecen después de la etiqueta especificada. La forma de especificar una etiqueta se muestra en BasicNewsRecipe.remove_tags (Página 318). Por ejemplo: remove_tags_after = [dict(id='content')] eliminará todas las etiquetas después del primer elemento con id= content. remove_tags_before = None Elimina todas las etiquetas que aparecen antes de la etiqueta especificada. La forma de especificar una etiqueta se da en BasicNewsRecipe.remove_tags (Página 318). Por ejemplo: remove_tags_before = dict(id='content') eliminará todas las etiquetas antes del primer elemento con id= content. requires_version = (0, 6, 0) Versión mínima de calibre necesaria para usar esta fórmula resolve_internal_links = False Si es True los enlaces en los artículos descargados que apunten a otros artículos descargados se cambian para que apunten a la copia descargada del artículo en lugar de al URL original. Si lo establece en True, puede que también necesite implementar canonicalize_internal_url() (Página 311) para que funcione con el esquema URL del sitio web concreto. reverse_article_order = False Invierte el orden de los artículos de cada canal scale_news_images = None Dimensiones máximas (anchura, altura) para redimensionar las imágenes. Si scale_news_images_to_device es True, estas dimensiones son el tamaño de la pantalla del dispositivo 22 %20the %20Parse %20Tree 1.2. Añadir su sitio de noticias favorito 49

54 establecido en el perfil de salida, a menos que no haya un perfil seleccionado, en cuyo caso se deja en el valor que se le haya asignado (de manera predeterminada None). scale_news_images_to_device = True Cambiar el tamaño de las imágenes para que quepan en la pantalla del dispositivo establecido por el perfil de salida. Se omite si no hay un perfil de salida seleccionado. simultaneous_downloads = 5 Número de descargas simultáneas. Establecer en 1 si el servidor es exigente. Se reduce automáticamente a 1 si BasicNewsRecipe.delay (Página 316) > 0 summary_length = 500 Número máximo de caracteres en la descripción breve template_css = u \n.article_date {\n color: gray; font-family: monospace;\n }\n\n.article_description {\n text-indent: 0 El CSS que se usa para dar el estilo a las plantillas, por ejemplo, las barras de navegación y los índices. En lugar de sustituir esta variable, puede usar extra_css en la fórmula para personalizar la apariencia. timefmt = [ %a, %d %b %Y] El texto de formato para la fecha que se muestra en la primera página. Predeterminado: Nombre_del_día, Número_del_día Nombre_del_mes Año timeout = Tiempo de espera para obtener archivos desde el servidor, en segundos title = u Fuente de noticias desconocida El título que se usará para el libro electrónico use_embedded_content = None Normalmente se intenta deducir si un canal contiene artículos completos incrustados, sobre la base de la longitud del contenido incrustado. Si es Ninguno, entonces se utiliza el método predeterminado. Si es True, se supone siempre que los canales contienen artículos incrustados y si es False, se supone siempre que los canales no contienen artículos incrustados. use_javascript_to_login = False Si establece esto como True, entonces calibre usará javascript para iniciar sesión en el sitio de Internet. Esto es necesario para ciertos sitios que requieren el uso de javascript para iniciar sesión. Si establece esto como True debe implementar el método javascript_login() (Página 313), para iniciar una sesión. 1.3 El visor de libros electrónicos calibre incluye un visor de libros electrónicos que puede mostrar los principales formatos de libros electrónicos. El visor es altamente personalizable y posee muchas funciones avanzadas. Iniciar el visor (Página 50) Desplazarse por un libro electrónico (Página 51) Personalizar la apariencia de la experiencia de lectura (Página 52) Búsqueda en diccionarios (Página 53) Copiar texto e imágenes (Página 53) Iniciar el visor Puede ver cualquiera de los libros de la biblioteca calibre seleccionando el libro y pulsando el botón «Mostrar». Esto abrirá el libro en el visor de libros electrónicos. También puede iniciar el visor por sí mismo desde el menú Inicio en 50 Capítulo 1. Secciones

55 Windows o utilizando la orden ebook-viewer en Linux y OS X (primero debe instalar las herramientas de línea de órdenes en OS X en Preferencias > Avanzado > Miscelánea) Desplazarse por un libro electrónico Puede «pasar las páginas» en un libro utilizando los botones Siguiente página o :guilabel: Página anterior, o pulsando las teclas Av Pág o Re Pág. A diferencia de la mayoría de los lectores de libros electrónicos, calibre no obliga a ver libros en modo paginado. Puede desplazar el texto cantidades inferiores a una página mediante el uso de la barra de desplazamiento o distintos atajos de teclado personalizables. Marcadores Si cierra el visor en medio de un libro, recordará dónde se detuvo la lectura y retornará a esa posición la próxima vez que abra el libro. También puede establecer marcadores en el libro mediante el botón Marcador. Al ver libros en formato EPUB, estos marcadores se guardan realmente en el mismo archivo EPUB. Puede añadir marcadores y posteriormente, enviar el archivo a un amigo. Cuando abra el archivo, podrá ver los marcadores. Índice Si el libro que está leyendo tiene definido un índice, puede acceder a él pulsando el botón índice. Se mostrará una lista de secciones en el libro. Puede hacer pulsar en cualquiera de ellas para ir a la posición correspondiente del libro. Navegar por ubicación Los libros electrónicos, a diferencia de los de papel, no tienen el concepto de páginas. En cambio, a medida que lea el libro, se dará cuenta de que la posición en el libro se muestra en la esquina superior izquierda en un cuadro como éste. Esto muestra tanto la posición actual como la longitud total del libro. Estos números son independientes del tamaño de la pantalla y el tamaño de la letra en que muestra el libro, y desempeñan un papel similar al de los números de página en los libros de papel. Puede introducir cualquier número que desee para ir a la ubicación correspondiente en el libro. calibre también tiene un modo de referencia muy útil. Puede activarlo pulsando en el botón Modo de referencia. Una vez hecho esto, cada vez que se mueve el cursor sobre un párrafo, calibre mostrará un número exclusivo formado por los números de sección y párrafo El visor de libros electrónicos 51

56 Puede usar este número para hacer especificar sin ambigüedades las distantas partes de un libro al hablar con amigos o al hacer referencias al libro en otros documentos. Puede introducir estos números en la casilla Ir a... en la parte superior de la ventana para ir a un lugar de referencia particular. Si pulsa en enlaces dentro del libro electrónico para ir a diferentes partes del libro, como una nota al final, puede utilizar los botones atrás y adelante en la esquina superior izquierda para volver a la posición inicial. Estos botones se comportan igual que los de un navegador de Internet Personalizar la apariencia de la experiencia de lectura Puede cambiar los tamaños de letra sobre la marcha mediante el uso de los botones de tamaño de letra. También puede hacer que el visor se muestre a pantalla completa pulsando el botón Pantalla completa. Si 52 Capítulo 1. Secciones

57 pulsa en el botón Preferencias, podrá cambiar los tipos de letra predeterminados utilizados por el visor por los que prefiera, así como el tamaño de letra predeterminado al iniciar el visor. Puede lograr una personalización más avanzada mediante la configuración de una hoja de estilos de usuario. Ésta es una hoja de estilos opcional que se aplicará a todos los libros. Por medio de ella puede hacer cosas como tener texto en blanco sobre un fondo negro, cambiar estilos de párrafo, la justificación del texto, etc. Para ver ejemplos de hojas de estilo personalizadas utilizadas por otros usuarios de calibre, vea los foros 23 (en inglés) Búsqueda en diccionarios Puede buscar el significado de las palabras en el libro actual pulsando con el botón dercho derecho sobre una palabra. calibre utiliza el servidor de diccionario público dict.org para buscar palabras. La definición se muestra en una pequeña caja en la parte inferior de la pantalla Copiar texto e imágenes Puede seleccionar texto e imágenes arrastrando el contenido con el ratón y luego pulsando con el botón derecho para copiar en el portapapeles. El material copiado se puede pegar en otra aplicación como texto sin formato e imágenes. 1.4 Conversión de libros calibre tiene un sistema de conversión diseñado para que sea fácil de usar. Normalmente no tiene más que añadir un libro a calibre, pulsar en convertir y calibre intentará generar una salida tan parecida como sea posible a la entrada. Sin embargo, calibre acepta un gran número de formatos de entrada, y no todos son tan adecuados como otros para convertirse a otros formatos. En el caso de los formatos menos adecuados, o si simplemente desea tener mayor control sobre el sistema de conversión, calibre tiene muchas opciones para ajustar los detalles del sistema de conversion. Tenga en cuenta que el sistema de conversión de calibre no es un sustituto para un editor completo de libros electrónicos. Para modificar libros le recomiendo que los convierta primero a EPUB o AZW3 con cailbre y luego use la función Modificar libro para darle la forma perfecta. Después puede usar el libro modificado como entrada para otros formatos en calibre. Este documento se referirá principalmente a las opciones de conversión que se encuentran en el cuadro de diálogo de conversión, mostrado a continuación. Todas estas opciones también están disponibles en la interfaz de línea de órdenes para la conversión, documentada en ebook-convert (Página 287). En calibre, puede obtener ayuda sobre cualquier opción manteniendo el cursor sobre ella, aparecerá una ayuda emergente que describe la opción Conversión de libros 53

58 Índice Introducción (Página 55) Apariencia (Página 56) Configuración de página (Página 58) Procesado heurístico (Página 59) Buscar y sustituir (Página 60) Detección de estructura (Página 60) Índice (Página 61) Usar imágenes como títulos de capítulo al convertir documentos de entrada HTML (Página 63) Usar atributos de etiquetas para suministrar el texto de las entradas del índice (Página 63) Cómo se establecen y guardan las opciones de conversión (Página 63) Consejos para formatos específicos (Página 64) 54 Capítulo 1. Secciones

59 1.4.1 Introducción Lo primero que debe comprender sobre el sistema de conversión es que está diseñado como una serie de operaciones. Esquemáticamente, es alg así: El formato de entrada se convierte primero a XHTML con el complemento de entrada apropiado. Después este HTML se transforma. En el último paso, el XHTML procesado se convierte al formato de salida especificado con el complemento de salida adecuado. Los resultados de la conversión pueden variar enormemente según el formato de entrada. Algunos formatos de entrada se convierten mucho mejorque otros. Una lista de los mejores formatos de origen para la conversión está disponible aquí (Página 103). Todo el trabajo tiene lugar en las transformaciones que operan sobre la salida XHTML. Hay varias transformaciones, por ejemplo, para insertar los metadatos del libro en una página al inicio del libro, para detectar encabezados de capítulo y crear un índice automáticamente, para ajustar los tamaños de letra proporcionalmente, etc. Es importante recordar que todas las transformaciones actúan sobre el XHTML creado por el complemento de entrada, no sobre el archivo de entrada en sí. Así, por ejemplo, si pide a calibre que convierta un archivo RTF a EPUB, primero lo convertirá a XHTML internamente, se aplicarán las distintas transformaciones sobre el XHTML y después el complemento de salida creará el archivo EPUB, generando automáticamente todos los metadatos, índice, etc. Puede ver este proceso en acción usando la opción de depuración. Simplemente especifique la ruta de acceso a un directorio para la salida de depuración. Durante la conversión, calibre guardará el XHTML generado por las distintas etapas del proceso de conversión en subdirectorios separados. Los cuatro subdirectorios son: 1.4. Conversión de libros 55

60 parsed Directorio input structure processed Descripción Tabla 1.2: Etapas del proceso de conversión Contiene el HTML creado por el complemento de entrada. Úselo para depurar el complemento de entrada. El resultado del preprocesado y conversión a XHTML de la salida del complemento de entrada. Úselo para depurar la detección de estructura. Posterior a la detección de estructura, pero anterior al aplanado de CSS y conversión de tamaños de letra. Úselo para depurar la conversión de tamaños de letra y las transformaciones de CSS. Justo antes de que el libro pase al complemento de salida. Úselo para depurar el complemento de salida Si desea modificar el documento de salida antes de que calibre lo convierta, lo mejor es modificar los archivos en el subdirectorio input, comprimirlos en un archivo zip y usar éste como formato de entrada para las subsiguientes conversiones. Para hacer esto use el cuadro de diálogo Modificar metadatos para añadir el zip como formato para el libro y entonces, en la esquina superior izquierda del cuadro de diálogo de conversión, seleccione ZIP como formato de entrada. Este documento se ocupará principalmente de las distintas transformaciones que operan sobre el XHTML intermedio y cómo controlarlas. Al final hay algunos consejos específicos para cada formato de entrada o salida Apariencia Índice Redimensionado de tamaño de letra (Página 56) Espaciado de párrafos (Página 57) CSS adicional (Página 58) Miscelánea (Página 58) Las opciones de este grupo controlan varios aspectos del aspecto del libro electrónico convertido. Redimensionado de tamaño de letra Una de las ventajas de la lectura electrónica es la posibilidad de ajustar los tamaños de letra según las necesidades individuales y las condiciones de iluminación. calibre incluye sofisticados algoritmos para asegurar que todos los libros que crea tienen tamaños de letra coherentes, independientemente de los tamaños de letra especificados en el documento de entrada. El tamaño de letra base de un documento es el tamaño de letra más común en el documento, es decir, el tamaño del texto principal del documento. Cuando especifica un Tamaño de letra base, calibre redimensiona automáticamente todos los tamaños de letra del documento proporcionalmente, de manera que el tamaño más común pasa a ser el tamaño base especificado y el resto de los tamaños de letra se redimensionan adecuadamente. Si elige un tamaño de letra base mayor hará que todos los textos del documento sean mayores. Al establecer un tamaño de letra base, para obtener mejores resultados debe establecer también la clave de tamaño de letra. Normalmente calibre elegirá automáticamente un tamaño de letra base adecuado para el perfil de salida que haya seleccionado (ver Configuración de página (Página 58)). Si el tamaño predeterminado no le satisface, puede especificar otro aquí. La opción Clave de tamaño de letra le permite especificar cómo se redimensionan los tamaños de letra que no son el base. El algoritmo de redimensionado funciona usando una clave de tamaño de letra, que no es más que una lista 56 Capítulo 1. Secciones

61 de tamaños de letra separados por comas. La clave de tamaño de letra le dice a calibre cuántos «escalones» mayor o menor debe ser un tamaño determinado comparado con el tamaño de letra base. La idea es que debe haber un número limitado de tamaños de letra en un documento. Por ejemplo, un tamaño para el texto principal, un par de tamaños para distintos niveles de encabezados, y un par de tamaños para subíndices o superíndices, o notas a pie de página. La clave de tamaño de letra le permite a calibre clasificar los tamaños de letra en los documentos de entrada en distintas «casillas» que corresponden a los distintos tamaños de letra lógicos. Veámoslo con un ejemplo. Supongamos que el documento de origen que estamos convirtiendo lo produjo alguien con una vista excelente y tiene un tamaño de letra base de 8pt. Esto significa que el texto principal del documento tiene un tamaño de 8 pt, mientras que los encabezados son algo mayores (digamos 10pt y 12pt) y las notas a pie de página algo menores (6pt). Si usamos las siguientes configuraciones: Base font size : 12pt Font size key : 7, 8, 10, 12, 14, 16, 18, 20 El documento de salida tendrá un tamaño de letra base de 12pt, encabezados de 14pt y 16pt y notas a pie de página de 8pt. Ahora supongamos que queremos que los encabezados mayores destaquen más y hacer las notas a pie de página algo mayores también. Para conseguir esto, debemos cambiar la clave de tamaño de letra a: New font size key : 7, 9, 12, 14, 18, 20, 22 Los encabezados mayores serán ahora de 18pt, mientras que las notas a pie de página serán de 9pt. Puede ajustar estos valores para tratar de optimizarlos usando el asistente de redimensionado de tamaños de letra, al que se puede acceder pulsando en el pequeño botón junto a la opción Clave de tamaño de letra. También puede desactivarse aquí todo el redimensionado de tamaños de letra en la conversión, si dese mantener los tamaños de letra del documento de entrada. Una opción relacionada es Altura de línea. La altura de línea controla la separación vertical entre renglones. De manera predeterminada (una altura de línea de 0), no se realiza ninguna manipulación de alturas de línea. Si especifica otro valor, se incluirá una altura de línea en todos los lugares que no especifique su propia altura de línea. Esto es una herramienta bastante tosca y debería usarla en contadas ocasiones. Si quiere ajustar la altura de línea en alguna sección particular de la entrada, es mejor usar el CSS adicional (Página 58). Espaciado de párrafos Normally, paragraphs in XHTML are rendered with a blank line between them and no leading text indent. calibre has a couple of options to control this. Remove spacing between paragraphs forcefully ensure that all paragraphs have no inter paragraph spacing. It also sets the text indent to 1.5em (can be changed) to mark the start of every paragraph. Insert blank line does the opposite, guaranteeing that there is exactly one blank line between each pair of paragraphs. Both these options are very comprehensive, removing spacing, or inserting it for all paragraphs (technically <p> and <div> tags). This is so that you can just set the option and be sure that it performs as advertised, irrespective of how messy the input file is. The one exception is when the input file uses hard line breaks to implement inter-paragraph spacing. If you want to remove the spacing between all paragraphs, except a select few, don t use these options. Instead add the following CSS code to CSS adicional (Página 58): p, div { margin: 0pt; border: 0pt; text-indent: 1.5em }.spacious { margin-bottom: 1em; text-indent: 0pt; } Then, in your source document, mark the paragraphs that need spacing with class= spacious. If your input document is not in HTML, use the Debug option, described in the Introduction to get HTML (use the input sub-directory) Conversión de libros 57

62 CSS adicional This option allows you to specify arbitrary CSS that will be applied to all HTML files in the input. This CSS is applied with very high priority and so should override most CSS present in the input document itself. You can use this setting to fine tune the presentation/layout of your document. For example, if you want all paragraphs of class endnote to be right aligned, just add:.endnote { text-align: right } o si desea cambiar la sangría de todos los párrafos: p { text-indent: 5mm; } Extra CSS is a very powerful option, but you do need an understanding of how CSS works to use it to its full potential. You can use the debug pipeline option described above to see what CSS is present in your input document. Miscelánea Hay algunas opciones más en esta sección. Sin justificación de texto Normally, if the output format supports it, calibre will force the output ebook to have justified text (i.e., a smooth right margin). This option will turn off this behavior, in which case whatever justification is specified in the input document will be used instead. Linealizar tablas Some badly designed documents use tables to control the layout of text on the page. When converted these documents often have text that runs off the page and other artifacts. This option will extract the content from the tables and present it in a linear fashion. Note that this option linearizes all tables, so only use it if you are sure the input document does not use tables for legitimate purposes, like presenting tabular information. Transliterar los caracteres unicode a ASCII Transliterate unicode characters to an ASCII representation. Use with care because this will replace unicode characters with ASCII. For instance it will replace Михаил Горбачёв with Mikhail Gorbachiov. Also, note that in cases where there are multiple representations of a character (characters shared by Chinese and Japanese for instance) the representation used by the largest number of people will be used (Chinese in the previous example). This option is mainly useful if you are going to view the ebook on a device that does not have support for unicode. Codificación de entrada Older documents sometimes don t specify their character encoding. When converted, this can result in non-english characters or special characters like smart quotes being corrupted. calibre tries to auto-detect the character encoding of the source document, but it does not always succeed. You can force it to assume a particular character encoding by using this setting. cp1252 is a common encoding for documents produced using windows software. You should also read Cómo convierto un archivo que contiene caracteres «exóticos» (acentuados, no latinos, comillas tipográficas, etc.)? (Página 103) for more on encoding issues Configuración de página The Page Setup options are for controlling screen layout, like margins and screen sizes. There are options to setup page margins, which will be used by the Output Plugin, if the selected Output Format supports page margins. In addition, you should choose an Input profile and an Output profile. Both sets of profiles basically deal with how to interpret measurements in the input/output documents, screen sizes and default font rescaling keys. If you know that the file you are converting was intended to be used on a particular device/software platform, choose the corresponding input profile, otherwise just choose the default input profile. If you know the files you are producing are meant for a particular device type, choose the corresponding Output profile. In particular, for MOBI Output files, you should choose the Kindle, for LIT the Microsoft Reader and for EPUB the Sony Reader. In the case of EPUB, the Sony Reader profile will result in EPUB files that will work everywhere. However, it has some side effects, like inserting artificial section breaks to keep internal components below the size threshold, needed for SONY devices. In 58 Capítulo 1. Secciones

63 particular for the iphone/android phones, choose the SONY output profile. If you know your EPUB files will not be read on a SONY or similar device, use the default output profile. If you are producing MOBI files that are not intended for the Kindle, choose the Mobipocket books output profile. The Output profile also controls the screen size. This will cause, for example, images to be auto-resized to be fit to the screen in some output formats. So choose a profile of a device that has a screen size similar to your device Procesado heurístico Heuristic Processing provides a variety of functions which can be used to try and detect and correct common problems in poorly formatted input documents. Use these functions if your input document suffers from poor formatting. Because these functions rely on common patterns, be aware that in some cases an option may lead to worse results, so use with care. As an example, several of these options will remove all non-breaking-space entities, or may include false positive matches relating to the function. Activar el procesado heurístico This option activates calibre s Heuristic Processing stage of the conversion pipeline. This must be enabled in order for various sub-functions to be applied Unir líneas Enabling this option will cause calibre to attempt to detect and correct hard line breaks that exist within a document using punctuation clues and line length. calibre will first attempt to detect whether hard line breaks exist, if they do not appear to exist calibre will not attempt to unwrap lines. The line-unwrap factor can be reduced if you want to force calibre to unwrap lines. Factor de unión de líneas This option controls the algorithm calibre uses to remove hard line breaks. For example, if the value of this option is 0.4, that means calibre will remove hard line breaks from the end of lines whose lengths are less than the length of 40 % of all lines in the document. If your document only has a few line breaks which need correction, then this value should be reduced to somewhere between 0.1 and 0.2. Detectar y marcar cabeceras y subcabeceras de capítulos sin formato If your document does not have chapter headings and titles formatted differently from the rest of the text, calibre can use this option to attempt detection them and surround them with heading tags. <h2> tags are used for chapter headings; <h3> tags are used for any titles that are detected. This function will not create a TOC, but in many cases it will cause calibre s default chapter detection settings to correctly detect chapters and build a TOC. Adjust the XPath under Structure Detection if a TOC is not automatically created. If there are no other headings used in the document then setting //h:h2 under Structure Detection would be the easiest way to create a TOC for the document. The inserted headings are not formatted, to apply formatting use the Extra CSS option under the Look and Feel conversion settings. For example, to center heading tags, use the following: h2, h3 { text-align: center } Renumerar secuencias de etiquetas <h1> o <h2> para evitar divisiones Some publishers format chapter headings using multiple <h1> or <h2> tags sequentially. calibre s default conversion settings will cause such titles to be split into two pieces. This option will re-number the heading tags to prevent splitting. Borrar líneas en blanco entre párrafos This option will cause calibre to analyze blank lines included within the document. If every paragraph is interleaved with a blank line, then calibre will remove all those blank paragraphs. Sequences of multiple blank lines will be considered scene breaks and retained as a single paragraph. This option differs from the Remove Paragraph Spacing option under Look and Feel in that it actually modifies the HTML content, while the other option modifies the document styles. This option can also remove paragraphs which were inserted using calibre s Insert blank line option. Asegurar que los cambios de escena tienen un formato consistente With this option calibre will attempt to detect common scene-break markers and ensure that they are center aligned. Soft scene break markers, i.e. scene breaks only defined by extra white space, are styled to ensure that they will not be displayed in conjunction with page breaks Conversión de libros 59

64 Sustituir cambios de escena If this option is configured then calibre will replace scene break markers it finds with the replacement text specified by the user. Please note that some ornamental characters may not be supported across all reading devices. In general you should avoid using html tags, calibre will discard any tags and use pre-defined markup. <hr /> tags, i.e. horizontal rules, and <img> tags are exceptions. Horizontal rules can optionally be specified with styles, if you choose to add your own style be sure to include the width setting, otherwise the style information will be discarded. Image tags can used, but calibre does not provide the ability to add the image during conversion, this must be done after the fact using the Edit Book feature. Ejemplo de etiqueta de imagen (guarda la imagen dentro de la carpeta «Images» dentro del epub después de la conve <img style= width:10 % src=../images/scenebreak.png /> Ejemplo de barra horizontal con estilos: <hr style= width:20 %;padding-top: 1px;border-top: 2px ridge black;border-bottom: 2px groove black; /> Eliminar los guiones ortográficos innecesarios calibre will analyze all hyphenated content in the document when this option is enabled. The document itself is used as a dictionary for analysis. This allows calibre to accurately remove hyphens for any words in the document in any language, along with made-up and obscure scientific words. The primary drawback is words appearing only a single time in the document will not be changed. Analysis happens in two passes, the first pass analyzes line endings. Lines are only unwrapped if the word exists with or without a hyphen in the document. The second pass analyzes all hyphenated words throughout the document, hyphens are removed if the word exists elsewhere in the document without a match. Poner en cursiva palabras y patrones habituales When enabled, calibre will look for common words and patterns that denote italics and italicize them. Examples are common text conventions such as ~word~ or phrases that should generally be italicized, e.g. latin phrases like etc. or et cetera. Sustituir el sangrado mediante caracteres por sangrado CSS Some documents use a convention of defining text indents using non-breaking space entities. When this option is enabled calibre will attempt to detect this sort of formatting and convert them to a 3 % text indent using css Buscar y sustituir These options are useful primarily for conversion of PDF documents or OCR conversions, though they can also be used to fix many document specific problems. As an example, some conversions can leaves behind page headers and footers in the text. These options use regular expressions to try and detect headers, footers, or other arbitrary text and remove or replace them. Remember that they operate on the intermediate XHTML produced by the conversion pipeline. There is a wizard to help you customize the regular expressions for your document. Click the magic wand beside the expression box, and click the Test button after composing your search expression. Successful matches will be highlighted in Yellow. The search works by using a python regular expression. All matched text is simply removed from the document or replaced using the replacement pattern. The replacement pattern is optional, if left blank then text matching the search pattern will be deleted from the document. You can learn more about regular expressions and their syntax at Todo acerca de cómo utilizar expresiones regulares en calibre (Página 204) Detección de estructura Structure detection involves calibre trying its best to detect structural elements in the input document, when they are not properly specified. For example, chapters, page breaks, headers, footers, etc. As you can imagine, this process varies widely from book to book. Fortunately, calibre has very powerful options to control this. With power comes complexity, but if once you take the time to learn the complexity, you will find it well worth the effort. 60 Capítulo 1. Secciones

65 Capítulos y saltos de página calibre has two sets of options for chapter detection and inserting page breaks. This can sometimes be slightly confusing, as by default, calibre will insert page breaks before detected chapters as well as the locations detected by the page breaks option. The reason for this is that there are often location where page breaks should be inserted that are not chapter boundaries. Also, detected chapters can be optionally inserted into the auto generated Table of Contents. calibre uses XPath, a powerful language to allow the user to specify chapter boundaries/page breaks. XPath can seem a little daunting to use at first, fortunately, there is a XPath tutorial (Página 157) in the User Manual. Remember that Structure Detection operates on the intermediate XHTML produced by the conversion pipeline. Use the debug option described in the Introducción (Página 55) to figure out the appropriate settings for your book. There is also a button for a XPath wizard to help with the generation of simple XPath expressions. De manera predeterminada, calibre utiliza la siguiente expresión para la detección de capítulos: //*[((name()='h1' or name()='h2') and re:test(., 'chapter book section part\s+', 'i')) = 'c La expresión es algo compleja, porque intenta tener en cuenta distintos casos comunes simultáneamente. Lo que significa es que calibre supondrá que los capítulos empiezan en etiquetas <h1> o <h2> que contengan alguna de las palabras chapter, book, section o part o que tengan el atributo class= chapter. A related option is Chapter mark, which allows you to control what calibre does when it detects a chapter. By default, it will insert a page break before the chapter. You can have it insert a ruled line instead of, or in addition to the page break. You can also have it do nothing. La configuración por defecto para la detección de saltos de página es: //*[name()='h1' or name()='h2'] lo que significa que calibre insertará de forma predeterminada saltos de página antes de cada etiqueta <h1> y <h2>. Nota: Las expresiones predeterminadas pueden cambiar, dependiendo del formato de entrada de la conversión. Miscelánea Hay algunas opciones más en esta sección. Insertar metadatos en una página al principio del libro One of the great things about calibre is that it allows you to maintain very complete metadata about all of your books, for example, a rating, tags, comments, etc. This option will create a single page with all this metadata and insert it into the converted ebook, typically just after the cover. Think of it as a way to create your own customised book jacket. Eliminar la primera imagen Sometimes, the source document you are converting includes the cover as part of the book, instead of as a separate cover. If you also specify a cover in calibre, then the converted book will have two covers. This option will simply remove the first image from the source document, thereby ensuring that the converted book has only one cover, the one specified in calibre Índice When the input document has a Table of Contents in its metadata, calibre will just use that. However, a number of older formats either do not support a metadata based Table of Contents, or individual documents do not have one. In these cases, the options in this section can help you automatically generate a Table of Contents in the converted ebook, based on the actual content in the input document. Nota: Using these options can be a little challenging to get exactly right. If you prefer creating/editing the Table of Contents by hand, convert to the EPUB or AZW3 formats and select the checkbox at the bottom of the Table of 1.4. Conversión de libros 61

66 Contents section of the conversion dialog that says Manually fine-tune the Table of Contents after conversion. This will launch the ToC Editor tool after the conversion. It allows you to create entries in the Table of Contents by simply clicking the place in the book where you want the entry to point. You can also use the ToC Editor by itself, without doing a conversion. Go to Preferences->Toolbars and add the ToC Editor to the main toolbar. Then just select the book you want to edit and click the ToC Editor button. The first option is Force use of auto-generated Table of Contents. By checking this option you can have calibre override any Table of Contents found in the metadata of the input document with the auto generated one. The default way that the creation of the auto generated Table of Contents works is that, calibre will first try to add any detected chapters to the generated table of contents. You can learn how to customize the detection of chapters in the Detección de estructura (Página 60) section above. If you do not want to include detected chapters in the generated table of contents, check the Do not add detected chapters option. If less than the Chapter threshold number of chapters were detected, calibre will then add any hyperlinks it finds in the input document to the Table of Contents. This often works well many input documents include a hyperlinked Table of Contents right at the start. The Number of links option can be used to control this behavior. If set to zero, no links are added. If set to a number greater than zero, at most that number of links is added. calibre will automatically filter duplicates from the generated Table of Contents. However, if there are some additional undesirable entries, you can filter them using the TOC Filter option. This is a regular expression that will match the title of entries in the generated table of contents. Whenever a match is found, it will be removed. For example, to remove all entries titles Next or Previous use: Next Previous The Level 1,2,3 TOC options allow you to create a sophisticated multi-level Table of Contents. They are XPath expressions that match tags in the intermediate XHTML produced by the conversion pipeline. See the Introducción (Página 55) for how to get access to this XHTML. Also read the Cursillo de XPath (Página 157), to learn how to construct XPath expressions. Next to each option is a button that launches a wizard to help with the creation of basic XPath expressions. The following simple example illustrates how to use these options. Supongamos que tiene un documento de entrada que da lugar a un XHTML como éste: <html xmlns=" <head> <title>sample document</title> </head> <body> <h1>chapter 1</h1>... <h2>section 1.1</h2>... <h2>section 1.2</h2>... <h1>chapter 2</h1>... <h2>section 2.1</h2>... </body> </html> Entonces configuramos las opciones como: Level 1 TOC : //h:h1 Level 2 TOC : //h:h2 Esto dará lugar a un índice de dos niveles generado automáticamente que tendrá esta estructura: 62 Capítulo 1. Secciones

67 Chapter 1 Section 1.1 Section 1.2 Chapter 2 Section 2.1 Advertencia: Not all output formats support a multi level Table of Contents. You should first try with EPUB Output. If that works, then try your format of choice Usar imágenes como títulos de capítulo al convertir documentos de entrada HTML Suppose you want to use an image as your chapter title, but still want calibre to be able to automatically generate a Table of Contents for you from the chapter titles. Use the following HTML markup to achieve this <html> <body> <h2>chapter 1</h2> <p>chapter 1 text...</p> <h2 title="chapter 2"><img src="chapter2.jpg" /></h2> <p>chapter 2 text...</p> </body> </html> Set the Level 1 TOC setting to //h:h2. Then, for chapter two, calibre will take the title from the value of the title attribute on the <h2> tag, since the tag has no text Usar atributos de etiquetas para suministrar el texto de las entradas del índice Si los capítulos tienen títulos especialmente largos y quiere versiones más cortas en el Índice, puede usar el atributo «title» para ello, por ejemplo: <html> <body> <h2 title="chapter 1">Chapter 1: Some very long title</h2> <p>chapter 1 text...</p> <h2 title="chapter 2">Chapter 2: Some other very long title</h2> <p>chapter 2 text...</p> </body> </html> Set the Level 1 TOC setting to //h:h2/@title. Then calibre will take the title from the value of the title attribute on the <h2> tags, instead of using the text inside the tag. Note the trailing /@title on the XPath expression, you can use this form to tell calibre to get the text from any attribute you like Cómo se establecen y guardan las opciones de conversión There are two places where conversion options can be set in calibre. The first is in Preferences->Conversion. These settings are the defaults for the conversion options. Whenever you try to convert a new book, the settings set here will be used by default. You can also change settings in the conversion dialog for each book conversion. When you convert a book, calibre remembers the settings you used for that book, so that if you convert it again, the saved settings for the individual 1.4. Conversión de libros 63

68 book will take precedence over the defaults set in Preferences. You can restore the individual settings to defaults by using the Restore to defaults button in the individual book conversion dialog. You can remove the saved settings for a group of books by selecting all the books and then clicking the edit metadata button to bring up the bulk metadata edit dialog, near the bottom of the dialog is an option to remove stored conversion settings. Al convertir en masa un conjunto de libros, las configuraciones se toman en el siguiente orden (el último prevalece): De la configuración predeterminada en Preferencias > Conversión From the saved conversion settings for each book being converted (if any). This can be turned off by the option in the top left corner of the Bulk Conversion dialog. De la configuración establecida en el cuadro de diálogo Convertir en masa Note that the final settings for each book in a Bulk Conversion will be saved and re-used if the book is converted again. Since the highest priority in Bulk Conversion is given to the settings in the Bulk Conversion dialog, these will override any book specific settings. So you should only bulk convert books together that need similar settings. The exceptions are metadata and input format specific settings. Since the Bulk Conversion dialog does not have settings for these two categories, they will be taken from book specific settings (if any) or the defaults. Nota: You can see the actual settings used during any conversion by clicking the rotating icon in the lower right corner and then double clicking the individual conversion job. This will bring up a conversion log that will contain the actual settings used, near the top Consejos para formatos específicos Here you will find tips specific to the conversion of particular formats. Options specific to particular format, whether input or output are available in the conversion dialog under their own section, for example TXT Input or EPUB Output. Convertir documentos de Microsoft Word calibre puede convertir automáticamente archivos.docx creados por Microsoft Word 2007 y versiones posteriores. Sólo tiene que añadir el archivo a calibre y pulsar en Convertir (asegúrese de que está ejecutando la última versión de calibre, ya que la compatibilidad con los archivos.docx es muy reciente). Nota: There is a demo.docx file 24 that demonstrates the capabilities of the calibre conversion engine. Just download it and convert it to EPUB or AZW3 to see what calibre can do. calibre will automatically generate a Table of Contents based on headings if you mark your headings with the Heading 1, Heading 2, etc. styles in Word. Open the output ebook in the calibre viewer and click the Table of Contents button to view the generated Table of Contents. Archivos.doc antiguos For older.doc files, you can save the document as HTML with Microsoft Word and then convert the resulting HTML file with calibre. When saving as HTML, be sure to use the Save as Web Page, Filtered option as this will produce clean HTML that will convert well. Note that Word produces really messy HTML, converting it can take a long time, so be patient. If you have a newer version of Word available, you can directly save it as docx as well. Another alternative is to use the free OpenOffice. Open your.doc file in OpenOffice and save it in OpenOffice s format.odt. calibre can directly convert.odt files Capítulo 1. Secciones

69 Convertir documentos TXT TXT documents have no well defined way to specify formatting like bold, italics, etc, or document structure like paragraphs, headings, sections and so on, but there are a variety of conventions commonly used. By default calibre attempts automatic detection of the correct formatting and markup based on those conventions. TXT input supports a number of options to differentiate how paragraphs are detected. Estilo de párrafo: auto Analyzes the text file and attempts to automatically determine how paragraphs are defined. This option will generally work fine, if you achieve undesirable results try one of the manual options. Estilo de párrafo: block Asume que los párrafos están separados por una o más líneas en blanco: This is the first. This is the second paragraph. Estilo de párrafo: single Asume que cada línea es un párrafo: This is the first. This is the second. This is the third. Estilo de párrafo: print Assumes that every paragraph starts with an indent (either a tab or 2+ spaces). Paragraphs end when the next line that starts with an indent is reached: This is the first. This is the second. This is the third. Estilo de párrafo: unformatted Assumes that the document has no formatting, but does use hard line breaks. Punctuation and median line length are used to attempt to re-create paragraphs. Estilo de formato: auto Attempts to detect the type of formatting markup being used. If no markup is used then heuristic formatting will be applied. Estilo de formato: heuristic Analyzes the document for common chapter headings, scene breaks, and italicized words and applies the appropriate html markup during conversion. Estilo de formato: markdown calibre also supports running TXT input though a transformation preprocessor known as markdown. Markdown allows for basic formatting to be added to TXT documents, such as bold, italics, section headings, tables, lists, a Table of Contents, etc. Marking chapter headings with a leading # and setting the chapter XPath detection expression to //h:h1 is the easiest way to have a proper table of contents generated from a TXT document. You can learn more about the markdown syntax at daringfireball 25. Estilo de formato: none Applies no special formatting to the text, the document is converted to html with no other changes. Convertir documentos PDF PDF documents are one of the worst formats to convert from. They are a fixed page size and text placement format. Meaning, it is very difficult to determine where one paragraph ends and another begins. calibre will try to unwrap Conversión de libros 65

70 paragraphs using a configurable, Line Un-Wrapping Factor. This is a scale used to determine the length at which a line should be unwrapped. Valid values are a decimal between 0 and 1. The default is 0.45, just under the median line length. Lower this value to include more text in the unwrapping. Increase to include less. You can adjust this value in the conversion settings under PDF Input. Also, they often have headers and footers as part of the document that will become included with the text. Use the Search and Replace panel to remove headers and footers to mitigate this issue. If the headers and footers are not removed from the text it can throw off the paragraph unwrapping. To learn how to use the header and footer removal options, read Todo acerca de cómo utilizar expresiones regulares en calibre (Página 204). Algunas limitaciones de la entrada de PDF son: No soporta documentos complejos, con columnas múltiples o basados en imágenes. Extraction of vector images and tables from within the document is also not supported. Some PDFs use special glyphs to represent ll or ff or fi, etc. Conversion of these may or may not work depending on just how they are represented internally in the PDF. No soporta enlaces e índices PDFs that use embedded non-unicode fonts to represent non-english characters will result in garbled output for those characters Some PDFs are made up of photographs of the page with OCRed text behind them. In such cases calibre uses the OCRed text, which can be very different from what you see when you view the PDF file PDFs that are used to display complex text, like right to left languages and math typesetting will not convert correctly To re-iterate PDF is a really, really bad format to use as input. If you absolutely must use PDF, then be prepared for an output ranging anywhere from decent to unusable, depending on the input PDF. Colecciones de libros de historietas A comic book collection is a.cbc file. A.cbc file is a zip file that contains other CBZ/CBR files. In addition the.cbc file must contain a simple text file called comics.txt, encoded in UTF-8. The comics.txt file must contain a list of the comics files inside the.cbc file, in the form filename:title, as shown below: one.cbz:chapter One two.cbz:chapter Two three.cbz:chapter Three El archivo.cbc contendrá: comics.txt one.cbz two.cbz three.cbz calibre will automatically convert this.cbc file into a ebook with a Table of Contents pointing to each entry in comics.txt. EPUB de demostración de formato avanzado Various advanced formatting for EPUB files is demonstrated in this demo file 26. The file was created from hand coded HTML using calibre and is meant to be used as a template for your own EPUB creation efforts Capítulo 1. Secciones

71 The source HTML it was created from is available demo.zip 27. The settings used to create the EPUB from the ZIP file are: ebook-convert demo.zip.epub -vv --authors "Kovid Goyal" --language en --level1-toc Note that because this file explores the potential of EPUB, most of the advanced formatting is not going to work on readers less capable than calibre s built-in EPUB viewer. Convertir documentos ODT calibre can directly convert ODT (OpenDocument Text) files. You should use styles to format your document and minimize the use of direct formatting. When inserting images into your document you need to anchor them to the paragraph, images anchored to a page will all end up in the front of the conversion. To enable automatic detection of chapters, you need to mark them with the build-in styles called Heading 1, Heading 2,..., Heading 6 ( Heading 1 equates to the HTML tag <h1>, Heading 2 to <h2> etc). When you convert in calibre you can enter which style you used into the Detect chapters at box. Example: If you mark Chapters with style Heading 2, you have to set the Detect chapters at box to //h:h2 For a nested TOC with Sections marked with Heading 2 and the Chapters marked with Heading 3 you need to enter //h:h2 //h:h3. On the Convert - TOC page set the Level 1 TOC box to //h:h2 and the Level 2 TOC box to //h:h3. Well-known document properties (Title, Keywords, Description, Creator) are recognized and calibre will use the first image (not to small, and with good aspect-ratio) as the cover image. There is also an advanced property conversion mode, which is activated by setting the custom property opf.metadata ( Yes or No type) to Yes in your ODT document (File->Properties->Custom Properties). If this property is detected by calibre, the following custom properties are recognized (opf.authors overrides document creator): opf.titlesort opf.authors opf.authorsort opf.publisher opf.pubdate opf.isbn opf.language opf.series opf.seriesindex In addition to this, you can specify the picture to use as the cover by naming it opf.cover (right click, Picture- >Options->Name) in the ODT. If no picture with this name is found, the smart method is used. As the cover detection might result in double covers in certain output formats, the process will remove the paragraph (only if the only content is the cover!) from the document. But this works only with the named picture! To disable cover detection you can set the custom property opf.nocover ( Yes or No type) to Yes in advanced mode. Convertir a PDF The first, most important, setting to decide on when converting to PDF is the page size. By default, calibre uses a page size defined by the current Output profile. So if your output profile is set to Kindle, calibre will create a PDF with page size suitable for viewing on the small kindle screen. However, if you view this PDF file on a computer screen, then Conversión de libros 67

72 it will appear to have too large fonts. To create normal sized PDFs, use the Override page size option under PDF Output in the conversion dialog. Encabezados y pies de página You can insert arbitrary headers and footers on each page of the PDF by specifying header and footer templates. Templates are just snippets of HTML code that get rendered in the header and footer locations. For example, to display page numbers centered at the bottom of every page, in green, use the following footer template: <p style="text-align:center; color:green">page _PAGENUM_</p> calibre will automatically replace _PAGENUM_ with the current page number. You can even put different content on even and odd pages, for example the following header template will show the title on odd pages and the author on even pages: <p style="text-align:right"><span class="even_page">_author_</span><span class="odd_page"><i>_title_< calibre will automatically replace _TITLE_ and _AUTHOR_ with the title and author of the document being converted. You can also display text at the left and right edges and change the font size, as demonstrated with this header template: <div style="font-size:x-small"><p style="float:left">_title_</p><p style="float:right;"><i>_author_</ This will display the title at the left and the author at the right, in a font size smaller than the main text. También puede usar la sección actual en plantillas, como se muestra a continuación: <p style="text-align:right">_section_</p> _SECTION_ is replaced by whatever the name of the current section is. These names are taken from the metadata Table of Contents in the document (the PDF Outline). If the document has no table of contents then it will be replaced by empty text. If a single PDF page has multiple sections, the first section on the page will be used. You can even use javascript inside the header and footer templates, for example, the following template will cause page numbers to start at 4 instead of 1: <p id="pagenum" style="text-align:center;"></p><script>document.getelementbyid("pagenum").innerhtml = Nota: When adding headers and footers make sure you set the page top and bottom margins to large enough values, under the Page Setup section of the conversion dialog. Índice imprimible You can also insert a printable Table of Contents at the end of the PDF that lists the page numbers for every section. This is very useful if you intend to print out the PDF to paper. If you wish to use the PDF on an electronic device, then the PDF Outline provides this functionality and is generated by default. You can customize the look of the the generated Table of contents by using the Extra CSS conversion setting under the Look & Feel part of the conversion dialog. The default css used is listed below, simply copy it and make whatever changes you like..calibre-pdf-toc table { width: 100%% }.calibre-pdf-toc table tr td:last-of-type { text-align: right }.calibre-pdf-toc.level-0 { font-size: larger; 68 Capítulo 1. Secciones

73 }.calibre-pdf-toc.level-1 td:first-of-type { padding-left: 1.4em }.calibre-pdf-toc.level-2 td:first-of-type { padding-left: 2.8em } 1.5 Modificar libros electrónicos calibre tiene un editor de libros electrónicos integrado que puede usarse para modificar libros en formatos EPUB y AZW3 (Kindle). El editor muestra el código HTML y CSS usado internamente en los archivos del libro, con una vista previa que se actualiza según se hacen cambios. También contiene varias herramientas automatizadas para realizar tareas comunes de limpieza y corrección. Puede utilizar este editor pulsando con el botón derecho sobre cualquier libro en calibre y seleccionando Modificar libro Modificar libros electrónicos 69

74 Índice Flujo de trabajo básico (Página 70) El explorador de archivos (Página 73) Cambiar nombres de archivo (Página 74) Unir archivos (Página 74) Cambiar el orden de los archivos de texto (Página 74) Marcar la portada (Página 74) Borrar archivos (Página 75) Exportar archivos (Página 75) Añadir nuevas imágenes, tipos de letra, etc. o crear nuevos archivos en blanco. (Página 75) Sustituir archivos (Página 75) Vincular hojas de estilo con archivos HTML de manera eficiente (Página 75) Buscar y sustituir (Página 75) Búsquedas guardadas (Página 76) Modo de función (Página 76) Herramientas automatizadas (Página 76) Modificar el índice (Página 76) Comprobar libro (Página 78) Añadir una portada (Página 79) Incrustando tipos de letra referenciados (Página 79) Reduciendo tipos de letra incrustados (Página 79) Corrigiendo puntuación (Página 79) Eliminando reglas CSS sin usar (Página 79) Corregir HTML (Página 80) Embellecer archivos (Página 80) Insertar índice en línea (Página 80) Establecer concepto (Página 80) Filtrar información de estilo (Página 80) Hitos (Página 81) El panel de previsualización en vivo (Página 82) Dividir archivos HTML (Página 83) El panel de CSS en vivo (Página 84) Herramientas variadas (Página 84) La vista del Índice (Página 85) Comprobar la ortografía en el libro (Página 85) Insertar caracteres especiales (Página 86) La vista del inspector de código (Página 87) Organizar archivos en carpetas por tipo (Página 87) Importar archivos en otros formatos de libro electrónico como EPUB (Página 87) La herramienta de Informes (Página 95) Características especiales del editor de código (Página 96) Resaltado de sintaxis (Página 96) Ayuda sensible al contexto (Página 96) Completado automático (Página 96) Fragmentos (Página 97) Flujo de trabajo básico Nota: Un recorrido en forma de video del editor de calibre está disponible aquí Capítulo 1. Secciones

75 Al abrir un libro con la herramienta Modificar libro, aparecerá una lista de archivos a la izquierda. Éstos son los archivos HTML individuales, hojas de estilo, imágenes, etc. que constituyen el contenido del libro. Simplemente pulse dos veces en un archivo para comenzar a modificarlo. Tenga en cuenta que si quiere hacer alg más sofisticado que unos pequeños retoques, debe conocer HTML (cursillo) 29 y CSS (cursillo) 30. Según se hacen cambios en el código HTML o CSS, éstos se muestran en vivo en el panel de vista previa a la derecha. Cuando esté satisfecho con el aspecto de los cambios, pulse en el botón Guardar o use Archivo > Guardar para guardar los cambios en el libro. Una característica útil es is Hitos. Antes de comenzar un conjunto ambicioso de modificaciones, puede crear un hito. El hito preservará el estado actual del libro y, si en el futuro decide que no quiere conservar los cambios realizados, podrá volver a la situación de cuando se creó el hito. Para crear un hito, use Editar > Crear hito. También se crean hitos automáticamente cada vez que ejecute una herramienta automatizada como una búsqueda y sustitución global. Los hitos son una adición al mecanismo normal de deshacer y rehacer al modificar archivos individuales, y son útiles cuando los cambios afecta a varios archivos en el libro. Ésta es la secuencia de trabajo básica para modificar libros: Abrir un archivo, hacer los cambios, comprobar la vista previa y guardar. En el resto de este manual hablaremos de las herramientas y características que le permitirán realizar tareas especificas de manera eficiente Modificar libros electrónicos 71

76 72 Capítulo 1. Secciones

77 1.5.2 El explorador de archivos 1.5. Modificar libros electrónicos 73

78 El Explorador de archivos proporciona un resumen de los distintos archivos dentro del libro que está modificando. Los archivos están dispuestos por categoría, con los archivos de texto (HTML) al principio, seguidos de los archivos de estilo (CSS), imágenes, etc. Pulse dos veces sobre un archivo para modificarlo. Puede modificar archivos HTML, CSS y de imagen. El order de los archivos de texto es el mismo orden en que mostrarían si estuviera leyendo el libro. El resto de archivos están ordenados alfabéticamente. Pasando el ratón por encima de una entrada, puede ver su tamaño y, en la parte inferior de la pantalla, la ruta de acceso completa al archivo dentro del libro. Tenga en cuenta que los archivos en el libro están comprimidos, por lo que el tamaño final del libro no es la suma de los tamaños de los archivos individuales. Muchos archivos tienen un significado especial en el libro. Normalmente éstos tendrán un icono junto a su nombre, indicando el significado especial. Por ejemplo, en la imagen de la izquierda puede ver que los archivos cover_image.jpg y titlepage.xhtml tienen el icono de una portada, lo que indica que son la imagen de portada y la página de título. Igualmente, el archivo content.opf tiene un icono de metadatos, indicando que contiene los metadatos del libro, y el archivo toc.ncx tiene un icono de T, indicando que se trata del índice. Puede realizar varias acciones sobre archivos individuales, pulsando con el botón derecho sobre ellos. Cambiar nombres de archivo Puede cambiar el nombre de un archivo concreto pulsando con el botón derecho sobre él y seleccionando Cambiar nombre. Al cambiar el nombre de un archivo se actualizan automáticamente todos los enlaces y referencias al archivo en todo el libro. Todo lo que tiene que hacer es escribir un nuevo nombre y calibre se encarga del resto. También puede cambiar el nombre de muchos archivos a la vez. Esto es útil si quiere que los nombres de los archivos sigan un patrón sencillo. Por ejemplo, puede querer cambiar el nombre de todos los archivos HTML para que sean Capitulo-1.html, Capitulo-2.html, etc. Seleccione los archivos a los que quiere cambiar el nombre manteniendo pulsada la tecla Mayús o Ctrl y pulsando con el ratón sobre los archivos. Luego pulse con el botón derecho y seleccione Cambiar el nombre en masa. Introduzca un prefijo y el número por el que desea que empiece la numeración automática, pulse «Aceptar» y ya está. Unir archivos A veces, puede querer unir dos archivos HTML o dos archivos CSS. En ciertas ocasiones puede ser útil tener todo en un solo archivo. Pero tenga cuidado, poner una gran cantidad de contenido en un solo archivo causará problemas de rendimiento cuando visualice su libro en un lector de libros electrónicos normal. Para combinar varios archivos en uno, selecciónelos manteniendo pulsada la tecla Ctrl y pulsando con el ratón sobre ellos (asegúrese de que sólo selecciona archivos de un tipo, ya sean todos HTML o todos CSS). Luego pulse con el botón derecho y seleccione Unir. Eso es todo, calibre combinará los archivos, migrando automáticamente todos los enlaces y referencias a los archivos originales. Tenga en cuenta que al combinar archivos se puede dar lugar a cambios de estilo, pues los archivos individuales podían usar diferentes hojas de estilo. Cambiar el orden de los archivos de texto Puede modificar el orden en el que los archivos de texto (HTML) se mostrarán al leer el libro simplemente arrastrando y soltándolos en el Explorador de archivos. Para los curiosos, esto se llama reordenar el lomo. Teng en cuenta que debe soltar los elementos entre otros elementos, no encima de ellos, esto puede ser un poco delicado hasta que se acostumbre. Marcar la portada Los libros electrónicos tienen normalmente una imagen de portada. Esta imagen se indica en Explorador de archivos con un icono de un libro marrón junto al nombre de la imagen. Si quiere designar otra imagen como la portada, puede 74 Capítulo 1. Secciones

79 hacerlo pulsando con el botón derecho sobre el archivo y eligiendo Marcar como imagen de portada. Además, los archivos EPUB tienen el concepto de página de título. Una página de título es un archivo HTML que funciona como la portada o portadilla del libro. Puede marcar un archivo HTML como página de título al modificar archivos EPUB pulsando con el botón derecho. Asegúrese de que el archivo marcado contiene sólo la información de portada. Si tiene otro contenido, como el primer capítulo, dicho contenido se perderá si se convierte el libro a algún otro formato con calibre. Esto sucede porque, durante la conversión, calibre asume que la página de título contiene sólo la portada y nada más. Borrar archivos Puede borrar archivos pulsando con el botón derecho sobre ellos o seleccionándolos y pulsando la tecla Supr. Al borrar un archivo se eliminan todas las referencias a éste en el archivo OPF, evitándole la molestia. Sin embargo, las referencias en otros lugares no se eliminan. Puede usar la herramienta Comprobar libro para encontrarlas y eliminarlas o sustituirlas. Exportar archivos Puede exportar un archivo contenido en el libro a algún otro lugar del equipo. Esto es útil si quiere trabajar en el archivo de manera aislada, con herramientas especializadas. Para ello, pulse con el botón derecho sobre el archivo y elija Exportar Una vez que haya terminado con el archivo exportado, puede volver a importarlo en el libro, pulsando con el botón derecho sobre el archivo otra tez y eligiendo Sustituir por archivo..., lo que le permitirá sustituir el archivo del libro por el archivo previamente exportado. Añadir nuevas imágenes, tipos de letra, etc. o crear nuevos archivos en blanco. Puede añadir una nueva image, tipo de letra, hoja de estilo, etc. del equipo al libro, seleccionando Archivo > Nuevo archivo. Esto le permite importar un archivo pulsando el botón :guilabel: Importar archivo de recursos o crear un archivo HTML u hoja de estilo en blanco, introduciendo su nombre en el cuadro. También puede importar múltiples archivos en el libro de una vez usando Archivo > Importar archivos a libro. Sustituir archivos Puede sustituir archivos existentes en el libro pulsando con el botón derecho y eligiendo Sustituir. Esto actualizará automáticamente todos los enlaces y referencias en el caso de que el nuevo archivo tenga un nombre distinto del original. Vincular hojas de estilo con archivos HTML de manera eficiente Como opción práctica, puede seleccionar varios archivos HTML en el Explorador de archivos, pulsar con el botón derecho y elegir Enlazar hojas de estilo, para que calibre inserte automáticamente las etiquetas <link> de las hojas de estilo en todos los archivos HTML seleccionados Buscar y sustituir El editor de libros tiene una interfaz muy potente de búsqueda y sustitución que le permite buscar y sustituir texto en el archivo actual, en todos los archivos e incluso en una región marcada del archivo actual. Puede buscar usando una 1.5. Modificar libros electrónicos 75

80 búsqueda normal o expresiones regulares. Para aprender cómo usar las expresiones regulares en búsquedas avanzadas, vea Todo acerca de cómo utilizar expresiones regulares en calibre (Página 204). Inicie la búsqueda y sustitución en el menú Buscar > Buscar y sustituir (debe estar modificando un archivo HTML o CSS). Introduzca el texto que quiere encontrar en el cuadro Buscar y lo que quiere poner en su lugar en el cuadro Sustituir. Puede pulsar los botones respectivos para buscar la siguiente coincidencia, sustituir la coincidencia actual y sustituir todas las coincidencias. Mediante los cuadros desplegables en la parte inferior puede hacer que la búsqueda se realice sobre el archivo actual, todos los archivos de texto, todos los archivos de estilo o todos los archivos. También puede elegir el modo de búsqueda entre normal (texto) o expresión regular. Puede contar todas las coincidencias de una expresión de búsqueda a través de Buscar->Contar todo. El recuento se ejecutará sobre cualquier archivo/regiones que haya seleccionado en el cuadro desplegable. También puede ir a una línea específica en el editor abierto actualmente por medio de Buscar > Ir a línea. Nota: Recuerde que para poder aprovechar toda la potencia de buscar y sustituir tendrá que usar expresiones regulares. Véase Todo acerca de cómo utilizar expresiones regulares en calibre (Página 204). Búsquedas guardadas Puede guardar expresiones de búsquedas frecuentes de búsqueda/reemplazo y reutilizarlas varias veces más. Para guardar una búsqueda simplemente clic botón derecho en el cuadro de Búsqueda y seleccione Guardar actual búsqueda. Puede abrir el cuadro de diálogo de búsquedas guardadas a través de :guilabel: Buscar->Búsquedas guardadas. Esto le presentará una lista de expresiones de búsqueda y reemplazo que se pueden aplicar. Incluso puede seleccionar varias entradas de la lista, mantenga pulsada la tecla Ctrl mientras hace clic con el fin de ejecutar múltiples expresiones de búsquedas y reemplazos en una sola operación. Modo de función El modo de función le permite escribir funciones python tan potentes como desee, que se ejecutan en cada búsqueda o sustitución. Puede realizar prácticamente cualquier manipulación de texto en el modo de función. Para más información vea Modo de función para buscar y sustituir en el editor (Página 87) Herramientas automatizadas Modificar libro posee varias herramientas útiles para tareas usuales. A éstas se accede a través del menú Herramientas. Modificar el índice Hay una herramienta específica para facilitar la edición del Índice. Iníciela con Herramientas > Índice > Modificar índice. 76 Capítulo 1. Secciones

81 La herramienta Editar Tabla de Contenidos le muestra la actual Tabla de Contenidos (si existiera) a su izquierda. Simplemente un doble clic en cualquier entrada para modificar su texto. Puede también reorganizar las entradas simplemente arrastrando y soltando o utilizando los botones de la derecha. Para los libros que no tienen una Tabla de Contenidos pre-existente, la herramienta le otorga varias opciones para generar automáticamente una Tabla de Contenido desde el texto. Puede generarla a partir de los títulos del documento, de los enlaces, a partir de archivos individuales y así sucesivamente. You can edit individual entries by clicking on them and then clicking the Change the location this entry points to button. This will open up a mini-preview of the book, simply move the mouse cursor over the book view panel, and click where you want the entry to point to. A thick green line will show you the location. Click OK once you are happy with the location Modificar libros electrónicos 77

82 Comprobar libro The Check Book tool searches your book for problems that could prevent it working as intended on actual reader devices. Activate it via Tools->Check Book. Any problems found are reported in a nice, easy to use list. Clicking any entry in the list shows you some help about that error as well as giving you the option to auto-fix that error, if the error can be fixed automatically. You can also double click the error to open the location of the error in an editor, so you can fix it yourself. Algunas de las comprobaciones realizadas son: Malformed HTML markup. Any HTML markup that does not parse as well-formed XML is reported. Correcting it will ensure that your markup works as intended in all contexts. calibre can also auto-fix these errors, but autofixing can sometimes have unexpected effects, so use with care. As always, a checkpoint is created before auto-fixing so you can easily revert all changes. Auto-fixing works by parsing the markup using the HTML5 algorithm, which is highly fault tolerant and then converting to well formed XML. 78 Capítulo 1. Secciones

83 Estilos CSS malformados o desconocidas. Cualquier CSS que no es válida o que posee propiedades no definidas según el estándar CSS 2.1 (más algunos de CSS 3) son informados. CSS es verificado en todas las hojas de estilo, sus atributos de estilo en línea y las etiquetas <style> en los archivos HTML. Enlaces rotos. Se informa de los enlaces que apuntan a archivos en el libro que no existen. Archivos sin referencias. Se muestran los archivos en el libro que no están referenciados por ningún otro archivo o no están en el lomo. Varios problemas comunes en archivos OPF tales como elementos del manifiesto o lomo duplicados, idrefs o etiquetas meta de portadas rotos, secciones requeridas ausentes, etc. Se ralizan distintas comprobaciones de compatibilidad relativas a problemas conocidos que pueden provocar un mal funcionamiento del libro electrónico en dispositivos de lectura. Añadir una portada Puede agregar fácilmente una portada para el libro vía Herramientas->Agregar portada. Esto le permite o elegir una imagen existente en el libro como la portada o importar una nueva imagen en el libro y hacerlo su portada. Al editar archivos EPUB, el contenedor HTML para la portada se genera de forma automática. Si se encuentra una portada existente en el libro, se sustituye. La herramienta también se encarga automáticamente de marcar correctamente los archivos de la portada como cubiertas en el OPF. Incrustando tipos de letra referenciados Se accede a través de Herramientas->Fuentes de referencia integradas, esta herramienta busca todos las fuentes de letra integradas en el libro y si éstas no lo están, las busca en su computadora y las integra en el libro, si las encuentra. Por favor, asegúrese que posee los derechos de autor necesarios para incrustar fuentes comercialmente con licencia, antes de hacer esto. Reduciendo tipos de letra incrustados Se accede a través de Herramientas->Subconjunto de fuentes integradas, esta herramienta reduce todas las fuentes en el libro a sólo aquellas que contienen glifos para el texto realmente presente en el libro. Esto reduce comúnmente el tamaño de los archivos de fuentes en un ~ 50 %. Sin embargo, tenga en cuenta que una vez que las fuentes son un subconjunto, si agrega nuevo texto cuyos caracteres no estaban previamente presentes en el subconjunto de la fuente, la fuente no se verá en el nuevo texto. Así que lleve a cabo esta acción como el último paso en su flujo de trabajo. Corrigiendo puntuación Convertir guiones de texto sin formato, elipsis, citas, múltiples guiones, etc. en sus equivalentes tipográficos correctos. Tenga en cuenta que el algoritmo a veces puede generar resultados incorrectos, especialmente cuando las comillas simples en el inicio de las contracciones están involucradas. Se accede a través de :guilabel: Herramientas->Puntuación inteligente. Eliminando reglas CSS sin usar Eliminar todas las reglas sin usar de las hojas de estilo y etiquetas <style>. Algunos libros creados a partir de plantillas de producción pueden contener un gran número de reglas CSS innecesarias que no afectan a ningún contenido del libro. Estas reglas adicionales pueden ralentizar los lectores, que necesitan procesarlas todas. Accesible en Herramientas > Eliminar CSS sin usar Modificar libros electrónicos 79

84 Corregir HTML This tool simply converts HTML that cannot be parsed as XML into well-formed XML. It is very common in ebooks to have non-well-formed XML, so this tool simply automates the process of fixing such HTML. The tool works by parsing the HTML using the HTML5 algorithm (the algorithm used in all modern browsers) and then converting the result into XML. Be aware that auto-fixing can sometimes have counter-intuitive results. If you prefer, you can use the Check Book tool discussed above to find and manually correct problems in the HTML. Accessed via Tools->Fix HTML. Embellecer archivos Esta herramienta se utiliza para auto-formato de todos los archivos HTML y CSS para que se vean atractivos. El código genera automáticamente una sangría para que se alinee de manera correcta, se insertan líneas en blanco donde sea apropiado y así sucesivamente. Tenga en cuenta que este embellecimiento también genera auto-correcciones en el HTML/CSS deficiente. Por lo tanto, si no quiere que ninguna auto-corrección se lleve a cabo, utilice primero la herramienta Comprobar libro para corregir todos los problemas y sólo entonces ejecutar Embellecer. Se accede a través de Herramientas->Embellecer todos los archivos. Nota: In HTML any text can have significant whitespace, via the CSS white-space directive. Therefore, beautification could potentially change the rendering of the HTML. To avoid this as far as possible, the beautify algorithm only beautifies block level tags that contain other block level tags. So, for example, text inside a <p> tag will not have its whitespace changed. But a <body> tag that contains only other <p> and <div> tags will be beautified. This can sometimes mean that a particular file will not be affected by beautify as it has no suitable block level tags. In such cases you can try different beautification tools, that are less careful, for example: HTML Tidy 31. Insertar índice en línea Normalmente en los libros electrónicos, el índice es independiente del texto principal y por lo general se accede a través de un botón o menú de índice en el dispositivo de lectura. También puede hacer que calibre genere automáticamente un índice que sea parte del texto del libro. Éste se genera de acuerdo al índice actualmente ya definido. Si utiliza esta herramienta varias veces, en cada ocasión se sustituirá el Índice creado previamente. La herramienta está accesible en Herramientas > Índice > Insertar un Índice explícito. Establecer concepto This tool is used to set semantics in EPUB files. Semantics are simply, links in the OPF file that identify certain locations in the book as having special meaning. You can use them to identify the foreword, dedication, cover, table of contents, etc. Simply choose the type of semantic information you want to specify and then select the location in the book the link should point to. This tool can be accessed via Tools->Set semantics. Filtrar información de estilo This tool can be used to easily remove specified CSS style properties from the entire book. You can tell it what properties you want removed, for example, color, background-color, line-height and it will remove them from everywhere they occur stylesheets, <style> tags and inline style attributes. After removing the style information, a summary of all the changes made is displayed so you can see exactly what was changed. The tool can be accessed via Tools->Filter style information Capítulo 1. Secciones

85 1.5.5 Hitos Checkpoints are a way to mark the current state of the book as special. You can then go on to do whatever changes you want to the book and if you dont like the results, return to the checkpointed state. Checkpoints are automatically created every time you run any of the automated tools described in the previous section. Puede crear un hito en Editar > Crear hito. Y volver a un hito anterior con Editar > Revertir a... The checkpointing functionality is in addition to the normal Undo/redo mechanism when editing individual files. Checkpoints are particularly useful for when changes are spread over multiple files in the book or when you wish to be able to revert a large group of related changes as a whole. You can see a list of available checkpoints via View->Checkpoints. You can compare the current state of the book to a specified checkpoint using the Comparar libros electrónicos (Página 97) tool by selecting the checkpoint of interest and clicking the Compare button. The Revert to button restores the book to the selected checkpoint, undoing all changes since that checkpoint was created Modificar libros electrónicos 81

86 1.5.6 El panel de previsualización en vivo The File Preview gives you an overview of the various files inside The live preview panel shows you the changes you are making live (with a second or two of delay). As you edit HTML or CSS files, the preview panel is updated automatically to reflect your changes. As you move the cursor around in the editor, the preview panel will track its location, showing you the corresponding location in the book. Clicking in the preview panel, will cause the cursor in the editor to be positioned over the element you clicked. If you click a link pointing to another file in the book, that 82 Capítulo 1. Secciones

87 file will be opened in the edit and the preview panel, automatically. Puede desactivar la sincronización automática de la posición y vista previa en vivo de los cambios, por medio de los botones bajo el panel de vista previa. La actualización en vivo del panel de vista previa sólo ocurre cuando no se está escribiendo activamente en el editor, a fin de no crear una distracción o reducir la velocidad mientras se espera a que se genere la vista previa. The preview panel shows you how the text will look when viewed. However, the preview panel is not a substitute for actually testing your book an actual reader device. It is both more, and less capable than an actual reader. It will tolerate errors and sloppy markup much better than most reader devices. It will also not show you page margins, page breaks and embedded fonts that use font name aliasing. Use the preview panel while you are working on the book, but once you are done, review it in an actual reader device or software emulator. Nota: El panel de vista previa no admite fuentes incrustadas si el nombre de la fuente dentro del código del archivo no coincide con el nombre de la regla Puede utilizar la herramienta Comprobar libro para encontrar y corregir rápidamente cualquier fuente con dichos problemas. Dividir archivos HTML One, perhaps non-obvious, use of the preview panel is to split long HTML files. While viewing the file you want to split, click the split mode button under the preview panel. Then simply move your mouse to the place where you want to split the file and click. A thick green line will show you exactly where the split will happen as you move your mouse. Once you have found the location you want, simply click and the split will be performed. Dividiendo el archivo automáticamente actualizará todos los enlaces y referencias que apuntaban en la mitad inferior del archivo y se abrirá el reciente archivo dividido en un editor. You can also split a single HTML file at multiple locations automatically, by right clicking inside the file in the editor and choosing Split at multiple locations. This will allow you to easily split a large file at all heading tags or all tags having a certain class and so on Modificar libros electrónicos 83

88 1.5.7 El panel de CSS en vivo El panel CSS en vivo muestra todas las reglas de estilo que se aplican a la etiqueta que está editando actualmente. El nombre de la etiqueta, junto con su número de línea son mostrados, seguido de una lista de reglas de estilo coincidentes. Es una gran manera de ver rápidamente qué reglas de estilo se aplican a cualquier etiqueta. La vista también posee enlaces al que se le puede hacer clic (en azul), que lo llevarán directamente a la ubicación definida en el estilo, por caso de que desee realizar algún cambio a las reglas de estilo. Se muestran las reglas de estilo que se aplican directamente a la etiqueta, así como las reglas que se heredan de los etiquetas principales. El panel también muestra lo que son los estilos finalmente calculados para la etiqueta. Las Propiedades en la lista son sustituidas por las reglas de mayor prioridad y son mostradas con una línea cruzándolas. Puede habilitar el panel de CSS en vivo en Ver > CSS en vivo Herramientas variadas Existen algunas herramientas más que pueden ser útiles mientras se modifica un libro. 84 Capítulo 1. Secciones

89 La vista del Índice The Table of Contents view shows you the current table of contents in the book. Double clicking on any entry opens the place that entry points to in an editor. You can right click to edit the Table of Contents, refresh the view or expand/collapse all items. Access this view via Views->Table of Contents. Comprobar la ortografía en el libro Puede ejecutar un corrector ortográfico en Herramientas > Comprobar ortografía. Words are shown with the number of times they occur in the book and the language the word belongs to. Language information is taken from the books metadata and from lang attributes in the HTML files. This allows the spell checker to work well even with books that contain text in multiple languages. For example, in the following HTML extract, the word color will be checked using American English and the word colour using British English: 1.5. Modificar libros electrónicos 85

90 <div lang="en_us">color <span lang="en_gb">colour</span></div> Nota: Puede pulsar dos veces sobre una palabra para resaltar la siguiente aparición de esta palabra en el editor. Esto es útil si desea modificar la palabra manualmente, o ver en qué contexto se encuentra. Para cambiar una palabra, simplemente pulse dos veces en una de las alternativas sugeridas a la derecha, o escriba su propia sugerencia correcta y pulse en el botón Cambiar la palabra seleccionada a. Esto sustituirá todas las apariciones de esta palabra en el libro. También puede pulsar con el botón derecho sobre una palabra en la lista principal de palabras para cambiar la palabra directamente desde el menú emergente. You can have the spelling checker ignore a word for the current session by clicking the Ignore button. You can also add a word to the user dictionary by clicking the Add to dictionary button. The spelling checker supports multiple user dictionaries, so you can select the dictionary you want the word added to. También puede hacer que el corrector ortográfico muestre todas las palabras de su libro, no sólo las escritas incorrectamente. Esto es útil para ver qué palabras son las más usuales en su libro y ejecutar una simple búsqueda y reemplazo de ciertas palabras. Nota: Si realiza cambios en el libro modificando los archivos mientras la herramienta de corrección ortográfica está abierta, debe hacer clic en el botón :guilabel: Actualizar en la herramienta de corrección ortográfica. Si no lo hace y continúa utilizando la herramienta de corrección ortográfica, podría perder los cambios realizados en el editor. Añadir nuevos diccionarios El corrector ortográfico viene con diccionarios incorporados para los idiomas inglés y español. Puede instalar sus propios diccionarios vía Preferencias-> Editor->Administrar diccionarios de ortografía. El corrector ortográfico puede utilizar diccionarios del programa OpenOffice (con el formato.oxt). Puede descargar estos diccionarios desde El repositorio de extensiones de OpenOffice 32. Insertar caracteres especiales Puede insertar caracteres que son difíciles de teclear mediante la herramienta :guilabel: Edición > Insertar carácter especial. Esto muestra todos los caracteres Unicode, simplemente pulse en el carácter que desea escribir. Si mantiene pulsada la tecla Ctrl mientras pulsa, la ventana se cerrará después de insertar el carácter seleccionado. Esta herramienta se puede utilizar para insertar caracteres especiales en el texto principal o en cualquier otra área de la interfaz de usuario, como la herramienta de búsqueda y sustitución. Debido a que hay una gran cantidad de personajes, puede definir su propio: caracteres Favoritos, que se mostrarán en primer lugar. Simplemente haga clic derecho sobre un caracter para marcarlo como Favorito. También puede hacer clic derecho sobre un caracter en Favoritos para quitarlo de los mismos. Por último, se puede volver a organizar el orden de los caracteres en favoritos haciendo clic en el botón Re-organizar Favoritos y luego arrastrar y soltar los caracteres en Favoritos. También puede escribir directamente caracteres especiales mediante el teclado. Para ello, escriba el código Unicode para el carácter (en hexadecimal) y luego presione Alt+X, lo que convertirá el código previamente escrito en el carácter correspondiente. Por ejemplo, para escribir «ÿ» debería escribir «ff» y luego pulsar Alt+X. Para escribir un espacio duro debería usar «a0» y luego Alt+X, para escribir puntos suspensivos horizontales debería usar «2026» y Alt+X, y así sucesivamente. Por último, puede escribir caracteres especiales mediante el uso de las entidades con nombr HTML. Por ejemplo, si escribe sustituido por un espacio duro al introducir el punto y coma. La sustitución ocurre sólo cuando se escribe el punto y coma Capítulo 1. Secciones

91 La vista del inspector de código Esta vista muestra el código HTML y CSS que se aplica al actual elemento de interés. Se abre pulsando con el botón derecho sobre una ubicación en el panel de vista previa y seleccionando Inspeccionar. Le permite ver el código HTML para ese elemento y lo más importante, los estilos CSS que se aplican al mismo. Incluso puede editar dinámicamente los estilos y ver qué efecto tienen los cambios al instante. Tenga en cuenta que la edición de los estilos en realidad no realiza cambios en el contenido del libro, sólo permite una experimentación rápida. La capacidad de modificación en tiempo real del inspector está en desarrollo. Organizar archivos en carpetas por tipo Often when editing EPUB files that you get from somewhere, you will find that the files inside the EPUB are arranged haphazardly, in different sub-folders. This tool allows you to automatically move all files into sub-folders based on their types. Access it via Tools->Arrange into folders. Note that this tool only changes how the files are arranged inside the EPUB, it does not change how they are displayed in the Files Browser. Importar archivos en otros formatos de libro electrónico como EPUB El editor incluye la habilidad de importar archivos en otros formatos de libro electrónico directamente como un nuevo EPUB, sin requerir una conversión total. Esto es particularmente útil para crear archivos EPUB a partir de archivos HTML editados a mano. Puede hacer esto por medio de Archivo > Importar un archivo HTML o DOCX como un libro nuevo. Modo de función para buscar y sustituir en el editor La herramienta de buscar y sustituir en el editor admite un modo de función. En este modo se pueden combinar expresiones regulares (ver Todo acerca de cómo utilizar expresiones regulares en calibre (Página 204)) con funciones de complejidad arbitraria para realizar todo tipo de procesamiento de texto avanzado. En el modo estándar de expresiones regulares para buscar y sustituir, se especifica una expresión regular para buscar y una plantilla que se usa para sustituir todas las coincidencias. En el modo de función, en lugar de usar una sola plantilla, se especifica una función arbitraria en el lenguaje de programación python 33. Esto le permite hacer muchas cosas que no son posibles sólo con plantillas. Algunas técnicas para usar el modo de función y su sintaxis se describirán a través de ejemplos, que le mostrarán cómo crear funciones para realizar tareas cada vez más complejas. Corregir automáticamente las mayúsculas y minúsculas en las cabeceras del documento Aquí aprovecharemos una de las funciones incorporadas del editor para poner la primera letra de cada palabra dentro de una etiqueta de encabezado en mayúscula: Find expression: <([Hh][1-6])[^>]*>.+?</\1> Modificar libros electrónicos 87

92 Como función, elija la función predefinida Capitalize (ignore tags). Esto cambiará los títulos de la forma <h1>algún TÍTULO</h1> a <h1>algún título</h1>. Funcionará incluso si hay otras etiquetas HTML en la etiqueta de cabecera. La primera función personalizada: mejorar guiones La verdadera potencia del modo de función procede de la posibilidad de crear funciones propias para procesar el texto de manera arbitraria. La herramienta Mejorar puntuación del editor no modifica los guiones aislados, así que puede usar esta función para sustituirlos por rayas. Para crear una nueva función, simplemente pulse en el botón Crear o modificar y copie el código python siguiente. def replace(match, number, file_name, metadata, dictionaries, data, functions, *args, **kwargs): return match.group().replace('--', '--').replace('-', '--') Toda función personalizada de buscar y sustituir debe tener un nombre único y consister en una función python llamada «replace», que acepte todos los argumentos mostrados arriba. Por ahora no vamos a preocuparnos de los diferentes argumentos de la función replace(). Fíjese sólo en el argumento match. Representa una coincidencia al realizar una búsqueda y sustitución. La documentación completa se encuentra aquí 34. match.group() devuelve todo el texto de la coincidencia y todo lo que hacemos es sustituir los guiones del texto por rayas, sustituyendo primero los guiones dobles y luego los sencillos. Use esta función con la expresión regular de búsqueda: >[^<>]+< Y sustituirá todos los guiones por rayas, pero sólo en texto real y no dentro de las definiciones de etiqueta HTML. La potencia del modo de función: usar un diccionario para corregir palabras mal divididas por guiones A menudo, los libros electrónicos creados a partir de imágenes de libros impresos contienen palabras mal divididas por guiones: palabras que estaban divididas al final de un renglón en la página impresa. Vamos a escribir una función sencilla para encontrar y corregir automáticamente estas palabras. import regex from calibre import replace_entities from calibre import prepare_string_for_xml def replace(match, number, file_name, metadata, dictionaries, data, functions, *args, **kwargs): def replace_word(wmatch): # Try to remove the hyphen and replace the words if the resulting # hyphen free word is recognized by the dictionary without_hyphen = wmatch.group(1) + wmatch.group(2) if dictionaries.recognized(without_hyphen): return without_hyphen return wmatch.group() # Search for words split by a hyphen text = replace_entities(match.group()[1:-1]) # Handle HTML entities like & corrected = regex.sub(r'(\w+)\s*-\s*(\w+)', replace_word, text, flags=regex.version1 regex.unic return '>%s<' % prepare_string_for_xml(corrected) # Put back required entities Use esta función con la misma expresión de búsqueda anterior, es decir: >[^<>]+< Y corregirá automáticamente todas las palabras con guiones incorrectos en el el texto del libro. El truco principal es utilizar uno de los argumentos adicionales de la función «replace»: dictionaries. Esto se refiere a los diccionarios Capítulo 1. Secciones

93 que el propio editor usa para comprobar la ortografía en el libro. Lo que hace esta función es buscar palabras unidas por un guión, eliminar el guión y comprobar si el diccionario reconoce la palabra compuesta; si lo hace, las palabras originales se sustituyen por la palabra sin guión. Tenga en cuenta que una limitación de esta técnica es que sólo funciona par libros monolingües, porque de manera predeterminada dictionaries.recognized() usa el idioma principal del libro. Enumerar secciones automáticamente Ahora veremos algo un poco diferente. Supongamos que un archivo HTML tiene muchas secciones, cada una con una cabecera en una etiqueta <h2> de esta forma: <h2>algún texto</h2>. Puede crear una función personalizada que numere automáticamente estas cabeceras con números consecutivos, para que tengan esta forma: <h2>1. Algún texto</h2>. def replace(match, number, file_name, metadata, dictionaries, data, functions, *args, **kwargs): section_number = '%d. ' % number return match.group(1) + section_number + match.group(2) # Ensure that when running over multiple files, the files are processed # in the order in which they appear in the book replace.file_order = 'spine' Úselo con la expresión de búsqueda: (?s)(<h2[^<>]*>)(.+?</h2>) Coloque el cursor al principio del archivo y pulse Sustituir todo. Esta función usa otro de los prácticos argumentos adicionales de replace(): el argumento number. Al usar Sustituir todo, number se incrementa automáticamente en cada coincidencia. Otra característica nueva es el uso de replace.file_order. Establecerlo en spine significa que si la búsqueda se ejecuta sobre múltiples archivos HTML, los archivos se procesarán en el orden en el que aparecen en el libro. Más detalles en Elegir un orden de archivos al ejecutar sobre múltiples archivos HTML (Página 92). Crear un índice automáticamente Por último, vamos a intentar algo un poco más ambicioso. Supongamos que el libro tiene encabezados en etiquetas h1 y h2 del tipo <h1 id="un_id">algún texto</h1>. Vamos a crear un índice HTML generado automáticamente a partir de estos encabezados. Creamos la siguiente función: from calibre import replace_entities from calibre.ebooks.oeb.polish.toc import TOC, toc_to_html from calibre.gui2.tweak_book import current_container from calibre.ebooks.oeb.base import xml2str def replace(match, number, file_name, metadata, dictionaries, data, functions, *args, **kwargs): if match is None: # All matches found, output the resulting Table of Contents. # The argument metadata is the metadata of the book being edited if 'toc' in data: toc = data['toc'] root = TOC() for (file_name, tag_name, anchor, text) in toc: parent = root.children[-1] if tag_name == 'h2' and root.children else root parent.add(text, file_name, anchor) toc = toc_to_html(root, current_container(), 'toc.html', 'Table of Contents for ' + metad print (xml2str(toc)) else: print ('No headings to build ToC from found') else: # Add an entry corresponding to this match to the Table of Contents 1.5. Modificar libros electrónicos 89

94 if 'toc' not in data: # The entries are stored in the data object, which will persist # for all invocations of this function during a 'Replace All' operation data['toc'] = [] tag_name, anchor, text = match.group(1), replace_entities(match.group(2)), replace_entities(m data['toc'].append((file_name, tag_name, anchor, text)) return match.group() # We dont want to make any actual changes, so return the original match # Ensure that we are called once after the last match is found so we can # output the ToC replace.call_after_last_match = True # Ensure that when running over multiple files, this function is called, # the files are processed in the order in which they appear in the book replace.file_order = 'spine' Y úselo con la expresión de búsqueda: <(h[12]) [^<>]* id=['"]([^'"]+)['"][^<>]*>([^<>]+) Ejecutamos la búsqueda sobre Todos los archivos de texto y al final de la búsqueda se abrirá una ventana con «Salida de depuración de la función», que contendrá el índice HTML, listo par copiarlo en toc.html. La función de arriba está muy comentada, así que debe ser fácil de seguir. La principal nueva característica es el uso de un argumento adicional de la función replace(), el objeto data. El objeto data es un diccionario python que sobrevive entre sucesivas llamadas a la función replace() durante una única operación Sustituir todo. Otra característica nueva es el uso de call_after_last_match. Establecerlo en True en la función replace() significa que el editor ejecutará replace() una vez adicional después de haber encontrado todas las coincidencias. En esa ejecución adicional el objeto de coincidencia será None. Esto ha sido sólo una demostración de la potencia del modo de función, si realmente necesita generar un índice a partir de encabezados en un libro, es mejor usar la herramienta específica para índices en Herramientas > Índice. La API para el modo de función «replace» y con la siguiente firma: Todas las funciones del modo función deben ser funciones python con el nombre def replace(match, number, file_name, metadata, dictionaries, data, functions, *args, **kwargs): return a_string Cuando se realiza una búsqueda y sustitución, la función replace() se ejecuta para cada coincidencia, debe devolver el texto de sustitución para dicha coincidencia. Si no se ha de efectuar ninguna sustitución, debe devolver match.group(), que es el texto original. Los distintos argumentos de la función replace() se documentan a continuación. El argumento match El argumento match representa la coincidencia actual. Es un objeto Match de python 35. Su método más útil es group(), que puede emplearse para obtener el texto correspondiente a los grupos de captura individuales en la expresión regular de búsqueda. El argumento number El argumento number es el número de la coincidencia actual. Al ejecutar Sustituir todo, cada coincidencia sucesiva da lugar a una ejecución de replace(), con un número que va en aumento. La primera coincidencia tiene el número Capítulo 1. Secciones

95 El argumento file_name Éste es el nombre del archivo donde se encontró la coincidencia actual. Al buscar un texto marcado, file_name está vacío. El argumento file_name está en forma canónica: una ruta de acceso relativa a la raíz del libro, usando / como separador. El argumento metadata Esto representa los metadatos del libro actual, como título, autores, idioma, etc. Es un objeto de clase calibre.ebooks.metadata.book.base.metadata (Página 201). Algunos atributos útiles son title, authors (una lista de autores) y language (el código del idioma). El argumento dictionaries Esto representa la colección de diccionarios usados para la comprobación de ortografía del libro actual. Su método más útil es dictionaries.recognized(word), que devuelve True si la palabra word es reconocida por el diccionario para el idioma del libro actual. El argumento data Esto es un diccionario de python sencillo. Al ejecutar Sustituir todo, cada coincidencia sucesiva da lugar a una ejecución de replace() con el mismo data. Por lo tanto puede usarlo para almacenar datos arbitrarios entre ejecuciones de replace() durante una operación de Sustituir todo. El argumento functions El argumento functions proporciona acceso a todas las otras funciones definidas por el usuario. Esto es útil para la reutilización de código. Puede definir funciones en un lugar y luego reutilizarlas en todas las otras funciones. Por ejemplo, supongamos que crea una función con nombre My Function así: def utility(): # do something def replace(match, number, file_name, metadata, dictionaries, data, functions, *args, **kwargs):... Luego, en otra función, puede acceder a la función utility() de esta manera: def replace(match, number, file_name, metadata, dictionaries, data, functions, *args, **kwargs): utility = functions['my Function']['utility']... También puede usar el objeto functions para guardar datos persistentes que sean accesibles a otras funciones. Por ejemplo, puede tener una función que al ejecutarse con Sustituir todo recopile datos y otra función que los use cuando se ejecuta a continuación. Considere las dos funciones siguientes: # Function One persistent_data = {} def replace(match, number, file_name, metadata, dictionaries, data, functions, *args, **kwargs):... persistent_data['something'] = 'some data' # Function Two def replace(match, number, file_name, metadata, dictionaries, data, functions, *args, **kwargs): persistent_data = functions['function One']['persistent_data']... Depurar las funciones propias Puede depurar las funciones que cree con la función estándar de python print(). La salida de print() se mostrará en una ventana emergente cuando la búsqueda y sustitución se haya completado. Ya hemos visto anteriormente un ejemplo del uso de print() para mostrar un índice completo Modificar libros electrónicos 91

96 Elegir un orden de archivos al ejecutar sobre múltiples archivos HTML Al ejecutar Sustituir todo sobre múltiples archivos HTML, el orden en que se procesan los archivos depende de qué archivos estén abiertos para modificar. Puede hacer que la búsqueda procese los archivos en el orden en el que aparecen estableciendo el attributo file_order de la función, de esta manera: def replace(match, number, file_name, metadata, dictionaries, data, functions, *args, **kwargs):... replace.file_order = 'spine' file_order acepta dos valores, spine y spine-reverse, que hacen que el la búsqueda procese archivos múltiples en el orden en que aparecen en el libro, hacia adelante o hacia atrás, respectivamente Hacer que una función se ejecute una vez más después de la última coincidencia A veces, como en el ejemplo anterior del índice generado automáticamente, es útil que la función se ejecute una vez adicional después de haber encontrado la última coincidencia. Puede conseguir esto estableciendo el atributo call_after_last_match en la función, de esta manera: def replace(match, number, file_name, metadata, dictionaries, data, functions, *args, **kwargs):... replace.call_after_last_match = True Fragmentos El editor de calibre admite fragmentos. Un fragmento es una porción de texto que se reutiliza a menudo o contiene gran cantidad de texto redundante. El editor le permite insertar un fragmento con unas pocas pulsaciones de tecla. Por ejemplo, supongamos inserta a menudo etiquetas de enlace cuando modifica archivos HTML, entonces podrá escribir simplemente <a en el editor y pulsar Control+J. El editor lo expandirá a: <a href="filename"></a> No sólo eso, la palabra filename estará seleccionada, con el cursor sobre ella, para que pueda teclear el nombre de archivo real usando la función Completado automático (Página 96) del editor. Y una vez que haya terminado de escribir el nombre de archivo, pulse Control+J de nuevo y el cursor saltará a la posición entre las etiquetas <a> para que pueda teclear directamente el texto par el enlace. El sistema de fragmentos del editor es muy sofisticado, hay algunos fragmentos predefinidos y puede crear otros adecuados para su estilo de modificación. La siguiente discusión sobre los fragmentos predefinidos debería ayudar a ilustrar la potencia del sistema de fragmentos. Nota: También puede usar fragmentos en los campos de entrada de texto del panel de Buscar y sustituir, pero los marcadores de posición (para pasar por ellos usando Control+J) no funcionarán. Los fragmentos predefinidos Los fragmentos predefinidos se definen a continuación. Tenga en cuenta que puede reemplazarlos creando fragmentos propios con el mismo texto de activación. Insertar texto de relleno [Lorem] El primer fragmento predefinido y el más simple, se usa para insertar texto de relleno en un documento. El texto de relleno se toma de De finibus bonorum et malorum 36, una obra filosófica de Capítulo 1. Secciones

97 Cicerón (traducida al inglés). Para usarlo, simplemente teclee Lorem en un archivo HTML y pulse Control+J. Se sustituirá por un par de párrafos de relleno. La definición de este fragmento es muy simple, el texto de activación se define como Lorem y la plantilla no es más que el texto literal que se inserta. Es muy sencillo personalizarlo par usar el texto de relleno que prefiera. Insertar una etiqueta HTML con cierre incorporado [<>] Veamos un ejemplo sencillo del potente concepto de marcadores de lugar. Digamos que quiere insertar la etiqueta con cierre incorporado <hr/>. Únicamente teclee <> y pulse Control+J, el editor expandirá el fragmento a: < /> Aquí, el símbolo representa la posición actual del cursor. Ahora puede teclear hr y pulsar Control+J para mover el cursor al final de la etiqueta. Este fragmento está definido como: Trigger: <> Template: <$1/>$2 Los marcadores de posición son simplemente el símbolo de dólar ($) seguido de un número. Cuando el fragmento se expande al pulsar Control+J el cursor se coloca en el primer marcador de posición (el que tenga el número más bajo). Cuando pulsa Control+J otra vez el cursor se desplaza al siguiente marcador de posición (el que tenga el siguiente número más bajo). Insertar un enlace HTML [<a] Todas las etiquetas de enlace HTML tienen una estructura común. Tienen un atributo href y algún texto entre las etiquetas de apertura y cierre. Vamos a ver otras características de los marcadores de posición con un fragmento que hará más eficiente teclear estas etiquetas. Para usar este fragmento, simplemente teclee <a y pulse Control+J. El editor lo expandirá a: <a href="filename "></a> No sólo eso, la palabra filename estará seleccionada, con el cursor sobre ella, para que pueda teclear el nombre de archivo real usando la función Completado automático (Página 96) del editor. Y una vez que haya terminado de escribir el nombre de archivo, pulse Control+J de nuevo y el cursor saltará a la posición entre las etiquetas <a> para que pueda teclear directamente el texto par el enlace. Cuando termine de escribir el texto, pulse Control+J otra vez para saltar a la derecha de la etiqueta de cierre. Este fragmento está definido como: Trigger: <a Template: <a href="${1:filename}">${2*}</a>$3 Hay un par de nuevas características. Primero, el marcador $1 se ha vuelto más complejo. Ahora incluye un texto predeterminado (la palabra filename). Si un marcador de posición contiene un texto predeterminado, el marcador se sustituye por el texto al expandir el fragmento. Además, al saltar a un marcador con texto predeterminado usando Control+J, el texto se selecciona. De esta manera, puede usar el texto predeterminado como un recordatorio para rellenar las partes importantes de la plantilla. Puede especificar un texto predeterminado para un marcador de posición usando la sintaxis: ${<número>:texto predeterminado}. La otra nueva característica es que el segundo marcador de posición tiene un asterisco al final (${2*}). Esto significa que cualquier texto que estuviera seleccionado antes de expandir la plantilla sustituirá al marcador. Para verlo en acción, seleccione algún texto en el editor, pulse Control+J, teclee <a y pulse Control+J otra vez, la plantilla se expandirá a: <a href="filename">whatever text you selected</a> Insertar una etiqueta de imagen HTML [<i] Esto es muy parecido a insertar un enlace HTML, como hemos visto anteriormente. Le permite introducir rápidamente <img src="filename" alt="description" /> y saltar entre los atributos src y alt: 1.5. Modificar libros electrónicos 93

98 Trigger: <i Template: <img src="${1:filename}" alt="${2*:description}" />$3 Insertar una etiqueta HTML arbitraria [<<] Esto le permito insertar una etiqueta completa HTML arbitraria (o incluir un texto previamente seleccionado en la etiqueta). Para usarlo, teclee << y pulse Control+J. El editor lo expandirá a: < ></> Teclee el nombre de la etiqueta, por ejemplo span, y pulse Control+J, el resultado será: <span> </span> Verá que la etiqueta de cierre se ha rellenado automáticamente con span. Esto se obtiene gracias a otra característica de los marcadores de posición, la duplicación. Duplicación significa simplemente que si especifica el mismo marcador más de una vez en una plantilla, la segunda posición y las posteriores se rellenarán automáticamente, al pulsar Control+J, con lo que haya tecleado en la primera posición. La definición para este fragmento es: Trigger: << Template: <$1>${2*}</$1>$3 Como puede ver, el primer marcador de posición ($1) se ha especificado dos veces, la segunda en la etiqueta de cierre, lo que sencillamente copiará lo que sea que haya introducido en la etiqueta de apertura. Insertar una etiqueta HTML arbitraria con un atributo de clase [<c] Esto es muy parecido al ejemplo anterior de inserción de una etiqueta arbitraria, excepto que supone que querrá especificar una clase para la etiqueta: Trigger: <c Template: <$1 class="${2:classname}">${3*}</$1>$4 Esto le permitirá teclear primero el nombre de la etiqueta, pulsar Control+J, teclear el nombre de clase, pulsar Control+J, teclear el contenido de la etiqueta y pulsar Control+J una última vez para saltar fuera de la etiqueta. La etiqueta de cierre se rellenará automáticamente. Crear fragmentos propios Lo mejor de los fragmentos es que puede crear los suyos propios que mejor se adapten a su estilo. Para crear fragmentos propios vaya a Editar > Preferencias > Configuración del editor > Administrar fragmentos en el editor. Esto mostrará un cuadro de diálog fácil de usar que le ayudará a crear fragmentos. Pulse en el botón Añadir fragmento y verá un cuadro de diálogo parecido a: 94 Capítulo 1. Secciones

99 Primero asigne un nombre al fragmento, algo descriptivo, para ayudarle a identificar el fragmento en el futuro. Luego especifique el activador. Un activador no es más que el texto que debe teclear en el editor antes de pulsar Control+J para expandir el fragmento. Después especifique la plantilla del fragmento. Es recomendable que empiece con alguno de los ejemplos anteriores y lo modifique según sus necesidades. Finalmente, especifique en qué tipos de archivo quiere que esté disponible el fragmento. De esta forma puede tener varios fragmentos con el mismo texto activador que funcionan de manera distinta en distintos tipos de archivo. El siguiente paso es probar el fragmento recién creado. Use el cuadro Prueba en la parte inferior. Teclee el texto activador y pulse Control+J para expandir el fragmento y para saltar entre los marcadores de posición. La herramienta de Informes El editor incluye una útil herramienta de Informes (en Herramientas > Informes) que muestra resúmenes de los archivos, imágenes, enlaces, palabras, caracteres y estilos usados en el libro. Cada línea del informe es activa. Al pulsar dos veces en una línea se salta al lugar del libro donde se usa o define (según sea más apropiado) el elemento. Por ejemplo, en la vista de Enlaces, puede pulsar dos veces en la columna Origen para saltar al lugar donde se define el enlace y en las entradas de la columna Destino para saltar a donde apunta el enlace Modificar libros electrónicos 95

100 1.5.9 Características especiales del editor de código El editor de HTML de calibre es muy potente. Tiene muchas funciones que facilitan la modificación de HTML (y CSS). Resaltado de sintaxis El editor HTML tiene un resaltado de sintaxis muy sofisticado. Sus características incluyen: El texto dentro de etiquetas de negrita, cursiva o cabeceras se muestra en negrita o cursiva Al mover el cursor por el HTML, se resaltan las etiquetas HTML emparejadas El código HTML no válido se subraya en rojo Los problemas de ortografía en el texto dentro de las etiquetas HTML y en atributos como «title» se resaltan. La comprobación de ortografía detecta el idioma especificado en el atributo «lang» de la etiqueta actual y el idioma global del libro. El código CSS dentro de etiquetas <style> también se resalta Los caracteres especiales que pueden ser indistinguibles, como espacios duros, diferentes tipos de guiones y rayas, etc., se resaltan Los enlaces a otros archivos en etiquetas <a>, <img> y <link> tienen el nombre de archivo resaltado. Si el archivo al que apuntan no existe, el nombre se subraya en rojo. Ayuda sensible al contexto Puede pulsar con el botón derecho sobre cualquier nombre de etiqueta o de propiedad CSS para obtener ayuda para esa etiqueta o propiedad. También puede mantener pulsada la tecla Ctrl y pulsar sobre cualquier nombre de archivo en una etiqueta de enlace para abrir dicho archivo automáticamente en el editor. Completado automático Al modificar un libro, una de las tareas más engorrosas es crear enlaces a otros archivos dentro del libro, a hojas de estilo CSS o a imágenes. Debe encontrar el nombre y ubicación relativa correctos para el archivo. El editor tiene una 96 Capítulo 1. Secciones

101 función de completado automático para hacerlo más sencillo. Según teclea un nombr de archivo, el editor muestra sugerencias automáticas. Use la tecla de tabulador para seleccionar el nombre correcto. El editor también ofrece sugerencias para enlaces que apuntan a un punto de anclaje dentre de otro archivo HTML. Después de introducir el carácter #, el editor mostrará una lista de todos los puntos de anclaje en el archivo de destino, con un pequeño fragmento de texto para ayudarle a elegir el punto de anclaje correcto. Tenga en cuenta que, a diferencia de la mayoría de sistemas de completado, el sistema usa una correspondencia de subsecuencias. Esto significa que puede teclear sólo dos o tres letras de cualquier parte del nombre de archivo para completarlo. Por ejemplo, supongamos que quiere el nombre de archivo../imagenes/flecha1.png, puede teclear simplemente if1 y pulsar el tabulador para completar el nombre de archivo. Al buscar coincidencias, el sistema de completado da prioridad a las letras que están al inicio de una palabra, o justo detras de un separador de ruta. Cuando se acostumbre a este sistema, notará que ahorra mucho tiempo y esfuerzo. Fragmentos El editor de calibre admite fragmentos. Un fragmento es una porción de texto que se reutiliza a menudo o contiene gran cantidad de texto redundante. El editor le permite insertarun fragmento con unas pocas pulsaciones de tecla. Los fragmentos son muy potentes, con muchas funciones como marcadores de posición por los que puede desplazarse, duplicación automática de texto repetido, etc. Para más información, véase Fragmentos (Página 92). 1.6 Comparar libros electrónicos calibre incluye una herramienta integrada de comparación de libros electrónicos que se puede utilizar para ver lo que ha cambiado en el interior de un libro electrónico después de editarlo o convertirlo. Puede comparar libros en los formatos EPUB y AZW3. Para usarla, sea abrir el libro en la herramienta para Modificar libros electrónicos (Página 69) y después pulse en Archivo > Comparar con otro libro o use el panel Detalles del libro (Página 15). Si hace una conversion de EPUB a EPUB, el archivo EPUB original se guardará como ORIGINAL_EPUB. Simplemente pulse con el botón derecho en la entrada ORIGINAL_EPUB en el panel de los detalles del libro y seleccione Comparar con formato EPUB. La herramienta de comparación que se abre será parecida a la siguiente imagen. Muestra las diferencias en el texto, estilos e imágenes entre los libros elegidos Comparar libros electrónicos 97

102 1.6.1 Comprender la vista de comparación Como se puede ver en la imagen anterior, la vista de comparación muestra las diferencias entre los dos libros uno junto a otro. Sólo se muestran las diferencias con unas pocas líneas de contexto a su alrededor. Esto hace que sea fácil ver de un vistazo sólo lo que ha cambiado dentro de un documento de gran tamaño como un libro. El texto añadido se muestra con un fondo verde, el texto eliminado con un fondo rojo y el texto modificado con un fondo azul. Los números de línea de todo el texto modificado se muestran en los lados, por lo que es fácil desplazarse a un cambio determinado en el editor. Al abrir la herramienta de comparación desde el editor, también puede pulsar dos veces en una línea en el panel de la derecha para ir a esa línea en el editor de forma automática. Una técnica útil cuando se comparan libros es decirle a la herramienta de comparación que embellezca los archivos de texto y estilo antes de calcular las diferencias. Esto a menudo puede resultar en diferencias más limpias y más faciles de seguir. Para ello, pulse en el botón :guilabel: Opciones en la parte inferior derecha y elija Embellecer los archivos 98 Capítulo 1. Secciones

103 antes de compararlos. Tenga en cuenta que el embellecimiento a veces puede tener efectos no deseados, ya que puede causar que un código no válido pase a ser válido. También puede cambiar el número de líneas de contexto que se muestran en torno a las diferencias mediante el botón :guilabel: Opciones. Puede buscar cualquier texto en las diferencias a través de la barra de búsqueda en la parte inferior. Tendrá que especificar en qué panel buscar, el Izquierdo o el Derecho Cómo iniciar la herramienta de comparación La herramienta de comparación es más útil cuando se tienen dos versiones de un mismo libro y se desea ver lo que es diferente entre ellos. Hay varias formas de iniciar la herramienta. Comparar dos archivos de libro electrónico Abra el primer archivo en la herramienta Modificar libros electrónicos (Página 69). Ahora pulse en Archivo > Comparar con otro libro y elija el segundo archivo (debe estar en el mismo formato que el primero). La vista de comparación se abrirá con el archivo que se está modificando a la derecha y el otro a la izquierda. Comparar el ORIGINAL_FMT con FMT Cuando realiza una conversión en calibre desde un FMT a sí mismo, el archivo original es guardado como ORI- GINAL_FMT. Puede ver qué ha cambiado en la conversión, pulsando con el botón derecho en la entrada ORIGI- NAL_FMT en el panel Detalles del libro (Página 15) de la ventana principal de calibre y seleccionando Comparar con FMT. La vista de comparación se abrirá con el ORIGINAL_FMT a la izquierda y el FMT a la derecha. Comparar un hito con el estado actual del libro durante su modificación La herramienta Modificar libros electrónicos (Página 69) posee una función muy útil, llamada Hitos (Página 81). Esto le permite guardar el estado actual de un libro como un hito, al cual puede retornar si no le agrada los cambios que ha hecho desde que se creó el hito. Estos hitos también se crean automáticamente cuando realizan algunas acciones automatizadas. Puede ver la lista de hitos en Ver > Hitos y después puede usar el botón Comparar para comparar el libro en el hito seleccionado con el estado actual. La herramienta de comparación mostrará el hito a la izquierda y el estado actual a la derecha. 1.7 Modificar metadatos de libros electrónicos Índice Editar metadatos de libros, de uno en uno (Página 100) Descargar metadatos (Página 100) Gestionar formatos de libros (Página 100) Todo sobre las portadas (Página 100) Modificar los metadatos de varios libros a la vez (Página 101) Buscar y sustituir (Página 101) Descargar metadatos en masa (Página 102) Los libros electrónicos vienen en todas formas y tamaños, y en la mayoría de las ocasiones sus metadatos (tales como título, autor, serie, editorial) son incompletos o incorrectos. La forma más sencilla de cambiar los metadatos en calibre 1.7. Modificar metadatos de libros electrónicos 99

104 es simplemente pulsar dos veces sobre una entrada y escribir el dato correcto. Para un modificación más sofisticada, utilice las herramientas de edición de metadatos discutidas a continuación Editar metadatos de libros, de uno en uno Pulse en el libro que desea editar y luego en el botón Modificar metadatos o pulse la tecla E. Se abrirá un cuadro de diálogo que le permite modificar toda clase de metadatos. Tiene diversas funciones para hacer la modificación más rápida y eficiente. Una lista de los consejos más prácticos: Puede pulsar en el botón entre título y autores para intercambiarlos automáticamente. Puede pulsar en botón junto al orden de autor para que calibre rellene el campo automáticamente usando el valor de orden almacenado para cada autor. Utilice el cuadro de diálogo Administrar autores para ver y cambiar los valores de orden de autores. Este cuadro de diálogo se puede abrir manteniendo pulsado el botón junto al orden de autor. Puede pulsor en el botón junto a las etiquetas para usar el editor de etiquetas para gestionar las etiquetas asociadas con el libro. El cuadro ISBN tendrá un fondo rojo si introduce un ISBN no válido. Será verde para los ISBN válidos El cuadro de orden de autor será de color rojo si el valor del orden de autor difiere de lo que calibre piensa que debería ser. Descargar metadatos La mejor característica del cuadro de diálogo de modificación de metadatos es la posibilidad de rellenar automáticamente muchos de os campos de metadatos al obtenerlos de diversos sitios de Internet. Actualmente, calibre utiliza isbndb.com, Google Books, Amazon y Library Thing. La descarga de metadatos puede rellenar el título, autor, serie, etiquetas, calificación, descripción e ISBN. Para utilizar la descarga, rellene los campos de título y autor y pulse en el botón Descargar metadatos. calibre le presentará una lista de los libros que mejor coinciden con el título y el autor. Si rellena el campo ISBN primero, se le dará prioridad con respecto respecto al título y autor. Si no se encuentran coincidencias, trate de hacer su búsqueda un poco menos específica incluyendo sólo algunas palabras clave en el título y sólo el apellido del autor. Gestionar formatos de libros En calibre, una sola entrada de libro puede tener varios formatos diferentes asociados. Por ejemplo, puede haber obtenido las obras completas de Cervantes en formato EPUB y haberlas convertido más tarde a MOBI para leerlas en el Kindle. calibre gestiona automáticamente múltiples formatos. En la sección Formatos disponibles del cuadro de diálogo Modificar metadatos, puede administrar estos formatos. Puede agregar un nuevo formato, borrar uno existente y también solicitar a calibre que obtenga los metadatos y la portada del libro a partir de los metadatos contenidos en alguno de los formatos. Todo sobre las portadas Puede hacer que calibre descargue las portadas de los libros, siempre y cuando el libro posea un ISBN conocido. Alternativamente, puede especificar un archivo en el equipo para utilizarlo como portada. calibre puede incluso generar una portada predeterminada con metadatos básicos. Puede arrastrar y soltar imágenes sobre la portada para cambiarla o hacer click con el botón derecho para copiar y pegar imágenes. Además, hay un botón para recortar automáticamente los bordes de la portada, en el caso que la imagen de la portada tenga un borde antiestético. 100 Capítulo 1. Secciones

105 1.7.2 Modificar los metadatos de varios libros a la vez Primero seleccione los libros que desea editar manteniendo presionada la tecla Ctrl o Mayúsculas y pulsando sobre ellos. Si selecciona más de un libro, pulse en el botón Modificar metadatos lo que provocará que se abra un nuevo cuadro de diálogo de Modificar metadatos en masa. Usando este cuadro, puede establecer rápidamente el autor, editorial, calificación, etiquetas, series, etc de un conjunto de libros con el mismo dato. Esto es particularmente útil si acaba de importar es una serie de libros que tienen varios metadatos en común. Esta función es muy potente, por ejemplo, tiene una pestaña de buscar y sustituir que se puede utilizar para llevar a cabo operaciones masivas sobre los metadatos e incluso copiar los metadatos de una columna a otra. El cuadro de diálogo de modificar metadatos normal también posee los botones Siguiente y Anterior que puede utilizar para modificar los metadatos de varios libros uno tras otro. Buscar y sustituir El cuadro de diálogo de edición de metadatos en masa le permite realizar operaciones de búsqueda y sustitución de complejidad arbitrara en los libros seleccionados. De manera predeterminada usa una búsqueda y sustitución simple de texto, pero también admite expresiones regulares. Para más información sobre las expresiones regulares, consulte Todo acerca de cómo utilizar expresiones regulares en calibre (Página 204). Como se señaló anteriormente, hay dos modos de buscar y sustituir: coincidencia de caracteres y expresión regular. Coincidencia de caracteres buscará en el Campo de búsqueda que elija los caracteres que escriba en el cuadro Buscar y las sustituirá por los que escriba en el cuadro Sustituir por. Todas las instancias de los caracteres buscados en el campo se sustituirán. Por ejemplo, supongamos que el campo que se está buscado contiene un gato malo. Si busca a para sustituirla por HOLA, el resultado será un gholato mholalo. Si el campo en el que está buscando es un campo múltiple como las etiquetas, entonces cada etiqueta se considera separadamente. Por ejemplo, si las etiquetas contienen Horror, Miedo, la expresión de búsqueda r, no encontrará nada, porque la expresión se aplicará primero a Horror y después a Miedo. Si desea que la búsqueda ignore las diferencias entre mayúsculas y minúsculas, desactive la casilla Distinguir mayúsculas. Puede hacer que calibre cambie las mayúsculas y minúsculas de los resultados de las búsquedas (información después de sustituir) eligiendo una de las funciones del cuadro Aplicar función después de sustituir. Las operaciones disponibles son: Minúsculas cambia todos los caracteres del campo a minúsculas Mayúsculas cambia todos los caracteres del campo a mayúsculas Mayúsculas iniciales cambia a mayúscula la primera letra de cada palabra en el resultado. En el cuadro Su prueba puede introducir texto para comprobar que el efecto de buscar y sustituir es el deseado. En la mayoría de los casos, los cuadros de prueba de libro serán suficiente, pero es posible que haya un caso que quiera comprobar y que no se muestre en estos cuadres. Intruduzca dicho caso en Su prueba. El modo de expresión regular tiene algunas diferencias con respecto al modo de caracteres, más allá, evidentemente, del hecho de usar expresiones regulares. La primera es que las funciones se aplican a las partes del texto que coincidan con el texto de búsqueda, no a todo el campo. La segunda es que las funciones se aplican al texto de sustitución, no a todo el campo. La tercera y más importante es que el texto de sustitución puede hacer referencia a partes del texto de búsqueda mediante el uso de retroreferencias. Una retroreferencia es \\n donde n es un entero que se refiere al grupo entre paréntesis número n en la expresión de búsqueda. Por ejemplo, dado el mismo ejemplo anterior, un gato malo, una expresión de búsqueda un (...) (...), y una expresión de reemplazo un \2 \1, el resultado será un malo gato. Consulte el Todo acerca de cómo utilizar expresiones regulares en calibre (Página 204) para obtener más información acerca de las retroreferencias Modificar metadatos de libros electrónicos 101

106 Una pauta útil: supongamos que desea cambiar las mayúsculas y minúsculas de un campo entero. La forma más sencilla de hacerlo es utilizar el modo de caracteres, pero supongamos que desea utilizar el modo de expresión regular. La expresión de búsqueda debe ser (.*) la expresión de sustitución debe ser \1, y tendrá que seleccionar la función de cambio de mayúsculas y minúsculas que desee. Finalmente, en el modo de expresión regular puede copiar los valores de un campo a otro. Simplemente ponga diferentes campos en origen y destino. La copia puede sustituir el campo de destino, anteponerse al campo (añadirse al principio), o añadirse al campo (añadirse al final). La casilla de verificación «usar coma» hace que calibre añada (o no) una coma entre el texto y el campo de destino en los modos de anteponer y añadir. Si el destino es múltiple (por ejemplo, etiquetas), entonces no se puede desactivar esta casilla. La búsqueda y sustitución se realiza después de aplicar todos los cambios en los metadatos de las otras pestañas. Esto puede llevar a cierta confusión, ya que los cuadros de prueba mostrarán la información anterior a los otros cambios, pero la operación se aplicará después de ellos. Si tiene alguna duda sobre lo que pueda suceder, no mezcle buscar y sustituir con otros cambios. Descargar metadatos en masa Si quiere descargar los metadatos de varios libros a la vez, pulse en el botón Modificar metadatos y seleccione Descargar metadatos. Puede elegir descargar sólo metadatos, sólo portadas o ambos. 1.8 Preguntas frecuentes Índice Conversión de formatos de libro electrónico (Página 102) Integración con dispositivos (Página 106) Gestión de la biblioteca (Página 113) Miscelánea (Página 117) Conversión de formatos de libro electrónico Índice Qué formatos puede convertir calibre? (Página 103) Cuáles son los mejores formatos de origen para convertir?. (Página 103) He convertido un archivo PDF, pero el resultado tiene varios problemas. (Página 103) Cómo convierto un archivo que contiene caracteres «exóticos» (acentuados, no latinos, comillas tipográficas, etc.)? (Página 103) Qué ocurre con los índices de los archivos MOBI? (Página 103) Las portadas de los archivos MOBI han dejado de aparecer en Kindle para PC, Kindle para Android, ipad, etc. (Página 104) Cómo convierto una colección de archivos HTML en un orden específico? (Página 105) El EPUB que he creado con calibre no es válido (Página 105) Cómo puedo utilizar algunas de las funciones avanzadas de las herramientas de conversión? (Página 105) 102 Capítulo 1. Secciones

107 Qué formatos puede convertir calibre? calibre soporta la conversión de muchos formatos de entrada a muchos formatos de salida. Puede convertir cualquier formato de entrada de la siguiente lista a cualquier formato de salida. Formatos de entrada: AZW, AZW3, AZW4, CBZ, CBR, CBC, CHM, DJVU, DOCX, EPUB, FB2, HTML, HTMLZ, LIT, LRF, MOBI, ODT, PDF, PRC, PDB, PML, RB, RTF, SNB, TCR, TXT, TXTZ Formatos de salida: Nota: PRC es un formato genérico. calibre soporta archivos PRC con cabeceras TextRead y MOBIBook. PDB es tambien un formato genérico. calibre soporta archivos PDB ereader, Plucker, PML y ztxt. El soporte DJVU es solamente para convertir los archivos DJVU que contienen texto incrustado. Éstos están normalmente generados por por software OCR. Los libros MOBI pueden ser de dos tipos Mobi6 y KF8. calibre soporta ambos tipos. Los archivos MOBI usualmente tienen extensiones.azw o.azw3. Los archivos DOCX de Microsoft Word 2007 en adelante están soportados. Cuáles son los mejores formatos de origen para convertir?. En orden de preferencia decreciente: LIT, MOBI, AZW, EPUB, AZW3, FB2, DOCX, HTML, PRC, ODT, RTF, PDB, TXT, PDF He convertido un archivo PDF, pero el resultado tiene varios problemas. PDF es un formato terrible como origen de conversión. Puede ver una lista de los distintintos problemas que puede encontrar al convertir archivos PDF en: Convertir documentos PDF (Página 65). Cómo convierto un archivo que contiene caracteres «exóticos» (acentuados, no latinos, comillas tipográficas, etc.)? Hay dos aspectos en este problema: 1. Conocer la codificación del archivo de origen: calibre trata de adivinar qué codificación de caracteres utilizan los archivos de origen, pero a menudo esto es imposible, así que es necesario indicar la codificación que se debe usar. Se puede hacer a través de la interfaz gráfica en el campo Codificación de entrada en la sección Apariencia. Todas las herramientas de línea de órdenes tienen una opción --input-encoding. 2. Al añadir archivos HTML a calibre, puede ser necesario indicarle la codificación que usan. Para hacerlo, vaya a :gulabel: Preferencias > Complementos > Complementos de tipo de archivo y personalice el complemento HTML2Zip, indicando la codificación de los archivos HTML. A partir de ahora al añadir archivos HTML se procesarán correctamente. Los archivos HTML de diferentes fuentes suelen tener codificaciones diferentes, así que puede que sea necesario cambiar la configuración varias veces. Una codificación habitual para archivos de la web es cp1252, así que sugerimos que pruebe con ésta primero. Al convertir archivos HTML, deje el campo de codificación de entrada mencionado anteriormente en blanco. Esto es porque el complemento HTML2Zip convierte automáticamente los HTML añadidos a una codificación estándar (utf-8). Qué ocurre con los índices de los archivos MOBI? Lo primero que hay que saber es que la mayoría de los libros electronicos tienen dos índices. El primero es un índice común, tal como se hallaría en un libro de papel. Este índice forma parte del flujo principal del documento, y se puede modificar su formato. A este índice lo llamamos índice de contenido Preguntas frecuentes 103

108 También está el índice de metadatos. Un índice de metadatos es un índice que no forma parte del texto del libro y al que se accede normalmente a través de un botón especial en el lector. Por ejemplo, en el lectorde calibre puede usar el botón Índice para ver este índice. El aspecto de este índice no está especificado por creador del libro, sino que depende del programa de lectura. En formato MOBI la situación es algo confusa debido a que es el único formato de los habituales para ebooks que no tiene soporte decente para índice de metadatos. Un libro MOBI simula la presencia de un índice de metadatos poniendo un índice de contenido adicional al final del libro. Cuando selecciona «Ir al índice» en un Kindle, éste va dicho índice de contenido adicional. Puede parecer que el libro MOBI tiene dos índices idénticos. Recuerde que uno es semánticamente el índice de contenido y el otro el de metadatos, a pesar de que ambos tengan las mismas entradas y el mismo aspecto. A uno se puede acceder directamente desde el menú del Kindle, al otro no. Al convertir a MOBI, calibre detecta el indice de metadatos en el documento de entrada y genera un índice al final de archivo en el MOBI. Puede deshabilitar esta opción en la configuración de salida MOBI. También puede indicar a calibre que lo ponga al principio o al final del libro en la configuración de salida MOBI. Recuerde que este índice es semánticamente un índice de metadatos, en cualquier formato que no sea MOBI no puede ser parte del texto. El hecho de que sea parte el texto en MOBI es accidental debido a las limitaciones de MOBI. Si quiere un índice en un lugar concreto del texto del documento, cree uno a mano. Recomendamos que deje las opciones predeterminadas tal cual están, es decir, con el índice de metadatos al final del libro. También tenga en cuenta que si deshabilita la generación del índice al final del archivo, puede que el MOBI no funcione correctamente en un Kindle, ya que el Kindle usa el índice de metadatos para diversas funciones, incluyendo el paso rápido de páginas. Si tiene un índice editado a mano en el documento de entrada, puede usar las opciones de detección de índice de calibre para generar automáticamente el índice de metadatos a partir de aquél. Consulte la sección de conversión del Manual de usuario para obtener más detalles sobre cómo usar estas opciones. Por último, recomendamos eliminar el índice de contenido y mantener únicamente el índice de metadatos en los libros electrónicos. Los índices de metadatos proporcionan a los lectores una experiencia de navegación muy superior (excepto en Kindle, donde son esencialmente iguales a que un índice de contenido). Nota: El formato AZW3, más reciente, tiene soporte adecuado para el índice de metadatos. Sin embargo, el firmware de Kindle tiende a fallar si se deshabilita la generación del índice al final del archivo. Por lo tanto, se recomienda no tocar el índice generado. Si crea un archivo AZW3 con índice de metadatos sin índice generado al final del archivo, algunas características del Kindle no funcionarán, como el paso rápido de página. Las portadas de los archivos MOBI han dejado de aparecer en Kindle para PC, Kindle para Android, ipad, etc. Esto se debe a un arror en el software de Amazon. Puede evitarlo yendo a Preferencias > Opciones de salida > Salida MOBI y seleccionando la opción «Activar el intercambio del contenido del libro». Si está reconvirtiendo un libro anteriormente convertido, también deberá habilitar la opción del diálogo de conversión para ese libro concreto (puesto que las configuraciones de conversión libro a libro se guardan y tienen preferencia). Tenga en cuenta esto hará que el MOBI generado aparezca en «Documentos personales» en vez de en «Libros» en el Kindle Fire, y la sincronización de Amazon no funcionará, pero las portadas sí. Debe elegir qué funcionalidad es más importante. Recomendamos contactar con Amazon y pedirles que arreglen este error. El problema en el software de Amazon es que al pasar un archivo MOBI a un Kindle, a menos que el archivo esté marcado como documento personal, Amazon supone que el libro ha sido comprado en Amazon e intenta descargar la miniatura de portada de sus servidores. Cuando falla la descarga, se niega a usar la portada definida en el archivo MOBI. Esto es probablemente una acción deliberada por parte de Amazón para tratar de obligar a los autores a vender sólo a través de ellos. En otras palabras, los Kindles sólo muestran las portadas de los libros marcados como documento personal o descargados directamente de Amazon 104 Capítulo 1. Secciones

109 Si envía un archivo MOBI a un Kindle con calibre usando una conexión USB, calibre evita este problema enviando él mismo la portada. Sin embargo, esta solución sólo es posible si se usa una conexión USB y se envía el libro con calibre. Tenga en cuenta que si envía el libro mediante correo electrónico, Amazón marcará el archivo MOBI automáticamente como documento personal y la portada funcionará, pero el libro aparecerá en los documentos personales. Cómo convierto una colección de archivos HTML en un orden específico? Para convertir una colección de archivos HTML en un orden concreto, debe crear un archivo de índice. Esto es, otro archivo HTML que contenga enlaces a los otros archivos en el orden desado. Dicho archivo tendrá este aspecto: <html> <body> <h1>table of Contents</h1> <p style="text-indent:0pt"> <a href="file1.html">first File</a><br/> <a href="file2.html">second File</a><br/>... </p> </body> </html> Entonces, simplemente añada este archivo HTML a la interfaz gráfica y use el botón de convertir para crear el libro. Puede usar las opciones en la sección Índice del cuadro de diálogo de conversión para controlar cómo se genera el índice. Nota: De manera predeterminada, al añadir archivos HTML, calibre sigue enlaces en los archivos en el orden de profundidad. Esto quiere decir que si el archivo A.html enlaza a B.html, C.html y D.html, pero B.html también enlaza a D.html, entonces los archivos estarán en el orden A.html, B.html, D.html, C.html. Si por el contrario desea que el orden sea A.html, B.html, C.html, D.html deberá indicar a calibre que los añada en el orden de anchura. Puedes hacerlo yendo a Preferencias > Complementos y personalizando el complemento HTML2ZIP. El EPUB que he creado con calibre no es válido calibre no garantiza que los EPUB que produzca sean válidos, la única garantía es que si le proporciona XHTML CSS 2.1 válido, producirá un EPUB válido. calibre se esfuerza por asegurar que los EPUB que produce funcionen realmente como deben en una amplia variedad de dispositivos, un objetivo incompatible con producir EPUB válidos, y que es mucho más importante para la gran mayoría de los usuarios. Si necesita una herramienta que siempre produzca EPUB válidos, calibre no es la adecuada. Esto significa que si quiere enviar un EPUB producido por calibre a una tienda online que use un comprobador de validez para EPUB, debe asegurarse de que el EPUB es válido, cosa que calibre no hace. En otras palabras, debe proporcionar a calibre documentos de entrada XHTML + CSS válidos. Cómo puedo utilizar algunas de las funciones avanzadas de las herramientas de conversión? Puede obtener ayuda sobre cualquier característica individual de los conversores pasando el ratón por encima de ellos en la interfaz gráfica o ejecutando ebook-convert prueba.html.epub -h en una terminal. Un buen punto de partida es el siguiente archivo de demostracion, que muestra algunas de las características avanzadas htmldemo.zip Preguntas frecuentes 105

110 1.8.2 Integración con dispositivos Índice Cuáles dispositivos admite calibre? (Página 106) Cómo puedo ayudar para que mi dispositivo sea compatible con calibre? (Página 106) Mi dispositivo no es detectado por calibre (Página 107) Mi dispositivo no es estándar o es inusual. Qué puedo hacer para conectar con él? (Página 107) Cómo gestiona calibre las colecciones en un lector SONY? (Página 107) Puedo utilizar tanto calibre y el software de SONY para gestionar mi lector? (Página 108) Cómo puedo usar calibre con mi ipad/iphone/ipod touch? (Página 108) Cómo utilizo calibre con mi teléfono o tableta Android o mi Kindle Fire HD? (Página 109) Can I access my calibre books using the web browser in my Kindle or other reading device? (Página 111) Me sale el mensaje de error «Fallo al iniciar el servidor de contenidos: Port 8080 not free on ». (Página 111) No puedo enviar correos electrónicos usando calibre (Página 111) Por qué no se detecta mi dispositivo en Linux? (Página 112) Mi dispositivo está montado en linux como sólo lectura, por lo que calibre no puede conectarse con él. (Página 112) Por qué calibre no es compatible con las colecciones de Kindle o los estantes de Nook? (Página 112) Me sale un error cuando trato de usar calibre con el Kobo Touch, Glo, etc. (Página 112) He enviado algunos libros al Kindle con calibre y no aparecen (Página 113) Cuáles dispositivos admite calibre? calibre puede conectar directamente con todos los lectores de libros electrónicos, smartphones, tablets, etc. principales (y la mayoria de los secundarios). Además, usando la función Conectar a carpeta, puede usar cualqueir lector de libros electrónicos que se muestre como disco USB. Puede incluso conectar dispositivos de Apple (a través de itunes), usando la función Conectar a itunes. Cómo puedo ayudar para que mi dispositivo sea compatible con calibre? Si el dispositivo aparece como un disco USB en el sistema operativo, es muy fácil añadir soporte en calibre. Sólo necesitamos que nos proporcione cierta información: Lista completa de los formatos de libro electrónico compatibles con el dispositivo. Hay algún directorio especial del dispositivo en el que se deban poner los archivos? El dispositivo detecta archivos en subdirectorios? We also need information about your device that calibre will collect automatically. First, if your device supports SD cards, insert them. Then connect your device to the computer. In calibre go to Preferences->Miscellaneous and click the Debug device detection button. This will create some debug output. Copy it to a file and repeat the process, this time with your device disconnected from your computer. Send both the above outputs to us with the other information and we will write a device driver for your device. Once you send us the output for a particular operating system, support for the device in that operating system will appear in the next release of calibre. To send us the output, open a bug report and attach the output to it. See calibre bugs Capítulo 1. Secciones

111 Mi dispositivo no es detectado por calibre Siga estos pasos para encontrar el problema: Make sure that you are connecting only a single device to your computer at a time. Do not have another calibre supported device like an iphone/ipad etc. at the same time. Si está conectando un dispositivo de Apple (ipad, ipod Touch, iphone), utilice el método «Conect to itunes» en las instrucciones de «Introducción» en el hilo Calibre + Apple idevices: Start here 39 (en inglés). Asegúrese de que está ejecutando la última versión de calibre. Siempre se puede descargar la última versión en el sitio de Internet de calibre 40. Puede averiguar qué versión de calibre está ejecutando actualmente examinando la línea inferior de la ventana principal de calibre. Asegúrese de que el sistema operativo ha detectado el dispositivo. Si es así, el dispositivo debería verse en el Explorador de Windows (en Windows) o en Finder (en Mac OS X). En calibre, vaya a Preferencias > Dispositivos ignorados y compruebe que el dispositivo no está siendo ignorado If all the above steps fail, go to Preferences->Miscellaneous and click Debug device detection with your device attached and post the output as a ticket on the calibre bug tracker 41. Mi dispositivo no es estándar o es inusual. Qué puedo hacer para conectar con él? In addition to the Connect to Folder function found under the Connect/Share button, calibre provides a User Defined device plugin that can be used to connect to any USB device that shows up as a disk drive in your operating system. Note: on windows, the device must have a drive letter for calibre to use it. See the device plugin Preferences -> Plugins -> Device Plugins -> User Defined and Preferences -> Miscellaneous -> Get information to setup the user defined device for more information. Note that if you are using the user defined plugin for a device normally detected by a builtin calibre plugin, you must disable the builtin plugin first, so that your user defined plugin is used instead. Cómo gestiona calibre las colecciones en un lector SONY? When calibre connects with the reader, it retrieves all collections for the books on the reader. The collections of which books are members are shown on the device view. When you send a book to the reader, calibre will add the book to collections based on the metadata for that book. By default, collections are created from tags and series. You can control what metadata is used by going to Preferences- >Plugins->Device Interface plugins and customizing the SONY device interface plugin. If you remove all values, calibre will not add the book to any collection. Collection management is largely controlled by the Metadata management option found at Preferences- >Import/Export->Sending books to devices. If set to Manual (the default), managing collections is left to the user; calibre will not delete already existing collections for a book on your reader when you resend the book to the reader, but calibre will add the book to collections if necessary. To ensure that the collections for a book are based only on current calibre metadata, first delete the books from the reader, then resend the books. You can edit collections directly on the device view by double-clicking or right-clicking in the collections column. If Metadata management is set to Only on send, then calibre will manage collections more aggressively. Collections will be built using calibre metadata exclusively. Sending a book to the reader will correct the collections for that book so its collections exactly match the book s metadata, adding and deleting collections as necessary. Editing collections on the device view is not permitted, because collections not in the metadata will be removed automatically Preguntas frecuentes 107

112 If Metadata management is set to Automatic management, then calibre will update metadata and collections both when the reader is connected and when books are sent. When calibre detects the reader and generates the list of books on the reader, it will send metadata from the library to the reader for all books on the reader that are in the library (On device is True), adding and removing books from collections as indicated by the metadata and device customization. When a book is sent, calibre corrects the metadata for that book, adding and deleting collections. Manual editing of metadata on the device view is not allowed. Note that this option specifies sending metadata, not books. The book files on the reader are not changed. In summary, choose manual management if you want to manage collections yourself. Collections for a book will never be removed by calibre, but can be removed by you by editing on the device view. Choose Only on send if you want calibre to manage collections when you send a book, adding books to and removing books from collections as needed. Choose Automatic management if you want calibre to keep collections up to date whenever the reader is connected. If you use multiple installations of calibre to manage your reader, then option Automatic management may not be what you want. Connecting the reader to one library will reset the metadata to what is in that library. Connecting to the other library will reset the metadata to what is in that other library. Metadata in books found in both libraries will be flopped back and forth. Puedo utilizar tanto calibre y el software de SONY para gestionar mi lector? Sí, puede usar ambos, siempre y cuando no se utilicen al mismo tiempo. Es decir, se debe utilizar la siguiente secuencia: Conectar el lector > Utilizar uno de los programas > Desconectar el lector. Conectar el lector de nuevo > Usar el otro programa > Desconectar el lector. The underlying reason is that the Reader uses a single file to keep track of meta information, such as collections, and this is written to by both calibre and the Sony software when either updates something on the Reader. The file will be saved when the Reader is (safely) disconnected, so using one or the other is safe if there s a disconnection between them, but if you re not the type to remember this, then the simple answer is to stick to one or the other for the transfer and just export/import from/to the other via the computers hard disk. If you do need to reset your metadata due to problems caused by using both at the same time, then just delete the media.xml file on the Reader using your PC s file explorer and it will be recreated after disconnection. With recent reader iterations, SONY, in all its wisdom has decided to try to force you to use their software. If you install it, it auto-launches whenever you connect the reader. If you don t want to uninstall it altogether, there are a couple of tricks you can use. The simplest is to simply re-name the executable file that launches the library program. More detail in the forums 42. Cómo puedo usar calibre con mi ipad/iphone/ipod touch? Por la red The easiest way to browse your calibre collection on your Apple device (ipad/iphone/ipod) is by using the calibre content server, which makes your collection available over the net. First perform the following steps in calibre Set the Preferred Output Format in calibre to EPUB (The output format can be set under Preferences->Interface- >Behavior) Set the output profile to ipad (this will work for iphone/ipods as well), under Preferences->Conversion- >Common Options->Page Setup Convert the books you want to read on your idevice to EPUB format by selecting them and clicking the Convert button Capítulo 1. Secciones

113 Turn on the Content Server by clicking the Connect/Share button and leave calibre running. You can also tell calibre to automatically start the content server via Preferences->Sharing over the net. There are many apps for your idevice that can connect to calibre. Here we describe using two of them, ibooks and Stanza. Uso de Stanza You should be able to access your books on your iphone by opening Stanza. Go to Get Books and then click the Shared tab. Under Shared you will see an entry Books in calibre. If you don t, make sure your ipad/iphone is connected using the WiFi network in your house, not 3G. If the calibre catalog is still not detected in Stanza, you can add it manually in Stanza. To do this, click the Shared tab, then click the Edit button and then click Add book source to add a new book source. In the Add Book Source screen enter whatever name you like and in the URL field, enter the following: Replace with the local IP address of the computer running calibre. If you have changed the port the calibre content server is running on, you will have to change 8080 as well to the new port. The local IP address is the IP address you computer is assigned on your home network. A quick Google search will tell you how to find out your local IP address. Now click Save and you are done. If you get timeout errors while browsing the calibre catalog in Stanza, try increasing the connection timeout value in the stanza settings. Go to Info->Settings and increase the value of Download Timeout. Con ibooks Inicie el navegador Safari y teclee la dirección IP y el puerto del equipo que está ejecutando el servidor de calibre, de este modo: Replace with the local IP address of the computer running calibre. If you have changed the port the calibre content server is running on, you will have to change 8080 as well to the new port. The local IP address is the IP address you computer is assigned on your home network. A quick Google search will tell you how to find out your local IP address. Verá una lista de libros en Safari, simplemente pulse en el enlace del libro que desee leer, Safari le pedirá que lo abra con ibooks. Con el cable USB e itunes Utilice el método «Conect to itunes» en las instrucciones de «Introducción» en el hilo Calibre + Apple idevices: Start here 43 (en inglés). Este método sólo funciona en Windows Wista o posterior, y OS X hasta Linux no está soportado (itunes no está disponible en linux) y OS X posterior a 10.8 no está soportado, ya que Apple ha eliminado la posibilidad de usar itunes para administrar libros, sustituyéndolo por ibooks Cómo utilizo calibre con mi teléfono o tableta Android o mi Kindle Fire HD? Hay dos maneras de conectar un dispositivo Android con calibre. Usando un cable USB o inalámbricamente. El primer paso es instalar una aplicación de lectura de libros electrónicos en el dispositivo Android. Existen varias aplicaciones Preguntas frecuentes 109

114 gratuitas y de pagos: Algunos ejemplos (sin ningún orden particular): FBReader 44, Moon+ 45, Mantano 46, Aldiko 47, Kindle 48. Con un cable USB Simply plug your device into the computer with a USB cable. calibre should automatically detect the device and then you can transfer books to it by clicking the Send to Device button. calibre does not have support for every single android device out there, so if your device is not automatically detected, follow the instructions at Cómo puedo ayudar para que mi dispositivo sea compatible con calibre? (Página 106) to get your device supported in calibre. Nota: En los dispositivos Android más recientes, la conexión USB no es compatible con Windows XP ni OS X anterior a Mavericks (10.9). Si está usando Windows XP o una versión antigua de OS X, debe utilizar las opciones de conexiones inalámbricas. Por la red The easiest way to transfer books wirelessly to your Android device is to use the Calibre Companion 49 Android app. This app is maintained by a core calibre developer and allows calibre to connect to your Android device wirelessly, just as though you plugged in the device with a USB cable. You can browse files on the device in calibre and use the Send to device button to transfer files to your device wirelessly. calibre also has a builtin web server, the Content Server. You can browse your calibre collection on your Android device is by using the calibre content server, which makes your collection available over the net. First perform the following steps in calibre Set the Preferred Output Format in calibre to EPUB for normal Android devices or MOBI for Kindles (The output format can be set under Preferences->Interface->Behavior) Convert the books you want to read on your device to EPUB/MOBI format by selecting them and clicking the Convert button. Active el servidor de contenidos en las preferencias de calibre y deje calibre funcionando. Ahora, en el dispositivo Android, abra el navegador y vaya a Replace with the local IP address of the computer running calibre. If your local network supports the use of computer names, you can replace the IP address with the network name of the computer. If you have changed the port the calibre content server is running on, you will have to change 8080 as well to the new port. The local IP address is the IP address you computer is assigned on your home network. A quick Google search will tell you how to find out your local IP address. You can now browse your book collection and download books from calibre to your device to open with whatever ebook reading software you have on your android device. Some reading programs support browsing the Calibre library directly. For example, in Aldiko, click My Catalogs, then + to add a catalog, then give the catalog a title such as Calibre and provide the URL listed above. You can now browse the Calibre library and download directly into the reading software Capítulo 1. Secciones

115 Can I access my calibre books using the web browser in my Kindle or other reading device? calibre has a Content Server that exports the books in calibre as a web page. You can turn it on under Preferences- >Sharing over the net. Then just point the web browser on your device to the computer running the Content Server and you will be able to browse your book collection. For example, if the computer running the server has IP address , in the browser, you would type: Some devices, like the Kindle (1/2/DX), do not allow you to access port 8080 (the default port on which the content server runs. In that case, change the port in the calibre Preferences to 80. (On some operating systems, you may not be able to run the server on a port number less than 1024 because of security settings. In this case the simplest solution is to adjust your router to forward requests on port 80 to port 8080). Me sale el mensaje de error «Fallo al iniciar el servidor de contenidos: Port 8080 not free on ». The most likely cause of this is your antivirus program. Try temporarily disabling it and see if it does the trick. No puedo enviar correos electrónicos usando calibre Because of the large amount of spam in , sending can be tricky, as different mail servers use different strategies to block . The most common problem is if you are sending directly (without a mail relay) in calibre. Many servers (for example, Amazon) block that does not come from a well known relay. The most robust way to setup sending in calibre is to do the following: Cree una cuenta de GMX gratuita en GMX 50. Goto Preferences->Sharing by in calibre and click the Use GMX button and fill in the information asked for. calibre usará entonces GMX para enviar el correo electrónico. If you are sending to your Kindle, remember to update the preferences on your Amazon Kindle page to allow sent from your GMX address. Also note that Amazon does not allow delivery of AZW3 and new style (KF8) MOBI files. Even after doing this, you may have problems. One common source of problems is that some poorly designed antivirus programs block calibre from opening a connection to send . Try adding an exclusion for calibre in your antivirus program. Nota: Microsoft, Google o Gmx pueden desactivar una cuenta si se usa para enviar gran cantidad de correos. Por lo tanto, al usar Hotmail o Gmail para enviar correos calibre se limita a enviar un libro cada cinco minutos. Si no tiene inconveniente en arriesgarse a que su cuenta sea bloqueada, puede reducir este intervalo en Preferencias > Ajustes en calibre. Nota: Google recently deliberately broke their sending protocol (SMTP) support in an attempt to force everyone to use their web interface so they can show you more ads. They are trying to claim that SMTP is insecure, that is incorrect and simply an excuse. If you have trouble with gmail you will need to allow less secure apps as descibed here 51. Nota: If you are concerned about giving calibre access to your account, simply create a new free account Preguntas frecuentes 111

116 with GMX or Hotmail and use it only for calibre. Por qué no se detecta mi dispositivo en Linux? calibre needs your linux kernel to have been setup correctly to detect devices. If your devices are not detected, perform the following tests: grep SYSFS_DEPRECATED /boot/config-`uname -r` Debería ver algo como CONFIG_SYSFS_DEPRECATED_V2 is not set. Además, grep CONFIG_SCSI_MULTI_LUN /boot/config-`uname -r` debe devolver CONFIG_SCSI_MULTI_LUN=y. Si no ve alguno de los dos, debe recompilar el kernel con la configuración correcta. Mi dispositivo está montado en linux como sólo lectura, por lo que calibre no puede conectarse con él. Linux kernels mount devices read-only when their filesystems have errors. You can repair the filesystem with: sudo fsck.vfat -y /dev/sdc Replace /dev/sdc with the path to the device node of your device. You can find the device node of your device, which will always be under /dev by examining the output of: mount Por qué calibre no es compatible con las colecciones de Kindle o los estantes de Nook? Neither the Kindle nor the Nook provide any way to manipulate collections over a USB connection. If you really care about using collections, I would urge you to sell your Kindle/Nook and get a Kobo. Only Kobo seems to understand that life is too short to be entering collections one by one on an e-ink screen :) Note that in the case of the Kindle, there is a way to manipulate collections via USB, but it requires that the Kindle be rebooted every time it is disconnected from the computer, for the changes to the collections to be recognized. As such, it is unlikely that any calibre developers will ever feel motivated enough to support it. There is however, a calibre plugin that allows you to create collections on your Kindle from the calibre metadata. It is available from here 52. Nota: Amazon have removed the ability to manipulate collections completely in their newer models, like the Kindle Touch and Kindle Fire, making even the above plugin useless, unless you root your Kindle and install custom firmware. Me sale un error cuando trato de usar calibre con el Kobo Touch, Glo, etc. The Kobo has very buggy firmware. Connecting to it has been known to fail at random. Certain combinations of motherboard, USB ports/cables/hubs can exacerbate this tendency to fail. If you are getting an error when connecting to your touch with calibre try the following, each of which has solved the problem for some calibre users. Conecte el Kobo directamente al equipo, sin utilizar un hub USB. Pruebe un cable USB diferente y un puerto USB diferente en el equipo Capítulo 1. Secciones

117 Try a different computer, in particular the Kobo does not work well with some Windows XP machines. If you are on Windows XP, try a computer with a newer version of windows. Intente actualizar el firmware del Kobo Touch a la última versión Try resetting the Kobo (sometimes this cures the problem for a little while, but then it re-appears, in which case you have to reset again and again) Try only putting one or two books onto the Kobo at a time and do not keep large collections on the Kobo He enviado algunos libros al Kindle con calibre y no aparecen Los libros enviados al Kindle sólo aparecen en el Kindle una vez que éste los ha indexado. Esto puede llevar algún tiempo. Si el libro sigue sin aparecer al cabo de unos minutos, es posible que el indexador del Kindle hay fallado. A veces un libro particular puede hacer que el indexador falle. Por desgracia, Amazon no proporciona ninguna forma de saber qué libro causa el fallo. El único recurse es reiniciar el Kindle o borrar todos los archivos de su memoria con el explorador de Windows (o el administrador de archivos que utilice) y volver a enviar los libros, uno a uno, hasta descubrir el libro problemático. Una vez localizado el libro, bórrelo del Kindle, haga una conversión de MOBI a MOBI o de MOBI a AZW3 en calibre y envíelo de nuevo. Muy probablemente esto solucione el problema Gestión de la biblioteca Índice De qué formatos lee calibre los metadatos? (Página 113) Dónde se almacenan los archivos de los libros? (Página 113) How does calibre manage author names and sorting? (Página 114) Por qué calibre no me deja guardar mis libros en mi propia estructura de directorios? (Página 115) Por qué calibre no tiene una columna para tal o cual cosa? (Página 116) Can I have a column showing the formats or the ISBN? (Página 116) Cómo muevo mi biblioteca de calibre de un equipo a otro? (Página 116) La lista de libros en calibre está vacía! (Página 116) I am getting errors with my calibre library on a networked drive/nas? (Página 117) De qué formatos lee calibre los metadatos? calibre lee metadatos de los siguientes formatos: CHM, LRF, PDF, LIT, RTF, OPF, MOBI, PRC, EPUB, FB2, IMP, RB, HTML. Asimismo, puede escribir metadatos a: LRF, RTF, OPF, EPUB, PDF, MOBI Dónde se almacenan los archivos de los libros? When you first run calibre, it will ask you for a folder in which to store your books. Whenever you add a book to calibre, it will copy the book into that folder. Books in the folder are nicely arranged into sub-folders by Author and Title. Note that the contents of this folder are automatically managed by calibre, do not add any files/folders manually to this folder, as they may be automatically deleted. If you want to add a file associated to a particular book, use the top right area of Edit metadata dialog to do so. Then, calibre will automatically put that file into the correct folder and move it around when the title/author changes. Metadata about the books is stored in the file metadata.db at the top level of the library folder This file is is a sqlite database. When backing up your library make sure you copy the entire folder and all its sub-folders Preguntas frecuentes 113

118 The library folder and all it s contents make up what is called a calibre library. You can have multiple such libraries. To manage the libraries, click the calibre icon on the toolbar. You can create new libraries, remove/rename existing ones and switch between libraries easily. You can copy or move books between different libraries (once you have more than one library setup) by right clicking on a book and selecting the Copy to library action. How does calibre manage author names and sorting? Author names are complex, especially across cultures, see this note 53 for some of complexities. calibre has a very flexible strategy for managing author names. The first thing to understand is that books and authors are separate entities in calibre. A book can have more than one author, and an author can have more than one book. You can manage the authors of a book by the edit metadata dialog. You can manage individual authors by right clicking on the author in the Tag Browser on the left of the main calibre screen and selecting Manage authors. Using this dialog you can change the name of an author and also how that name is sorted. This will automatically change the name of the author in all the books of that author. When a book has multiple authors, separate their names using the & character. En cuanto a la ordenación de nombres de autor: When a new author is added to calibre (this happens whenever a book by a new author is added), calibre automatically computes a sort string for both the book and the author. Authors in the Tag Browser are sorted by the sort value for the authors. Remember that this is different from the Author sort field for a book. By default, this sort algorithm assumes that the author name is in First name Last name format and generates a Last name, First name sort value. You can change this algorithm by going to Preferences->Tweaks and setting the author_sort_copy_method tweak. You can force calibre to recalculate the author sort values for every author by right clicking on any author and selecting Manage authors, then pushing the Recalculate all author sort values button. Do this after you have set the author_sort_copy_method tweak to what you want. You can force calibre to recalculate the author sort values for all books by using the bulk metadata edit dialog (select all books and click edit metadata, check the Automatically set author sort checkbox, then press OK.) When recalculating the author sort values for books, calibre uses the author sort values for each individual author. Therefore, ensure that the individual author sort values are correct before recalculating the books author sort values. You can control whether the Tag Browser display authors using their names or their sort values by setting the categories_use_field_for_author_name tweak in Preferences->Tweaks Note that you can set an individual author s sort value to whatever you want using Manage authors. This is useful when dealing with names that calibre will not get right, such as complex multi-part names like Miguel de Cervantes Saavedra or when dealing with Asian names like Sun Tzu. With all this flexibility, it is possible to have calibre manage your author names however you like. For example, one common req Set the author_sort_copy_method tweak to copy as described above. Restart calibre. Do not change any book metadata before doing the remaining steps. Change all author names to LN, FN using the Manage authors dialog. After you have changed all the authors, press the Recalculate all author sort values button Capítulo 1. Secciones

119 Nota: Pulse Aceptar, calibre cambiará los autors de todos los libros. Esto puede llevar un rato. When changing from FN LN to LN, FN, it is often the case that the values in author_sort are already in LN, FN format. If this is set the author_sort_copy_method tweak to copy as described above. Reinicie calibre. No cambie ningún metadato de los libros antes de cumplir los siguientes pasos. open the Manage authors dialog. Press the copy all author sort values to author button. Check through the authors to be sure you are happy. You can still press Cancel to abandon the changes. Once you press OK, there is no undo. Pulse Aceptar, calibre cambiará los autors de todos los libros. Esto puede llevar un rato. Por qué calibre no me deja guardar mis libros en mi propia estructura de directorios? The whole point of calibre s library management features is that they provide a search and sort based interface for locating books that is much more efficient than any possible directory scheme you could come up with for your collection. Indeed, once you become comfortable using calibre s interface to find, sort and browse your collection, you wont ever feel the need to hunt through the files on your disk to find a book again. By managing books in its own directory structure of Author -> Title -> Book files, calibre is able to achieve a high level of reliability and standardization. To illustrate why a search/tagging based interface is superior to folders, consider the following. Suppose your book collection is nicely sorted into folders with the following scheme: Genre -> Author -> Series -> ReadStatus Now this makes it very easy to find for example all science fiction books by Isaac Asimov in the Foundation series. But suppose you want to find all unread science fiction books. There s no easy way to do this with this folder scheme, you would instead need a folder scheme that looks like: ReadStatus -> Genre -> Author -> Series In calibre, you would instead use tags to mark genre and read status and then just use a simple search query like tag:scifi and not tag:read. calibre even has a nice graphical interface, so you don t need to learn its search language instead you can just click on tags to include or exclude them from the search. To those of you that claim that you need access to the filesystem to so that you can have access to your books over the network, calibre has an excellent content server that gives you access to your calibre library over the net. If you are worried that someday calibre will cease to be developed, leaving all your books marooned in its folder structure, explore the powerful Save to Disk feature in calibre that lets you export all your files into a folder structure of arbitrary complexity based on their metadata. Finally, the reason there are numbers at the end of every title folder, is for robustness. That number is the id number of the book record in the calibre database. The presence of the number allows you to have multiple records with the same title and author names. It is also part of what allows calibre to magically regenerate the database with all metadata if the database file gets corrupted. Given that calibre s mission is to get you to stop storing metadata in filenames and stop using the filesystem to find things, the increased robustness afforded by the id numbers is well worth the uglier folder names. If you are still not convinced, then I m afraid calibre is not for you. Look elsewhere for your book cataloguing needs. Just so we re clear, this is not going to change. Kindly do not contact us in an attempt to get us to change this Preguntas frecuentes 115

120 Por qué calibre no tiene una columna para tal o cual cosa? calibre está diseñado con columnas para los campos más frecuentes y extendidos. Además, puede añadir cualquier otra columna que desee. Las columnas pueden añadirse en Preferencias > Interfaz > Añadir columnas personalizadas. Vea el cursillo UI Power tips 54 (en inglés) para aprender a crear columnas personalizadas, o lea esta entrada de blog 55 (en inglés). También puede crear «columnas virtuales» que contienen combinaciones de los metadatos de otras columnas. En el cuadro de añadir columna, use los enlaces de Creación rápida para crear columnas que muestren el ISBN del libro o los formatos. Puede usar el potente lenguaje de plantillas de calibre para hacer mucho más con las columnas. Para más detalles, véase El lenguaje de plantillas de calibre (Página 159). Can I have a column showing the formats or the ISBN? Yes, you can. Follow the instructions in the answer above for adding custom columns. Cómo muevo mi biblioteca de calibre de un equipo a otro? Simply copy the calibre library folder from the old to the new computer. You can find out what the library folder is by clicking the calibre icon in the toolbar. The very first item is the path to the library folder. Now on the new computer, start calibre for the first time. It will run the Welcome Wizard asking you for the location of the calibre library. Point it to the previously copied folder. If the computer you are transferring to already has a calibre installation, then the Welcome wizard wont run. In that case, right-click the calibre icon in the tooolbar and point it to the newly copied directory. You will now have two calibre libraries on your computer and you can switch between them by clicking the calibre icon on the toolbar. Transferring your library in this manner preserver all your metadata, tags, custom columns, etc. Note that if you are transferring between different types of computers (for example Windows to OS X) then after doing the above you should also right-click the calibre icon on the tool bar, select Library Maintenance and run the Check Library action. It will warn you about any problems in your library, which you should fix by hand. Nota: A calibre library is just a folder which contains all the book files and their metadata. All the metadata is stored in a single file called metadata.db, in the top level folder. If this file gets corrupted, you may see an empty list of books in calibre. In this case you can ask calibre to restore your books by doing a right-click on the calibre icon in the toolbar and selecting Library Maintenance->Restore database La lista de libros en calibre está vacía! In order to understand why that happened, you have to understand what a calibre library is. At the most basic level, a calibre library is just a folder. Whenever you add a book to calibre, that book s files are copied into this folder (arranged into sub folders by author and title). Inside the calibre library folder, at the top level, you will see a file called metadata.db. This file is where calibre stores the metadata like title/author/rating/tags etc. for every book in your calibre library. The list of books that calibre displays is created by reading the contents of this metadata.db file. Hay dos razones por las que calibre puede mostrar una lista de libros vacía: La carpeta de la biblioteca de calibre ha cambiado de ubicación. Esto puede ocurrir si estaba en un disco externo y la letra de unidad del disco ha cambiado, o si ha movido la carpeta accidentalmente. En este caso, calibre no puede encontrar la biblioteca y se inicia con una biblioteca vacía. Para corregir esto, pulse con el botón derecho sobre el botón de bibloteca de la barra de herramientas de calibre y seleccione Cambiar o crear bibloteca. Pulse Capítulo 1. Secciones

121 el pequeño icono azul para seleccionar una nueva ubicación para la biblioteca de calibre y pulse Aceptar. Si no conoce la nueva ubicación, busque el archivo metadata.db en el equipo. Your metadata.db file was deleted/corrupted. In this case, you can ask calibre to rebuild the metadata.db from its backups. Right click the calibre icon in the calibre toolbar and select Library maintenance->restore database. calibre will automatically rebuild metadata.db. I am getting errors with my calibre library on a networked drive/nas? No ubique la biblioteca de calibre en una unidad de red. A filesystem is a complex beast. Most network filesystems lack various filesystem features that calibre uses. Some dont support file locking, some dont support hardlinking, some are just flaky. Additionally, calibre is a single user application, if you accidentally run two copies of calibre on the same networked library, bad things will happen. Finally, different OSes impose different limitations on filesystems, so if you share your networked drive across OSes, once again, bad things will happen. Consider using the calibre Content Server to make your books available on other computers. Run calibre on a single computer and access it via the Content Server or a Remote Desktop solution. If you must share the actual library, use a file syncing tool like DropBox or rsync instead of a networked drive. If you are using a file-syncing tool it is essential that you make sure that both calibre and the file syncing tool do not try to access the calibre library at the same time. In other words, do not run the file syncing tool and calibre at the same time. Even with these tools there is danger of data corruption/loss, so only do this if you are willing to live with that risk. In particular, be aware that Google Drive is incompatible with calibre, if you put your calibre library in Google Drive, you will suffer data loss. See this thread 56 for details Miscelánea Índice Quiero que calibre descargue noticias de mi sitio de noticias favorito. (Página 118) Por qué el programa se llama «calibre»? (Página 118) Por qué calibre no muestra todos los tipos de letra de OS X? (Página 118) calibre no se inicia en Windows (Página 118) calibre se bloquea o cierra ocasionalmente (Página 119) Using the viewer or doing any conversions results in a permission denied error on windows (Página 120) calibre no se inicia o se detiene en OS X (Página 120) He descargado el instalador, pero no funciona. (Página 120) My antivirus program claims calibre is a virus/trojan? (Página 121) How do I backup calibre? (Página 121) How do I use purchased EPUB books with calibre (or what do I do with.acsm files)? (Página 121) I am getting a Permission Denied error? (Página 121) Can I have the comment metadata show up on my reader? (Página 122) How do I get calibre to use my HTTP proxy? (Página 122) Quiero que se añada una función a calibre. Qué puedo hacer? (Página 122) Por qué calibre no se actualiza automáticamente? (Página 123) Qué licencia tiene calibre? (Página 123) Cómo ejecuto calibre desde una memoria USB? (Página 123) How do I run parts of calibre like news download and the content server on my own linux server? (Página 123) Preguntas frecuentes 117

122 Quiero que calibre descargue noticias de mi sitio de noticias favorito. If you are reasonably proficient with computers, you can teach calibre to download news from any website of your choosing. To learn how to do this see Añadir su sitio de noticias favorito (Página 124). Otherwise, you can request a particular news site by posting in the calibre Recipes forum 57. Por qué el programa se llama «calibre»? Elija lo que prefiera: Convertor And LIBRary for Ebooks Un producto de alto calibre Un tributo al SONY Librie, que fue el primer lector de libros electrónicos con tecnología de «e-ink» Mi esposa lo eligió ;-) calibre is pronounced as cal-i-ber not ca-li-bre. If you re wondering, calibre is the British/commonwealth spelling for caliber. Being Indian, that s the natural spelling for me. Por qué calibre no muestra todos los tipos de letra de OS X? calibre embeds fonts in ebook files it creates. Ebook files support embedding only TrueType and OpenType (.ttf and.otf) fonts. Most fonts on OS X systems are in.dfont format, thus they cannot be embedded. calibre shows only TrueType and OpenType fonts found on your system. You can obtain many such fonts on the web. Simply download the.ttf/.otf files and add them to the Library/Fonts directory in your home directory. calibre no se inicia en Windows Puede haber varias causas para esto: If you are on Windows XP, or on a computer with a processor that does not support SSE2 (such as AMD processors from before 2003) try installing calibre version calibre 2.0 and newer use Qt 5 which is known to be incompatible with Windows XP machines, and requires SSE2. Simply un-install calibre and then install version 1.48, doing so will not affect your books/settings. If you get an error about calibre not being able to open a file because it is in use by another program, do the following: Desinstale calibre Reinicie el equipo Reinstale calibre. Pero no inicie calibre desde el asistente de instalación. Desactive temporalmente el programa antivirus (desconecte de Internet antes de hacerlo, por seguridad) Mire en la carpeta que ha elegido para la biblioteca de calibre. Si hay un archivo llamado metadata.db, bórrelo. Inicie calibre A partir de ahora debería poder iniciar calibre normalmente Capítulo 1. Secciones

123 If you get an error about a Python function terminating unexpectedly after upgrading calibre, first uninstall calibre, then delete the folders (if they exists) C:\Program Files\Calibre and C:\Program Files\Calibre2. Now re-install and you should be fine. If you get an error in the welcome wizard on an initial run of calibre, try choosing a folder like C:\library as the calibre library (calibre sometimes has trouble with library locations if the path contains non-english characters, or only numbers, etc.) Try running it as Administrator (Right click on the icon and select Run as Administrator ) If it still wont launch, start a command prompt (press the windows key and R; then type cmd.exe in the Run dialog that appears). At the command prompt type the following command and press Enter: calibre-debug -g Post any output you see in a help message on the Forum 59. calibre se bloquea o cierra ocasionalmente There are several possible things I know of, that can cause this: You recently connected an external monitor or TV to your computer. In this case, whenever calibre opens a new window like the edit metadata window or the conversion dialog, it appears on the second monitor where you dont notice it and so you think calibre has frozen. Disconnect your second monitor and restart calibre. If you use RoboForm, it is known to cause calibre to crash. Add calibre to the blacklist of programs inside RoboForm to fix this. Or uninstall RoboForm. The Logitech SetPoint Settings application causes random crashes in calibre when it is open. Close it before starting calibre. Constant Guard Protection by Xfinity causes crashes in calibre. You have to manually allow calibre in it or uninstall Constant Guard Protection. Spybot - Search & Destroy blocks calibre from accessing its temporary files breaking viewing and converting of books. You are using a Wacom branded USB mouse. There is an incompatibility between Wacom mice and the graphics toolkit calibre uses. Try using a non-wacom mouse. On some 64 bit versions of Windows there are security software/settings that prevent 64-bit calibre from working properly. If you are using the 64-bit version of calibre try switching to the 32-bit version. If the crashes happen specifically when you are using a file open dialog, like clicking on the Add Books button or the Save to Disk button, then you may have an issue with the windows file open dialogs on your computer. Some calibre users have reported that uninstalling the SpiderOak encrypted backup software also fixes these crashes. If you do not wish to uninstall SpiderOak, you can also turn off Enable OS integration in the SpiderOak preferences. If none of the above apply to you, then there is some other program on your computer that is interfering with calibre. First reboot your computer in safe mode, to have as few running programs as possible, and see if the crashes still happen. If they do not, then you know it is some program causing the problem. The most likely such culprit is a program that modifies other programs behavior, such as an antivirus, a device driver, something like RoboForm (an automatic form filling app) or an assistive technology like Voice Control or a Screen Reader. The only way to find the culprit is to eliminate the programs one by one and see which one is causing the issue. Basically, stop a program, run calibre, check for crashes. If they still happen, stop another program and repeat Preguntas frecuentes 119

124 Using the viewer or doing any conversions results in a permission denied error on windows Something on your computer is preventing calibre from accessing its own temporary files. Most likely the permissions on your Temp folder are incorrect. Go to the folder file:c:\users\username\appdata\local in Windows Explorer and then right click on the file:temp folder, select Properties and go to the Security tab. Make sure that your user account has full control for this folder. Some users have reported that running the following command in an Administrator Command Prompt fixed their permissions. To get an Administrator Command Prompt search for cmd.exe in the start menu, then right click on the command prompt entry and select Run as Administrator. At the command prompt type the following command and press Enter: icacls "%appdata%\..\local\temp" /reset /T Alternately, you can run calibre as Administrator, but doing so will cause some functionality, such as drag and drop to not work. Finally, some users have reported that disabling UAC fixes the problem. calibre no se inicia o se detiene en OS X Una causa frecuente de fallos en OS X es el uso de tecnologías de accesibilidad no compatibles con las herramientas gráficas que usa calibre. Pruebe a desactivar VoiceOver si lo tiene activado. También vaya a Preferencias > Sistema > Acceso universal y desactive la opción para permitir el acceso a dispositivos de ayuda en todas las pestañas. Otra causa puede ser el uso de herramientas de terceros que modifican el comportamiento del sistema, como Smart Scroll. You can obtain debug output about why calibre is not starting by running Console.app. Debug output will be printed to it. If the debug output contains a line that looks like: Qt: internal: -108: Error ATSUMeasureTextImage text/qfontengine_mac.mm then the problem is probably a corrupted font cache. You can clear the cache by following these instructions 60. If that doesn t solve it, look for a corrupted font file on your system, in ~/Library/Fonts or the like. An easy way to check for corrupted fonts in OS X is to start the Font Book application, select all fonts and then in the File menu, choose Validate fonts. He descargado el instalador, pero no funciona. Downloading from the Internet can sometimes result in a corrupted download. If the calibre installer you downloaded is not opening, try downloading it again. If re-downloading it does not work, download it from an alternate location 61. If the installer still doesn t work, then something on your computer is preventing it from running. Try temporarily disabling your antivirus program (Microsoft Security Essentials, or Kaspersky or Norton or McAfee or whatever). This is most likely the culprit if the upgrade process is hanging in the middle. Try rebooting your computer and running a registry cleaner like Wise registry cleaner 62. Try a clean install. That is, uninstall calibre, delete C:\Program Files\Calibre2 (or wherever you previously chose to install calibre). Then re-install calibre. Note that uninstalling does not touch your books or settings. Try downloading the installer with an alternate browser. For example if you are using Internet Explorer, try using Firefox or Chrome instead Capítulo 1. Secciones

125 If you get an error about a missing DLL on windows, then most likely, the permissions on your temporary folder are incorrect. Go to the folder C:\Users\USERNAME\AppData\Local in Windows explorer and then right click on the Temp folder and select Properties and go to the Security tab. Make sure that your user account has full control for this folder. If you still cannot get the installer to work and you are on windows, you can use the calibre portable install 63, which does not need an installer (it is just a zip file). My antivirus program claims calibre is a virus/trojan? The first thing to check is that you are downloading calibre from the official website: Make sure you are clicking the download links on the left, not the advertisements on the right. calibre is a very popular program and unscrupulous people try to setup websites offering it for download to fool the unwary. If you have the official download and your antivirus program is still claiming calibre is a virus, then, your antivirus program is wrong. Antivirus programs use heuristics, patterns of code that look suspicious to detect viruses. It s rather like racial profiling. calibre is a completely open source product. You can actually browse the source code yourself (or hire someone to do it for you) to verify that it is not a virus. Please report the false identification to whatever company you buy your antivirus software from. If the antivirus program is preventing you from downloading/installing calibre, disable it temporarily, install calibre and then re-enable it. How do I backup calibre? The most important thing to backup is the calibre library folder, that contains all your books and metadata. This is the folder you chose for your calibre library when you ran calibre for the first time. You can get the path to the library folder by clicking the calibre icon on the main toolbar. You must backup this complete folder with all its files and sub-folders. You can switch calibre to using a backed up library folder by simply clicking the calibre icon on the toolbar and choosing your backup library folder. A backed up library folder backs up your custom columns and saved searches as well as all your books and metadata. If you want to backup the calibre configuration/plugins, you have to backup the config directory. You can find this config directory via Preferences->Miscellaneous. Note that restoring configuration directories is not officially supported, but should work in most cases. Just copy the contents of the backup directory into the current configuration directory to restore. How do I use purchased EPUB books with calibre (or what do I do with.acsm files)? Most purchased EPUB books have DRM 64. This prevents calibre from opening them. You can still use calibre to store and transfer them to your ebook reader. First, you must authorize your reader on a windows machine with Adobe Digital Editions. Once this is done, EPUB books transferred with calibre will work fine on your reader. When you purchase an epub book from a website, you will get an.acsm file. This file should be opened with Adobe Digital Editions, which will then download the actual.epub ebook. The ebook file will be stored in the folder My Digital Editions, from where you can add it to calibre. I am getting a Permission Denied error? A permission denied error can occur because of many possible reasons, none of them having anything to do with calibre Preguntas frecuentes 121

126 You can get permission denied errors if you are using an SD card with write protect enabled. If you, or some program you used changed the file permissions of the files in question to read only. If there is a filesystem error on the device which caused your operating system to mount the filesystem in read only mode or mark a particular file as read only pending recovery. If the files have their owner set to a user other than you. If your file is open in another program. If the file resides on a device, you may have reached the limit of a maximum of 256 files in the root of the device. In this case you need to reformat the device/sd card referered to in the error message with a FAT32 filesystem, or delete some files from the SD card/device memory. You will need to fix the underlying cause of the permissions error before resuming to use calibre. Read the error message carefully, see what file it points to and fix the permissions on that file or its containing folders. Can I have the comment metadata show up on my reader? Most readers do not support this. You should complain to the manufacturer about it and hopefully if enough people complain, things will change. In the meantime, you can insert the metadata, including comments into a Jacket page at the start of the ebook, by using the option to Insert metadata as page at start of book during conversion. The option is found in the Structure Detection section of the conversion settings. Note that for this to have effect you have to convert the book. If your book is already in a format that does not need conversion, you can convert from that format to the same format. Another alternative is to create a catalog in ebook form containing a listing of all the books in your calibre library, with their metadata. Click-and-hold the convert button to access the catalog creation tool. And before you ask, no you cannot have the catalog link directly to books on your reader. How do I get calibre to use my HTTP proxy? De manera predeterminada, calibre usa las configuraciones de proxy que estén establecidas en el SO. En ocasiones éstas son incorrectas, por ejemplo en Windows, si no usa Internet Explorer, las configuraciones de proxy pueden estar anticuadas. Puede hacer que calibre use un servidor proxy específico estableciendo la variable de entorno http_proxy. El formato de la variable es: Pregunte al administrador de la red por el valor correcto de esta variable. Tenga en cuenta que calibre sólo soporta servidores HTTP, no SOCKS. Puede ver los proxys usados actualmente por calibre en Preferencias > Miscelánea. Quiero que se añada una función a calibre. Qué puedo hacer? Tiene dos opciones: 1. Create a patch by hacking on calibre and send it to me for review and inclusion. See Development Open a bug requesting the feature 66. Remember that while you may think your feature request is extremely important/essential, calibre developers might not agree. Fortunately, calibre is open source, which means you always have the option of implementing your feature yourself, or hiring someone to do it for you. Furthermore, calibre has a comprehensive plugin architecture, so you might be able to develop your feature as a plugin, see Escribir sus propios complementos para extender la funcionalidad de calibre (Página 213) Capítulo 1. Secciones

127 Por qué calibre no se actualiza automáticamente? Por muchos motivos: There is no need to update every week. If you are happy with how calibre works turn off the update notification and be on your merry way. Check back to see if you want to update once a year or so. There is a check box to turn off the update notification, on the update notification itself. Las descargas actuales de calibre consumen alrededor de 100 TB de ancho de banda al mes 67. Activar las descargas automáticas incrementaría este valor y acabaría costando miles de dólares al mes, que alguien tendría que pagar. If I implement a dialog that downloads the update and launches it, instead of going to the website as it does now, that would save the most ardent calibre updater, at most five clicks a week. There are far higher priority things to do in calibre development. If you really, really hate downloading calibre every week but still want to be up to the latest, I encourage you to run from source, which makes updating trivial. Instructions are available here (Página 303). Hay actualizadores automáticos de calibre no oficiales, creados por usuarios de calibre, en el foro de calibre 68 (en inglés). Qué licencia tiene calibre? calibre is licensed under the GNU General Public License v3 (an open source license). This means that you are free to redistribute calibre as long as you make the source code available. So if you want to put calibre on a CD with your product, you must also put the calibre source code on the CD. The source code is available for download 69. You are free to use the results of conversions from calibre however you want. You cannot use either code or libraries from calibre in your software without making your software open source. For details, see The GNU GPL v3 70. Cómo ejecuto calibre desde una memoria USB? Hay una versión portátil de calibre disponible aquí 71. How do I run parts of calibre like news download and the content server on my own linux server? En primer lugar, debe instalar calibre en el servidor linux. Si el servidor usa una distribución moderna de linux, no debe tener ningún problema para instalar calibre. Nota: calibre necesita GLIBC >= 2.13 y libstdc++ >= Si tiene un servidor más antiguo tendrá que compilarlas a partir del código fuente o usar calibre 1.48, que requiere sólo GLIBC >= Además, aunque las utilidades de línea de órdenes de calibre no necesitan un servidor X en ejecución, algunas de ellas necesitan que las bibliotecas de servidor X estén instaladas en el sistema. Esto es debido al uso de Qt, que enlaza con estas bibliotecas. Si obtiene un «ImportError» con respecto a algún módulo Qt, probablemente sea porque le falte alguna biblioteca X. Puede ejecutar el servidor de calibre mediante la orden: /opt/calibre/calibre-server --with-library /path/to/the/library/you/want/to/share Puede descargar noticias y convertirlas en un libro electrónico con la orden: Preguntas frecuentes 123

128 /opt/calibre/ebook-convert "Title of news source.recipe" outputfile.epub Si quiere generar un archivo MOBI, use outputfile.mobi y --output-profile kindle. Puede enviar las noticias descargadas por correo electrónico con la orden: /opt/calibre/calibre-smtp La orden exacta la dejo como ejercicio para el lector. Por último, puede añadir noticias descargadas a la biblioteca de calibre con: /opt/calibre/calibredb add --with-library /path/to/library outfile.epub Recuerde leer la sección de documentación de línea de órdenes del Manual de Usuario de Calibre para aprender más sobre estas y otras órdenes. 1.9 Cursillos Aquí puede encontrar cursillos para iniciarse en las funciones más avanzadas de calibre, como XPath y plantillas Añadir su sitio de noticias favorito calibre tiene un estructura potente, flexible y fácil de usar para descargar noticias de Internet y convertirlas en un libro electrónico. A continuación se le mostrará, a través de ejemplos, cómo acceder a las noticias de varios sitios de Internet. Para comprender mejor cómo utilizar la estructura, siga los ejemplos en el orden indicado a continuación: Recopilación totalmente automática (Página 124) El blog de calibre (Página 125) bbc.co.uk (Página 126) Personalizar el proceso de obtención (Página 126) Usar la versión para imprimir de bbc.co.uk (Página 126) Sustituir los estilos de los artículos (Página 127) Dividir y reordenar (Página 128) Ejemplo de la vida real (Página 140) Consejos para desarrollar nuevas fórmulas (Página 142) Lecturas adicionales (Página 143) Documentación de la API (Página 143) Recopilación totalmente automática Si la fuente de noticias es suficientemente simple, es posible que calibre sea capaz de obtener las noticias de forma totalmente automática, todo lo que tiene que hacer es proporcionar el URL. calibre reúne toda la información necesaria para descargar una fuente de noticias en una fórmula. Si quiere añadir una fuente de noticias en calibre, debe crear una fórmula para ello. Veamos algunos ejemplos: 124 Capítulo 1. Secciones

129 El blog de calibre El blog de calibre es un blog de mensajes que describen varias características útiles de calibre de una manera sencilla y accesible para los nuevos usuarios de calibre. Para descargar este blog en un libro electrónico, nos basamos en el RSS del blog: Obtenemos la dirección URL del RSS de la sección «Subscribe to» al final de la página del blog, eligiendo «Posts > Atom». Para hacer que calibre descargue los canales y los convierta en un libro electrónico, debe pulsar con el botón derecho en el botón Obtener noticias y luego el elemento del menú Añadir una nueva fuente de noticias y el botón Nueva fórmula. Se abrirá un cuadro de diálogo similar al que se muestra a continuación. Primero introduzca Blog de calibre dentro del campo Título de la fórmula. Éste será el título del libro electrónico que se creará a partir de los artículos provenientes de los canales anteriores. Los dos campos siguientes (Artículo más antiguo y Número máximo de artículos por canal) le permiten controlar cuántos artículos se descargan desde cada canal, ambos son suficientemente explícitos. Para añadir los canales a la fórmula, introduzca el título y dirección URL del canal y pulse en el botón Añadir canal. Una vez añadido el canal, simplemente pulse en el botón Añadir o actualizar fórmula y ya está! Cierre el cuadro de diálogo. Para probar la nueva fórmula, pulse en el botón Obtener noticias, en el submenú Personalizado, y en Blog de calibre. En un par de minutos, el nuevo libro electrónico descargado con las entradas al blog aparecerá en la biblioteca principal 1.9. Cursillos 125

130 (si tiene conectado un dispositivo de lectura, aparecerá en él en vez de la biblioteca). Selecciónelo y pulse en el botón Mostrar para leerlo. La razón por la que esto funcionó tan bien, con tan poco esfuerzo, es que el blog proporciona una fuente RSS con el contenido completo, es decir, el contenido del artículo está incrustado en el propio canal de información. Para la mayoría de las fuentes de noticias que proporcionan noticias de esta manera, con un canal RSS con el contenido completo, no necesitará mayores esfuerzos para convertirlas en libros electrónicos. Ahora veremos en una fuente de noticias que no proporciona un canal de noticias RSS con el contenido completo. En dichos canales, el artículo completo es una página de Internet y el canal de información RSS sólo contiene un enlace a la página con un breve resumen del artículo. bbc.co.uk Vamos a probar los siguentes dos canales de The BBC: 1. Portal de noticias: 2. Ciencia y naturaleza: Siga el procedimiento descrito anteriormente en El blog de calibre (Página 125) para crear una fórmula para La BBC (usando los canales RSS mencionados más arriba). Al examinar el libro electrónico descargado, vemos que calibre ha hecho un trabajo encomiable al extraer sólo el contenido que significativo de la página de Internet de cada artículo. Sin embargo, el proceso de extracción no es perfecto. A veces quedan contenidos no deseados como los menús y las ayudas a la navegación o se elimina contenido que debería haber sido mantenido, como las cabeceras de los artículos. Para que la extracción de contenido sea perfecta, tendremos que personalizar el proceso de Obtención, como se describe en la siguiente sección. Personalizar el proceso de obtención Cuando desea perfeccionar el proceso de descarga, o descargar el contenido de un sitio de Internet particularmente complejo, puede servirse de toda la potencia y flexibilidad de la estructura de una fórmula. Con ese fin, en el cuadro de diálogo Añadir nueva fuente de noticias, simplemente pulse en el botón Cambiar a modo avanzado. La personalización más fácil y a menudo más productiva es el uso de la versión para imprimir de los artículos en línea. La versión para imprimir normalmente tiene mucho menos contenido superfluo y se transforma de maner más fluida en un libro electrónico. Vamos a tratar de utilizar la versión impresa de los artículos de La BBC. Usar la versión para imprimir de bbc.co.uk El primer paso es buscar en el libro electrónico que descargamos previamente de bbc.co.uk (Página 126). Al final de cada artículo, en el libro electrónico, hay una pequeña reseña que dice desde dónde ha sido descargado el artículo. Copie y pegue la dirección URL en un navegador. Ahora en la página de Internet del artículo, busque un enlace que apunta a la «Versión para imprimir». Pulse en él para ver la versión para imprimir del artículo. Es mucho más limpia! Ahora compare ambas direcciones URL. En mi caso eran: URL del artículo URL de la versión para imprimir Así que parece que para obtener la versión para imprimir, tenemos que poner delante de cada URL de artículo: newsvote.bbc.co.uk/mpapps/pagetools/print/ Ahora en el Modo avanzado cuadro de diálogo de nuevas fuentes de noticias, debería ver algo así (recuerde seleccionar la fórmula La BBC antes de cambiar al modo avanzado): 126 Capítulo 1. Secciones

131 Se puede ver que los campos del Modo básico han sido traducidos a código python de una manera directa. Necesitamos añadir instrucciones para que esta fórmula utilice la versión para imprimir de los artículos. Todo lo que se necesita es añadir las siguientes dos líneas: def print_version(self, url): return url.replace(' ' Esto es python, por lo que la sangría es importante. Después de añadir las líneas, debe ser algo así: En lo anterior, def print_version(self, url) define un método que es utilizado por calibre para cada artículo. url es la dirección URL del artículo original. Lo que hace print_version es tomar la dirección URL y sustituirla por la nueva dirección URL que apunta a la versión para imprimir del artículo. Para aprender sobre python 72 vea el cursillo 73 (en inglés). Ahora, pulse en el botón Añadir o actualizar fórmula y se guardarán los cambios. Vuelva a descargar el libro electrónico. Ahora debe tener un libro electrónico muy mejorado. Uno de los problemas con la nueva versión es que los tipos de letra en la página de Internet de la versión impresa son demasiado pequeños. Esto es corregido automáticamente cuando se convierte a un libro electrónico, pero incluso después del proceso de corrección, el tamaño de la letra de los menús y barra de navegación pueden llegar a ser demasiado grande en relación con el texto del artículo. Para solucionar esto, vamos a personalizar un poco más, en la siguiente sección. Sustituir los estilos de los artículos En la sección anterior, hemos visto que el tamaño de letra para los artículos de la versión impresa de La BBC era demasiado pequeño. En la mayoría de sitios de Internet, incluido La BBC, el tamaño de letra se establece por medio de las hojas de estilo CSS. Podemos desactivar la obtención de dichas hojas de estilo añadiendo esta línea: Cursillos 127

132 no_stylesheets = True La fórmula queda ahora como: La nueva versión está bastante bien. Si es usted perfeccionista, querrá leer la siguiente sección, que trata de hacer cambios en el contenido descargado. Dividir y reordenar calibre contiene funciones muy poderosas y flexibles a la hora de manipular el contenido descargado. Para mostrar un par de ellas, echemos un nuevo vistazo a nuestra vieja amiga, la fórmula La BBC (Página 128). Mirando el código fuente (HTML) de un par de artículos (versiones para imprimir), vemos que tienen un pie de página que no contiene ninguna información útil, que figura en <div class="footer">... </div> Esto se puede quitar agregando: remove_tags = [dict(name='div', attrs={'class':'footer'})] a la fórmula. Finalmente, reemplacemos parte del CSS que deshabilitamos anteriormente, con nuestro propio CSS, más adecuado para la conversión en un libro electrónico: extra_css = '.headline {font-size: x-large;} \n.fact { padding-top: 10pt }' Con estas adiciones, nuestra fórmula ha alcanzado «calidad de producción», de hecho, está muy cerca de la fórmula real utilizada por calibre para la BBC, mostrada a continuación: ## ## Title: BBC News, Sport, and Blog Calibre Recipe ## Contact: mattst - jmstanfield@gmail.com ## ## License: GNU General Public License v3 - ## Copyright: mattst - jmstanfield@gmail.com ## ## Written: November 2011 ## Last Edited: ## license = 'GNU General Public License v Capítulo 1. Secciones

133 copyright = 'mattst - jmstanfield@gmail.com' ''' BBC News, Sport, and Blog Calibre Recipe ''' # Import the regular expressions module. import re # Import the BasicNewsRecipe class which this class extends. from calibre.web.feeds.recipes import BasicNewsRecipe class BBCNewsSportBlog(BasicNewsRecipe): # # **** IMPORTANT USERS READ ME **** # # First select the feeds you want then scroll down below the feeds list # and select the values you want for the other user preferences, like # oldest_article and such like. # # # Select the BBC rss feeds which you want in your ebook. # Selected feed have NO '#' at their start, de-selected feeds begin with a '#'. # # Eg. ("News Home", " - include feed. # Eg. #("News Home", " - do not include feed. # # There are 68 feeds below which constitute the bulk of the available rss # feeds on the BBC web site. These include 5 blogs by editors and # correspondants, 16 sports feeds, 15 'sub' regional feeds (Eg. North West # Wales, Scotland Business), and 7 Welsh language feeds. # # Some of the feeds are low volume (Eg. blogs), or very low volume (Eg. Click) # so if "oldest_article = 1.5" (only articles published in the last 36 hours) # you may get some 'empty feeds' which will not then be included in the ebook. # # The 15 feeds currently selected below are simply my default ones. # # Note: With all 68 feeds selected, oldest_article set to 2, # max_articles_per_feed set to 100, and simultaneous_downloads set to 10, # the ebook creation took 29 minutes on my speedy 100 mbps net connection, # fairly high-end desktop PC running Linux (Ubuntu Lucid-Lynx). # More realistically with 15 feeds selected, oldest_article set to 1.5, # max_articles_per_feed set to 100, and simultaneous_downloads set to 20, # it took 6 minutes. If that's too slow increase 'simultaneous_downloads'. # # Select / de-select the feeds you want in your ebook. # feeds = [ ("News Home", " ("UK", " ("World", " #("England", " #("Scotland", " #("Wales", " #("N. Ireland", " Cursillos 129

134 #("Africa", " #("Asia", " #("Europe", " #("Latin America", " #("Middle East", " ("US & Canada", " ("Politics", " ("Science/Environment", " ("Technology", " ("Magazine", " ("Entertainment/Arts", " #("Health", " #("Education/Family", " ("Business", " ("Special Reports", " ("Also in the News", " #("Newsbeat", " #("Click", " ("Blog: Nick Robinson (Political Editor)", " #("Blog: Mark D'Arcy (Parliamentary Correspondent)", " #("Blog: Robert Peston (Business Editor)", " #("Blog: Stephanie Flanders (Economics Editor)", " ("Blog: Rory Cellan-Jones (Technology correspondent)", " ("Sport Front Page", " #("Football", " #("Cricket", " #("Rugby Union", " #("Rugby League", " #("Tennis", " #("Golf", " #("Motorsport", " #("Boxing", " #("Athletics", " #("Snooker", " #("Horse Racing", " #("Cycling", " #("Disability Sport", " #("Other Sport", " #("Olympics 2012", " #("N. Ireland Politics", " #("Scotland Politics", " #("Scotland Business", " #("E. Scotland, Edinburgh & Fife", " #("W. Scotland & Glasgow", " #("Highlands & Islands", " #("NE. Scotland, Orkney & Shetland", " #("South Scotland", " #("Central Scotland & Tayside", " #("Wales Politics", " #("NW. Wales", " #("NE. Wales", " #("Mid. Wales", " #("SW. Wales", " #("SE. Wales", " #("Newyddion - News in Welsh", " #("Gwleidyddiaeth", " #("Gogledd-Ddwyrain", " #("Gogledd-Orllewin", " 130 Capítulo 1. Secciones

135 ] #("Canolbarth", " #("De-Ddwyrain", " #("De-Orllewin", " # **** SELECT YOUR USER PREFERENCES **** # Title to use for the ebook. # title = 'BBC News' # A brief description for the ebook. # description = u'bbc web site ebook created using rss feeds.' # The max number of articles which may be downloaded from each feed. # I've never seen more than about 70 articles in a single feed in the # BBC feeds. # max_articles_per_feed = 100 # The max age of articles which may be downloaded from each feed. This is # specified in days - note fractions of days are allowed, Eg. 2.5 (2 and a # half days). My default of 1.5 days is the last 36 hours, the point at # which I've decided 'news' becomes 'old news', but be warned this is not # so good for the blogs, technology, magazine, etc., and sports feeds. # You may wish to extend this to 2-5 but watch out ebook creation time will # increase as well. Setting this to 30 will get everything (AFAICT) as long # as max_articles_per_feed remains set high (except for 'Click' which is # v. low volume and its currently oldest article is 4th Feb 2011). # oldest_article = 1.5 # Number of simultaneous downloads. 20 is consistantly working fine on the # BBC News feeds with no problems. Speeds things up from the defualt of 5. # If you have a lot of feeds and/or have increased oldest_article above 2 # then you may wish to try increasing simultaneous_downloads to 25-30, # Or, of course, if you are in a hurry. [I've not tried beyond 20.] # simultaneous_downloads = 20 # Timeout for fetching files from the server in seconds. The default of # 120 seconds, seems somewhat excessive. # timeout = 30 # The format string for the date shown on the ebook's first page. # List of all values: # Default in news.py has a leading space so that's mirrored here. # As with 'feeds' select/de-select by adding/removing the initial '#', # only one timefmt should be selected, here's a few to choose from. # timefmt = ' [%a, %d %b %Y]' # [Fri, 14 Nov 2011] (Calibre default) #timefmt = ' [%a, %d %b %Y %H:%M]' # [Fri, 14 Nov :30] #timefmt = ' [%a, %d %b %Y %I:%M %p]' # [Fri, 14 Nov :30 PM] #timefmt = ' [%d %b %Y]' # [14 Nov 2011] #timefmt = ' [%d %b %Y %H:%M]' # [14 Nov ] 1.9. Cursillos 131

136 #timefmt = ' [%Y-%m-%d]' # [ ] #timefmt = ' [%Y-%m-%d-%H-%M]' # [ ] # # **** IMPORTANT **** # # DO NOT EDIT BELOW HERE UNLESS YOU KNOW WHAT YOU ARE DOING. # # DO NOT EDIT BELOW HERE UNLESS YOU KNOW WHAT YOU ARE DOING. # # I MEAN IT, YES I DO, ABSOLUTELY, AT YOU OWN RISK. :) # # **** IMPORTANT **** # # Author of this recipe. author = 'mattst' # Specify English as the language of the RSS feeds (ISO-639 code). language = 'en_gb' # Set tags. tags = 'news, sport, blog' # Set publisher and publication type. publisher = 'BBC' publication_type = 'newspaper' # Disable stylesheets from site. no_stylesheets = True # Specifies an override encoding for sites that have an incorrect charset # specified. Default of 'None' says to auto-detect. Some other BBC recipes # use 'utf8', which works fine (so use that if necessary) but auto-detecting # with None is working fine, so stick with that for robustness. encoding = None # Sets whether a feed has full articles embedded in it. The BBC feeds do not. use_embedded_content = False # Removes empty feeds - why keep them!? remove_empty_feeds = True # Create a custom title which fits nicely in the Kindle title list. # Requires "import time" above class declaration, and replacing # title with custom_title in conversion_options (right column only). # Example of string below: "BBC News - 14 Nov 2011" # # custom_title = "BBC News - " + time.strftime('%d %b %Y') ''' # Conversion options for advanced users, but don't forget to comment out the # current conversion_options below. Avoid setting 'linearize_tables' as that # plays havoc with the 'old style' table based pages. 132 Capítulo 1. Secciones

137 # conversion_options = { 'title' : title, 'comments' : description, 'tags' : tags, 'language' : language, 'publisher' : publisher, 'authors' : publisher, 'smarten_punctuation' : True } ''' conversion_options = { 'smarten_punctuation' : True } # Specify extra CSS - overrides ALL other CSS (IE. Added last). extra_css = 'body { font-family: verdana, helvetica, sans-serif; } \.introduction,.first { font-weight: bold; } \.cross-head { font-weight: bold; font-size: 125%; } \.cap,.caption { display: block; font-size: 80%; font-style: italic; } \.cap,.caption,.caption img,.caption span { display: block; text-align: center; ma.byl,.byd,.byline img,.byline-name,.byline-title,.author-name,.author-position.correspondent-portrait img,.byline-lead-in,.name,.bbc-role { display: block; text-align: center; font-size: 80%; font-style: italic; margin: 1px auto; } \.story-date,.published { font-size: 80%; } \ table { width: 100%; } \ td img { display: block; margin: 5px auto; } \ ul { padding-top: 10px; } \ ol { padding-top: 10px; } \ li { padding-top: 5px; padding-bottom: 5px; } \ h1 { text-align: center; font-size: 175%; font-weight: bold; } \ h2 { text-align: center; font-size: 150%; font-weight: bold; } \ h3 { text-align: center; font-size: 125%; font-weight: bold; } \ h4, h5, h6 { text-align: center; font-size: 100%; font-weight: bold; }' # Remove various tag attributes to improve the look of the ebook pages. remove_attributes = [ 'border', 'cellspacing', 'align', 'cellpadding', 'colspan', 'valign', 'vspace', 'hspace', 'alt', 'width', 'height' ] # Remove the (admittedly rarely used) line breaks, "<br />", which sometimes # cause a section of the ebook to start in an unsightly fashion or, more # frequently, a "<br />" will muck up the formatting of a correspondant's byline. # "<br />" and "<br clear/>" are far more frequently used on the table formatted # style of pages, and really spoil the look of the ebook pages. preprocess_regexps = [(re.compile(r'<br[ ]*/>', re.ignorecase), lambda m: ''), (re.compile(r'<br[ ]*clear.*/>', re.ignorecase), lambda m: '')] # Create regular expressions for tag keeping and removal to make the matches more # robust against minor changes and errors in the HTML, Eg. double spaces, leading # and trailing spaces, missing hyphens, and such like. # Python regular expression ('re' class) page: # *************************************** # Regular expressions for keep_only_tags: # *************************************** # The BBC News HTML pages use variants of 'storybody' to denote the section of a HTML # page which contains the main text of the article. Match storybody variants: 'storybody', # 'story-body', 'story body','storybody ', etc Cursillos 133

138 storybody_reg_exp = '^.*story[_ -]*body.*$' # The BBC sport and 'newsbeat' (features) HTML pages use 'blq_content' to hold the title # and published date. This is one level above the usual news pages which have the title # and date within 'story-body'. This is annoying since 'blq_content' must also be kept, # resulting in a lot of extra things to be removed by remove_tags. blq_content_reg_exp = '^.*blq[_ -]*content.*$' # The BBC has an alternative page design structure, which I suspect is an out-of-date # design but which is still used in some articles, Eg. 'Click' (technology), 'FastTrack' # (travel), and in some sport pages. These alternative pages are table based (which is # why I think they are an out-of-date design) and account for -I'm guesstimaking- less # than 1% of all articles. They use a table class 'storycontent' to hold the article # and like blq_content (above) have required lots of extra removal by remove_tags. story_content_reg_exp = '^.*story[_ -]*content.*$' # Keep the sections of the HTML which match the list below. The HTML page created by # Calibre will fill <body> with those sections which are matched. Note that the # blq_content_reg_exp must be listed before storybody_reg_exp in keep_only_tags due to # it being the parent of storybody_reg_exp, that is to say the div class/id 'story-body' # will be inside div class/id 'blq_content' in the HTML (if 'blq_content' is there at # all). If they are the other way around in keep_only_tags then blq_content_reg_exp # will end up being discarded. keep_only_tags = [ dict(name='table', attrs={'class':re.compile(story_content_reg_exp, re.ignorec dict(name='div', attrs={'class':re.compile(blq_content_reg_exp, re.ignorecas dict(name='div', attrs={'id':re.compile(blq_content_reg_exp, re.ignorecase)} dict(name='div', attrs={'class':re.compile(storybody_reg_exp, re.ignorecase) dict(name='div', attrs={'id':re.compile(storybody_reg_exp, re.ignorecase)}) # ************************************ # Regular expressions for remove_tags: # ************************************ # Regular expression to remove share-help and variant tags. The share-help class # is used by the site for a variety of 'sharing' type links, Eg. Facebook, delicious, # twitter, . Removed to avoid page clutter. share_help_reg_exp = '^.*share[_ -]*help.*$' # Regular expression to remove embedded-hyper and variant tags. This class is used to # display links to other BBC News articles on the same/similar subject. embedded_hyper_reg_exp = '^.*embed*ed[_ -]*hyper.*$' # Regular expression to remove hypertabs and variant tags. This class is used to # display a tab bar at the top of an article which allows the user to switch to # an article (viewed on the same page) providing further info., 'in depth' analysis, # an editorial, a correspondant's blog entry, and such like. The ability to handle # a tab bar of this nature is currently beyond the scope of this recipe and # possibly of Calibre itself (not sure about that - TO DO - check!). hypertabs_reg_exp = '^.*hyper[_ -]*tabs.*$' # Regular expression to remove story-feature and variant tags. Eg. 'story-feature', # 'story-feature related narrow', 'story-feature wide', 'story-feature narrow'. # This class is used to add additional info. boxes, or small lists, outside of # the main story. TO DO: Work out a way to incorporate these neatly. story_feature_reg_exp = '^.*story[_ -]*feature.*$' # Regular expression to remove video and variant tags, Eg. 'videoinstoryb', # 'videoinstoryc'. This class is used to embed video. 134 Capítulo 1. Secciones

139 video_reg_exp = '^.*video.*$' # Regular expression to remove audio and variant tags, Eg. 'audioinstoryd'. # This class is used to embed audio. audio_reg_exp = '^.*audio.*$' # Regular expression to remove picturegallery and variant tags, Eg. 'picturegallery'. # This class is used to embed a photo slideshow. See also 'slideshow' below. picture_gallery_reg_exp = '^.*picture.*$' # Regular expression to remove slideshow and variant tags, Eg. 'dslideshow-enclosure'. # This class is used to embed a slideshow (not necessarily photo) but both # 'slideshow' and 'picturegallery' are used for slideshows. slideshow_reg_exp = '^.*slide[_ -]*show.*$' # Regular expression to remove social-links and variant tags. This class is used to # display links to a BBC bloggers main page, used in various columnist's blogs # (Eg. Nick Robinson, Robert Preston). social_links_reg_exp = '^.*social[_ -]*links.*$' # Regular expression to remove quote and (multi) variant tags, Eg. 'quote', # 'endquote', 'quote-credit', 'quote-credit-title', etc. These are usually # removed by 'story-feature' removal (as they are usually within them), but # not always. The quotation removed is always (AFAICT) in the article text # as well but a 2nd copy is placed in a quote tag to draw attention to it. # The quote class tags may or may not appear in div's. quote_reg_exp = '^.*quote.*$' # Regular expression to remove hidden and variant tags, Eg. 'hidden'. # The purpose of these is unclear, they seem to be an internal link to a # section within the article, but the text of the link (Eg. 'Continue reading # the main story') never seems to be displayed anyway. Removed to avoid clutter. # The hidden class tags may or may not appear in div's. hidden_reg_exp = '^.*hidden.*$' # Regular expression to remove comment and variant tags, Eg. 'comment-introduction'. # Used on the site to display text about registered users entering comments. comment_reg_exp = '^.*comment.*$' # Regular expression to remove form and variant tags, Eg. 'comment-form'. # Used on the site to allow registered BBC users to fill in forms, typically # for entering comments about an article. form_reg_exp = '^.*form.*$' # Extra things to remove due to the addition of 'blq_content' in keep_only_tags. #<div class="story-actions"> Used on sports pages for ' ' and 'print'. story_actions_reg_exp = '^.*story[_ -]*actions.*$' #<div class="bookmark-list"> Used on sports pages instead of 'share-help' (for # social networking links). bookmark_list_reg_exp = '^.*bookmark[_ -]*list.*$' #<div id="secondary-content" class="content-group"> # NOTE: Don't remove class="content-group" that is needed. # Used on sports pages to link to 'similar stories'. secondary_content_reg_exp = '^.*secondary[_ -]*content.*$' 1.9. Cursillos 135

140 #<div id="featured-content" class="content-group"> # NOTE: Don't remove class="content-group" that is needed. # Used on sports pages to link to pages like 'tables', 'fixtures', etc. featured_content_reg_exp = '^.*featured[_ -]*content.*$' #<div id="navigation"> # Used on sports pages to link to pages like 'tables', 'fixtures', etc. # Used sometimes instead of "featured-content" above. navigation_reg_exp = '^.*navigation.*$' #<a class="skip" href="#blq-container-inner">skip to top</a> # Used on sports pages to link to the top of the page. skip_reg_exp = '^.*skip.*$' # Extra things to remove due to the addition of 'storycontent' in keep_only_tags, # which are the alterative table design based pages. The purpose of some of these # is not entirely clear from the pages (which are a total mess!). # Remove mapping based tags, Eg. <map id="world_map"> # The dynamic maps don't seem to work during ebook creation. TO DO: Investigate. map_reg_exp = '^.*map.*$' # Remove social bookmarking variation, called 'socialbookmarks'. social_bookmarks_reg_exp = '^.*social[_ -]*bookmarks.*$' # Remove page navigation tools, like 'search', ' ', 'print', called 'blq-mast'. blq_mast_reg_exp = '^.*blq[_ -]*mast.*$' # Remove 'sharesb', I think this is a generic 'sharing' class. It seems to appear # alongside 'socialbookmarks' whenever that appears. I am removing it as well # under the assumption that it can appear alone as well. sharesb_reg_exp = '^.*sharesb.*$' # Remove class 'o'. The worst named user created css class of all time. The creator # should immediately be fired. I've seen it used to hold nothing at all but with # 20 or so empty lines in it. Also to hold a single link to another article. # Whatever it was designed to do it is not wanted by this recipe. Exact match only. o_reg_exp = '^o$' # Remove 'promotopbg' and 'promobottombg', link lists. Have decided to # use two reg expressions to make removing this (and variants) robust. promo_top_reg_exp = '^.*promotopbg.*$' promo_bottom_reg_exp = '^.*promobottombg.*$' # Remove 'nlp', provides heading for link lists. Requires an exact match due to # risk of matching those letters in something needed, unless I see a variation # of 'nlp' used at a later date. nlp_reg_exp = '^nlp$' # Remove 'mva', provides embedded floating content of various types. Variant 'mvb' # has also now been seen. Requires an exact match of 'mva' or 'mvb' due to risk of # matching those letters in something needed. mva_or_mvb_reg_exp = '^mv[ab]$' # Remove 'mvtb', seems to be page navigation tools, like 'blq-mast'. mvtb_reg_exp = '^mvtb$' # Remove 'blq-toplink', class to provide a link to the top of the page. 136 Capítulo 1. Secciones

141 blq_toplink_reg_exp = '^.*blq[_ -]*top[_ -]*link.*$' # Remove 'products and services' links, Eg. desktop tools, alerts, and so on. # Eg. Class="servicev4 ukfs_services" - what a mess of a name. Have decided to # use two reg expressions to make removing this (and variants) robust. prods_services_01_reg_exp = '^.*servicev4.*$' prods_services_02_reg_exp = '^.*ukfs[_ -]*services.*$' # Remove -what I think is- some kind of navigation tools helper class, though I am # not sure, it's called: 'blq-rst blq-new-nav'. What I do know is it pops up # frequently and it is not wanted. Have decided to use two reg expressions to make # removing this (and variants) robust. blq_misc_01_reg_exp = '^.*blq[_ -]*rst.*$' blq_misc_02_reg_exp = '^.*blq[_ -]*new[_ -]*nav.*$' # Remove 'puffbox' - this may only appear inside 'storyextra', so it may not # need removing - I have no clue what it does other than it contains links. # Whatever it is - it is not part of the article and is not wanted. puffbox_reg_exp = '^.*puffbox.*$' # Remove 'sibtbg' and 'sibtbgf' - some kind of table formatting classes. sibtbg_reg_exp = '^.*sibtbg.*$' # Remove 'storyextra' - links to relevant articles and external sites. storyextra_reg_exp = '^.*story[_ -]*extra.*$' dict(name='div', attrs={'id':re.compile(social_bookmarks_reg_exp, re.ignorecase)} remove_tags = [ dict(name='div', attrs={'class':re.compile(story_feature_reg_exp, re.ignorecase) dict(name='div', attrs={'class':re.compile(share_help_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(embedded_hyper_reg_exp, re.ignorecase dict(name='div', attrs={'class':re.compile(hypertabs_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(video_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(audio_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(picture_gallery_reg_exp, re.ignorecas dict(name='div', attrs={'class':re.compile(slideshow_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(quote_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(hidden_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(comment_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(story_actions_reg_exp, re.ignorecase) dict(name='div', attrs={'class':re.compile(bookmark_list_reg_exp, re.ignorecase) dict(name='div', attrs={'id':re.compile(secondary_content_reg_exp, re.ignorecase dict(name='div', attrs={'id':re.compile(featured_content_reg_exp, re.ignorecase) dict(name='div', attrs={'id':re.compile(navigation_reg_exp, re.ignorecase)}), dict(name='form', attrs={'id':re.compile(form_reg_exp, re.ignorecase)}), dict(attrs={'class':re.compile(quote_reg_exp, re.ignorecase)}), dict(attrs={'class':re.compile(hidden_reg_exp, re.ignorecase)}), dict(attrs={'class':re.compile(social_links_reg_exp, re.ignorecase)}), dict(attrs={'class':re.compile(comment_reg_exp, re.ignorecase)}), dict(attrs={'class':re.compile(skip_reg_exp, re.ignorecase)}), dict(name='map', attrs={'id':re.compile(map_reg_exp, re.ignorecase)}), dict(name='map', attrs={'name':re.compile(map_reg_exp, re.ignorecase)}), dict(name='div', attrs={'id':re.compile(blq_mast_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(sharesb_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(o_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(promo_top_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(promo_bottom_reg_exp, re.ignorecase)} dict(name='div', attrs={'class':re.compile(nlp_reg_exp, re.ignorecase)}), 1.9. Cursillos 137

142 dict(name='div', attrs={'class':re.compile(mva_or_mvb_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(mvtb_reg_exp, re.ignorecase)}), dict(name='div', attrs={'class':re.compile(blq_toplink_reg_exp, re.ignorecase)}) dict(name='div', attrs={'class':re.compile(prods_services_01_reg_exp, re.ignorec dict(name='div', attrs={'class':re.compile(prods_services_02_reg_exp, re.ignorec dict(name='div', attrs={'class':re.compile(blq_misc_01_reg_exp, re.ignorecase)}) dict(name='div', attrs={'class':re.compile(blq_misc_02_reg_exp, re.ignorecase)}) dict(name='div', attrs={'class':re.compile(puffbox_reg_exp, re.ignorecase)}), dict(attrs={'class':re.compile(sibtbg_reg_exp, re.ignorecase)}), dict(attrs={'class':re.compile(storyextra_reg_exp, re.ignorecase)}) ] # Uses url to create and return the 'printer friendly' version of the url. # In other words the 'print this page' address of the page. # # There are 3 types of urls used in the BBC site's rss feeds. There is just # 1 type for the standard news while there are 2 used for sports feed urls. # Note: Sports urls are linked from regular news feeds (Eg. 'News Home') when # there is a major story of interest to 'everyone'. So even if no BBC sports # feeds are added to 'feeds' the logic of this method is still needed to avoid # blank / missing / empty articles which have an index title and then no body. def print_version(self, url): # Handle sports page urls type 01: if (url.find("go/rss/-/sport1/")!= -1): temp_url = url.replace("go/rss/-/", "") # Handle sports page urls type 02: elif (url.find("go/rss/int/news/-/sport1/")!= -1): temp_url = url.replace("go/rss/int/news/-/", "") # Handle regular news page urls: else: temp_url = url.replace("go/rss/int/news/-/", "") # Always add "?print=true" to the end of the url. print_url = temp_url + "?print=true" return print_url # Remove articles in feeds based on a string in the article title or url. # # Code logic written by: Starson17 - posted in: "Recipes - Re-usable code" # thread, in post with title: "Remove articles from feed", see url: # # Many thanks and all credit to Starson17. # # Starson17's code has obviously been altered to suite my requirements. def parse_feeds(self): # Call parent's method. feeds = BasicNewsRecipe.parse_feeds(self) # Loop through all feeds. for feed in feeds: # Loop through all articles in feed. 138 Capítulo 1. Secciones

143 for article in feed.articles[:]: return feeds # End of class and file. # Match key words and remove article if there's a match. # Most BBC rss feed video only 'articles' use upper case 'VIDEO' # as a title prefix. Just match upper case 'VIDEO', so that # articles like 'Video game banned' won't be matched and removed. if 'VIDEO' in article.title: feed.articles.remove(article) # Most BBC rss feed audio only 'articles' use upper case 'AUDIO' # as a title prefix. Just match upper case 'AUDIO', so that # articles like 'Hi-Def audio...' won't be matched and removed. elif 'AUDIO' in article.title: feed.articles.remove(article) # Most BBC rss feed photo slideshow 'articles' use 'In Pictures', # 'In pictures', and 'in pictures', somewhere in their title. # Match any case of that phrase. elif 'IN PICTURES' in article.title.upper(): feed.articles.remove(article) # As above, but user contributed pictures. Match any case. elif 'YOUR PICTURES' in article.title.upper(): feed.articles.remove(article) # 'Sportsday Live' are articles which contain a constantly and # dynamically updated 'running commentary' during a live sporting # event. Match any case. elif 'SPORTSDAY LIVE' in article.title.upper(): feed.articles.remove(article) # Sometimes 'Sportsday Live' (above) becomes 'Live - Sport Name'. # These are being matched below using 'Live - ' because removing all # articles with 'live' in their titles would remove some articles # that are in fact not live sports pages. Match any case. elif 'LIVE - ' in article.title.upper(): feed.articles.remove(article) # 'Quiz of the week' is a Flash player weekly news quiz. Match only # the 'Quiz of the' part in anticipation of monthly and yearly # variants. Match any case. elif 'QUIZ OF THE' in article.title.upper(): feed.articles.remove(article) # Remove articles with 'scorecards' in the url. These are BBC sports # pages which just display a cricket scorecard. The pages have a mass # of table and css entries to display the scorecards nicely. Probably # could make them work with this recipe, but might take a whole day # of work to sort out all the css - basically a formatting nightmare. elif 'scorecards' in article.url: feed.articles.remove(article) Esta fórmula muestra sólo la punta del iceberg en lo que se refiere a la potencia de calibre. Para explorar más sobre las 1.9. Cursillos 139

144 capacidades de calibre, examinaremos un ejemplo de la vida real más complejo en la siguiente sección. Ejemplo de la vida real Un ejemplo real bastante complejo que expone más partes de la API de BasicNewsRecipe es la fórmula de The New York Times import string, re from calibre import strftime from calibre.web.feeds.recipes import BasicNewsRecipe from calibre.ebooks.beautifulsoup import BeautifulSoup class NYTimes(BasicNewsRecipe): title = 'The New York Times' author = 'Kovid Goyal' description = 'Daily news from the New York Times' timefmt = ' [%a, %d %b, %Y]' needs_subscription = True remove_tags_before = dict(id='article') remove_tags_after = dict(id='article') remove_tags = [dict(attrs={'class':['articletools', 'post-tools', 'side_tool', 'nextarticlelink c dict(id=['footer', 'toolsright', 'articleinline', 'navigation', 'archive', 'side_sear dict(name=['script', 'noscript', 'style'])] encoding = 'cp1252' no_stylesheets = True extra_css = 'h1 {font: sans-serif large;}\n.byline {font:monospace;}' def get_browser(self): br = BasicNewsRecipe.get_browser() if self.username is not None and self.password is not None: br.open(' br.select_form(name='login') br['userid'] = self.username br['password'] = self.password br.submit() return br def parse_index(self): soup = self.index_to_soup(' def feed_title(div): return ''.join(div.findall(text=true, recursive=false)).strip() articles = {} key = None ans = [] for div in soup.findall(true, attrs={'class':['section-headline', 'story', 'story headline']}): if div['class'] == 'section-headline': key = string.capwords(feed_title(div)) articles[key] = [] ans.append(key) elif div['class'] in ['story', 'story headline']: a = div.find('a', href=true) 140 Capítulo 1. Secciones

145 if not a: continue url = re.sub(r'\?.*', '', a['href']) url += '?pagewanted=all' title = self.tag_to_string(a, use_alt=true).strip() description = '' pubdate = strftime('%a, %d %b') summary = div.find(true, attrs={'class':'summary'}) if summary: description = self.tag_to_string(summary, use_alt=false) feed = key if key is not None else 'Uncategorized' if not articles.has_key(feed): articles[feed] = [] if not 'podcasts' in url: articles[feed].append( dict(title=title, url=url, date=pubdate, description=description, content='')) ans = self.sort_index_by(ans, {'The Front Page':-1, 'Dining In, Dining Out':1, 'Obituaries':2 ans = [(key, articles[key]) for key in ans if articles.has_key(key)] return ans def preprocess_html(self, soup): refresh = soup.find('meta', {'http-equiv':'refresh'}) if refresh is None: return soup content = refresh.get('content').partition('=')[2] raw = self.browser.open(' return BeautifulSoup(raw.decode('cp1252', 'replace')) Vemos varias características nuevas en esta fórmula. En primer lugar, tenemos: timefmt = ' [%a, %d %b, %Y]' Esto hace que la fecha que aparece en la primera página del libro electrónico creado se muestre en este formato, Día, Número de día Mes, Año. Vea: attr:timefmt <calibre.web.feeds.news.basicnewsrecipe.timefmt>. Después vemos un grupo de directivas para depurar el HTML descargado: remove_tags_before = dict(name='h1') remove_tags_after = dict(id='footer') remove_tags =... Éstas eliminan todo lo que hay antes de la primera etiqueta <h1> y todo lo que hay después de la primera etiqueta cuyo id es footer. Véanse remove_tags (Página 318), remove_tags_before (Página 318), remove_tags_after (Página 318). La siguiente función interesante es: needs_subscription = True... def get_browser(self):... needs_subscription = True le comunica a calibre que esta fórmula necesita un nombre de usuario y contraseña para poder acceder al contenido. Esto hace que calibre pida un nombre de usuario y contraseña cada vez que intente utilizar esta fórmula. El código en calibre.web.feeds.news.basicnewsrecipe.get_browser() (Página 311) es el que realmente inicia la sesión en el sitio de Internet del New York Times. Una vez iniciada la sesión, 1.9. Cursillos 141

146 calibre utilizará esta misma sesión para obtener todo el contenido. Véase mechanize 74 para entender el código en get_browser. La siguiente nueva función es el método calibre.web.feeds.news.basicnewsrecipe.parse_index() (Página 313). Su trabajo consiste en ir a a buscar la lista de los artículos que aparecen en el número de hoy. Aunque es más compleja que simplemente usar el RSS, la fórmula crea un libro electrónico que se corresponde muy de cerca con el periódico del día. parse_index hace un uso intensivo de BeautifulSoup 75 para analizar la página del diario. También puede utilizar otros programas de análisis, más modernos, si no le gusta BeatifulSoup. calibre incluye lxml 76 y html5lib 77, que son los programas de análisis recomendados. Para usarlos, sustituya la llamada a index_to_soup() por lo siguiente: raw = self.index_to_soup(url, raw=true) # For html5lib import html5lib root = html5lib.parse(raw, namespacehtmlelements=false, treebuilder='lxml') # For the lxml html 4 parser from lxml import html root = html.fromstring(raw) La última nueva característica es el método calibre.web.feeds.news.basicnewsrecipe.preprocess_html() (Página 314). Se puede utilizar para realizar transformaciones arbitrarias en cada página HTML descargada. Aquí se usa para evitar la publicidad que nytimes muestra antes de cada artículo. Consejos para desarrollar nuevas fórmulas La mejor manera de desarrollar nuevas fórmulas es utilizar la interfaz de línea de órdenes. Cree la fórmula usando su editor de python favorito y guárdela en un archivo, digamos mifórmula.recipe. La extensión.recipe es necesaria. Puede descargar contenido usando esta fórmula con la orden: ebook-convert myrecipe.recipe.epub --test -vv --debug-pipeline debug La orden ebook-convert descargará todas las páginas de Internet y las guardará en el archivo EPUB mifórmula.epub. -vv hace que ebook-convert muestre una gran cantidad de información acerca de lo que está haciendo. --test hace que se descargue sólo un par de artículos de un máximo de dos canales RSS. Además, ebook-convert pondrá el HTML descargado en el directorio debug/input, donde debug es el directorio que haya especificado en la opción :option: debug-pipeline. Una vez que la descarga está completa, puede ver el HTML descargado abriendo el archivo debug/input/index.html en un navegador. Cuando que esté satisfecho con la descarga y el procesado previo, puede generar libros electrónicos en diferentes formatos, como se muestra a continuación: ebook-convert myrecipe.recipe myrecipe.epub ebook-convert myrecipe.recipe myrecipe.mobi... Si está satisfecho con fórmula y cree que existe suficiente demanda para justificar su inclusión en el conjunto de fórmulas incorporadas, compártala en el Foro de fórmulas de calibre 78 (en inglés). Nota: En OS X, las herramientas de línea de órdenes están dentro del paquete calibre, por ejemplo, si ha instalado calibre en /Aplicaciones las herramientas de línea de órdenes están en /Aplicaciones/calibre.app/Contents/console.app/Contents/MacOS Capítulo 1. Secciones

147 Ver también: generated/en/ebook-convert La interfaz de la línea de órdenes para todas las conversiones de libros electrónicos. Lecturas adicionales Para obtener más información acerca de cómo escribir fórmulas avanzadas usando algunas de las opciones disponibles en BasicNewsRecipe debe consultar las siguientes fuentes: Documentación de la API (Página 310) La documentación de la clase BasicNewsRecipe y todos sus métodos y campos importantes. BasicNewsRecipe 79 Fórmulas predefinidas 80 El código fuente de BasicNewsRecipe El código fuente de las fórmulas predefinidas que incluye calibre El foro de fórmulas de calibre 81 (en inglés) Un buen número de creadores de fórmulas de calibre pasan el rato aquí. Documentación de la API Documentación de la API para fórmulas La API para crear fórmulas está definida por la clase BasicNewsRecipe (Página 310) class calibre.web.feeds.news.basicnewsrecipe(options, log, progress_reporter) La clase base que contiene la lógica necesaria para todas las fórmulas. Reemplazando progresivamente las distintas funciones de esta clase, puede generar fórmulas cada vez más personalizadas y potentes. Para un cursillo introductorio a la creación de fórmulas, véase Añadir su sitio de noticias favorito (Página 124). abort_article(msg=none) Ejecute este método dentro de cualquiera de los métodos de preprocesado para cancelar la descarga del artículo actual. Es útil para evitar la descarga de artículos con contenido no adecuado, como artículos que sólo contienen vídeos. abort_recipe_processing(msg) Hace que el sistema de descarga de fórmulas cancele la descarga de esta fórmula, mostrando al usuario un mensaje de información sencillo. add_toc_thumbnail(article, src) Utilice este método desde populate_article_metadata con el atributo src de una etiqueta <img> del artículo que quiera usar como la miniatura que representa el artículo en el índice. Si la miniatura se usa realmente o no dependerá del dispositivo (actualmente sólo la usan los Kindles). Tenga en cuenta que la imagen a que se hace referencia debe haber sido descargada con éxito, de lo contrario se ignorará. classmethod adeify_images(soup) Si la fórmula, al ser convertida a EPUB, tiene problemas con las imágenes cuando se muestra en Adobe Digital Editions, utilice este método desde postprocess_html() (Página 314). canonicalize_internal_url(url, is_link=true) Devuelve un conjunto de representaciones canónicas de url. La implementación predeterminada usa el nombre del servidor y la ruta de acceso del URL, descartando parámetros de consulta, fragmentos, etc. Las representaciones canónicas deben ser únicas para todos los URL de esta fuente de noticias. Si no lo son, los enlaces internos pueden ser incorrectos. Parámetros is_link Es True si el URL viene de un enlace interno en un archivo HTML. False si el URL es el URL usado para descargar un artículo Cursillos 143

148 cleanup() Usado cuando todos los artículos han sido descargados. Úselo para hacer limpieza, como cerrar sesiones en los sitios que requieren suscripción, etc. clone_browser(br) Clonar el navegador br. Los navegadores clonados se utilizan para las descargas multihilo, ya que mechanize no es seguro. Las rutinas de clonación predeterminadas deberían reconocer la mayoría de las personalizaciones del navegador, pero si se hace algo exótico en una fórmula, debe sustituir este método en la fórmula y clonarlo de forma manual. Los navegadores clonados usan el mismo CookieJar seguro en varios hilos, de manera predeterminada, a menos que haya personalizado el manejo de las cookies. default_cover(cover_file) Crear una portada genérica para las fórmulas que no poseen una. download() Descargar y preprocesar todos los artículos de los canales RSS en esta fórmula. Este método debe utilizarse una sola vez en cada fórmula. Si se usa más de una vez se obtendrá un comportamiento indefinido. :return: Ruta de acceso al index.html extract_readable_article(html, url) Extrae el contenido del artículo principal desde «html», lo depura y lo devuelve como una tupla (html_artículo, título_extraído). Basado en el algoritmo original de legilibilidad de Arc90. get_article_url(article) Sustituir en una subclase para personalizar la extracción del URL que apunta al contenido de cada artículo. Devuelve el URL del artículo. Se ejecuta con article, un objeto que representa un artículo analizado de un canal. Véase feedparser 82. De manera predeterminada busca el enlace original (para canales agregados mediante un servicio como feedburner o pheedo) y, si se encuentra, devuelve dicho enlace o article.link 83 en caso contrario. get_browser(*args, **kwargs) Devuelve un navegador utilizado para obtener documentos desde Internet. De manera predeterminada devuelve un navegador mechanize< _ que soporta cookies, ignora robots.txt, tiene en cuenta los refrescos y tiene un agente de usuario de tipo mozilla firefox. Si la fórmula requiere un inicio de sesión, reemplace este método en la subclase. Por ejemplo, el siguiente código se usa en la fórmula del New York Times para iniciar la sesión y tener acceso total: def get_browser(self): br = BasicNewsRecipe.get_browser(self) if self.username is not None and self.password is not None: br.open(' br.select_form(name='login') br['userid'] = self.username br['password'] = self.password br.submit() return br get_cover_url() Devuelve un URL para la imagen de portada de este número o None. De manera predeterminada, devuelve el valor del miembro self.cover_url que es normalmente None. Si quiere que la fórmula descargue una portada para el libro electrónico reemplace este método en la subclase, o establezca la variable miembro self.cover_url antes de utilizar este método. get_feeds() Devuelve una lista de canales RSS para obtener en este perfil. Cada elemento de la lista debe ser una tupla Capítulo 1. Secciones

149 de 2 elementos de la forma (título, url). Si el título es None o un texto vacío, se utiliza el título del canal RSS. Este método es útil si la fórmula tiene que hacer algún tipo de procesado para obtener la lista de canales RSS para descargar. Si es así, reemplácelo en la subclase. get_masthead_title() Reemplácelo en la subclase para usar algo distinto del título de la fórmula get_masthead_url() Devuelve un URL a la imagen de cabecera de este número o None. De manera predeterminada, devuelve el valor del miembro self.masthead_url que es normalmente None. Si quiere que la fórmula descargue una imagen de cabecera para el libro electrónico reemplace este método en la subclase, o establezca la variable miembro self.masthead_url antes de utilizar este método. Las imágenes de cabecera se usan en los archivos MOBI de Kindle. get_obfuscated_article(url) Si establece articles_are_obfuscated este método se usa con cada URL de artículo. Debe devolver la ruta de acceso a un archivo en el sistema que contenga el código HTML del artículo. Este archivo es procesado por el motor de recolección de HTML recursivo, por lo que puede contener enlaces a páginas o imágenes en Internet. Este método es normalmente útil para sitios que tratan de dificultar el acceso automático al contenido de los artículos. classmethod image_url_processor(baseurl, url) Realiza algún procesado sobre las direcciones URL de las imágenes (tal vez eliminando restricciones de tamaño para imágenes generadas dinámicamente, etc.) y devuelve la dirección URL procesada. index_to_soup(url_or_raw, raw=false, as_tree=false) Método práctico que toma el URL de una página de índice y devuelve un objeto BeautifulSoup 84 que lo representa. url_or_raw: Un URL o la página de índice descargada como texto is_link_wanted(url, tag) Devuelve True si el enlace debe seguirse o False en caso contrario. De manera predeterminada, presenta NotImplementedError, que hace que el programa de descarga lo ignore. Parámetros url La dirección URL que debe seguirse tag La etiqueta de la que se extrajo la dirección URL javascript_login(browser, username, password) Este método se usa para iniciar una sesión en un sitio de Internet que emplee javascript en el correspondiente formulario. Una vez que la conexión se completa, las cookies devueltas por el sitio se copian en un navegador normal (sin javascript) y la descarga continúa con esas cookies. Un ejemplo de implementación: def javascript_login(self, browser, username, password): browser.visit(' form = browser.select_form(nr=0) # Select the first form on the page form['username'] = username form['password'] = password browser.submit(timeout=120) # Submit the form and wait at most two minutes for loading t Tenga en cuenta que también puede seleccionar formularios con selectores CSS2, de esta forma: Cursillos 145

150 browser.select_form('form#login_form') browser.select_from('form[name="someform"]') parse_feeds() Crea una lista de artículos desde la lista de canales devuelta por BasicNewsRecipe.get_feeds() (Página 312). Devuelve una lista objetos Feed. parse_index() Este método debe implementarse en las fórmulas que analizan una página de Internet en lugar de canales RSS para generar una lista de artículos. Los usos típicos son fuentes de noticias que tienen una página del tipo «edición impresa» que enumera todos los artículos de la edición impresa actual. Si se implementa esta función, se usará con prioridad sobre BasicNewsRecipe.parse_feeds() (Página 313). Debe devolver una lista. Cada elemento de la lista debe ser una tupla de 2 elementos de la forma ( título del canal, lista de artículos). Cada lista de artículos deben contener diccionarios del tipo: { 'title' : article title, 'url' : URL of print version, 'date' : The publication date of the article as a string, 'description' : A summary of the article 'content' : The full article (can be an empty string). Obsolete do not use, instead save the content to a temporary file and pass a file:///path/to/temp/file.html as the URL. } Como ejemplo, véase la fórmula para descargar The Atlantic. Además, puede añadir «author» para el autor del artículo. Si desea cancelar el proceso por alguna razón y hacer que calibre muestre al usuario un simple mensaje en lugar de un error, use abort_recipe_processing() (Página 310). populate_article_metadata(article, soup, first) Utilizada al descargar cada página HTML perteneciente al artículo. Pensada para obtener los metadatos del artículo, como autor, resumen, etc. a partir del HTML analizado (el argumento soup). :param article: Un objeto de la clase calibre.web.feeds.article. Si cambia el resumen, recuerde que debe cambiar también el text_summary :param soup: HTML analizado perteneciente a este artículo :param first: es True si y sólo si el HTML analizado es la primera página del artículo. postprocess_book(oeb, opts, log) Ejecutar cualquier procesado posterior necesario sobre el libro electrónico descargado. Parámetros oeb Un objeto OEBBook opts Opciones de conversión postprocess_html(soup, first_fetch) Este método se ejecuta con el código fuente de cada archivo HTML, después de analizar sus imágenes y enlaces. Puede usarse para efectuar un procesado arbitrario sobre el HTML. Debe devolver soup después del procesado. Parámetros soup Un objeto BeautifulSoup 85 que contiene el HTML descargado Capítulo 1. Secciones

151 first_fetch True si ésta es la primera página de un artículo. preprocess_html(soup) Este método se ejecuta con el código fuente de cada archivo HTML, antes de analizar sus imágenes y enlaces. Se ejecuta después de la limpieza especificada por remove_tags, etc. Puede usarse para efectuar un preprocesado arbitrario sobre el HTML. Debe devolver soup después del procesado. soup: Un objeto BeautifulSoup 86 que contiene el HTML descargado. preprocess_raw_html(raw_html, url) Este método se ejecuta con el código fuente de cada archivo HTML, antes de convertirlo en un árbol de objetos. raw_html es un texto unicode que representa el HTML en bruto descargado de Internet. url es la dirección URL desde donde se descargó el HTML. Tenga en cuenta que este método actúa antes de preprocess_regexps. Este método debe devolver el archivo raw_html procesado como un objeto unicode. classmethod print_version(url) Tomar un url que apunta a la página de Internet con el contenido del artículo y devuelve el URL de la versión para imprimir del artículo. De manera predeterminada no hace nada. Por ejemplo: def print_version(self, url): return url + '?&pagewanted=print' skip_ad_pages(soup) Este método se ejecuta con el código fuente de cada archivo HTML descargado, antes de aplicar ningún atributo de limpieza como remove_tags o keep_only_tags. Tenga en cuenta que preprocess_regexps ya se habrá aplicado. Está pensado para permitir que la fórmula evite las páginas de publicidad. Si soup representa una página de publicidad, devuelve el HTML de la página real. De lo contrario devuelve None. soup: Un objeto BeautifulSoup 87 que contiene el HTML descargado. sort_index_by(index, weights) Método práctico para ordenar los títulos en index según weights. index se ordena en su lugar. Devuelve index. index: Una lista de títulos. weights: Un diccionario que asigna pesos a los títulos. Si un título del índice no está en weights, se asume que tiene un peso de 0. classmethod tag_to_string(tag, use_alt=true, normalize_whitespace=true) Método práctico que toma un objeto Tag de BeautifulSoup 88 y extrae el texto recursivamente, incluyendo secciones CDATA y atributos «alt». Devuelve un texto unicode posiblemente vacío. use_alt: Si es True intenta usar el atributo «alt» para las etiquetas que no poseen contenido textual tag: Un objeto Tag de BeautifulSoup 89 articles_are_obfuscated = False Establézcalo a True e implemente get_obfuscated_article() (Página 312) para manejar sitios de Internet que tratan de dificultar la obtención de contenido. auto_cleanup = False Extrae automáticamente todo el texto de las páginas de artículos descargadas. Utiliza los algoritmos del proyecto legibilidad. Si se establece en True, no hay necesidad de preocuparse de limpiar el código HTML manualmente (aunque la limpieza manual siempre será mejor) Cursillos 147

152 auto_cleanup_keep = None Especifica los elementos que el algoritmo de limpieza automática no debe eliminar nunca. La sintaxis es una expresión XPath. Por ejemplo: auto_cleanup_keep = '//div[@id="article-image"]' will keep all divs with id="article-image" auto_cleanup_keep = '//*[@class="important"]' will keep all elements with class="important" auto_cleanup_keep = '//div[@id="article-image"] //span[@class="important"]' will keep all divs with id="article-image" and spans with class="important" center_navbar = True Si es True la barra de navegación se alinea al centro, en caso contrario se alinea a la izquierda compress_news_images = False Si es False, se descartan todos los parámetros de escala y compresión y se dejan las imágenes sin modificar. Si es True y los otros parámetros de compresión se dejan en sus valores predeterminados, las imágenes jpeg se redimensionarán para adaptarse al tamaño de la pantalla establecido por el perfil de salida y se comprimen a un tamaño máximo de (w h)/16, donde «w» y «h» son la anchura y altura redimensionadas de la imagen. compress_news_images_auto_size = 16 El factor utilizado cuando se comprimen automáticamente las imágenes jpeg. Si se establece en None, la compresión automática se desactiva. De lo contrario, las imágenes se reducirán a un tamaño en bytes de (w h)/compress_news_images_auto_size, si es posible, reduciendo el nivel de calidad, donde «w» y «h» son la anchura y la altura de la imagen en píxeles. La calidad mínima del jpeg mínima será 5/100 por lo que es posible que no pueda cumplirse con esta restricción. Este parámetro se puede anular con el parámetro compress_news_images_max_size, que proporciona un tamaño máximo fijo para las imágenes. Tenga en cuenta que si se habilita scale_news_images_to_device entonces la imagen se ampliará primero y luego su calidad se reducirá hasta que su tamaño sea menor que (w h)/factor donde «w» y «h» son ahora las dimensiones de imagen redimensionada. En otras palabras, esta compresión ocurre después del redimensionado. compress_news_images_max_size = None Establece la calidad de los archivos jpeg para que las imágenes no excedan el tamaño dado (en kbytes). Si se establece este parámetro, la compresión automática vía compress_news_images_auto_size no tiene lugar. La calidad mínima del jpeg será 5/100 por lo que es posible que no pueda cumplirse con esta restricción. conversion_options = {} Opciones específicas de la fórmula para controlar la conversión del contenido descargado en un libro electrónico. Éstas tienen prioridad sobre cualquier valor especificado por el usuario o un complemento, por lo que deben utilizarse sólo si es absolutamente necesario. Por ejemplo: conversion_options = { 'base_font_size' : 16, 'tags' : 'mytag1,mytag2', 'title' : 'My Title', 'linearize_tables' : True, } cover_margins = (0, 0, #ffffff ) De manera predeterminada, la imagen de portada devuelta por get_cover_url() se utilizará como portada para la publicación. Si se establece un valor para esta variable en una fórmula, calibre colocará la portada descargada dentro de un marco cuya anchura y altura se expresan como un porcentaje de la portada descargada. cover_margins = (10, 15, #ffffff ) rellena la portada con un margen blanco de 10px a la izquierda y derecha, 15px en la parte superior e inferior. Los nombres de los colores están definidos en 148 Capítulo 1. Secciones

153 Tenga en cuenta que, por alguna razón, «white» no siempre funciona en Windows. Utilice «#ffffff» en su lugar. delay = 0 Tiempo de espera, en segundos, entre descargas consecutivas. El argumento puede ser un número decimal para indicar un tiempo más preciso. description = u Un par de líneas que describen el contenido que descarga esta fórmula. Se usará principalmente en una interfaz gráfica que presenta una lista de fórmulas. encoding = None Especifica una codificación para los sitios que tienen una especificación de conjunto de caracteres incorrecta. El error más común es declarar latin1 y usar cp1252. Si es None, trata de detectar la codificación. Si es un método ejecutable, se usará con dos argumentos: el objeto de la fórmula y el código fuente para descodificar. Debe devolver el código descodificado. extra_css = None Especifica cualquier CSS extra que deba añadirse a los archivos HTML descargados. Se insertará en etiquetas <style>, justo antes de la etiqueta de cierre </head> con prioridad sobre todo CSS excepto el que se declara con el atributo «style» en etiquetas HTML individuales. Por ejemplo: extra_css = '.heading { font: serif x-large }' feeds = None Lista de canales para descargar. Puede ser [url1, url2,...] o [( título1, url1), ( título2, url2),...] filter_regexps = [] Lista de expresiones regulares que determina qué enlaces ignorar. Si está vacía no se tiene en cuenta. Usado sólo si is_link_wanted no está implementado. Por ejemplo: filter_regexps = [r'ads\.doubleclick\.net'] eliminará todos los URL que contengan ads.doubleclick.net. Sólo uno de entre BasicNewsRecipe.match_regexps (Página 317) y BasicNewsRecipe.filter_regexps (Página 316) deben definirse. ignore_duplicate_articles = None Ignorar duplicados de los artículos que están presentes en más de una sección. Un artículo duplicado es un artículo que tiene el mismo título o dirección URL. Para ignorar artículos con el mismo título, establézcalo como: ignore_duplicate_articles = {'title'} En cambio, para utilizar las direcciones URL, establézcalo como: ignore_duplicate_articles = {'url'} Para hacer que coincida el título o URL, establézcalo como: ignore_duplicate_articles = {'title', 'url'} keep_only_tags = [] Mantiene sólo las etiquetas especificadas y sus descendientes. El formato para especificar una etiqueta está definido en BasicNewsRecipe.remove_tags (Página 318). Si la lista no está vacía, entonces la etiqueta <body> se vaciará y se volverá a llenar con las etiquetas que coincidan con las entradas en esta lista. Por ejemplo: 1.9. Cursillos 149

154 keep_only_tags = [dict(id=['content', 'heading'])] mantendrá sólo las etiquetas que posean un atributo id igual a content o heading. language = und El idioma en que están las noticias. Debe ser un código ISO-639 de dos o tres letras masthead_url = None De manera predeterminada, calibre usará la imagen predeterminada para la cabecera (sólo en Kindle). Dé un valor a esta variable en la fórmula para proporcionar un URL para usar como cabecera. match_regexps = [] Lista de expresiones regulares que determina qué enlaces seguir. Si está vacía, no se tiene en cuenta. Se usa sólo si is_link_wanted no está implementado. Por ejemplo: match_regexps = [r'page=[0-9]+'] coincidirá con todas las direcciones URLs que posean page=algún número. Sólo uno de entre BasicNewsRecipe.match_regexps (Página 317) y BasicNewsRecipe.filter_regexps (Página 316) deben definirse. max_articles_per_feed = 100 Número máximo de artículos para descargar de cada canal. Esto es útil sobre todo para los canales que no tienen fechas en los artículos. Para la mayoría de los canales, debe usar BasicNewsRecipe.oldest_article (Página 317) needs_subscription = False Si es True, la interfaz gráfica pedirá al usuario un nombre y una contraseña para utilizar en la descarga. Si se establece en "optional" el nombre y contraseña serán opcionales. no_stylesheets = False Opción útil para desactivar la carga de hojas de estilo en los sitios de Internet que tienen hojas de estilo excesivamente complejas, poco apropiadas para la conversión a formatos de libro electrónico. Si es True, las hojas de estilo no se descargan ni procesan oldest_article = 7.0 Artículo más antiguo para descargar desde la fuente de noticias. En días. preprocess_regexps = [] Lista de reglas de sustitución regexp para ejecutar sobre los HTML descargados. Cada elemento de la lista debe ser una tupla de dos elementos. El primer elemento de la tupla debe ser una expresión regular compilada y el segundo un método ejecutable que toma un objeto de coincidencia único y devuelve un texto para sustituir a la coincidencia. Por ejemplo: preprocess_regexps = [ (re.compile(r'<!--article ends here-->.*</body>', re.dotall re.ignorecase), lambda match: '</body>'), ] eliminará todo lo que haya entre <! Article ends here > y </body>. publication_type = unknown Tipo de publicación. Establecer como «newspaper», «magazine» o «blog». Si se establece en None, no se escribirá el metadato de tipo de publicación en el archivo opf. recipe_disabled = None Establecer a un texto no vacío para desactivar esta fórmula. El texto se utilizará como el mensaje de desactivación. 150 Capítulo 1. Secciones

155 recursions = 0 Número de niveles de enlaces para seguir en las páginas web de los artículos remove_attributes = [] Lista de atributos para quitar de todas las etiquetas. Por ejemplo: remove_attributes = ['style', 'font'] remove_empty_feeds = False Si es True los canales vacíos se eliminan de la salida. Esta opción no tiene efecto si parse_index se reemplaza en la subclase. Está pensado sólo para las fórmulas que devuelven una lista de canales que utilizan feeds o get_feeds() (Página 312). También se utiliza si se emplea la opción ignore_duplicate_articles. remove_javascript = True Opción útil para eliminar todas las etiquetas javascript del archivo HTML descargado remove_tags = [] Lista de etiquetas para ser eliminadas. Las etiquetas especificadas se eliminan del HTML descargado. Cada etiqueta se especifica como un diccionario de la forma: { name : 'tag name', #e.g. 'div' attrs : a dictionary, #e.g. {class: 'advertisment'} } Todas las claves son opcionales. Para una explicación completa de los criterios de búsqueda, véase Beautiful Soup 90 (en inglés). Un ejemplo frecuente: remove_tags = [dict(name='div', attrs={'class':'advert'})] Esto eliminará todas las etiquetas <div class= advert > y todos sus elementos descendientes del HTML descargado. remove_tags_after = None Elimina todas las etiquetas que se aparecen después de la etiqueta especificada. La forma de especificar una etiqueta se muestra en BasicNewsRecipe.remove_tags (Página 318). Por ejemplo: remove_tags_after = [dict(id='content')] eliminará todas las etiquetas después del primer elemento con id= content. remove_tags_before = None Elimina todas las etiquetas que aparecen antes de la etiqueta especificada. La forma de especificar una etiqueta se da en BasicNewsRecipe.remove_tags (Página 318). Por ejemplo: remove_tags_before = dict(id='content') eliminará todas las etiquetas antes del primer elemento con id= content. requires_version = (0, 6, 0) Versión mínima de calibre necesaria para usar esta fórmula resolve_internal_links = False Si es True los enlaces en los artículos descargados que apunten a otros artículos descargados se cambian para que apunten a la copia descargada del artículo en lugar de al URL original. Si lo establece en True, puede que también necesite implementar canonicalize_internal_url() (Página 311) para que funcione con el esquema URL del sitio web concreto. reverse_article_order = False Invierte el orden de los artículos de cada canal 90 %20the %20Parse %20Tree 1.9. Cursillos 151

156 scale_news_images = None Dimensiones máximas (anchura, altura) para redimensionar las imágenes. Si scale_news_images_to_device es True, estas dimensiones son el tamaño de la pantalla del dispositivo establecido en el perfil de salida, a menos que no haya un perfil seleccionado, en cuyo caso se deja en el valor que se le haya asignado (de manera predeterminada None). scale_news_images_to_device = True Cambiar el tamaño de las imágenes para que quepan en la pantalla del dispositivo establecido por el perfil de salida. Se omite si no hay un perfil de salida seleccionado. simultaneous_downloads = 5 Número de descargas simultáneas. Establecer en 1 si el servidor es exigente. Se reduce automáticamente a 1 si BasicNewsRecipe.delay (Página 316) > 0 summary_length = 500 Número máximo de caracteres en la descripción breve template_css = u \n.article_date {\n color: gray; font-family: monospace;\n }\n\n.article_description {\n text-indent: 0 El CSS que se usa para dar el estilo a las plantillas, por ejemplo, las barras de navegación y los índices. En lugar de sustituir esta variable, puede usar extra_css en la fórmula para personalizar la apariencia. timefmt = [ %a, %d %b %Y] El texto de formato para la fecha que se muestra en la primera página. Predeterminado: Nombre_del_día, Número_del_día Nombre_del_mes Año timeout = Tiempo de espera para obtener archivos desde el servidor, en segundos title = u Fuente de noticias desconocida El título que se usará para el libro electrónico use_embedded_content = None Normalmente se intenta deducir si un canal contiene artículos completos incrustados, sobre la base de la longitud del contenido incrustado. Si es Ninguno, entonces se utiliza el método predeterminado. Si es True, se supone siempre que los canales contienen artículos incrustados y si es False, se supone siempre que los canales no contienen artículos incrustados. use_javascript_to_login = False Si establece esto como True, entonces calibre usará javascript para iniciar sesión en el sitio de Internet. Esto es necesario para ciertos sitios que requieren el uso de javascript para iniciar sesión. Si establece esto como True debe implementar el método javascript_login() (Página 313), para iniciar una sesión Gestionar subgrupos de libros, por ejemplo «género» Algunas personas prefieren organizar los libros de su biblioteca en subgrupos, de forma similar a las subcarpetas. El motivo más frecuente es crear jerarquías de géneros, pero hay muchas otras. Un usuario pide una forma de organizar los libros de texto por número de curso y tema. Otro usuario quiere hacer un seguimiento de los regalos por tema y destinatario. Este cursillo usará el caso de los géneros para el resto de esta entrada. Antes de continuar, tenga en cuenta que no estamos hablando de carpetas en el disco duro. Los subgrupos no son carpetas de archivos. Los libros no se copiarán en ningún lugar. La estructura de archivos de la biblioteca de calibre no se ve afectada. En su lugar, se trata de una forma de organizar y mostrar subgrupos de libros en una biblioteca calibre. Configuración (Página 154) Búsqueda (Página 156) Restricciones (Página 156) Funciones de plantilla útiles (Página 157) 152 Capítulo 1. Secciones

157 Los requisitos normalmente establecidos para subgrupos tales como géneros son: Un subgrupo (por ejemplo, un género) debe contener (o apuntar a) libros, no categorías de libros. Esto es lo que distingue los subgrupos de las categorías de usuario de calibre. Un libro puede estar en varios subgrupos (géneros). Esto distingue a los subgrupos de las carpetas físicas de archivos. Los subgrupos (géneros) deben formar una jerarquía; los subgrupos pueden contener subgrupos. Las etiquetas satisfacen los dos primeros. Si etiqueta un libro con el género, puede utilizar el explorador de etiquetas (o una búsqueda) para encontrar los libros con ese género, lo que satisface el primer requisito. Varios libros pueden tener la misma etiqueta, lo que satisface el segundo. El problema es que las etiquetas no satisfacen el tercer requisito. No proporcionan una jerarquía. La función jerárquica de calibre proporciona la tercer opción, la posibilidad de ver los géneros como un «árbol» y la capacidad de buscar libros por género o subgénero. Por ejemplo, supongamos que la estructura de géneros es parecida a la siguiente: Genre. History.. Japanese.. Military.. Roman. Mysteries.. English.. Vampire. Science Fiction.. Alternate History.. Military.. Space Opera. Thrillers.. Crime.. Horror etc. Mediante la función de jerarquía se pueden ver estos géneros en el explorador de etiquetas en forma de árbol, como 1.9. Cursillos 153

158 se muestra en la imagen de la pantalla. En este ejemplo, el nivel superior (Género) es una columna personalizada que contiene los géneros. Éstos contienen subgéneros que aparecen con un pequeño triángulo a su lado. Al pulsar en ese triángulo se abrirá el elemento y se mostrarán los subgéneros, como se puede ver con Historia y Ciencia ficción. Al pulsar en un género puede buscar todos los libros con ese género sus descendientes. Por ejemplo, al pulsar en «Ciencia ficción» obtendrá también todos los libros en los géneros desdendientes: «Historia alternativa», «militar» y «Ópera espacial».. Al pulsar en «Historia alternativa» obtendrá los libros de ese género, y no los de los géneros «Militar» y «Ópera espacial». Por supuesto, un libro puede tener múltiples géneros. Si un libro tiene tanto los géneros «Ópera espacial» como «Militar», dicho libro aparecerá al pulsar en cualquiera de los dos géneros. Las búsquedas se discuten con más detalle a continuación. Otra cosa que se puede ver en la imagen es que el género «Militar» aparece dos veces, una vez bajo «Historia» y otra bajo «Ciencia ficción». Dado que los géneros forman una jerarquía, se trata de dos géneros distintos. Un libro puede estar en uno, otro, o (poco probable en este caso) en ambos. Por ejemplo, los libros de la serio «La Segunda Guerra Mundial» de Winston Churchill podrían estar en «Historia.Militar». Los libros de la serie «Honor Harrington» de David Weber podrían estar en «Ciencia ficción.militar», y ya puestos también en «Ciencia ficción.ópera espacial». Una vez que existe un género, es decir, que existe al menos un libro con ese género, puede aplicarlo fácilmente a otros libros arrastrando los libros desde la vista de biblioteca al género que desea que tengan los libros. También puede aplicar los géneros en los editores de metadatos; más sobre esto, más adelante. Configuración Por el momento puede que se esté preguntando cómo se ha conseguido todo esto. Hay tres pasos: 1) crear la columna personalizada, 2) comunicar a calibre que la nueva columna debe tratarse como una jerarquía y 3) añadir los géneros. Cree la columna personalizada de la forma habitual, usando Preferencias > Interfaz > Añadir columnas personalizadas. Este ejemplo utiliza «#género» como el nombre de búsqueda y «Género» como el encabezado de columna. El tipo de columna es «texto separado por comas, como las etiquetas, se mostrará en el explorador de etiquetas. Después de reiniciar calibre, debe informar a calibre de que la columna debe ser tratada como una jerarquía. En Preferencias > Apariencia > Explorador de etiquetas escriba el nombre de la búsqueda «#género» en «Categorías con elementos jerárquicos». Pulse «Aplicar», y ya está concluida la configuración. 154 Capítulo 1. Secciones

159 En este punto aún no hay géneros en la columna. Nos queda el último paso: cómo aplicar un género a un libro. Un género no existe en calibre hasta que aparece en al menos un libro. Para aprender cómo aplicar un género por primera vez, hay que entrar en algunos detalles acerca de cómo se muestra un género en los metadatos de un libro. Una jerarquía de «cosas» se construye mediante la creación de un elemento que consiste en frases separadas por puntos. Continuando con el ejemplo de los géneros, estos elementos serían «Historia.Militar», «Misterio.Vampiros», «Ciencia ficción.ópera espacial», etc. Por lo tanto, para crear un nuevo género, simplemente elija un libro que deba tener ese género, modifique sus metadatos e introduzca el nuevo género dentro de la columna que ha creado. Continuando con nuestro ejemplo, si desea asignar un nuevo género «Historietas» con un subgénero «Superhéroes» a un libro, activaría «Modificar metadatos» para ese libro, eligiría la pestaña de metadatos personalizados y a continuación introduciría «Historieta.Superhéroes» como se muestra a continuación (no preste atención a las otras columnas personalizadas): Después de hacer lo anterior, el explorador de etiquetas mostrará: 1.9. Cursillos 155

160 A partir de ahora, para aplicar este nuevo género a un libro, puede arrastrar el libro sobre el género o añadirlo al libro usando el editor de metadatos, de la misma manera que se ha hecho anteriormente. Búsqueda La forma más fácil de buscar géneros es utilizar el explorador de etiquetas, pulsando en el género que desee ver. Al hacerlo sobre un género con descendientes se mostrarán los libros con ese género y todos los géneros de sus descendientes. Sin embargo, esto suscita una cuestión. El hecho de que un género tenga descendientes, no significa que no sea un género en sí mismo. Por ejemplo, un libro puede tener el género «Historia», pero no «Historia.Militar». Cómo buscar libros con sólo «Historia»? El mecanismo de búsqueda del explorador de etiquetas sabe si un elemento tiene descendientes. Si es así, al pulsar sobre el elemento se pasa sucesivamente por cinco búsquedas en lugar de las tres normales. La primera es el signo «+» verde, que muestra libros con sólo ese género (por ejemplo, «Historia»). El segundo es un doble signo «+» (mostrado arriba), que muestra libros con ese género y todos los subgéneros (por ejemplo, «Historia» e «Historia.Militar»). El tercero es el signo «-» rojo normal, que muestra los libros sin ese género exacto. El cuarto es un signo «-» duplicado, que muestra libros sin ese género o subgéneros. El quinto vuelve nuevamente al principio, ninguna marca, es decir, sin ninguna búsqueda. Restricciones Si busca un género, cree una búsqueda guardada; puede utilizar la opción «restringir a» para crear una biblioteca virtual de libros con ese género. Esto es útil si quiere hacer otras búsquedas dentro del género o para gestionar o actualizar metadatos de los libros de ese género. Continuando con nuestro ejemplo, puede crear una búsqueda guardada llamada 156 Capítulo 1. Secciones

161 «Historia.Japonesa» pulsando primero en el género «Japonesa» del explordor de etiquetas para obtener una búsqueda en el cuadro de búsqueda, introduciendo «Historia.Japonesa» dentro del cuadro de búsqueda guardada y a continuación pulsando el botón «guardar búsqueda» (el cuadro verde con el signo + blanco, en el lado derecho). Una vez creada la búsqueda guardada, puede utilizarla como una restricción. Funciones de plantilla útiles Es posible que desee utilizar la información de género en una plantilla, tales como guardar en disco o enviar a dispositivo. La pregunta podría ser entonces: «Cómo puedo obtener ell nombre o nombres de género más externo?». Hay una función de plantilla de calibre, subítems, que hace esto más fácil. Por ejemplo, supongamos que desea agregar el nivel de género más extrerno a la plantilla de guardar en disco para hacer carpetas de género, como «Historia/Se cierne la tormenta - Churchill, Winston». Para conseguirlo, debe extraer el primer nivel de la jerarquía y añadirlo al principio, junto con una barra para indicar que se debe hacer una carpeta. La siguiente plantilla hace esto: {#genre:subitems(0,1) /}{title} - {authors} Vea El lenguaje de plantillas (Página 159) para más información sobre las plantillas y la función subitems() Cursillo de XPath En este cursillo, se presentará una pequeña introducción a XPath 91, un lenguaje de consulta que se puede utilizar para seleccionar partes arbitrarias de documentos HTML 92 en calibre. XPath es un estándar ampliamente utilizado, y una búsqueda a través de Google proporcionará gran cantidad de información. Este cursillo, sin embargo, se centra en el uso de XPath para tareas relacionadas con libros electrónicos, como la búsqueda de cabeceras de capítulos en un documento HTML sin estructura Cursillos 157

162 Índice Seleccionar por nombre de etiqueta (Página 158) Seleccionar por atributos (Página 158) Seleccionar por contenido de etiqueta (Página 159) Libro electrónico de muestra (Página 159) Funciones XPath predefinidas (Página 159) Seleccionar por nombre de etiqueta La forma más simple de selección es seleccionar las etiquetas por su nombre. Por ejemplo, suponga que desea seleccionar todas las etiquetas <h2> en un documento. La consulta XPath para esto es simplemente: //h:h2 (Selects all <h2> tags) El prefijo // significa buscar en cualquier nivel del documento. Supongamos que desea encontarar las etiquetas <span> que están dentro de etiquetas <a>. Esto se puede lograr con: //h:a/h:span (Selects <span> tags inside <a> tags) Si quiere buscar etiquetas en un nivel particular del documento, cambie el prefijo: /h:body/h:div/h:p (Selects <p> tags that are children of <div> tags that are children of the <body> tag) Esto coincidirá sólo con <p>a very short ebook to demonstrate the use of XPath.</p> en Libro electrónico de muestra (Página 159), pero no con ninguna de las otras etiquetas <p>. El prefijo h: en los ejemplos anteriores se necesita para encontrar las etiquetas XHTML. Esto se debe a que internamente calibre representa todo el contenido como XHTML. En XHTML las etiquetas tienen un espacio de nombres, y h: es el prefijo de espacio de nombrs para las etiquetas HTML. Ahora supongamos que desea seleccionar ambas etiquetas <h1> y <h2>. Para hacer esto, necesitamos una construcción XPath llamada predicado. Un predicado es simplemente una comprobación que se utiliza para seleccionar etiquetas. Las comprobaciones pueden ser muy potentes y, según avance este cursillo, verá ejemplos más sofisticados. Un predicado se crea encerrando la expresión de comprobación entre corchetes: //*[name()='h1' or name()='h2'] Hay varias características nuevas en esta expresión XPath. La primera es el uso del comodín *. Significa cualquier etiqueta. Ahora observe la expresión de comprobación name()= h1 or name()= h2. name() es un ejemplo de función predefinida. Simplemente evalúa el nombre de la etiqueta. Por lo tanto, mediante su uso, podemos seleccionar etiquetas cuyo nombre sea h1 o h2. Tenga en cuenta que la función name() ignora los espacios de nombres de modo que no hay necesidad del prefijo h:. XPath tiene varias funciones predefinidas. Se presentarán algunas más en este cursillo. Seleccionar por atributos Para seleccionar etiquetas según sus atributos, es necesario usar predicados: //*[@style] (Select all tags that have a style attribute) //*[@class="chapter"] (Select all tags that have class="chapter") //h:h1[@class="booktitle"] (Select all h1 tags that have class="booktitle") Aquí, el se refiere a los atributos de la etiqueta. Puede utilizar algunas de las XPath built-in functions _ para realizar búsquedas más sofisticadas en los valores de los atributos. 158 Capítulo 1. Secciones

163 Seleccionar por contenido de etiqueta Utilizando XPath, puede incluso seleccionar etiquetas basadas en el texto que contienen. La mejor manera para para hacer esto es usar el poder de las expresiones regulares a través la función predefinida re:test(): //h:h2[re:test(., 'chapter section', 'i')] (Selects <h2> tags that contain the words chapter or section) Aquí el operador. se refiere a los contenidos de la etiqueta, igual que el se refiere a sus atributos. Libro electrónico de muestra <html> <head> <title>a very short ebook</title> <meta name="charset" value="utf-8" /> </head> <body> <h1 class="booktitle">a very short ebook</h1> <p style="text-align:right">written by Kovid Goyal</p> <div class="introduction"> <p>a very short ebook to demonstrate the use of XPath.</p> </div> <h2 class="chapter">chapter One</h2> <p>this is a truly fascinating chapter.</p> <h2 class="chapter">chapter Two</h2> <p>a worthy continuation of a fine tradition.</p> </body> </html> Funciones XPath predefinidas name() El nombre de la etiqueta actual. contains() contains(s1, s2) devuelve true si s1 contiene s2. re:test() re:test(fuente, patrón, opciones) devuelve true si el texto fuente coincide con la expresión regular patrón. Una opción particularmente útil es i, que hace que no se distingaa entre mayúsculas y minúsculas. Una buena introducción a la sintaxis de las expresiones regulares se puede encontrar en sintaxis de expresiones regulares 93 (en inglés) El lenguaje de plantillas de calibre The calibre template language is used in various places. It is used to control the folder structure and file name when saving files from the calibre library to the disk or ebook reader. It is also used to define virtual columns that contain data from other columns and so on. The basic template language is very simple, but has very powerful advanced features. The basic idea is that a template consists of text and names in curly brackets that are then replaced by the corresponding metadata from the book being processed. So, for example, the default template used for saving books to device in calibre is: Cursillos 159

164 {author_sort}/{title}/{title} - {authors} Para el libro «La Fundación» de «Isaac Asimov» da lugar a: Asimov, Isaac/The Foundation/The Foundation - Isaac Asimov The slashes are text, which is put into the template where it appears. For example, if your template is: {author_sort} Some Important Text {title}/{title} - {authors} Para el libro «La Fundación» de «Isaac Asimov» da lugar a: Asimov, Isaac Some Important Text The Foundation/The Foundation - Isaac Asimov You can use all the various metadata fields available in calibre in a template, including any custom columns you have created yourself. To find out the template name for a column simply hover your mouse over the column header. Names for custom fields (columns you have created yourself) always have a # as the first character. For series type custom fields, there is always an additional field named #seriesname_index that becomes the series index for that series. So if you have a custom series field named #myseries, there will also be a field named #myseries_index. Además de los campos basados en columnas, también puede usar: {formats} - A list of formats available in the calibre library for a book {identifiers:select(isbn)} - The ISBN number of the book If a particular book does not have a particular piece of metadata, the field in the template is automatically removed for that book. Consider, for example: {author_sort}/{series}/{title} {series_index} Si un libro tiene una serie, la plantilla producirá: Asimov, Isaac/Foundation/Second Foundation 3 y si un libro no pertenece a una serie: Asimov, Isaac/Second Foundation (calibre elimina automáticamente barras múltiples y espacios iniciales o finales). Formato avanzado You can do more than just simple substitution with the templates. You can also conditionally include text and control how the substituted data is formatted. First, conditionally including text. There are cases where you might want to have text appear in the output only if a field is not empty. A common case is series and series_index, where you want either nothing or the two values with a hyphen between them. Calibre handles this case using a special field syntax. Por ejemplo, supongamos que desea usar la plantilla: {series} - {series_index} - {title} If the book has no series, the answer will be - - title. Many people would rather the result be simply title, without the hyphens. To do this, use the extended syntax {field: prefix_text suffix_text}. When you use this syntax, if field has the value SERIES then the result will be prefix_textseriessuffix_text. If field has no value, then the result will be the empty string (nothing); the prefix and suffix are ignored. The prefix and suffix can contain blanks. Do not use subtemplates ( {... } ) or functions (see below) as the prefix or the suffix. Usando esta sintaxis, podemos resolver el problema anterior de las series con esta plantilla: 160 Capítulo 1. Secciones

165 {series}{series_index: - - }{title} The hyphens will be included only if the book has a series index, which it will have only if it has a series. Notes: you must include the : character if you want to use a prefix or a suffix. You must either use no characters or both of them; using one, as in {field: - }, is not allowed. It is OK not to provide any text for one side or the other, such as in {series: - }. Using {title: } is the same as using {title}. Second: formatting. Suppose you wanted to ensure that the series_index is always formatted as three digits with leading zeros. This would do the trick: {series_index:0>3s} - Three digits with leading zeros Si en lugar de ceros a la izquierda desea espacios, utilice: {series_index:>3s} - Three digits with leading spaces Para obtener ceros a la derecha use: {series_index:0<3s} - Three digits with trailing zeros If you use series indices with sub values (e.g., 1.1), you might want to ensure that the decimal points line up. For example, you might want the indices 1 and 2.5 to appear as and so that they will sort correctly. To do this, use: {series_index:0>5.2f} - Five characters, consisting of two digits with leading zeros, a decimal point Si quiere sólo las dos primeras letras de los datos, use: {author_sort:.2} - Only the first two letter of the author sort name El lenguaje de plantillas de calibre proviene de python, para obtener más detalles sobre la sintaxis de estas operaciones de formato avanzadas, vea la documentación de Python 94 (en inglés). Funciones avanzadas Usar plantillas en columnas personalizadas There are sometimes cases where you want to display metadata that calibre does not normally display, or to display data in a way different from how calibre normally does. For example, you might want to display the ISBN, a field that calibre does not display. You can use custom columns for this by creating a column with the type column built from other columns (hereafter called composite columns), and entering a template. Result: calibre will display a column showing the result of evaluating that template. To display the ISBN, create the column and enter {identifiers:select(isbn)} into the template box. To display a column containing the values of two series custom columns separated by a comma, use {#series1:,}{#series2}. Las columnas compuestas pueden utilizar cualquier opción de plantilla, incluidas las de formato. You cannot change the data contained in a composite column. If you edit a composite column by double-clicking on any item, you will open the template for editing, not the underlying data. Editing the template on the GUI is a quick way of testing and changing composite columns. Usar funciones en plantillas: modo de función única Suppose you want to display the value of a field in upper case, when that field is normally in title case. You can do this (and many more things) using the functions available for templates. For example, to display the title in upper case, use Cursillos 161

166 {title:uppercase()}. To display it in title case, use {title:titlecase()}. Function references appear in the format part, going after the : and before the first or the closing }. If you have both a format and a function reference, the function comes after another :. Functions must always end with (). Some functions take extra values (arguments), and these go inside the (). Functions are always applied before format specifications. See further down for an example of using both a format and a function, where this order is demonstrated. The syntax for using functions is {field:function(arguments)}, or {field:function(arguments) prefix suffix}. Arguments are separated by commas. Commas inside arguments must be preceeded by a backslash ( \ ). The last (or only) argument cannot contain a closing parenthesis ( ) ). Functions return the value of the field used in the template, suitably modified. Important: If you have programming experience, please note that the syntax in this mode (single function) is not what you might expect. Strings are not quoted. Spaces are significant. All arguments must be constants; there is no sub-evaluation. Do not use subtemplates ( {... } ) as function arguments. Instead, use template program mode (Página 164) and general program mode (Página 185). Muchas funciones usan expresiones regulares. En todos los casos, la expresión regular no distingue entre mayúsculas y minúsculas. Las funciones disponibles se enumeran a continuación. Tenga en cuenta que la documentación definitiva para las funciones está disponibles en la sección Clasificación de funciones (Página 170): lowercase() devuelve el valor del campo en minúsculas. uppercase() devuelve el valor del campo en mayúsculas. titlecase() devuelve el valor del campo con las iniciales en mayúscula. capitalize() devuelve el valor con la primera letra mayúscula y el resto en minúsculas. contains(pattern, text if match, text if not match) checks if field contains matches for the regular expression pattern. Returns text if match if matches are found, otherwise it returns text if no match. count(separador) interpreta el valor como una lista de elementos separados por separador y devuelve el número de elementos de la lista. La mayoría de las listas usan una coma como separador, pero «authors» usa un ampersand («&»). Ejemplos: {tags:count(,)}, {authors,count(&)} format_number(template) interprets the value as a number and format that number using a python formatting template such as {0:5.2f} or {0:,d} or ${0:5,.2f}. The field_name part of the template must be a 0 (zero) (the {0: in the above examples). See the template language and python documentation for more examples. Returns the empty string if formatting fails. human_readable() espera que el valor sea un número y devuelve un texto que representa ese número en KB, MB, GB, etc. ifempty(texto) si el campo no está vacío, devuelve el valor del campo. En caso contrario devuelve texto. in_list(separator, pattern, found_val, not_found_val) interpret the field as a list of items separated by separator, comparing the pattern against each value in the list. If the pattern matches a value, return found_val, otherwise return not_found_val. language_codes(lang_strings) return the language codes for the strings passed in lang_strings. The strings must be in the language of the current locale. Lang_strings is a comma-separated list. language_strings(lang_codes, localize) return the strings for the language codes passed in lang_codes. If localize is zero, return the strings in English. If localize is not zero, return the strings in the language of the current locale. Lang_codes is a comma-separated list. 162 Capítulo 1. Secciones

167 list_item(index, separator) interpret the field as a list of items separated by separator, returning the index th item. The first item is number zero. The last item can be returned using list_item(-1,separator). If the item is not in the list, then the empty value is returned. The separator has the same meaning as in the count function. lookup(pattern, field, pattern, field,..., else_field) like switch, except the arguments are field (metadata) names, not text. The value of the appropriate field will be fetched and used. Note that because composite columns are fields, you can use this function in one composite field to use the value of some other composite field. This is extremely useful when constructing variable save paths (more later). re(pattern, replacement) return the field after applying the regular expression. All instances of pattern are replaced with replacement. As in all of calibre, these are python-compatible regular expressions. select(key) interpret the field as a comma-separated list of items, with the items being of the form id:value. Find the pair with the id equal to key, and return the corresponding value. This function is particularly useful for extracting a value such as an isbn from the set of identifiers for a book. shorten(left chars, middle text, right chars) Return a shortened version of the field, consisting of left chars characters from the beginning of the field, followed by middle text, followed by right chars characters from the end of the string. Left chars and right chars must be integers. For example, assume the title of the book is Ancient English Laws in the Times of Ivanhoe, and you want it to fit in a space of at most 15 characters. If you use {title:shorten(9,-,5)}, the result will be Ancient E-nhoe. If the field s length is less than left chars + right chars + the length of middle text, then the field will be used intact. For example, the title The Dome would not be changed. str_in_list(val, separator, string, found_val, not_found_val) treat val as a list of items separated by separator, comparing the string against each value in the list. If the string matches a value, return found_val, otherwise return not_found_val. If the string contains separators, then it is also treated as a list and each value is checked. subitems(val, start_index, end_index) This function is used to break apart lists of tag-like hierarchical items such as genres. It interprets the value as a comma-separated list of tag-like items, where each item is a period-separated list. Returns a new list made by first finding all the period-separated tag-like items, then for each such item extracting the components from start_index to end_index, then combining the results back together. The first component in a period-separated list has an index of zero. If an index is negative, then it counts from the end of the list. As a special case, an end_index of zero is assumed to be the length of the list. Examples: Assuming a #genre column containing "A.B.C": {#genre:subitems(0,1)} returns "A" {#genre:subitems(0,2)} returns "A.B" {#genre:subitems(1,0)} returns "B.C" Assuming a #genre column containing "A.B.C, D.E": {#genre:subitems(0,1)} returns "A, D" {#genre:subitems(0,2)} returns "A.B, D.E" sublist(val, start_index, end_index, separator) interpret the value as a list of items separated by separator, returning a new list made from the items from start_index to end_index. The first item is number zero. If an index is negative, then it counts from the end of the list. As a special case, an end_index of zero is assumed to be the length of the list. Examples assuming that the tags column (which is comma-separated) contains A, B,C : {tags:sublist(0,1,\,)} returns "A" {tags:sublist(-1,0,\,)} returns "C" {tags:sublist(0,-1,\,)} returns "A, B" swap_around_comma(val) -- given a value of the form B, A, return A B. This is most useful for converting names in LN, FN format to FN LN. If there is no comma, the function returns val unchanged Cursillos 163

168 switch(pattern, value, pattern, value,..., else_value) for each pattern, value pair, checks if the field matches the regular expression pattern and if so, returns that value. If no pattern matches, then else_value is returned. You can have as many pattern, value pairs as you want. test(text if not empty, text if empty) return text if not empty if the field is not empty, otherwise return text if empty. transliterate() Returns a string in a latin alphabet formed by approximating the sound of the words in the source field. For example, if the source field is Фёдор Михaйлович Достоевский the function returns Fiodor Mikhailovich Dostoievskii. Now, what about using functions and formatting in the same field. Suppose you have an integer custom column called #myint that you want to see with leading zeros, as in 003. To do this, you would use a format of 0>3s. However, by default, if a number (integer or float) equals zero then the field produces the empty value, so zero values will produce nothing, not 000. If you really want to see 000 values, then you use both the format string and the ifempty function to change the empty value back to a zero. The field reference would be: {#myint:0>3s:ifempty(0)} Note that you can use the prefix and suffix as well. If you want the number to appear as [003] or [000], then use the field: {#myint:0>3s:ifempty(0) [ ]} Usar funciones en plantillas: modo de programación de plantilla The template language program mode differs from single-function mode in that it permits you to write template expressions that refer to other metadata fields, modify values, and do arithmetic. It is a reasonably complete programming language. Puede usar las funciones documentadas anteriormente en modo de programación de plantilla. Véase más adelante para más detalles. Beginning with an example, assume that you want your template to show the series for a book if it has one, otherwise show the value of a custom field #genre. You cannot do this in the basic language because you cannot make reference to another metadata field within a template expression. In program mode, you can. The following expression works: {#series:'ifempty($, field('#genre'))'} El ejemplo muestra varias cosas: program mode is used if the expression begins with : and ends with. Anything else is assumed to be singlefunction. la variable $ representa el campo sobre el que opera la expresión, #series en este caso. functions must be given all their arguments. There is no default value. For example, the standard built-in functions must be given an additional initial parameter indicating the source field, which is a significant difference from single-function mode. los espacios en blanco se ignoran y se pueden utilizar en cualquier lugar dentro de la expresión. los textos constantes se encierran en comillas del mismo tipo, ya sea o ". The language is similar to functional languages in that it is built almost entirely from functions. A statement is a function. An expression is a function. Constants and identifiers can be thought of as functions returning the value indicated by the constant or stored in the identifier. La sintaxis del lenguaje se muestra en la siguiente gramática: 164 Capítulo 1. Secciones

169 constant ::= " string " ' string ' number identifier ::= sequence of letters or ``_`` characters function ::= identifier ( statement [, statement ]* ) expression ::= identifier constant function assignment assignment ::= identifier '=' expression statement ::= expression [ ; expression ]* program ::= statement Los comentarios son líneas que empiezan por un carácter «#». An expression always has a value, either the value of the constant, the value contained in the identifier, or the value returned by a function. The value of a statement is the value of the last expression in the sequence of statements. As such, the value of the program (statement): 1; 2; 'foobar'; 3 es 3. Otro ejemplo de un programa complejo pero más bien tonto podría ayudar a aclarar las cosas: {series_index:' substr( strcat($, '->', cmp(divide($, 2), 1, assign(c, 1); substr('lt123', c, 0), 'eq', 'gt')), 0, 6) ' prefix suffix} Este programa hace lo siguiente: specify that the field being looked at is series_index. This sets the value of the variable $. calls the substr function, which takes 3 parameters (str, start, end). It returns a string formed by extracting the start through end characters from string, zero-based (the first character is character zero). In this case the string will be computed by the strcat function, the start is 0, and the end is 6. In this case it will return the first 6 characters of the string returned by strcat, which must be evaluated before substr can return. calls the strcat (string concatenation) function. Strcat accepts 1 or more arguments, and returns a string formed by concatenating all the values. In this case there are three arguments. The first parameter is the value in $, which here is the value of series_index. The second paremeter is the constant string ->. The third parameter is the value returned by the cmp function, which must be fully evaluated before strcat can return. The cmp function takes 5 arguments (x, y, lt, eq, gt). It compares x and y and returns the third argument lt if x < y, the fourth argument eq if x == y, and the fifth argument gt if x > y. As with all functions, all of the parameters can be statements. In this case the first parameter (the value for x) is the result of dividing the series_index by 2. The second parameter y is the constant 1. The third parameter lt is a statement (more later). The fourth parameter eq is the constant string eq. The fifth parameter is the constant string gt. The third parameter (the one for lt) is a statement, or a sequence of expressions. Remember that a statement (a sequence of semicolon-separated expressions) is also an expression, returning the value of the last expression in the list. In this case, the program first assigns the value 1 to a local variable c, then returns a substring made by extracting the c th character to the end. Since c always contains the constant 1, the substring will return the second through end th characters, or t123. Once the statement providing the value to the third parameter is executed, cmp can return a value. At that point, strcat can return a value, then substr can return a value. The program then terminates. Para distintos valores de series_index, el programa devuelve: series_index == undefined, resultado = prefix ->t123 suffix 1.9. Cursillos 165

170 series_index == 0.5, resultado = prefix 0.50-> suffix series_index == 1, resultado = prefix 1->t12 suffix series_index == 2, resultado = prefix 2->eq suffix series_index == 3, resultado = prefix 3->gt suffix All the functions listed under single-function mode can be used in program mode. To do so, you must supply the value that the function is to act upon as the first parameter, in addition to the parameters documented above. For example, in program mode the parameters of the test function are test(x, text_if_not_empty, text_if_empty). The x parameter, which is the value to be tested, will almost always be a variable or a function call, often field(). The following functions are available in addition to those described in single-function mode. Remember from the example above that the single-function mode functions require an additional first parameter specifying the field to operate on. With the exception of the id parameter of assign, all parameters can be statements (sequences of expressions). Note that the definitive documentation for functions is available in the section Function classification (Página 170): and(value, value,...) returns the string 1 if all values are not empty, otherwise returns the empty string. This function works well with test or first_non_empty. You can have as many values as you want. add(x, y) devuelve x + y. Da un error si x o y no son números. assign(id, val) asigna val a id y devuelve val. id debe ser un identificador, no una expresión approximate_formats() return a comma-separated list of formats that at one point were associated with the b author_links(val_separator, pair_separator) returns a string containing a list of authors and that author s link values in the form author1 val_separator author1link pair_separator author2 val_separator author2link etc. An author is separated from its link value by the val_separator string with no added spaces. author:linkvalue pairs are separated by the pair_separator string argument with no added spaces. It is up to you to choose separator strings that do not occur in author names or links. An author is included even if the author link is empty. author_sorts(val_separator) returns a string containing a list of author s sort values for the authors of the book. The sort is the one in the author metadata (different from the author_sort in books). The returned list has the form author sort 1 val_separator author sort 2 etc. The author sort values in this list are in the same order as the authors of the book. If you want spaces around val_separator then include them in the separator string booksize() devuelve el valor del campo «tamaño» de calibre. Devuelve si no hay formatos. cmp(x, y, mn, ig, my) compara x e y después de convertirlas en números. Devuelve mn si x < y. Devuelve ig si x == y. Devuelve my en otros casos. current_library_name() -- return the last name on the path to the current calibre library. This function can be called in template program mode using the template {: current_library_name() }. current_library_path() -- return the path to the current calibre library. This function can be called in template program mode using the template {: current_library_path() } Capítulo 1. Secciones

171 days_between(fecha1, fecha2) devuelve el número de días entre fecha1 y fecha2. El número es positivo si fecha1 es posterior a fecha2, en caso contrario es negativo. Si fecha1 o fecha2 no son fechas, la función devuelve un texto vacío. divide(x, y) devuelve x / y. Da un error si x o y no son números. eval(string) evaluates the string as a program, passing the local variables (those assign ed to). This permits using the template processor to construct complex results from local variables. Because the { and } characters are special, you must use [[ for the { character and ]] for the } character; they are converted automatically. Note also that prefixes and suffixes (the prefix suffix syntax) cannot be used in the argument to this function when using template program mode. field(nombre) devuelve el campo de metadatos identificado por nombre. first_matching_cmp(val, cmp1, resultado1, cmp2, resultado2,..., otro_resultado) compara val < cmpn consecutivamente y devuelve resultadon para la primera comparación que sea cierta. Devuelve otro_resultado si ninguna comparación es cierta. Ejemplo: ``first_matching_cmp(10,5,"small",10,"middle",15,"large","giant")`` returns large. The same example with a first value of 16 returns giant. * first_non_empty(value, value,...) returns the first value that is not empty. If all values are empty, then the empty value is returned. You can have as many values as you want. * format_date(x, date_format) format_date(val, format_string) format the value, which must be a date field, using the format_string, returning a string. The formatting codes are: d : the day as number without a leading zero (1 to 31) dd : the day as number with a leading zero (01 to 31) ddd : the abbreviated localized day name (e.g. "Mon" to "Sun"). dddd : the long localized day name (e.g. "Monday" to "Sunday"). M : the month as number without a leading zero (1 to 12). MM : the month as number with a leading zero (01 to 12) MMM : the abbreviated localized month name (e.g. "Jan" to "Dec"). MMMM : the long localized month name (e.g. "January" to "December"). yy : the year as two digit number (00 to 99). yyyy : the year as four digit number. h : the hours without a leading 0 (0 to 11 or 0 to 23, depending on am/pm) hh : the hours with a leading 0 (00 to 11 or 00 to 23, depending on am/pm) m : the minutes without a leading 0 (0 to 59) mm : the minutes with a leading 0 (00 to 59) s : the seconds without a leading 0 (0 to 59) ss : the seconds with a leading 0 (00 to 59) ap : use a 12-hour clock instead of a 24-hour clock, with 'ap' replaced by the localized strin AP : use a 12-hour clock instead of a 24-hour clock, with 'AP' replaced by the localized strin iso : the date with time and timezone. Must be the only format present. You might get unexpected results if the date you are formatting contains localized month names, which can happen if you changed the format tweaks to contain MMMM. In this case, instead of using something like {pubdate:format_date(yyyy)}, write the template using template program mode as in {: format_date(raw_field( pubdate ), yyyy ) }. finish_formatting(val, fmt, prefix, suffix) apply the format, prefix, and suffix to a value in the same way as done in a template like {series_index:05.2f - - }. This function is provided to ease conversion of complex single-function- or template-program-mode templates to general program mode (Página 185) (see below) to take advantage of GPM template compilation. For example, the following program produces the same output as the above template: 1.9. Cursillos 167

172 program: finish_formatting(field("series_index"), "05.2f", " - ", " - ") Otro ejemplo: para la plantilla {series:re(([^\s])[^\s]+(\s $),\1)}{series_index:0>2s - - }{title} use: program: strcat( re(field('series'), '([^\s])[^\s]+(\s $)', '\1'), finish_formatting(field('series_index'), '0>2s', ' - ', ' - '), field('title') ) formats_modtimes(date_format) return a comma-separated list of colon_separated items representing modification times for the formats of a book. The date_format parameter specifies how the date is to be formatted. See the date_format function for details. You can use the select function to get the mod time for a specific format. Note that format names are always uppercase, as in EPUB. formats_paths() return a comma-separated list of colon_separated items representing full path to the formats of a book. You can use the select function to get the path for a specific format. Note that format names are always uppercase, as in EPUB. formats_sizes() return a comma-separated list of colon_separated items representing sizes in bytes of the formats of a book. You can use the select function to get the size for a specific format. Note that format names are always uppercase, as in EPUB. has_cover() devuelve Yes si el libro tiene portada, en caso contrario devuelve un texto vacío. not(value) returns the string 1 if the value is empty, otherwise returns the empty string. This function works well with test or first_non_empty. You can have as many values as you want. list_difference(list1, list2, separator) return a list made by removing from list1 any item found in list2, using a case-insensitive compare. The items in list1 and list2 are separated by separator, as are the items in the returned list. list_equals(list1, sep1, list2, sep2, yes_val, no_val) return yes_val if list1 and list2 contain the same items, otherwise return no_val. The items are determined by splitting each list using the appropriate separator character (sep1 or sep2). The order of items in the lists is not relevant. The compare is case insensitive. list_intersection(list1, list2, separator) return a list made by removing from list1 any item not found in list2, using a case-insensitive compare. The items in list1 and list2 are separated by separator, as are the items in the returned list. list_re(src_list, separator, include_re, opt_replace) Construct a list by first separating src_list into items using the separator character. For each item in the list, check if it matches include_re. If it does, then add it to the list to be returned. If opt_replace is not the empty string, then apply the replacement before adding the item to the returned list. list_re_group(src_list, separator, include_re, search_re, template_for_group_1, for_group_2,...) Like list_re except replacements are not optional. It uses re_group(item, search_re, template...) when doing the replacements. list_sort(list, direction, separator) return list sorted using a case-insensitive sort. If direction is zero, the list is sorted ascending, otherwise descending. The list items are separated by separator, as are the items in the returned list. list_union(list1, list2, separator) return a list made by merging the items in list1 and list2, removing duplicate items using a case-insensitive compare. If items differ in case, the 168 Capítulo 1. Secciones

173 one in list1 is used. The items in list1 and list2 are separated by separator, as are the items in the returned list. multiply(x, y) devuelve x * y. Da una excepción si x o y no son números. ondevice() devuelve el texto «Yes» si ondevice está activado, si no, devuelve un texto vacío or(value, value,...) returns the string 1 if any value is not empty, otherwise returns the empty string. This function works well with test or first_non_empty. You can have as many values as you want. print(a, b,...) prints the arguments to standard output. Unless you start calibre from the command line (calibre-debug -g), the output will go to a black hole. raw_field(name) devuelve el campo de metadatos llamado nombre sin aplicar ningún formato. raw_list(name, separator) returns the metadata list named by name without applying any formatting or sorting and with items separated by separator. re_group(val, pattern, template_for_group_1, for_group_2,...) return a string made by applying the reqular expression pattern to the val and replacing each matched instance with the string computed by replacing each matched group by the value returned by the corresponding template. The original matched value for the group is available as $. In template program mode, like for the template and the eval functions, you use [[ for { and ]] for }. The following example in template program mode looks for series with more than one word and uppercases the first word: {series:'re_group($, "(\S* )(.*)", "[[$:uppercase()]]", "[[$]]")'} series_sort() devuelve el valor de orden de serie. strcat(a, b,...) puede tomar cualquier número de argumentos. Devuelve texto formado por la concatenación de todos los argumentos. strcat_max(max, string1, prefix2, string2,...) Returns a string formed by concatenating the arguments. The returned value is initialized to string1. Prefix, string pairs are added to the end of the value as long as the resulting string length is less than max. String1 is returned even if string1 is longer than max. You can pass as many prefix, string pairs as you wish. strcmp(x, y, mn, ig, my) hace una comparación sin distinción de mayúsculas y minúsculas entre x e y como textos. Devuelve mn si x < y. Devuelve ig si x == y. Devuelve my en otros casos. strlen(a) Devuelve la longitud del texto pasado como argumento. substr(str, start, end) returns the start th through the end th characters of str. The first character in str is the zero th character. If end is negative, then it indicates that many characters counting from the right. If end is zero, then it indicates the last character. For example, substr( 12345, 1, 0) returns 2345, and substr( 12345, 1, -1) returns 234. subtract(x, y) devuelve x - y. Da un error si x o y no son números. today() return a date string for today. This value is designed for use in format_date or days_between, but can be manipulated like any other string. The date is in ISO format. template(x) evalúa x como una plantilla. La evaluación se realiza en un contexto propio, lo que significa que las variables no se comparten entre el proceso que llama a la función y la evaluación de la plantilla. Dado que los caracteres { y } tienen un uso especial, debe usar [[ en lugar de { y ]] para }; se convertirán automáticamente. Por ejemplo, template( [[orden_de_título]] ) evaluará la plantilla {orden_de_título} y devolverá su valor. Tenga en cuenta que los prefijos 1.9. Cursillos 169

174 y sufijos (la sintaxis prefijo sufijo) no puede usarse en el argumento de esta función en el modo de programación de plantilla. Clasificación de funciones Reference for all built-in template language functions Here, we document all the built-in functions available in the calibre template language. Every function is implemented as a class in python and you can click the source links to see the source code, in case the documentation is insufficient. The functions are arranged in logical groups by type. 170 Capítulo 1. Secciones

175 Arithmetic (Página 191) add(x, y) (Página 191) divide(x, y) (Página 191) multiply(x, y) (Página 191) subtract(x, y) (Página 191) Boolean (Página 191) and(valor, valor,...) (Página 191) not(valor) (Página 191) or(valor, valor,...) (Página 191) Date functions (Página 191) days_between(fecha1, fecha2) (Página 191) today() (Página 191) Formatting values (Página 192) finish_formatting(val, fmt, prefijo, sufijo) (Página 192) format_date(val, texto_formato) (Página 192) format_number(v, plantilla) (Página 192) human_readabe(v) (Página 192) Get values from metadata (Página 192) approximate_formats() (Página 192) author_links(sep_val, sep_par) (Página 193) author_sort(separador) (Página 193) booksize() (Página 193) current_library_name() (Página 193) current_library_path() (Página 193) field(nombre) (Página 193) formats_modtimes(formato_fecha) (Página 193) formats_paths() (Página 193) formats_sizes() (Página 194) has_cover() (Página 194) language_codes(nombres) (Página 194) language_strings(códigos, localizar) (Página 194) ondevice() (Página 194) raw_field(nombre) (Página 194) raw_list(nombre,separador) (Página 194) series_sort() (Página 194) user_categories() (Página 195) virtual_libraries() (Página 195) If-then-else (Página 195) contains(val, patrón, texto_si_coincide, texto_si_no_coincide) (Página 195) ifempty(val, texto_si_vacío) (Página 195) test(val, texto_si_no_vacío, texto_si_vacío) (Página 195) Iterating over values (Página 195) first_non_empty(valor, valor,...) (Página 195) lookup(val, patrón, campo, patrón, campo,..., otro_campo) (Página 195) switch(val, patrón, valor, patrón, valor,..., otro_valor) (Página 196) List lookup (Página 196) identifier_in_list(val, id, val_encontrado, val_no_encontrado) (Página 196) in_list(val, separador, patrón, encontrado, no_encontrado) (Página 196) list_item(val, índice, separador) (Página 196) select(val, clave) (Página 196) str_in_list(val, separador, texto, val_encontrado, val_no_encontrado) (Página 196) List manipulation (Página 196) count(val, separador) (Página 196) list_difference(lista1, lista2, separador) (Página 197) list_equals(lista1, sep1, lista2, sep2, val_sí, val_no) (Página 197) list_intersection(lista1, lista2, separador) (Página 197) 1.9. Cursillos list_re(list_orig, separador, incluir, sust_opt) (Página 197) 171 list_re_group(list_orig, separador, incluir, búsqueda, plantilla_grupo_1,...) (Página 197) list_sort(lista, dirección, separador) (Página 197) list_union(lista1, lista2, separador) (Página 197)

176 Arithmetic add(x, y) class calibre.utils.formatter_functions.builtinadd add(x, y) devuelve x + y. Da un error si «x» o «y» no son números. divide(x, y) class calibre.utils.formatter_functions.builtindivide divide(x, y) devuelve x / y. Da un error si «x» o «y» no son números. multiply(x, y) class calibre.utils.formatter_functions.builtinmultiply multiply(x, y) devuelve x * y. Da un error si «x» o «y» no son números. subtract(x, y) class calibre.utils.formatter_functions.builtinsubtract subtract(x, y) devuelve x - y. Da un error si «x» o «y» no son números. Boolean and(valor, valor,...) class calibre.utils.formatter_functions.builtinand and(valor, valor,...) devuelve el texto «1» si ninguno de los valores está vacío, en caso contrario, devuelve un texto vacío. Esta función funciona bien con «first_non_empty». Puede incluir tantos valores como quiera. not(valor) class calibre.utils.formatter_functions.builtinnot not(valor) devuelve el texto «1» si el valor está vacío, en caso contrario, devuelve un texto vacío. or(valor, valor,...) class calibre.utils.formatter_functions.builtinor or(valor, valor,...) devuelve el texto «1» si alguno de los valores no está vacío, en caso contrario, devuelve un texto vacío. Esta función funciona bien con «first_non_empty». Puede incluir tantos valores como quiera. Date functions days_between(fecha1, fecha2) class calibre.utils.formatter_functions.builtindaysbetween days_between(fecha1, fecha2) devuelve el número de días entre «fecha1» y «fecha2». El número es positivo si «fecha1» es posterior a «fecha2», en caso contrario es negativo. Si «fecha1» o «fecha2» no son fechas, la función devuelve un texto vacío. today() class calibre.utils.formatter_functions.builtintoday today() devuelve un texto para la fecha de hoy. Este valor está preparado para usarse con «format_date» o «days_between», pero puede manipularse como cualquier otro texto. La fecha está en formato ISO. 172 Capítulo 1. Secciones

177 Formatting values finish_formatting(val, fmt, prefijo, sufijo) class calibre.utils.formatter_functions.builtinfinishformatting finish_formatting(val, fmt, prefijo, sufijo) aplica el formato, prefijo y sufijo a un valor de la misma manera que se haría en una plantilla como «{series_index:05.2f - - }». Por ejemplo, el siguiente programa produce la misma salida que la plantilla anterior: program: finish_formatting(field( series_index ), 05.2f, -, - ) format_date(val, texto_formato) class calibre.utils.formatter_functions.builtinformatdate format_date(val, texto_formato) da formato a un valor, que debe ser un campo de fecha, según «texto_formato» y devuelve un texto. Los códigos de formato son: «d»: el día como un número, sin cero inicial (de 1 a 31). «dd»: el día como un número, con un cero inicial si es necesario (de 01 a 31). «ddd»: el día de la semana abreviado según el idioma local (p. ej. de «lun» a «dom»). «dddd»: el nombre local completo del día de la semana (p. ej. de «lunes» a «domingo»). «M»: el mes como un número sin cero inicial (de 1 a 12). «MM»: el mes como un número, con un cero inicial si es necesario (de 01 a 12). «MMM»: el mes abreviado según el idioma local (p. ej. de «ene» a «dic»). «MMMM»: el nombre local completo del mes (p. ej. de «enero» a «diciembre»). «yy»: el año como un número de dos cifras (de 00 a 99). «yyyy»: el año como un número de cuatro cifras. «h»: la hora sin cero inicial (de 0 a 11 o de 0 a 23, según am/pm). «hh»: la hora con un cero inicial si es necesario (de 00 a 11 o de 00 a 23, según am/pm). «m»: los minutos sin cero inicial (de 0 a 59). «mm»: los minutos con un cero inicial si es necesaro (de 00 a 59). «s»: los segundos sin cero inicial (de 0 a 59). «ss»: los segundos con un cero inicial si es necesario (de 00 a 59). «ap»: se escribe la hora en formato de 12 horas en lugar de 24, con «ap» sustituido por la forma local para am o pm. «AP»: se escribe la hora en formato de 12 horas en lugar de 24, con «AP» sustituido por la forma local para AM o PM. «iso»: la fecha con hora y zona horaria. Debe ser el único formato presente. format_number(v, plantilla) class calibre.utils.formatter_functions.builtinformatnumber format_number(v, plantilla) da formato al número «v» usando una plantilla de formato de python como «{0:5.2f}» o «{0:,d}» o «{0:5,.2f}». La parte del nombre de la plantilla debe ser un 0 (cero) (el «{0:» en los ejemplos anteriores). Véase la documentación del lenguaje de plantillas y de python para más ejemplos. Devuelve un texto vacío si el formato falla. human_readabe(v) class calibre.utils.formatter_functions.builtinhumanreadable human_readabe(v) devuelve un texto que representa el número «v» en KB, MB, GB, etc. Get values from metadata approximate_formats() class calibre.utils.formatter_functions.builtinapproximateformats approximate_formats() devuelve una lista separada por comas de formatos que en algún momento estuvieron asociados con el libro. No hay garantía de que esta lista sea correcta, aunque probablemente lo sea. Esta función puede llamarse en el modo de programación de plantillas usando la plantilla «{: approximate_formats() }». Tenga en cuenta que los nombres de formato están siempre en mayúsculas, como en «EPUB». Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar 1.9. Cursillos 173

178 author_links(sep_val, sep_par) class calibre.utils.formatter_functions.builtinauthorlinks author_links(sep_val, sep_par) devuelve un texto que contiene una lista de autores y enlaces a los autores de la forma: «autor1 sep_val enlace_autor1 sep_par autor2 sep_val enlace_autor2» etc. Cada autor está separado de su correspondiente enlace por el texto «sep_val», sin espacios adicionales. Los pares autor:enlace_autor están separados por el texto «sep_par», sin espacios adicionales. Es responsabilidad del usuario proporcionar separadores que no aparezcan en los nombres o enlaces de autor. El nombre de autor se incluye aunque su enlace esté vacío. author_sort(separador) class calibre.utils.formatter_functions.builtinauthorsorts author_sort(separador) devuelve un texto que contiene la lista de valores de orden de autor para los autores del libro. El orden es el de los autores en los metadatos (diferente del valor de orden de autor del libro). La lista devuelta es de la forma orden_de _autor_1 separador orden_de_autor_2 etc. Los valores de orden de autor en la lista están en el mismo orden que los autores del libro. Si quiere espacios alrededor de «separador», inclúyalos en el valor. booksize() class calibre.utils.formatter_functions.builtinbooksize booksize() devuelve el valor del campo de tamaño. Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar current_library_name() class calibre.utils.formatter_functions.builtincurrentlibraryname current_library_name() devuelve la última parte de la ruta a la biblioteca de calibre actual. Esta función puede llamarse en el modo de programación de plantilla usando la plantilla {: current_library_name() }. current_library_path() class calibre.utils.formatter_functions.builtincurrentlibrarypath current_library_path() devuelve la ruta a la biblioteca de calibre actual. Esta función puede usarse en el modo de programación de plantillas utilizando la plantilla «{: current_library_path() }». field(nombre) class calibre.utils.formatter_functions.builtinfield field(nombre) devuelve el campo de metadatos identificado por «nombre». formats_modtimes(formato_fecha) class calibre.utils.formatter_functions.builtinformatsmodtimes formats_modtimes(formato_fecha) devuelve una lista de elementos (separados por dos puntos) separados por comas que representa las fechas de modificación para los formatos de un libro. El argumento «formato_fecha» especifica cómo se da formato a la fecha. Véase la función «date_format» para más detalles. Puede usar la función «select» para obtener la fecha de modificación de un formato específico. Tenga en cuenta que los nombres de formato siempre están en mayúsculas, como en «EPUB». formats_paths() 174 Capítulo 1. Secciones

179 class calibre.utils.formatter_functions.builtinformatspaths formats_paths() devuelve una lista separada por comas de elementos separados por dos puntos que representan la ruta completa a los formatos de un libro. Puede usar la función «select» para obtener la ruta a un formato específico. Tenga en cuenta que los nombres de formato están siempre en mayúsculas, como en «EPUB». formats_sizes() class calibre.utils.formatter_functions.builtinformatssizes formats_sizes() devuelve una lista de elementos (separados por dos puntos) separados por comas que representa los tamaños en bytes de los formatos de un libro. Puede usar la función «select» para obtener el tamaño de un formato específico. Tenga en cuenta que los nombres de formato siempre están en mayúsculas, como en «EPUB». has_cover() class calibre.utils.formatter_functions.builtinhascover has_cover() devuelve «Yes» si el libro tiene portada, en caso contrario devuelve un texto vacío. language_codes(nombres) class calibre.utils.formatter_functions.builtinlanguagecodes language_codes(nombres) devuelve los códigos de idioma correspondientes a «nombres». Los nombres deben estar en el idioma actual. El argumento «nombres» es una lista separada por comas. language_strings(códigos, localizar) class calibre.utils.formatter_functions.builtinlanguagestrings language_strings(códigos, localizar) devuelve los nombres de los idiomas identificados por «códigos». Si «localizar» es cero, devuelve los nombres en inglés. Si «localizar» no es cero, devuelve los nombres en el idioma actual. El argumento «códigos» es una lista separada por comas. ondevice() class calibre.utils.formatter_functions.builtinondevice ondevice() devuelve «Yes» si ondevice está activado, si no, devuelve un texto vacío. Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar raw_field(nombre) class calibre.utils.formatter_functions.builtinrawfield raw_field(nombre) devuelve el campo de metadatos llamado «nombre» sin aplicar ningún formato. raw_list(nombre,separador) class calibre.utils.formatter_functions.builtinrawlist raw_list(nombre,separador) devuelve la lista de metadatos nombrada por «nombre» sin aplicar ningún formato u ordenación, con los elementos separados por «separador». series_sort() class calibre.utils.formatter_functions.builtinseriessort series_sort() devuelve el valor del orden de serie 1.9. Cursillos 175

180 user_categories() class calibre.utils.formatter_functions.builtinusercategories user_categories() devuelve una lista separada por comas de las categorías de usuario que contiene este libro. Esta función sólo funciona en la interfaz gráfica. Si desea utilizar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, deberá crear una plantilla personalizada «Columna generada a partir de otras columnas», utilice la función en la plantilla de esa columna y use el valor de esa columna en las plantillas para guardar o enviar virtual_libraries() class calibre.utils.formatter_functions.builtinvirtuallibraries virtual_libraries() devuelve una lista separada por comas de bibliotecas virtuales que contienen este libro. Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar If-then-else contains(val, patrón, texto_si_coincide, texto_si_no_coincide) class calibre.utils.formatter_functions.builtincontains contains(val, patrón, texto_si_coincide, texto_si_no_coincide) comprueba si el campo contiene coincidencias para la expresión regular «patrón». Devuelve «texto_si_coincide» si se encuentran coincidencias, en caso contrario devuelve «texto_si_no_coincide». ifempty(val, texto_si_vacío) class calibre.utils.formatter_functions.builtinifempty ifempty(val, texto_si_vacío) devuelve «val» si no está vacío, en caso contrario devuelve «texto_si_vacío». test(val, texto_si_no_vacío, texto_si_vacío) class calibre.utils.formatter_functions.builtintest test(val, texto_si_no_vacío, texto_si_vacío) devuelve «texto_si_no_vacío» si el campo no está vacío, «devuelve texto_si_vacío» en caso contrario. Iterating over values first_non_empty(valor, valor,...) class calibre.utils.formatter_functions.builtinfirstnonempty first_non_empty(valor, valor,...) devuelve el primer valor que no esté vacío. Si todos los valores están vacíos, se devuelve también un valor vacío. Puede incluir tantos valores como quiera. lookup(val, patrón, campo, patrón, campo,..., otro_campo) class calibre.utils.formatter_functions.builtinlookup lookup(val, patrón, campo, patrón, campo,..., otro_campo) como «switch», pero los argumentos son nombres de campo (metadatos), no texto. Se usará el valor del campo apropiado. Tenga en cuenta que puesto que las columnas compuestas son campos, puede usar esta función en un campo compuesto para usar el valor de otro campo compuesto. Esto es muy útil para construir rutas de guardado variables. 176 Capítulo 1. Secciones

181 switch(val, patrón, valor, patrón, valor,..., otro_valor) class calibre.utils.formatter_functions.builtinswitch switch(val, patrón, valor, patrón, valor,..., otro_valor) para cada pareja «patrón, valor», comprueba si el campo contiene coincidencias para la expresión regular «patrón» y, en tal caso, devuelve ese valor. Si no coincide ningún patrón, devuelve «otro_valor». Puede emplear tantas parejas «patrón, valor» como desee. List lookup identifier_in_list(val, id, val_encontrado, val_no_encontrado) class calibre.utils.formatter_functions.builtinidentifierinlist identifier_in_list(val, id, val_encontrado, val_no_encontrado) considera «val» como una lista de identificadores separados por comas, y compara el «id» con cada valor de la lista. Un identificador tiene el formato «id:valor». El argumento «id» debería ser «id» o «id:expreg». El primer caso, selecciona identificadores con dicho «id». El segundo caso, selecciona identificadores cuyo valor coincida con la expresión regular «expreg». Si existe alguna coincidencia, devuelve «val_encontrado», en caso contrario devuelve «val_no_encontrado». in_list(val, separador, patrón, encontrado, no_encontrado) class calibre.utils.formatter_functions.builtininlist in_list(val, separador, patrón, encontrado, no_encontrado) considera «val» como una lista de elementos separados por «separador» y compara «patrón» con cada valor de la lista. Si «patrón» coincide con alguno de los elementos de la lista, devuelve «encontrado», en caso contrario devuelve «no_encontrado». list_item(val, índice, separador) class calibre.utils.formatter_functions.builtinlistitem list_item(val, índice, separador) interpreta el campo como una lista de elementos separados por «separador» y devuelve el elemento número «índice». El primer elemento es el número cero. El último elemento puede obtenerse con «list_item(-1, separador)». Si el elemento no está en la lista devuelve un valor vacío. El separador tiene el mismo significado que en la función «count». select(val, clave) class calibre.utils.formatter_functions.builtinselect select(val, clave) interpreta el valor como una lista de elementos separados por comas, con los elementos de la forma «id:valor». Encuentra la pareja con «id» igual a «clave» y devuelve el valor correspondiente. str_in_list(val, separador, texto, val_encontrado, val_no_encontrado) class calibre.utils.formatter_functions.builtinstrinlist str_in_list(val, separador, texto, val_encontrado, val_no_encontrado) considera «val» como una lista de elementos separados por «separador», y compara el «texto» con cada valor de la lista. Si el texto coincide con alguno de los valores, devuelve «val_encontrado», en caso contrario devuelve «val_no_encontrado». Si el texto contiene separadores, también se considera como una lista y se comprueba cada elemento. List manipulation count(val, separador) class calibre.utils.formatter_functions.builtincount count(val, separador) interpreta el campo como una lista de elementos separados por «separador» y devuelve el número de elementos de la lista. La mayoría de las listas usan una coma como separador, pero «authors» usa un ampersand («&»). Ejemplos: {tags:count(,)}, {authors,count(&)} 1.9. Cursillos 177

182 list_difference(lista1, lista2, separador) class calibre.utils.formatter_functions.builtinlistdifference list_difference(lista1, lista2, separador) devuelve una lista construida eliminando de «lista1» cualquier elemento que aparezca en «lista2», sin distinguir mayúsculas y minúsculas. Los elementos de «lista1» y «lista2» están separados por «separador», así como los de la lista resultante. list_equals(lista1, sep1, lista2, sep2, val_sí, val_no) class calibre.utils.formatter_functions.builtinlistequals list_equals(lista1, sep1, lista2, sep2, val_sí, val_no) devuelve «val_sí» si «lista1» y «lista2» contienen los mismos elementos, en caso contrario devuelve «val_no». Los elementos se determinan dividiendo cada lista por el correspondiente carácter separador («sep1» o «sep2»). El orden de los elementos no es relevante. La comparación no diferencia mayúsculas y minúsculas. list_intersection(lista1, lista2, separador) class calibre.utils.formatter_functions.builtinlistintersection list_intersection(lista1, lista2, separador) devuelve una lista construida eliminando de «lista1» cualquier elemento que no aparezca en «lista2», sin distinguir mayúsculas y minúsculas. Los elementos de «lista1» y «lista2» están separados por «separador», así como los de la lista resultante. list_re(list_orig, separador, incluir, sust_opt) class calibre.utils.formatter_functions.builtinlistre list_re(list_orig, separador, incluir, sust_opt) construye una lista separando primero «list_orig» en elementos usando el carácter «separador». Para cada elemento en la lista, comprueba si coincide con la expresión regular «incluir». Si coincide, se añade a la lista final. Si «sust_opt» no es un texto vacío, se aplica la sustitución antes de añadir el elemento a la lista final. list_re_group(list_orig, separador, incluir, búsqueda, plantilla_grupo_1,...) class calibre.utils.formatter_functions.builtinlistregroup list_re_group(list_orig, separador, incluir, búsqueda, plantilla_grupo_1,...) como «list_re», pero las sustituciones no son opcionales. Usa re_group(elemento, búsqueda, plantilla_grupo_1,...) al hacer sustituciones en la lista final. list_sort(lista, dirección, separador) class calibre.utils.formatter_functions.builtinlistsort list_sort(lista, dirección, separador) devuelve «lista» ordenada sin distinción de mayúsculas y minúsculas. Si «dirección» es cero, la lista se ordena de manera ascendente, en caso contrario, de manera descendente. Los elementos de «lista» están separados por «separador», así como los de la lista resultante. list_union(lista1, lista2, separador) class calibre.utils.formatter_functions.builtinlistunion list_union(lista1, lista2, separador) devuelve una lista construida por combinación de los elementos en «lista1» y «lista2», eliminando los duplicados de «lista2» (no distingue mayúsculas y minúsculas, se mantiene la versión de «lista1»). Los elementos de «lista1» y «lista2» están separados por «separador», así como los de la lista resultante. subitems(val, índice_inicio, índice_fin) class calibre.utils.formatter_functions.builtinsubitems subitems(val, índice_inicio, índice_fin) Esta función se usa para separar listas de elementos tales como los géneros. Interpreta el valor como una lista de elementos separados por comas, donde cada elemento es a su 178 Capítulo 1. Secciones

183 vez una lista de elementos separados por puntos. Devuelve una nueva lista formada tomando, de cada lista de elementos separados por puntos, los elementos situados entre las posiciones «índice_inicio» e «índice_fin» y combinando los resultados. El primer elemento de cada lista separada por puntos ocupa la posición cero. Si un índice es negativo, se cuenta desde el final de la lista. Como caso especial, si «índice_fin» es cero, se considera que es el final de la lista. Ejemplos en el modo básico de plantilla y suponiendo que la columna #género contiene el valor «A.B.C»: {#género:subitems(0,1)} devuelve «A», {#género:subitems(0,2)} devuelve «A.B», {#género:subitems(1,0)} devuelve «B.C». Suponiendo que #género contiene el valor «A.B.C, D.E.F»: {#género:subitems(0,1)} devuelve «A, D», {#género:subitems(0,2)} devuelve «A.B, D.E». sublist(val, índice_inicio, índice_fin, separador) class calibre.utils.formatter_functions.builtinsublist sublist(val, índice_inicio, índice_fin, separador) interpreta el valor como una lista de elementos separados por «separador» y devuelve una nueva lista con los elementos comprendidos entre la posición «índice_inicio» e «índice_fin». El primer elemento ocupa la posición cero. Si un índice es negativo, se cuenta desde el final de la lista. Como caso especial, si «índice_fin» es cero, se considera que es el final de la lista. Ejemplos en el modo básico de plantilla y suponiendo que la columna de etiquetas (definida como valores separados por comas) contiene «A, B, C»: {tags:sublist{0,1 )} devuelve «A», {tags:sublist(-1,0 )} devuelve «C», {tags:sublist(0,-1 )} devuelve «A, B». Other assign(id, val) class calibre.utils.formatter_functions.builtinassign assign(id, val) asigna «val» a «id» y devuelve «val». «id» debe ser un identificador, no una expresión print(a, b,...) class calibre.utils.formatter_functions.builtinprint print(a, b,...) escribe los argumentos en la salida estándar. Sólo será visible si inicia calibre a partir de línea de órdenes (calibre-debug -g). Recursion eval(plantilla) class calibre.utils.formatter_functions.builtineval eval(plantilla) evalúa la plantilla, pasando las variables locales (las definidas con «assign») en lugar de los metadatos del libro. Esto permite usar el procesador de plantillas para elaborar resultados complejos a partir de variables locales. Dado que los caracteres «{» y «}» tienen un uso especial, debe usar «[[» en lugar de «{» y «]]» para «}»; se convertirán automáticamente. Tenga en cuenta que los prefijos y sufijos (la sintaxis «prefijo sufijo») no puede usarse en el argumento de esta función en el modo de programación de plantilla. template(x) class calibre.utils.formatter_functions.builtintemplate template(x) evalúa x como una plantilla. La evaluación se realiza en un contexto propio, lo que significa que las variables no se comparten entre el proceso que llama a la función y la evaluación de la plantilla. Dado que los caracteres «{» y «}» tienen un uso especial, debe usar «[[» en lugar de «{» y «]]» para «}»; se convertirán automáticamente. Por ejemplo, «template( [[orden_de_título]] )» evaluará la plantilla {orden_de_título} y devolverá su valor. Tenga en cuenta que los prefijos y sufijos (la sintaxis «prefijo sufijo») no puede usarse en el argumento de esta función en el modo de programación de plantilla Cursillos 179

184 Relational cmp(x, y, mn, ig, my) class calibre.utils.formatter_functions.builtincmp cmp(x, y, mn, ig, my) compara x e y después de convertirlas en números. Devuelve mn si x < y. Devuelve ig si x = y. Devuelve my en otros casos. first_matching_cmp(val, cmp1, resultado1, cmp2, resultado2,..., otro_resultado) class calibre.utils.formatter_functions.builtinfirstmatchingcmp first_matching_cmp(val, cmp1, resultado1, cmp2, resultado2,..., otro_resultado) compara «val < cmpn» consecutivamente y devuelve «resultadon» para la primera comparación que sea cierta. Devuelve «otro_resultado» si ninguna comparación es cierta. Ejemplo: first_matching_cmp(10,5, pequeño,10, mediano,15, grande, enorme ) devuelve grande. El mismo ejemplo con un primer valor de 16 devuelve enorme. strcmp(x, y, mn, ig, my) class calibre.utils.formatter_functions.builtinstrcmp strcmp(x, y, mn, ig, my) compara «x» e «y» como textos sin distinguir mayúsculas y minúsculas. Devuelve «mn» si x < y. Devuelve «ig» si x = y. Devuelve «my» en otros casos. String case changes capitalize(val) class calibre.utils.formatter_functions.builtincapitalize capitalize(val) devuelve el valor del campo con la primera letra mayúscula lowercase(val) class calibre.utils.formatter_functions.builtinlowercase lowercase(val) devuelve el valor del campo en minúsculas titlecase(val) class calibre.utils.formatter_functions.builtintitlecase titlecase(val) devuelve el valor del campo con las iniciales en mayúscula uppercase(val) class calibre.utils.formatter_functions.builtinuppercase uppercase(val) devuelve el valor del campo en mayúsculas String manipulation re(val, patrón, sustitución) class calibre.utils.formatter_functions.builtinre re(val, patrón, sustitución) devuelve el campo después de aplicar la expresión regular. Todas las veces que aparezca «patrón» se sustituirá por «sustitución». Como en todo calibre, se trata de expresiones regulares compatibles con python. 180 Capítulo 1. Secciones

185 re_group(val, patrón, plantilla_para_grupo_1, para_grupo_2,...) class calibre.utils.formatter_functions.builtinregroup re_group(val, patrón, plantilla_para_grupo_1, para_grupo_2,...) devuelve un texto formado por aplicación de la expresión regular «patrón» al valor «val», sustituyendo cada coincidencia con el texto calculado al sustituir cada grupo por el valor devuelto por la correspondiente plantilla. El valor de correspondencia original del grupo está disponible como «$». En el modo de programación de plantillas, como en las funciones «template» y «eval», use «[[» en lugar de «{» y «]]» en lugar de «}». El siguiente ejemplo en modo de programación de plantillas busca un nombre de serie con más de una palabra y pone la primera palabra en mayúsculas: {series: re_group($, (S* )(.*), [[$:uppercase()]], [[$]] ) } shorten(val, car_izq, texto_medio, car_der) class calibre.utils.formatter_functions.builtinshorten shorten(val, car_izq, texto_medio, car_der) devuelve una versión abreviada del campo, consistente en un número «car_izq» de caracteres del principio del campo, seguidos de «texto_medio», seguido de un número «car_der» de caracteres del final del campo. «car_izq» y «car_der» deben ser números enteros. Por ejemplo, supongamos que el título del libro es «Novísima recopilación de las leyes de España» y que quiere que quepa en un espacio de 15 caracteres a lo sumo. Si usa {title:shorten(8,-,6)}, el resultado será «Novísima-España». Si la longitud del campo es menor que «car_izq» + «car_der» + la longitud de «texto_medio», se usará el campo intacto. Por ejemplo, el título «La colmena» no se cambiará. strcat(a, b,...) class calibre.utils.formatter_functions.builtinstrcat strcat(a, b,...) admite un número arbitrario de argumentos. Devuelve un texto consistente en la unión de todos los argumentos consecutivamente. strcat_max(máx, texto1, prefijo2, texto2,...) class calibre.utils.formatter_functions.builtinstrcatmax strcat_max(máx, texto1, prefijo2, texto2,...) devuelve un texto formado por concatenación de los argumentos. El valor devuelto es inicialmente «texto1». Se van añadiendo parejas «prefijo, texto» al final del valor mientras la longitud del resultado sea menor que «máx». El resultado es siempre al menos «texto1», aunque su longitud sea mayor que «máx». Puede especificar tantas parejas «prefijo, texto» como desee. strlen(a) class calibre.utils.formatter_functions.builtinstrlen strlen(a) devuelve la longitud del texto pasado como argumento. substr(cad, inicio, fin) class calibre.utils.formatter_functions.builtinsubstr substr(cad, inicio, fin) devuelve los caracteres entre la posición «inicio» y «fin» del texto «cad». El primer carácter de «cad» está en la posición cero. Si «fin» es negativo, entonces indica la posición contando desde la derecha. Si «fin» es cero, indica el último carácter. Por ejemplo, substr( 12345, 1, 0) devuelve 2345, y substr( 12345, 1, -1) devuelve 234. swap_around_comma(val) class calibre.utils.formatter_functions.builtinswaparoundcomma swap_around_comma(val) dado un valor de la forma «B, A», devuelve «A B». Esto es útil para convertir nombres en formato APELLIDO, NOMBRE a NOMBRE APELLIDO. Si no hay ninguna coma, la función devuelve «val» sin cambios Cursillos 181

186 transliterate(a) class calibre.utils.formatter_functions.builtintransliterate transliterate(a) Devuelve un texto en el alfabeto latino formado por aproximación del sonido de las palabras en el texto origen. Por ejemplo, si el origen es «Фёдор Михaйлович Достоевский» la función devuelve «Fiodor Mikhailovich Dostoievskii». API of the Metadata objects The python implementation of the template functions is passed in a Metadata object. Knowing it s API is useful if you want to define your own template functions. class calibre.ebooks.metadata.book.base.metadata(title, authors=(u Desconocido, ), other=none, template_cache=none, formatter=none) A class representing all the metadata for a book. The various standard metadata fields are available as attributes of this object. You can also stick arbitrary attributes onto this object. Metadata from custom columns should be accessed via the get() method, passing in the lookup name for the column, for example: #mytags. Use the is_null() (Página 201) method to test if a field is null. This object also has functions to format fields into strings. The list of standard metadata fields grows with time is in STANDARD_METADATA_FIELDS (Página 202). Please keep the method based API of this class to a minimum. Every method becomes a reserved field name. is_null(field) Return True if the value of field is null in this object. null means it is unknown or evaluates to False. So a title of _( Unknown ) is null or a language of und is null. Be careful with numeric fields since this will return True for zero as well as None. Also returns True if the field does not exist. deepcopy(class_generator=<function <lambda>>) Do not use this method unless you know what you are doing, if you want to create a simple clone of this object, use deepcopy_metadata() instead. Class_generator must be a function that returns an instance of Metadata or a subclass of it. get_identifiers() Return a copy of the identifiers dictionary. The dict is small, and the penalty for using a reference where a copy is needed is large. Also, we don t want any manipulations of the returned dict to show up in the book. set_identifiers(identifiers) Set all identifiers. Note that if you previously set ISBN, calling this method will delete it. set_identifier(typ, val) If val is empty, deletes identifier of type typ standard_field_keys() return a list of all possible keys, even if this book doesn t have them custom_field_keys() return a list of the custom fields in this book all_field_keys() All field keys known by this instance, even if their value is None metadata_for_field(key) return metadata describing a standard or custom field. all_non_none_fields() Return a dictionary containing all non-none metadata fields, including the custom ones. 182 Capítulo 1. Secciones

187 get_standard_metadata(field, make_copy) return field metadata from the field if it is there. Otherwise return None. field is the key name, not the label. Return a copy if requested, just in case the user wants to change values in the dict. get_all_standard_metadata(make_copy) return a dict containing all the standard field metadata associated with the book. get_all_user_metadata(make_copy) return a dict containing all the custom field metadata associated with the book. get_user_metadata(field, make_copy) return field metadata from the object if it is there. Otherwise return None. field is the key name, not the label. Return a copy if requested, just in case the user wants to change values in the dict. set_all_user_metadata(metadata) store custom field metadata into the object. Field is the key name not the label set_user_metadata(field, metadata) store custom field metadata for one column into the object. Field is the key name not the label template_to_attribute(other, ops) Takes a list [(src,dest), (src,dest)], evaluates the template in the context of other, then copies the result to self[dest]. This is on a best-efforts basis. Some assignments can make no sense. smart_update(other, replace_metadata=false) Merge the information in other into self. In case of conflicts, the information in other takes precedence, unless the information in other is NULL. format_field(key, series_with_index=true) Returns the tuple (display_name, formatted_value) to_html() A HTML representation of this object. calibre.ebooks.metadata.book.base.standard_metadata_fields The set of standard metadata fields. ''' All fields must have a NULL value represented as None for simple types, an empty list/dictionary for complex types and (None, None) for cover_data ''' SOCIAL_METADATA_FIELDS = frozenset([ 'tags', # Ordered list 'rating', # A floating point number between 0 and 10 'comments', # A simple HTML enabled string 'series', # A simple string 'series_index', # A floating point number # Of the form { scheme1:value1, scheme2:value2} # For example: {'isbn':' ', 'doi':'xxxx',... } 'identifiers', ]) ''' The list of names that convert to identifiers when in get and set. ''' TOP_LEVEL_IDENTIFIERS = frozenset([ 'isbn', ]) 1.9. Cursillos 183

188 PUBLICATION_METADATA_FIELDS = frozenset([ 'title', # title must never be None. Should be _('Unknown') # Pseudo field that can be set, but if not set is auto generated # from title and languages 'title_sort', 'authors', # Ordered list. Must never be None, can be [_('Unknown')] 'author_sort_map', # Map of sort strings for each author # Pseudo field that can be set, but if not set is auto generated # from authors and languages 'author_sort', 'book_producer', 'timestamp', # Dates and times must be timezone aware 'pubdate', 'last_modified', 'rights', # So far only known publication type is periodical:calibre # If None, means book 'publication_type', 'uuid', # A UUID usually of type 4 'languages', # ordered list of languages in this publication 'publisher', # Simple string, no special semantics # Absolute path to image file encoded in filesystem_encoding 'cover', # Of the form (format, data) where format is, for e.g. 'jpeg', 'png', 'gif'... 'cover_data', # Either thumbnail data, or an object with the attribute # image_path which is the path to an image file, encoded # in filesystem_encoding 'thumbnail', ]) BOOK_STRUCTURE_FIELDS = frozenset([ # These are used by code, Null values are None. 'toc', 'spine', 'guide', 'manifest', ]) USER_METADATA_FIELDS = frozenset([ # A dict of dicts similar to field_metadata. Each field description dict # also contains a value field with the key #value#. 'user_metadata', ]) DEVICE_METADATA_FIELDS = frozenset([ 'device_collections', # Ordered list of strings 'lpath', # Unicode, / separated 'size', # In bytes 'mime', # Mimetype of the book file being represented ]) CALIBRE_METADATA_FIELDS = frozenset([ 'application_id', # An application id, currently set to the db_id. 'db_id', # the calibre primary key of the item. 'formats', # list of formats (extensions) for this book # a dict of user category names, where the value is a list of item names # from the book that are in that category 'user_categories', # a dict of author to an associated hyperlink 184 Capítulo 1. Secciones

189 'author_link_map', ) ] ALL_METADATA_FIELDS = SOCIAL_METADATA_FIELDS.union( PUBLICATION_METADATA_FIELDS).union( BOOK_STRUCTURE_FIELDS).union( USER_METADATA_FIELDS).union( DEVICE_METADATA_FIELDS).union( CALIBRE_METADATA_FIELDS) # All fields except custom fields STANDARD_METADATA_FIELDS = SOCIAL_METADATA_FIELDS.union( PUBLICATION_METADATA_FIELDS).union( BOOK_STRUCTURE_FIELDS).union( DEVICE_METADATA_FIELDS).union( CALIBRE_METADATA_FIELDS) # Metadata fields that smart update must do special processing to copy. SC_FIELDS_NOT_COPIED = frozenset(['title', 'title_sort', 'authors', 'author_sort', 'author_sort_map', 'cover_data', 'tags', 'languages', 'identifiers']) # Metadata fields that smart update should copy only if the source is not None SC_FIELDS_COPY_NOT_NULL = frozenset(['lpath', 'size', 'comments', 'thumbnail']) # Metadata fields that smart update should copy without special handling SC_COPYABLE_FIELDS = SOCIAL_METADATA_FIELDS.union( PUBLICATION_METADATA_FIELDS).union( BOOK_STRUCTURE_FIELDS).union( DEVICE_METADATA_FIELDS).union( CALIBRE_METADATA_FIELDS) - \ SC_FIELDS_NOT_COPIED.union( SC_FIELDS_COPY_NOT_NULL) SERIALIZABLE_FIELDS = SOCIAL_METADATA_FIELDS.union( USER_METADATA_FIELDS).union( PUBLICATION_METADATA_FIELDS).union( CALIBRE_METADATA_FIELDS).union( DEVICE_METADATA_FIELDS) - \ frozenset(['device_collections', 'formats', 'cover_data']) # these are rebuilt when needed Usar el modo de programa general For more complicated template programs, it is sometimes easier to avoid template syntax (all the { and } characters), instead writing a more classical-looking program. You can do this in calibre by beginning the template with program:. In this case, no template processing is done. The special variable $ is not set. It is up to your program to produce the correct results. One advantage of program: mode is that the brackets are no longer special. For example, it is not necessary to use [[ and ]] when using the template() function. Another advantage is that program mode templates are compiled to Python and can run much faster than templates in the other two modes. Speed improvement depends on the complexity of the templates; the more complicated the template the more the improvement. Compilation is turned off or on using 1.9. Cursillos 185

190 the tweak compile_gpm_templates (Compile General Program Mode templates to Python). The main reason to turn off compilation is if a compiled template does not work, in which case please file a bug report. The following example is a program: mode implementation of a recipe on the MobileRead forum: Put series into the title, using either initials or a shortened form. Strip leading articles from the series name (any). For example, for the book The Two Towers in the Lord of the Rings series, the recipe gives LotR [02] The Two Towers. Using standard templates, the recipe requires three custom columns and a plugboard, as explained in the following: The solution requires creating three composite columns. The first column is used to remove the leading articles. The second is used to compute the shorten form. The third is to compute the initials form. Once you have these columns, the plugboard selects between them. You can hide any or all of the three columns on the library view. Primera columna: Nombre: #stripped_series. Plantilla: {series:re(^(a The An)s+,) } Segunda columna (la forma abreviada): Nombre: #shortened. Plantilla: {#stripped_series:shorten(4,-,4)} Tercera columna (las iniciales): Nombre: #initials. Plantilla: {#stripped_series:re(([^s])[^s]+(s $),1)} Expresión para panel de conexiones: Plantilla:{#stripped_series:lookup(.s,#initials,.,#shortened,series)}{series_index:0>2.0f [ ] }{title} Campo de destino: title Este conjunto de campos y panel de conexiones produce: Serie: The Lord of the Rings Índice de serie: 2 Título: The Two Towers Salida: LotR [02] The Two Towers Serie: Dahak Índice de serie: 1 Título: Mutineers Moon Salida: Dahak [01] Mutineers Moon Serie: Berserkers Índice de serie: 4 Título: Berserker Throne Salida: Bers-kers [04] Berserker Throne Serie: Meg Langslow Mysteries Índice de serie: 3 Título: Revenge of the Wrought-Iron Flamingos Salida: MLM [03] Revenge of the Wrought-Iron Flamingos The following program produces the same results as the original recipe, using only one custom column to hold the results of a program that computes the special title value: Custom column: Name: #special_title Template: (the following with all leading spaces removed) program: # compute the equivalent of the composite fields and store them in local variables stripped = re(field('series'), '^(A The An)\s+', ''); shortened = shorten(stripped, 4, '-',4); initials = re(stripped, '[^\w]*(\w?)[^\s]+(\s $)', '\1'); # Format the series index. Ends up as empty if there is no series index. # Note that leading and trailing spaces will be removed by the formatter, # so we cannot add them here. We will do that in the strcat below. # Also note that because we are in 'program' mode, we can freely use # curly brackets in strings, something we cannot do in template mode. s_index = template('{series_index:0>2.0f}'); # print(stripped, shortened, initials, s_index); # Now concatenate all the bits together. The switch picks between # initials and shortened, depending on whether there is a space # in stripped. We then add the brackets around s_index if it is # not empty. Finally, add the title. As this is the last function in # the program, its value will be returned. strcat( switch( stripped, '.\s', initials, '.', shortened, field('series')), 186 Capítulo 1. Secciones

191 test(s_index, strcat(' [', s_index, '] '), ''), field('title')); Plugboard expression: Template:{#special_title} Destination field: title It would be possible to do the above with no custom columns by putting the program into the template box of the plugboard. However, to do so, all comments must be removed because the plugboard text box does not support multiline editing. It is debatable whether the gain of not having the custom column is worth the vast increase in difficulty caused by the program being one giant line. Funciones de plantilla definidas por el usuario You can add your own functions to the template processor. Such functions are written in python, and can be used in any of the three template programming modes. The functions are added by going to Preferences -> Advanced -> Template Functions. Instructions are shown in that dialog. Notas especiales para plantillas de guardado o envío Special processing is applied when a template is used in a save to disk or send to device template. The values of the fields are cleaned, replacing characters that are special to file systems with underscores, including slashes. This means that field text cannot be used to create folders. However, slashes are not changed in prefix or suffix strings, so slashes in these strings will cause folders to be created. Because of this, you can create variable-depth folder structure. For example, assume we want the folder structure series/series_index - title, with the caveat that if series does not exist, then the title should be in the top folder. The template to do this is: {series: /}{series_index: - }{title} La barra y el guión sólo aparecen si la serie no está vacía. The lookup function lets us do even fancier processing. For example, assume that if a book has a series, then we want the folder structure series/series index - title.fmt. If the book does not have a series, then we want the folder structure genre/author_sort/title.fmt. If the book has no genre, we want to use Unknown. We want two completely different paths, depending on the value of series. Para lograr esto: 1. Creamos un campo compuesto (llamémoslo AA) que contiene {series}/{series_index} - {title}. Si la serie no está vacía, esta plantilla produce serie/número_de_serie - título. 2. Creamos un campo compuesto (llamémoslo BB) que contenga {#genre:ifempty(desconocido)}/{author_sort}/{title}. Esta plantilla produce género/orden_de_autor/título, donde un género vacío se sustituye por Desconocido. 3. Establecemos la plantilla de guardado en {series:lookup(.,aa,bb)}. Esta plantilla elige el campo compuesto AA si la serie no está vacía y el campo compuesto BB si la serie está vacía. Obtenemos por lo tanto dos rutas de guardado completamente diferentes según el campo serie esté o no vacío. Plantillas y controles de metadatos Plugboards are used for changing the metadata written into books during send-to-device and save-to-disk operations. A plugboard permits you to specify a template to provide the data to write into the book s metadata. You can use plugboards to modify the following fields: authors, author_sort, language, publisher, tags, title, title_sort. This feature helps people who want to use different metadata in books on devices to solve sorting or display issues Cursillos 187

192 When you create a plugboard, you specify the format and device for which the plugboard is to be used. A special device is provided, save_to_disk, that is used when saving formats (as opposed to sending them to a device). Once you have chosen the format and device, you choose the metadata fields to change, providing templates to supply the new values. These templates are connected to their destination fields, hence the name plugboards. You can, of course, use composite columns in these templates. When a plugboard might apply (content server, save to disk, or send to device), calibre searches the defined plugboards to choose the correct one for the given format and device. For example, to find the appropriate plugboard for an EPUB book being sent to an ANDROID device, calibre searches the plugboards using the following search order: un panel de conexiones con una coincidencia exacta de formato y dispositivo, por ejemplo: EPUB y ANDROID un panel de conexiones con una coincidencia exacta de formato y el dispositivo especial any device, por ejemplo EPUB y any device un panel de conexiones con el formato especial any format y una coincidencia exacta de dispositivo, por ejemplo: any format y ANDROID un panel de conexiones con any format y any device The tags and authors fields have special treatment, because both of these fields can hold more than one item. A book can have many tags and many authors. When you specify that one of these two fields is to be changed, the template s result is examined to see if more than one item is there. For tags, the result is cut apart wherever calibre finds a comma. For example, if the template produces the value Thriller, Horror, then the result will be two tags, Thriller and Horror. There is no way to put a comma in the middle of a tag. The same thing happens for authors, but using a different character for the cut, a & (ampersand) instead of a comma. For example, if the template produces the value Blogs, Joe&Posts, Susan, then the book will end up with two authors, Blogs, Joe and Posts, Susan. If the template produces the value Blogs, Joe;Posts, Susan, then the book will have one author with a rather strange name. Plugboards affect the metadata written into the book when it is saved to disk or written to the device. Plugboards do not affect the metadata used by save to disk and send to device to create the file names. Instead, file names are constructed using the templates entered on the appropriate preferences window. Consejos útiles Puede encontrar útiles los siguientes consejos. Create a custom composite column to test templates. Once you have the column, you can change its template simply by double-clicking on the column. Hide the column when you are not testing. Las plantillas pueden usar otras plantillas haciendo referencia a una columna personalizada compuesta. In a plugboard, you can set a field to empty (or whatever is equivalent to empty) by using the special template {}. This template will always evaluate to an empty string. La técnica descrita anteriormente para mostrar los números incluso si son cero funciona con el campo estándar «series_index». Reference for all built-in template language functions Here, we document all the built-in functions available in the calibre template language. Every function is implemented as a class in python and you can click the source links to see the source code, in case the documentation is insufficient. The functions are arranged in logical groups by type. 188 Capítulo 1. Secciones

193 1.9. Cursillos 189

194 Arithmetic (Página 191) add(x, y) (Página 191) divide(x, y) (Página 191) multiply(x, y) (Página 191) subtract(x, y) (Página 191) Boolean (Página 191) and(valor, valor,...) (Página 191) not(valor) (Página 191) or(valor, valor,...) (Página 191) Date functions (Página 191) days_between(fecha1, fecha2) (Página 191) today() (Página 191) Formatting values (Página 192) finish_formatting(val, fmt, prefijo, sufijo) (Página 192) format_date(val, texto_formato) (Página 192) format_number(v, plantilla) (Página 192) human_readabe(v) (Página 192) Get values from metadata (Página 192) approximate_formats() (Página 192) author_links(sep_val, sep_par) (Página 193) author_sort(separador) (Página 193) booksize() (Página 193) current_library_name() (Página 193) current_library_path() (Página 193) field(nombre) (Página 193) formats_modtimes(formato_fecha) (Página 193) formats_paths() (Página 193) formats_sizes() (Página 194) has_cover() (Página 194) language_codes(nombres) (Página 194) language_strings(códigos, localizar) (Página 194) ondevice() (Página 194) raw_field(nombre) (Página 194) raw_list(nombre,separador) (Página 194) series_sort() (Página 194) user_categories() (Página 195) virtual_libraries() (Página 195) If-then-else (Página 195) contains(val, patrón, texto_si_coincide, texto_si_no_coincide) (Página 195) ifempty(val, texto_si_vacío) (Página 195) test(val, texto_si_no_vacío, texto_si_vacío) (Página 195) Iterating over values (Página 195) first_non_empty(valor, valor,...) (Página 195) lookup(val, patrón, campo, patrón, campo,..., otro_campo) (Página 195) switch(val, patrón, valor, patrón, valor,..., otro_valor) (Página 196) List lookup (Página 196) identifier_in_list(val, id, val_encontrado, val_no_encontrado) (Página 196) in_list(val, separador, patrón, encontrado, no_encontrado) (Página 196) list_item(val, índice, separador) (Página 196) select(val, clave) (Página 196) str_in_list(val, separador, texto, val_encontrado, val_no_encontrado) (Página 196) List manipulation (Página 196) count(val, separador) (Página 196) list_difference(lista1, lista2, separador) (Página 197) list_equals(lista1, sep1, lista2, sep2, val_sí, val_no) (Página 197) list_intersection(lista1, lista2, separador) (Página 197) 190 list_re(list_orig, separador, incluir, sust_opt) (Página 197) Capítulo 1. Secciones list_re_group(list_orig, separador, incluir, búsqueda, plantilla_grupo_1,...) (Página 197) list_sort(lista, dirección, separador) (Página 197) list_union(lista1, lista2, separador) (Página 197)

195 Arithmetic add(x, y) class calibre.utils.formatter_functions.builtinadd add(x, y) devuelve x + y. Da un error si «x» o «y» no son números. divide(x, y) class calibre.utils.formatter_functions.builtindivide divide(x, y) devuelve x / y. Da un error si «x» o «y» no son números. multiply(x, y) class calibre.utils.formatter_functions.builtinmultiply multiply(x, y) devuelve x * y. Da un error si «x» o «y» no son números. subtract(x, y) class calibre.utils.formatter_functions.builtinsubtract subtract(x, y) devuelve x - y. Da un error si «x» o «y» no son números. Boolean and(valor, valor,...) class calibre.utils.formatter_functions.builtinand and(valor, valor,...) devuelve el texto «1» si ninguno de los valores está vacío, en caso contrario, devuelve un texto vacío. Esta función funciona bien con «first_non_empty». Puede incluir tantos valores como quiera. not(valor) class calibre.utils.formatter_functions.builtinnot not(valor) devuelve el texto «1» si el valor está vacío, en caso contrario, devuelve un texto vacío. or(valor, valor,...) class calibre.utils.formatter_functions.builtinor or(valor, valor,...) devuelve el texto «1» si alguno de los valores no está vacío, en caso contrario, devuelve un texto vacío. Esta función funciona bien con «first_non_empty». Puede incluir tantos valores como quiera. Date functions days_between(fecha1, fecha2) class calibre.utils.formatter_functions.builtindaysbetween days_between(fecha1, fecha2) devuelve el número de días entre «fecha1» y «fecha2». El número es positivo si «fecha1» es posterior a «fecha2», en caso contrario es negativo. Si «fecha1» o «fecha2» no son fechas, la función devuelve un texto vacío. today() class calibre.utils.formatter_functions.builtintoday today() devuelve un texto para la fecha de hoy. Este valor está preparado para usarse con «format_date» o «days_between», pero puede manipularse como cualquier otro texto. La fecha está en formato ISO Cursillos 191

196 Formatting values finish_formatting(val, fmt, prefijo, sufijo) class calibre.utils.formatter_functions.builtinfinishformatting finish_formatting(val, fmt, prefijo, sufijo) aplica el formato, prefijo y sufijo a un valor de la misma manera que se haría en una plantilla como «{series_index:05.2f - - }». Por ejemplo, el siguiente programa produce la misma salida que la plantilla anterior: program: finish_formatting(field( series_index ), 05.2f, -, - ) format_date(val, texto_formato) class calibre.utils.formatter_functions.builtinformatdate format_date(val, texto_formato) da formato a un valor, que debe ser un campo de fecha, según «texto_formato» y devuelve un texto. Los códigos de formato son: «d»: el día como un número, sin cero inicial (de 1 a 31). «dd»: el día como un número, con un cero inicial si es necesario (de 01 a 31). «ddd»: el día de la semana abreviado según el idioma local (p. ej. de «lun» a «dom»). «dddd»: el nombre local completo del día de la semana (p. ej. de «lunes» a «domingo»). «M»: el mes como un número sin cero inicial (de 1 a 12). «MM»: el mes como un número, con un cero inicial si es necesario (de 01 a 12). «MMM»: el mes abreviado según el idioma local (p. ej. de «ene» a «dic»). «MMMM»: el nombre local completo del mes (p. ej. de «enero» a «diciembre»). «yy»: el año como un número de dos cifras (de 00 a 99). «yyyy»: el año como un número de cuatro cifras. «h»: la hora sin cero inicial (de 0 a 11 o de 0 a 23, según am/pm). «hh»: la hora con un cero inicial si es necesario (de 00 a 11 o de 00 a 23, según am/pm). «m»: los minutos sin cero inicial (de 0 a 59). «mm»: los minutos con un cero inicial si es necesaro (de 00 a 59). «s»: los segundos sin cero inicial (de 0 a 59). «ss»: los segundos con un cero inicial si es necesario (de 00 a 59). «ap»: se escribe la hora en formato de 12 horas en lugar de 24, con «ap» sustituido por la forma local para am o pm. «AP»: se escribe la hora en formato de 12 horas en lugar de 24, con «AP» sustituido por la forma local para AM o PM. «iso»: la fecha con hora y zona horaria. Debe ser el único formato presente. format_number(v, plantilla) class calibre.utils.formatter_functions.builtinformatnumber format_number(v, plantilla) da formato al número «v» usando una plantilla de formato de python como «{0:5.2f}» o «{0:,d}» o «{0:5,.2f}». La parte del nombre de la plantilla debe ser un 0 (cero) (el «{0:» en los ejemplos anteriores). Véase la documentación del lenguaje de plantillas y de python para más ejemplos. Devuelve un texto vacío si el formato falla. human_readabe(v) class calibre.utils.formatter_functions.builtinhumanreadable human_readabe(v) devuelve un texto que representa el número «v» en KB, MB, GB, etc. Get values from metadata approximate_formats() class calibre.utils.formatter_functions.builtinapproximateformats approximate_formats() devuelve una lista separada por comas de formatos que en algún momento estuvieron asociados con el libro. No hay garantía de que esta lista sea correcta, aunque probablemente lo sea. Esta función puede llamarse en el modo de programación de plantillas usando la plantilla «{: approximate_formats() }». Tenga en cuenta que los nombres de formato están siempre en mayúsculas, como en «EPUB». Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar 192 Capítulo 1. Secciones

197 author_links(sep_val, sep_par) class calibre.utils.formatter_functions.builtinauthorlinks author_links(sep_val, sep_par) devuelve un texto que contiene una lista de autores y enlaces a los autores de la forma: «autor1 sep_val enlace_autor1 sep_par autor2 sep_val enlace_autor2» etc. Cada autor está separado de su correspondiente enlace por el texto «sep_val», sin espacios adicionales. Los pares autor:enlace_autor están separados por el texto «sep_par», sin espacios adicionales. Es responsabilidad del usuario proporcionar separadores que no aparezcan en los nombres o enlaces de autor. El nombre de autor se incluye aunque su enlace esté vacío. author_sort(separador) class calibre.utils.formatter_functions.builtinauthorsorts author_sort(separador) devuelve un texto que contiene la lista de valores de orden de autor para los autores del libro. El orden es el de los autores en los metadatos (diferente del valor de orden de autor del libro). La lista devuelta es de la forma orden_de _autor_1 separador orden_de_autor_2 etc. Los valores de orden de autor en la lista están en el mismo orden que los autores del libro. Si quiere espacios alrededor de «separador», inclúyalos en el valor. booksize() class calibre.utils.formatter_functions.builtinbooksize booksize() devuelve el valor del campo de tamaño. Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar current_library_name() class calibre.utils.formatter_functions.builtincurrentlibraryname current_library_name() devuelve la última parte de la ruta a la biblioteca de calibre actual. Esta función puede llamarse en el modo de programación de plantilla usando la plantilla {: current_library_name() }. current_library_path() class calibre.utils.formatter_functions.builtincurrentlibrarypath current_library_path() devuelve la ruta a la biblioteca de calibre actual. Esta función puede usarse en el modo de programación de plantillas utilizando la plantilla «{: current_library_path() }». field(nombre) class calibre.utils.formatter_functions.builtinfield field(nombre) devuelve el campo de metadatos identificado por «nombre». formats_modtimes(formato_fecha) class calibre.utils.formatter_functions.builtinformatsmodtimes formats_modtimes(formato_fecha) devuelve una lista de elementos (separados por dos puntos) separados por comas que representa las fechas de modificación para los formatos de un libro. El argumento «formato_fecha» especifica cómo se da formato a la fecha. Véase la función «date_format» para más detalles. Puede usar la función «select» para obtener la fecha de modificación de un formato específico. Tenga en cuenta que los nombres de formato siempre están en mayúsculas, como en «EPUB». formats_paths() 1.9. Cursillos 193

198 class calibre.utils.formatter_functions.builtinformatspaths formats_paths() devuelve una lista separada por comas de elementos separados por dos puntos que representan la ruta completa a los formatos de un libro. Puede usar la función «select» para obtener la ruta a un formato específico. Tenga en cuenta que los nombres de formato están siempre en mayúsculas, como en «EPUB». formats_sizes() class calibre.utils.formatter_functions.builtinformatssizes formats_sizes() devuelve una lista de elementos (separados por dos puntos) separados por comas que representa los tamaños en bytes de los formatos de un libro. Puede usar la función «select» para obtener el tamaño de un formato específico. Tenga en cuenta que los nombres de formato siempre están en mayúsculas, como en «EPUB». has_cover() class calibre.utils.formatter_functions.builtinhascover has_cover() devuelve «Yes» si el libro tiene portada, en caso contrario devuelve un texto vacío. language_codes(nombres) class calibre.utils.formatter_functions.builtinlanguagecodes language_codes(nombres) devuelve los códigos de idioma correspondientes a «nombres». Los nombres deben estar en el idioma actual. El argumento «nombres» es una lista separada por comas. language_strings(códigos, localizar) class calibre.utils.formatter_functions.builtinlanguagestrings language_strings(códigos, localizar) devuelve los nombres de los idiomas identificados por «códigos». Si «localizar» es cero, devuelve los nombres en inglés. Si «localizar» no es cero, devuelve los nombres en el idioma actual. El argumento «códigos» es una lista separada por comas. ondevice() class calibre.utils.formatter_functions.builtinondevice ondevice() devuelve «Yes» si ondevice está activado, si no, devuelve un texto vacío. Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar raw_field(nombre) class calibre.utils.formatter_functions.builtinrawfield raw_field(nombre) devuelve el campo de metadatos llamado «nombre» sin aplicar ningún formato. raw_list(nombre,separador) class calibre.utils.formatter_functions.builtinrawlist raw_list(nombre,separador) devuelve la lista de metadatos nombrada por «nombre» sin aplicar ningún formato u ordenación, con los elementos separados por «separador». series_sort() class calibre.utils.formatter_functions.builtinseriessort series_sort() devuelve el valor del orden de serie 194 Capítulo 1. Secciones

199 user_categories() class calibre.utils.formatter_functions.builtinusercategories user_categories() devuelve una lista separada por comas de las categorías de usuario que contiene este libro. Esta función sólo funciona en la interfaz gráfica. Si desea utilizar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, deberá crear una plantilla personalizada «Columna generada a partir de otras columnas», utilice la función en la plantilla de esa columna y use el valor de esa columna en las plantillas para guardar o enviar virtual_libraries() class calibre.utils.formatter_functions.builtinvirtuallibraries virtual_libraries() devuelve una lista separada por comas de bibliotecas virtuales que contienen este libro. Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar If-then-else contains(val, patrón, texto_si_coincide, texto_si_no_coincide) class calibre.utils.formatter_functions.builtincontains contains(val, patrón, texto_si_coincide, texto_si_no_coincide) comprueba si el campo contiene coincidencias para la expresión regular «patrón». Devuelve «texto_si_coincide» si se encuentran coincidencias, en caso contrario devuelve «texto_si_no_coincide». ifempty(val, texto_si_vacío) class calibre.utils.formatter_functions.builtinifempty ifempty(val, texto_si_vacío) devuelve «val» si no está vacío, en caso contrario devuelve «texto_si_vacío». test(val, texto_si_no_vacío, texto_si_vacío) class calibre.utils.formatter_functions.builtintest test(val, texto_si_no_vacío, texto_si_vacío) devuelve «texto_si_no_vacío» si el campo no está vacío, «devuelve texto_si_vacío» en caso contrario. Iterating over values first_non_empty(valor, valor,...) class calibre.utils.formatter_functions.builtinfirstnonempty first_non_empty(valor, valor,...) devuelve el primer valor que no esté vacío. Si todos los valores están vacíos, se devuelve también un valor vacío. Puede incluir tantos valores como quiera. lookup(val, patrón, campo, patrón, campo,..., otro_campo) class calibre.utils.formatter_functions.builtinlookup lookup(val, patrón, campo, patrón, campo,..., otro_campo) como «switch», pero los argumentos son nombres de campo (metadatos), no texto. Se usará el valor del campo apropiado. Tenga en cuenta que puesto que las columnas compuestas son campos, puede usar esta función en un campo compuesto para usar el valor de otro campo compuesto. Esto es muy útil para construir rutas de guardado variables Cursillos 195

200 switch(val, patrón, valor, patrón, valor,..., otro_valor) class calibre.utils.formatter_functions.builtinswitch switch(val, patrón, valor, patrón, valor,..., otro_valor) para cada pareja «patrón, valor», comprueba si el campo contiene coincidencias para la expresión regular «patrón» y, en tal caso, devuelve ese valor. Si no coincide ningún patrón, devuelve «otro_valor». Puede emplear tantas parejas «patrón, valor» como desee. List lookup identifier_in_list(val, id, val_encontrado, val_no_encontrado) class calibre.utils.formatter_functions.builtinidentifierinlist identifier_in_list(val, id, val_encontrado, val_no_encontrado) considera «val» como una lista de identificadores separados por comas, y compara el «id» con cada valor de la lista. Un identificador tiene el formato «id:valor». El argumento «id» debería ser «id» o «id:expreg». El primer caso, selecciona identificadores con dicho «id». El segundo caso, selecciona identificadores cuyo valor coincida con la expresión regular «expreg». Si existe alguna coincidencia, devuelve «val_encontrado», en caso contrario devuelve «val_no_encontrado». in_list(val, separador, patrón, encontrado, no_encontrado) class calibre.utils.formatter_functions.builtininlist in_list(val, separador, patrón, encontrado, no_encontrado) considera «val» como una lista de elementos separados por «separador» y compara «patrón» con cada valor de la lista. Si «patrón» coincide con alguno de los elementos de la lista, devuelve «encontrado», en caso contrario devuelve «no_encontrado». list_item(val, índice, separador) class calibre.utils.formatter_functions.builtinlistitem list_item(val, índice, separador) interpreta el campo como una lista de elementos separados por «separador» y devuelve el elemento número «índice». El primer elemento es el número cero. El último elemento puede obtenerse con «list_item(-1, separador)». Si el elemento no está en la lista devuelve un valor vacío. El separador tiene el mismo significado que en la función «count». select(val, clave) class calibre.utils.formatter_functions.builtinselect select(val, clave) interpreta el valor como una lista de elementos separados por comas, con los elementos de la forma «id:valor». Encuentra la pareja con «id» igual a «clave» y devuelve el valor correspondiente. str_in_list(val, separador, texto, val_encontrado, val_no_encontrado) class calibre.utils.formatter_functions.builtinstrinlist str_in_list(val, separador, texto, val_encontrado, val_no_encontrado) considera «val» como una lista de elementos separados por «separador», y compara el «texto» con cada valor de la lista. Si el texto coincide con alguno de los valores, devuelve «val_encontrado», en caso contrario devuelve «val_no_encontrado». Si el texto contiene separadores, también se considera como una lista y se comprueba cada elemento. List manipulation count(val, separador) class calibre.utils.formatter_functions.builtincount count(val, separador) interpreta el campo como una lista de elementos separados por «separador» y devuelve el número de elementos de la lista. La mayoría de las listas usan una coma como separador, pero «authors» usa un ampersand («&»). Ejemplos: {tags:count(,)}, {authors,count(&)} 196 Capítulo 1. Secciones

201 list_difference(lista1, lista2, separador) class calibre.utils.formatter_functions.builtinlistdifference list_difference(lista1, lista2, separador) devuelve una lista construida eliminando de «lista1» cualquier elemento que aparezca en «lista2», sin distinguir mayúsculas y minúsculas. Los elementos de «lista1» y «lista2» están separados por «separador», así como los de la lista resultante. list_equals(lista1, sep1, lista2, sep2, val_sí, val_no) class calibre.utils.formatter_functions.builtinlistequals list_equals(lista1, sep1, lista2, sep2, val_sí, val_no) devuelve «val_sí» si «lista1» y «lista2» contienen los mismos elementos, en caso contrario devuelve «val_no». Los elementos se determinan dividiendo cada lista por el correspondiente carácter separador («sep1» o «sep2»). El orden de los elementos no es relevante. La comparación no diferencia mayúsculas y minúsculas. list_intersection(lista1, lista2, separador) class calibre.utils.formatter_functions.builtinlistintersection list_intersection(lista1, lista2, separador) devuelve una lista construida eliminando de «lista1» cualquier elemento que no aparezca en «lista2», sin distinguir mayúsculas y minúsculas. Los elementos de «lista1» y «lista2» están separados por «separador», así como los de la lista resultante. list_re(list_orig, separador, incluir, sust_opt) class calibre.utils.formatter_functions.builtinlistre list_re(list_orig, separador, incluir, sust_opt) construye una lista separando primero «list_orig» en elementos usando el carácter «separador». Para cada elemento en la lista, comprueba si coincide con la expresión regular «incluir». Si coincide, se añade a la lista final. Si «sust_opt» no es un texto vacío, se aplica la sustitución antes de añadir el elemento a la lista final. list_re_group(list_orig, separador, incluir, búsqueda, plantilla_grupo_1,...) class calibre.utils.formatter_functions.builtinlistregroup list_re_group(list_orig, separador, incluir, búsqueda, plantilla_grupo_1,...) como «list_re», pero las sustituciones no son opcionales. Usa re_group(elemento, búsqueda, plantilla_grupo_1,...) al hacer sustituciones en la lista final. list_sort(lista, dirección, separador) class calibre.utils.formatter_functions.builtinlistsort list_sort(lista, dirección, separador) devuelve «lista» ordenada sin distinción de mayúsculas y minúsculas. Si «dirección» es cero, la lista se ordena de manera ascendente, en caso contrario, de manera descendente. Los elementos de «lista» están separados por «separador», así como los de la lista resultante. list_union(lista1, lista2, separador) class calibre.utils.formatter_functions.builtinlistunion list_union(lista1, lista2, separador) devuelve una lista construida por combinación de los elementos en «lista1» y «lista2», eliminando los duplicados de «lista2» (no distingue mayúsculas y minúsculas, se mantiene la versión de «lista1»). Los elementos de «lista1» y «lista2» están separados por «separador», así como los de la lista resultante. subitems(val, índice_inicio, índice_fin) class calibre.utils.formatter_functions.builtinsubitems subitems(val, índice_inicio, índice_fin) Esta función se usa para separar listas de elementos tales como los géneros. Interpreta el valor como una lista de elementos separados por comas, donde cada elemento es a su 1.9. Cursillos 197

202 vez una lista de elementos separados por puntos. Devuelve una nueva lista formada tomando, de cada lista de elementos separados por puntos, los elementos situados entre las posiciones «índice_inicio» e «índice_fin» y combinando los resultados. El primer elemento de cada lista separada por puntos ocupa la posición cero. Si un índice es negativo, se cuenta desde el final de la lista. Como caso especial, si «índice_fin» es cero, se considera que es el final de la lista. Ejemplos en el modo básico de plantilla y suponiendo que la columna #género contiene el valor «A.B.C»: {#género:subitems(0,1)} devuelve «A», {#género:subitems(0,2)} devuelve «A.B», {#género:subitems(1,0)} devuelve «B.C». Suponiendo que #género contiene el valor «A.B.C, D.E.F»: {#género:subitems(0,1)} devuelve «A, D», {#género:subitems(0,2)} devuelve «A.B, D.E». sublist(val, índice_inicio, índice_fin, separador) class calibre.utils.formatter_functions.builtinsublist sublist(val, índice_inicio, índice_fin, separador) interpreta el valor como una lista de elementos separados por «separador» y devuelve una nueva lista con los elementos comprendidos entre la posición «índice_inicio» e «índice_fin». El primer elemento ocupa la posición cero. Si un índice es negativo, se cuenta desde el final de la lista. Como caso especial, si «índice_fin» es cero, se considera que es el final de la lista. Ejemplos en el modo básico de plantilla y suponiendo que la columna de etiquetas (definida como valores separados por comas) contiene «A, B, C»: {tags:sublist{0,1 )} devuelve «A», {tags:sublist(-1,0 )} devuelve «C», {tags:sublist(0,-1 )} devuelve «A, B». Other assign(id, val) class calibre.utils.formatter_functions.builtinassign assign(id, val) asigna «val» a «id» y devuelve «val». «id» debe ser un identificador, no una expresión print(a, b,...) class calibre.utils.formatter_functions.builtinprint print(a, b,...) escribe los argumentos en la salida estándar. Sólo será visible si inicia calibre a partir de línea de órdenes (calibre-debug -g). Recursion eval(plantilla) class calibre.utils.formatter_functions.builtineval eval(plantilla) evalúa la plantilla, pasando las variables locales (las definidas con «assign») en lugar de los metadatos del libro. Esto permite usar el procesador de plantillas para elaborar resultados complejos a partir de variables locales. Dado que los caracteres «{» y «}» tienen un uso especial, debe usar «[[» en lugar de «{» y «]]» para «}»; se convertirán automáticamente. Tenga en cuenta que los prefijos y sufijos (la sintaxis «prefijo sufijo») no puede usarse en el argumento de esta función en el modo de programación de plantilla. template(x) class calibre.utils.formatter_functions.builtintemplate template(x) evalúa x como una plantilla. La evaluación se realiza en un contexto propio, lo que significa que las variables no se comparten entre el proceso que llama a la función y la evaluación de la plantilla. Dado que los caracteres «{» y «}» tienen un uso especial, debe usar «[[» en lugar de «{» y «]]» para «}»; se convertirán automáticamente. Por ejemplo, «template( [[orden_de_título]] )» evaluará la plantilla {orden_de_título} y devolverá su valor. Tenga en cuenta que los prefijos y sufijos (la sintaxis «prefijo sufijo») no puede usarse en el argumento de esta función en el modo de programación de plantilla. 198 Capítulo 1. Secciones

203 Relational cmp(x, y, mn, ig, my) class calibre.utils.formatter_functions.builtincmp cmp(x, y, mn, ig, my) compara x e y después de convertirlas en números. Devuelve mn si x < y. Devuelve ig si x = y. Devuelve my en otros casos. first_matching_cmp(val, cmp1, resultado1, cmp2, resultado2,..., otro_resultado) class calibre.utils.formatter_functions.builtinfirstmatchingcmp first_matching_cmp(val, cmp1, resultado1, cmp2, resultado2,..., otro_resultado) compara «val < cmpn» consecutivamente y devuelve «resultadon» para la primera comparación que sea cierta. Devuelve «otro_resultado» si ninguna comparación es cierta. Ejemplo: first_matching_cmp(10,5, pequeño,10, mediano,15, grande, enorme ) devuelve grande. El mismo ejemplo con un primer valor de 16 devuelve enorme. strcmp(x, y, mn, ig, my) class calibre.utils.formatter_functions.builtinstrcmp strcmp(x, y, mn, ig, my) compara «x» e «y» como textos sin distinguir mayúsculas y minúsculas. Devuelve «mn» si x < y. Devuelve «ig» si x = y. Devuelve «my» en otros casos. String case changes capitalize(val) class calibre.utils.formatter_functions.builtincapitalize capitalize(val) devuelve el valor del campo con la primera letra mayúscula lowercase(val) class calibre.utils.formatter_functions.builtinlowercase lowercase(val) devuelve el valor del campo en minúsculas titlecase(val) class calibre.utils.formatter_functions.builtintitlecase titlecase(val) devuelve el valor del campo con las iniciales en mayúscula uppercase(val) class calibre.utils.formatter_functions.builtinuppercase uppercase(val) devuelve el valor del campo en mayúsculas String manipulation re(val, patrón, sustitución) class calibre.utils.formatter_functions.builtinre re(val, patrón, sustitución) devuelve el campo después de aplicar la expresión regular. Todas las veces que aparezca «patrón» se sustituirá por «sustitución». Como en todo calibre, se trata de expresiones regulares compatibles con python Cursillos 199

204 re_group(val, patrón, plantilla_para_grupo_1, para_grupo_2,...) class calibre.utils.formatter_functions.builtinregroup re_group(val, patrón, plantilla_para_grupo_1, para_grupo_2,...) devuelve un texto formado por aplicación de la expresión regular «patrón» al valor «val», sustituyendo cada coincidencia con el texto calculado al sustituir cada grupo por el valor devuelto por la correspondiente plantilla. El valor de correspondencia original del grupo está disponible como «$». En el modo de programación de plantillas, como en las funciones «template» y «eval», use «[[» en lugar de «{» y «]]» en lugar de «}». El siguiente ejemplo en modo de programación de plantillas busca un nombre de serie con más de una palabra y pone la primera palabra en mayúsculas: {series: re_group($, (S* )(.*), [[$:uppercase()]], [[$]] ) } shorten(val, car_izq, texto_medio, car_der) class calibre.utils.formatter_functions.builtinshorten shorten(val, car_izq, texto_medio, car_der) devuelve una versión abreviada del campo, consistente en un número «car_izq» de caracteres del principio del campo, seguidos de «texto_medio», seguido de un número «car_der» de caracteres del final del campo. «car_izq» y «car_der» deben ser números enteros. Por ejemplo, supongamos que el título del libro es «Novísima recopilación de las leyes de España» y que quiere que quepa en un espacio de 15 caracteres a lo sumo. Si usa {title:shorten(8,-,6)}, el resultado será «Novísima-España». Si la longitud del campo es menor que «car_izq» + «car_der» + la longitud de «texto_medio», se usará el campo intacto. Por ejemplo, el título «La colmena» no se cambiará. strcat(a, b,...) class calibre.utils.formatter_functions.builtinstrcat strcat(a, b,...) admite un número arbitrario de argumentos. Devuelve un texto consistente en la unión de todos los argumentos consecutivamente. strcat_max(máx, texto1, prefijo2, texto2,...) class calibre.utils.formatter_functions.builtinstrcatmax strcat_max(máx, texto1, prefijo2, texto2,...) devuelve un texto formado por concatenación de los argumentos. El valor devuelto es inicialmente «texto1». Se van añadiendo parejas «prefijo, texto» al final del valor mientras la longitud del resultado sea menor que «máx». El resultado es siempre al menos «texto1», aunque su longitud sea mayor que «máx». Puede especificar tantas parejas «prefijo, texto» como desee. strlen(a) class calibre.utils.formatter_functions.builtinstrlen strlen(a) devuelve la longitud del texto pasado como argumento. substr(cad, inicio, fin) class calibre.utils.formatter_functions.builtinsubstr substr(cad, inicio, fin) devuelve los caracteres entre la posición «inicio» y «fin» del texto «cad». El primer carácter de «cad» está en la posición cero. Si «fin» es negativo, entonces indica la posición contando desde la derecha. Si «fin» es cero, indica el último carácter. Por ejemplo, substr( 12345, 1, 0) devuelve 2345, y substr( 12345, 1, -1) devuelve 234. swap_around_comma(val) class calibre.utils.formatter_functions.builtinswaparoundcomma swap_around_comma(val) dado un valor de la forma «B, A», devuelve «A B». Esto es útil para convertir nombres en formato APELLIDO, NOMBRE a NOMBRE APELLIDO. Si no hay ninguna coma, la función devuelve «val» sin cambios. 200 Capítulo 1. Secciones

205 transliterate(a) class calibre.utils.formatter_functions.builtintransliterate transliterate(a) Devuelve un texto en el alfabeto latino formado por aproximación del sonido de las palabras en el texto origen. Por ejemplo, si el origen es «Фёдор Михaйлович Достоевский» la función devuelve «Fiodor Mikhailovich Dostoievskii». API of the Metadata objects The python implementation of the template functions is passed in a Metadata object. Knowing it s API is useful if you want to define your own template functions. class calibre.ebooks.metadata.book.base.metadata(title, authors=(u Desconocido, ), other=none, template_cache=none, formatter=none) A class representing all the metadata for a book. The various standard metadata fields are available as attributes of this object. You can also stick arbitrary attributes onto this object. Metadata from custom columns should be accessed via the get() method, passing in the lookup name for the column, for example: #mytags. Use the is_null() (Página 201) method to test if a field is null. This object also has functions to format fields into strings. The list of standard metadata fields grows with time is in STANDARD_METADATA_FIELDS (Página 202). Please keep the method based API of this class to a minimum. Every method becomes a reserved field name. is_null(field) Return True if the value of field is null in this object. null means it is unknown or evaluates to False. So a title of _( Unknown ) is null or a language of und is null. Be careful with numeric fields since this will return True for zero as well as None. Also returns True if the field does not exist. deepcopy(class_generator=<function <lambda>>) Do not use this method unless you know what you are doing, if you want to create a simple clone of this object, use deepcopy_metadata() instead. Class_generator must be a function that returns an instance of Metadata or a subclass of it. get_identifiers() Return a copy of the identifiers dictionary. The dict is small, and the penalty for using a reference where a copy is needed is large. Also, we don t want any manipulations of the returned dict to show up in the book. set_identifiers(identifiers) Set all identifiers. Note that if you previously set ISBN, calling this method will delete it. set_identifier(typ, val) If val is empty, deletes identifier of type typ standard_field_keys() return a list of all possible keys, even if this book doesn t have them custom_field_keys() return a list of the custom fields in this book all_field_keys() All field keys known by this instance, even if their value is None metadata_for_field(key) return metadata describing a standard or custom field. all_non_none_fields() Return a dictionary containing all non-none metadata fields, including the custom ones Cursillos 201

206 get_standard_metadata(field, make_copy) return field metadata from the field if it is there. Otherwise return None. field is the key name, not the label. Return a copy if requested, just in case the user wants to change values in the dict. get_all_standard_metadata(make_copy) return a dict containing all the standard field metadata associated with the book. get_all_user_metadata(make_copy) return a dict containing all the custom field metadata associated with the book. get_user_metadata(field, make_copy) return field metadata from the object if it is there. Otherwise return None. field is the key name, not the label. Return a copy if requested, just in case the user wants to change values in the dict. set_all_user_metadata(metadata) store custom field metadata into the object. Field is the key name not the label set_user_metadata(field, metadata) store custom field metadata for one column into the object. Field is the key name not the label template_to_attribute(other, ops) Takes a list [(src,dest), (src,dest)], evaluates the template in the context of other, then copies the result to self[dest]. This is on a best-efforts basis. Some assignments can make no sense. smart_update(other, replace_metadata=false) Merge the information in other into self. In case of conflicts, the information in other takes precedence, unless the information in other is NULL. format_field(key, series_with_index=true) Returns the tuple (display_name, formatted_value) to_html() A HTML representation of this object. calibre.ebooks.metadata.book.base.standard_metadata_fields The set of standard metadata fields. ''' All fields must have a NULL value represented as None for simple types, an empty list/dictionary for complex types and (None, None) for cover_data ''' SOCIAL_METADATA_FIELDS = frozenset([ 'tags', # Ordered list 'rating', # A floating point number between 0 and 10 'comments', # A simple HTML enabled string 'series', # A simple string 'series_index', # A floating point number # Of the form { scheme1:value1, scheme2:value2} # For example: {'isbn':' ', 'doi':'xxxx',... } 'identifiers', ]) ''' The list of names that convert to identifiers when in get and set. ''' TOP_LEVEL_IDENTIFIERS = frozenset([ 'isbn', ]) 202 Capítulo 1. Secciones

207 PUBLICATION_METADATA_FIELDS = frozenset([ 'title', # title must never be None. Should be _('Unknown') # Pseudo field that can be set, but if not set is auto generated # from title and languages 'title_sort', 'authors', # Ordered list. Must never be None, can be [_('Unknown')] 'author_sort_map', # Map of sort strings for each author # Pseudo field that can be set, but if not set is auto generated # from authors and languages 'author_sort', 'book_producer', 'timestamp', # Dates and times must be timezone aware 'pubdate', 'last_modified', 'rights', # So far only known publication type is periodical:calibre # If None, means book 'publication_type', 'uuid', # A UUID usually of type 4 'languages', # ordered list of languages in this publication 'publisher', # Simple string, no special semantics # Absolute path to image file encoded in filesystem_encoding 'cover', # Of the form (format, data) where format is, for e.g. 'jpeg', 'png', 'gif'... 'cover_data', # Either thumbnail data, or an object with the attribute # image_path which is the path to an image file, encoded # in filesystem_encoding 'thumbnail', ]) BOOK_STRUCTURE_FIELDS = frozenset([ # These are used by code, Null values are None. 'toc', 'spine', 'guide', 'manifest', ]) USER_METADATA_FIELDS = frozenset([ # A dict of dicts similar to field_metadata. Each field description dict # also contains a value field with the key #value#. 'user_metadata', ]) DEVICE_METADATA_FIELDS = frozenset([ 'device_collections', # Ordered list of strings 'lpath', # Unicode, / separated 'size', # In bytes 'mime', # Mimetype of the book file being represented ]) CALIBRE_METADATA_FIELDS = frozenset([ 'application_id', # An application id, currently set to the db_id. 'db_id', # the calibre primary key of the item. 'formats', # list of formats (extensions) for this book # a dict of user category names, where the value is a list of item names # from the book that are in that category 'user_categories', # a dict of author to an associated hyperlink 1.9. Cursillos 203

208 'author_link_map', ) ] ALL_METADATA_FIELDS = SOCIAL_METADATA_FIELDS.union( PUBLICATION_METADATA_FIELDS).union( BOOK_STRUCTURE_FIELDS).union( USER_METADATA_FIELDS).union( DEVICE_METADATA_FIELDS).union( CALIBRE_METADATA_FIELDS) # All fields except custom fields STANDARD_METADATA_FIELDS = SOCIAL_METADATA_FIELDS.union( PUBLICATION_METADATA_FIELDS).union( BOOK_STRUCTURE_FIELDS).union( DEVICE_METADATA_FIELDS).union( CALIBRE_METADATA_FIELDS) # Metadata fields that smart update must do special processing to copy. SC_FIELDS_NOT_COPIED = frozenset(['title', 'title_sort', 'authors', 'author_sort', 'author_sort_map', 'cover_data', 'tags', 'languages', 'identifiers']) # Metadata fields that smart update should copy only if the source is not None SC_FIELDS_COPY_NOT_NULL = frozenset(['lpath', 'size', 'comments', 'thumbnail']) # Metadata fields that smart update should copy without special handling SC_COPYABLE_FIELDS = SOCIAL_METADATA_FIELDS.union( PUBLICATION_METADATA_FIELDS).union( BOOK_STRUCTURE_FIELDS).union( DEVICE_METADATA_FIELDS).union( CALIBRE_METADATA_FIELDS) - \ SC_FIELDS_NOT_COPIED.union( SC_FIELDS_COPY_NOT_NULL) SERIALIZABLE_FIELDS = SOCIAL_METADATA_FIELDS.union( USER_METADATA_FIELDS).union( PUBLICATION_METADATA_FIELDS).union( CALIBRE_METADATA_FIELDS).union( DEVICE_METADATA_FIELDS) - \ frozenset(['device_collections', 'formats', 'cover_data']) # these are rebuilt when needed Todo acerca de cómo utilizar expresiones regulares en calibre Las expresiones regulares son funciones utilizadas en muchos lugares en calibre para llevar a cabo sofisticadas manipulaciones de contenido y metadatos de libros electrónicos. Este cursillo es una breve introducción al uso de expresiones regulares en calibre. 204 Capítulo 1. Secciones

209 Índice Primero, una advertencia y unas palabras de aliento (Página 205) Dónde puedo utilizar expresiones regulares en calibre? (Página 205) Pero qué es una expresión regular? (Página 205) Me lo puede explicar? (Página 206) No suena tan mal. Qué viene después? (Página 206) Estupendo! Esto empieza a tener sentido! (Página 206) Bien, estos caracteres especiales están muy bien, pero qué ocurre si quiero hacer coincidir un punto o un signo de interrogación? (Página 207) Y cuáles son los conjuntos más útiles? (Página 207) Pero si tengo varios textos diferentes para hacer coincidir, las cosas se complican? (Página 207) Falta algo... (Página 208) No dijo al principio que hay una manera de hacer que una expresión regular no distinga entre mayúsculas y minúsculas? (Página 208) Creo que empiezo a entender esto de las expresiones regulares... cómo las utilizo en calibre? (Página 208) Conversiones (Página 208) Añadir libros (Página 209) Modificar metadatos en masa (Página 209) Créditos (Página 210) Primero, una advertencia y unas palabras de aliento Esto, inevitablemente, va a ser un poco técnico, después de todo, las expresiones regulares son una herramienta técnica para hacer cosas técnicas. Voy a tener que usar una jerga y conceptos que pueden parecer complicados o enrevesados. Voy a tratar de explicar esos conceptos tan claramente como pueda, pero realmente no puedo hacerlo sin utilizarlos en absoluto. Dicho esto, no se desanime por la jerga según intento explicar las cosas nuevas. Y mientras que las expresiones regulares en sí pueden parecer cosa magia negra y arcana (o, siendo más prosaicos, una serie aleatoria de letras y signos sin sentido), le aseguro que no son tan complicadas. Incluso los que entienden las expresiones regulares muy bien tienen problemas para leer las más complejas, pero escribirlas no es tan difícil: se va construyendo la expresión paso a paso. Dicho esto, dé el primer paso y sígame en la madriguera. Dónde puedo utilizar expresiones regulares en calibre? Las expresiones regulares se usan en unos cuantos lugares de calibre. En buscar y sustituir en las opciones de conversión, en la detección de metadatos a partir de los nombres de archivo en los ajustes de importación y en buscar y sustituir al modificar metadatos en masa. El editor de libros de calibre también puede usar expresiones regulares para buscar y sustituir. Pero qué es una expresión regular? Una expresión regular es una manera de describir porciones de texto. Una sola expresión regular coincidir con una serie de diferentes textos. Esto es lo que hace a las expresiones regulares tan potentes: son una forma concisa de describir un número potencialmente elevado de variaciones. Nota: Aquí se habla de textos en el sentido en que se usan en los lenguajes de programación: un texto de uno o más caracteres, caracteres que incluyen caracteres reales, números, puntuacion y los llamados espacios en blanco (tabulaciones, saltos de línea, etc.). Tenga en cuenta que en general, los caracteres en mayúsculas y en minúsculas no se consideran iguales, por lo tanto «a» es diferente de «A», etc. En calibre, las expresiones regulares no distinguen mayúsculas y minúsculas en la barra de búsqueda, pero sí en las opciones de conversión. Hay una manera de hacer que las expresiones regulares no distingan nunca entre mayúsculas y minúsculas, pero hablaremos de eso más adelante. La 1.9. Cursillos 205

210 cosa se complica porque las expresiones regulares permiten variaciones en los textos con los que coinciden, de manera que una expresión pueden coincidir con varios textos, que es la causa por la mucha gente no se molesta en usarlas. Más sobre esto en un momento. Me lo puede explicar? Bueno, para eso estamos aquí. En primer lugar, éste es el concepto más importante en las expresiones regulares: Un texto por sí mismo es una expresión regular que coincide consigo mismo. Es decir, si yo quisiera encontrar el texto " Hola a todos!" utilizando una expresión regular, ésta sería Hola a todos!. Y sí, realmente es así de simple. Se dará cuenta, sin embargo, de que esto sólo coincide con el texto exacto " Hola a todos!" y no, por ejemplo, con " Hola a Todos!" u " hola a todos!" o cualquier otra variación. No suena tan mal. Qué viene después? Lo que viene después es lo bueno de verdad. Recuerda cuando dije que las expresiones regulares pueden coincidir con varios textos? Aquí se pone un poco más complicado. Digamos, como un ejercicio un poco más práctico, que un libro que quiere convertir tiene un incómodo pie de página con el número de páginas, como «Página 5 de 423». Obviamente, el número de página variará entre 1 y 423, así que deberá buscar 423 textos diferentes, no? Pues no: las expresiones regulares permiten definir conjuntos de caracteres que coinciden: para definir un conjunto, ponga todos los caracteres del conjunto entre corchetes. Así, por ejemplo, el conjunto [abc] coincidirá con los caracteres «a», «b» o «c». Los conjuntos sólo coincidirán con uno de los caracteres del conjunto. Los conjuntes «entienden» gamas de caracteres, es decir, si quisiera hacer coincidir todos los caracteres en minúsculas, tendría que utilizar el conjunto de minúsculas [a-z] y para mayúsculas o minúsculas tendría que utilizar [a-za-z], etc. Comprendido? Por lo tanto, usando la expresión Página [0-9] de 423 podrsa seleccionar las primeras 9 páginas, reduciendo así las expresiones necesarias a tres. La segunda expresión Página [0-9] [0-9] de 423 coincidirá con todos los números de página de dos dígitos, y seguro que puede adivinar cuál sería la tercera expresión. Sí, adelante, escríbala. Estupendo! Esto empieza a tener sentido! Esperaba que dijera eso. Pero prepárese, ahora se pone aún mejor! Acabamos de ver que con el uso de conjuntos, podemos detectar uno de varios caracteres a la vez. Pero incluso se puede repetir un carácter o conjunto, reduciendo el número de expresiones necesarias el ejemplo anterior de los númers de página a una. Sí, UNA! Emocionado? Debería estarlo! Funciona así: Algunos de los llamados caracteres especiales, «+», «?» y «*», repiten el elemento único que los precede. (Elemento significa un único carácter, un conjunto de caracteres, una secuencia de escape o un grupo (aprenderemos más acerca de los dos últimos más tarde), en resumen, cualquier entidad individual en una expresión regular). Estos caracteres se llaman comodines o cuantificadores. Para ser más precisos, «?» coincide con 0 o 1 copias del elemento anterior, «*» coincide con 0 o más copias del elemento anterior y «+» coincide con 1 o más copias del elemento anterior. Algunos ejemplos: La expresión a? coincidiría con (que es un texto vacío, no estrictamente útil en este caso) o «a», la expresión a* coincidiría con, «a», «aa» o cualquier número de aes seguidas, y, finalmente, la expresión a+ se coincidiría con «a», «aa» o cualquier número de aes seguidas. (Nota: no coincidiría con el texto vacío!). Lo mismo para los conjuntos. La expresión [0-9]+ coincidiría con cualquier número entero! Sé lo que está pensando, y tiene razón: si lo utiliza en el caso anterior de los números de página, no sería la forma de obtener una única expresión que coincida con todos los números de página? Sí, la expresión Página [0-9]+ de 423 coincidiría con cualquier número de página de ese libro! Nota: Un apunte sobre estos cuantificadores: Generalmente intentan hacer coincidir tanto como sea posible, así que tenga cuidado al usarlos. Esto se conoce como «comportamiento codicioso», seguro que entiende por qué. Se vuelve problemático cuando, por ejemplo, se intenta hacer coincidir una etiqueta. Consideremos, por ejemplo, el texto "<p class="calibre2">título aquí</p>" y digamos que le gustaría hacer coincidir la etiqueta de apertura (la parte entre el primer par de ángulos, veremos más sobre las etiquetas más adelante). Se podría pensar que la expresión <p.*> se correspondería con esa etiqueta, pero en realidad coincide con todo el texto! (El carácter «.» es otro carácter 206 Capítulo 1. Secciones

211 especial, coincide con cualquier cosa excepto saltos de línea, por lo que, básicamente, la expresión.* coincide con cualquier línea que se pueda imaginar). En lugar de eso, trate de usar <p.*?>, lo que hace que el cuantificador «*» no codicioso. Esa expresión sólo coincidiría con la primera etiqueta de apertura, como se pretende. De hecho, hay otra manera de lograr esto. La expresión <p[^>]*> coincidirá con la misma etiqueta de apertura, ya verá por qué después de la siguiente sección. Tenga en cuenta que frecuentemente hay más de una manera de escribir una expresión regular. Bien, estos caracteres especiales están muy bien, pero qué ocurre si quiero hacer coincidir un punto o un signo de interrogación? Por supuesto que puede hacerlo: simplemente escriba una barra invertida delante de cualquier carácter especial y se interpretará como un carácter literal, sin ningún significado especial. Esta pareja de barra invertida y un carácter se llama secuencia de escape, y el acto de poner una barra invertida delante de un carácter especial se llama escapar ese carácter. Una secuencia de escape se interpreta como un solo elemento. Hay, por supuesto, secuencias de escape que hacen más que sólo escapar caracteres especiales, por ejemplo "\t" representa una tabulación. Vamos a ver algunas de las secuencias de escape más adelante. Ah, por cierto, en relación con esos caracteres especiales: considere que cualquier carácter que señalemos en esta introducción como poseedor de alguna función es especial y por lo tanto necesita ser escapado si desea que sea un carácter literal. Y cuáles son los conjuntos más útiles? Sabía que lo preguntaría. Algunos conjuntos útiles son [0-9], que coincide con un solo dígintoo, [a-z], que coincide con una sola letra minúscula, [A-Z], que coincide con una sola letra mayúscula, [a-za-z], que coincide con una sola letra, y [a-za-z0-9], que coincide con una sola letra o número. También puede utilizar una secuencia de escape como abreviatura: \d is equivalent to [0-9] \w is equivalent to [a-za-z0-9_] \s is equivalent to any whitespace Nota: Espacios en blanco es un término para cualquier cosa que no se imprime. Estos caracteres incluyen el espacio, tabulador, avance de línea, salto de página y retorno de carro. Como último apunte sobre los conjuntos, también puede definir un conjunto como cualquier carácter excepto los especificados. Esto se hace incluyendo el carácter "^" como el primer carácter en el conjunto. Así, [^a] coincidirá con cualquier carácter excepto «a». Esto se llama complementar el conjunto. Las secuencias de escape anteriores que funcionan como abreviaturas también pueden complementarse. "\D" significa cualquier carácter que no sea un número, siendo por lo tanto equivalente a [^0-9]. Las otras abreviaturas se pueden complementar, como puede imaginar, utilizando la respectiva letra mayúscula en lugar de la minúscula. Volviendo al ejemplo <p[^>]*> de la sección anterior, ahora se puede ver que el conjunto especificado trata de coincidir con cualquier carácter excepto el ángulo de cierre. Pero si tengo varios textos diferentes para hacer coincidir, las cosas se complican? No tema, todo sigue siendo bueno y fácil. Considere este ejemplo: El libro que quiere convirtir tiene un «Título» escrito en cada página impar y «Autor» en cada página par. Queda muy bien en la versión impresa, no? Pero en libros electrónicos es molesto. Puede agrupar expresiones enteras en paréntesis normales, y el carácter " " hará que coincida la expresión a la derecha o la de la izquierda. Combínelas y ya está. Demasiado rápido? Bueno, en primer lugar, agrupamos las expresiones para páginas pares e impares, consiguiendo de este modo (Título)(Autor) como nuestras dos expresiones necesarias. Ahora hacemos las cosas más simples mediante el uso de la barra vertical (" " se llama barra vertical). Si utiliza la expresión (Título Autor) hará coincidir «Título» (en las páginas impares) o «Autor» (en las páginas pares). Bueno, no ha sido fácil? 1.9. Cursillos 207

212 También puede, por supuesto, usar la barra vertical sin utilizar paréntesis de agrupamiento. Recuerda cuando dije que los cuantificadores repiten el elemento que los precede? Pues bien, la barra vertical funciona de manera un poco diferente. La expresión Título Autor también coincide con el texto «Título» o el texto «Autor», igual que el ejemplo anterior utilizando agrupamiento. La barra vertical selecciona entre toda la expresión anterior y toda la posterior. Así que, si quiere que coincidan los textos «Calibre» y «calibre» y quiere seleccionar sólo entre la «c» mayúscula y minúscula, tendría que utilizar la expresión (c C)alibre, donde el agrupamiento asegura que sólo la «c» se selecciona. Si usara c Calibre, obtendría coincidencias con el texto «c» o el texto «Calibre», que no es lo que quería. En resumen: en caso de duda, utilice el agrupamiento con la barra vertical. Falta algo......espere un momento, hay una última cosa muy interesante que se puede hacer con los grupos. Si tiene un grupo que previamente ha hecho coincidir, puede utilizar referencias a ese grupo posteriormente en la expresión. Los grupos se numeran comenzando por 1, y se referencian escapando el número del grupo, por ejemplo, al quinto grupo se haría referencia como \5. Así, aplicando ([^ ]+) \1 sobre el texto «Prueba Prueba», se haría coincidir todo el texto! No dijo al principio que hay una manera de hacer que una expresión regular no distinga entre mayúsculas y minúsculas? Sí, lo hice, gracias por prestar atención y recordármelo. Puede decirle a calibre cómo desea ciertas cosas se comporten mediante el uso de opciones. Las opciones se incluyen en una expresión mediante la construcción especial (?aquí van las opciones), donde, obviamente, debe sustituir «aquí van las opciones» por las opciones específicas que desee. Para no distinguir mayúsculas y minúsculas, la opción es i, así que incluya (?i) en la expresión. Por lo tanto, prueba(?i) coincidiría con «Prueba», «prueba», «PRueba» y cualquier variación en las mayúsculas y minúsculas que pueda imaginar. Otra opción útil hace que el punto coincida con absolutamente cualquier carácter, incluyendo el salto de línea, la opción s. Si desea utilizar varias opciones en una expresión, sólo hay que ponerlas en la misma declaración: (?is) no distingue entr mayúsculas y minúsculas y hace que el punto coincida con todo. No importa qué opción se declara en primer lugar, (?si) sería equivalente a la anterior. Por cierto, es buena idea poner las opciones al principio o al final de la expresión, de esta manera no se mezclan con cualquier otra cosa. Creo que empiezo a entender esto de las expresiones regulares... cómo las utilizo en calibre? Conversiones Vamos a empezar con las configuraciones de conversión. En la sección Buscar y sustituir, puede introducir una regexp (abreviatura de expresión regular) que describe el texto que se sustituirá durante la conversión. La parte interesante es el asistente. Pulse en la varita mágica y obtendrá una vista previa de lo que calibre «ve» durante el proceso de conversión. Vaya al texto que desea eliminar, selecciónelo y cópielo, péguelo en el campo de expresión regular en la parte superior de la ventana. Si hay partes variables, como números de página o algo así, use conjuntos y cuantificadores para recogerlos, y ya que está en ello, recuerde que debe escapar los caracteres especiales, si hay alguno. Pulse el botón con la etiqueta Probar y calibre resaltará las partes que sustituiría al utilizar la expresión regular. Una vez que esté satisfecho, pulse «Aceptar» y se inicia el proceso de conversión. Tenga cuidado si el origen de la conversión tiene etiquetas como este ejemplo: Maybe, but the cops feel like you do, Anita. What's one more dead vampire? New laws don't change that. </p> <p class="calibre4"> <b class="calibre2">generated by ABC Amber LIT Conv <a href=" class="calibre3">erter, <p class="calibre4"> It had only been two years since Addison v. Clark. The court case gave us a revised version of what life was 208 Capítulo 1. Secciones

213 (copiado descaradamente de este hilo 95 ). Habría que eliminar también algunas de las etiquetas. En este ejemplo, recomendaría empezar con la etiqueta <b class="calibre2">, tiene que acabar con la etiqueta de cierre correspondiente (las etiquetas de apertura son <etiqueta>, las etiquetas de cierre son </etiqueta>), que es simplemente el siguiente </b> en este caso. (Consulte un buen manual de HTML o pregunte en el foro si tiene dudas sobre este punto). La etiqueta de apertura puede describirse usando <b.*?>, la etiqueta de cierre usando </b>, por lo que podríamos quitar todo lo que está entre estas etiquetas usando <b.*?>.*?</b>. Pero usar esta expresión sería una mala idea, ya que elimina todo lo encerrado entre las etiquetas <b> (que, por cierto, hacen que el texto encerrado se muestre en negrita), y es casi seguro que eliminaremos porciones del libro de esta manera. En su lugar, incluya también el principio del texto entre las etiquetas, haciendo la expresión regular <b.*?>\s*generated\s+by\s+abc\s+amber\s+lit.*?</b>. La \s con cuantificadores se incluye aquí en lugar de utilizar explícitamente los espacios que aparecen en el texto para recoger cualquier variación del texto que pudiera ocurrir. Si prueba una nueva expresión, recuerde revisar qué eliminará calibre para asegurarse de que no elimina partes que desea conservar. Si sólo examina un caso, es posible que pase por alto un desajuste en otro lugar del texto. También tenga en cuenta que en caso de que accidentalmente elimine más o menos etiquetas de las que realmente deseaba, calibre intenta reparar el código dañado después de hacer la eliminación. Añadir libros También puede utilizar expresiones regulares para extraer metadatos de los nombres de archivo. Puede encontrar esta función en la sección «Añadir libros» de la configuración. Hay una característica especial: puede utilizar nombres de campo para los campos de metadatos, por ejemplo (?P<title>), que indicaría que calibre utiliza esta parte del texto como el título del libro. Los nombres de los campos permitidos se enumeran en las ventanas, junto con otro útil campo de prueba. Un ejemplo: digamos que desea importar un gran número de archivos llamados así Textos clásicos: La divina comedia de Dante Alighieri.mobi (obviamente, ya lo tiene en la biblioteca, ya que a todos nos gusta la poesía italiana clásica) o Ciencia ficción épica: La Trilogía de la Fundación de Isaac Asimov.epub. Esto es obviamente un esquema de nombres del que calibre no va a extraer datos significativos: la expresión estándar para la extracción de los metadatos es (?P<titulo>.+) - (?P<autor>[^_]+). Una expresión regular que podría funcionar en este caso sería [a-za-z]+: (?P<titulo>.+) de (?P<autor>.+). Tenga en cuenta que, dentro del grupo para el campo de metadatos, es necesario utilizar expresiones para describir lo que el campo realmente recoge. Y también tenga en cuenta que, cuando se utiliza el campo de prueba que calibre ofrece, es necesario agregar la extensión de archivo al nombre de archivo de prueba, de lo contrario no recibirá ninguna correspondencia en absoluto, a pesar de utilizar una expresión correcta. Modificar metadatos en masa La última parte es la búsqueda y sustitución con expresiones regulares en los campos de metadatos. Puede acceder a esta función seleccionando varios libros en la biblioteca y usando la modificación de metadatos en masa. Tenga mucho cuidado al utilizar esta última función, ya que puede hacer cosas muy malas en la biblioteca! Verifique que las expresiones hacen lo que quiere que hagan en los campos de prueba, y sólo marque los libros que realmente quiere cambiar. En el modo de búsqueda de expresione regulare, puede buscar en un campo, sustituir el texto con algo e incluso escribir el resultado en otro campo. Un ejemplo práctico: Digamos que la biblioteca contiene los libros de la serie Dune de Frank Herbert, nombrados de este modo Dune 1 - Dune, Dune 2 - El mesías de Dune y así sucesivamente. Ahora desea incluir Dune en el campo serie. Puede hacerlo mediante la búsqueda (.*?) \d+ -.* en el campo título y sustituyendo con \1 en el campo serie. Ve lo que he hecho? Esto es una referencia al primer grupo que está de coincidencia en la expresión regular. Ahora que tiene toda la serie lista, sólo tiene que hacer otra búsqueda.*? - en el campo título y reemplazarlo con "" (un texto vacío), de nuevo en el campo título, y los metadatos estarán todos limpios y ordenados. No es genial? Por cierto, en lugar de sustituir todo el campo, puede también añadir al principio o al final del campo, por lo que, si quisiera el título del libro con la información de la serie delante, puede hacerlo también. Como sin duda se ha dado cuenta, hay una casilla etiquetada Distinguir mayúsculas, para que no tenga que usar la opción correspondiente dentro de la expresión regular en este caso Cursillos 209

214 Y con esto concluye la breve introduccion a las expresiones regulares. Espero haberle enseñado lo suficiente para que pueda empezar a trabajar y aprender por su cuenta. Un buen punto de partida sería la documentación de Python para expresiones regulares 96 (en inglés). Una última palabra de advertencia: las expresiones regulares son potentes, pero también es muy fácil equivocarse. calibre ofrece muy buenas posibilidades de pruebas para ver si las expresiones se comportan como se espera que lo hagan. Úselas. Intente no dispararse los pies (me encanta esta expresión...). Pero si, a pesar de la advertencia, se lesiona el pie (o cualquier otra parte del cuerpo), trate de aprender de ello. Créditos Gracias por ayudar con sugerencias, correcciones y demás: ldolse kovidgoyal chaley dwanthny kacir Starson17 Para saber más acerca de expresiones regulares, vea el manual de usario de Python 97 (en inglés) Integrar el servidor de contenidos de calibre en otros servidores Aquí, le mostraremos cómo integrar el servidor de contenidos de calibre en otro servidor. La razón más común para esto es hacer uso de SSL u otro tipo de autenticación más sofisticado. Existen dos técnicas principales: ejecutar el servidor de contenido calibre como un proceso independiente y utilizando un proxy inverso para conectar con el servidor principal, o ejecutar el servidor de contenido como un proceso en el servidor principal con WSGI. Los siguientes ejemplos son para Apache 2.x sobre linux, pero deberían ser fácilmente adaptables a otras plataformas. Índice Usar un proxy inverso (Página 210) En proceso (Página 211) Nota: Esto sólo se aplica a versiones de calibre >= Usar un proxy inverso Un proxy inverso es cuando el servidor principal acepta peticiones entrantes y las traslada al servidor de calibre. A continuación, lee la respuesta desde el servidor de calibre y la envía al cliente. Esto significa que sólo tiene que ejecutar el servidor de calibre de forma normal sin tratar de integrarlo estrechamente con el servidor principal y aprovechar cualquier sistema de autenticación que posea el servidor principal. Éste es el método más sencillo, ya que le permite usar la instalación de binaria de calibre sin dependencias externas o requisitos de integración en el sistema. A continuación se muestra un ejemplo de cómo lograr esto con Apache como servidor principal, pero funcionará con cualquier servidor compatible con servidores proxy inversos Capítulo 1. Secciones

215 Primero active el servidor de contenidos de calibre como se muestra a continuación: calibre-server --url-prefix /calibre --port 8080 El parámetro clave aquí es --url-prefix /calibre. Esto hace que el servidor de contenidos sirva todos los URL con el prefijo calibre. Para verlo en acción, visite en su navegador. Debería ver la página web habitual del servidor de contenido, pero ahora se ejecutará desde /calibre. Supongamos ahora que Apache es el servidor principal. En primer lugar, habilite los módulos de proxy en Apache, añadiendo lo siguiente a httpd.conf: LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_http_module modules/mod_proxy_http.so La técnica exacta para habilitar los módulos proxy variará según la instalación de Apache. Una vez que tenga los módulos proxy habilitados, agregue las siguientes reglas a httpd.conf (o, si está usando servidores virtuales, al archivo conf del servidor virtual en cuestión): RewriteEngine on RewriteRule ^/calibre/(.*) [proxy] RewriteRule ^/calibre [proxy] SetEnv force-proxy-request SetEnv proxy-nokeepalive 1 Eso es todo, ahora podrá acceder al servidor de contenidos de calibre bajo el URL /calibre en su servidor Apache. Las reglas anteriores pasan todas las peticiones bajo /calibre al servidor de calibre que se ejecuta en el puerto 8080 y gracias a la opción --url-prefix mencionada anteriormente, el servidor de calibre las gestiona de forma transparente. Nota: Si está dispuesto a dedicar todo un VirtualHost para el servidor de contenidos, entonces no hay necesidad de utilizar --url-prefix y RewriteRule, simplemente use la directiva ProxyPass. Nota: El motor del servidor que usa calibre, CherryPy, puede tener problemas cuando se utilizan proxys y peticiones KeepAlive, así que desactívelos en Apache, con las directivas SetEnv que se muestran arriba. En proceso El servidor de contenidos de calibre se puede ejecutar directamente, en proceso, dentro de un servidor anfitrión como Apache utilizando el marco WSGI. Nota: Para que esto funcione, todas las dependencias requeridas por calibre deben estar instaladas en el sistema. Conseguir esto no es en absoluto trivial, y se aconseja no usar servidores en proceso. No se proporcionará ninguna ayuda para depurar problemas relacionados con servidores en proceso. Primero, debemos crear un adaptador WSGI para el servidor de contenidos de calibre. Aquí hay una plantilla que puede utilizar para dicho propósito. Reemplace las rutas de acceso como se indica en los comentarios. # WSGI script file to run calibre content server as a WSGI app import sys, os # You can get the paths referenced here by running # calibre-debug --paths # on your server # The first entry from CALIBRE_PYTHON_PATH 1.9. Cursillos 211

216 sys.path.insert(0, '/home/kovid/work/calibre/src') # CALIBRE_RESOURCES_PATH sys.resources_location = '/home/kovid/work/calibre/resources' # CALIBRE_EXTENSIONS_PATH sys.extensions_location = '/home/kovid/work/calibre/src/calibre/plugins' # Path to directory containing calibre executables sys.executables_location = '/usr/bin' # Path to a directory for which the server has read/write permissions # calibre config will be stored here os.environ['calibre_config_directory'] = '/var/www/localhost/calibre-config' del sys del os from calibre.library.server.main import create_wsgi_app application = create_wsgi_app( # The mount point of this WSGI application (i.e. the first argument to # the WSGIScriptAlias directive). Set to empty string is mounted at / prefix='/calibre', # Path to the calibre library to be served # The server process must have write permission for all files/dirs # in this directory or BAD things will happen path_to_library='/home/kovid/documents/demo library', ) # The virtual library (restriction) to be used when serving this # library. virtual_library=none del create_wsgi_app Guarde este adaptador como calibre-wsgi-adapter.py en algún lugar al que el servidor tenga acceso. Supongamos que queremos usar WSGI en Apache. En primer lugar, habilite WSGI en Apache añadiendo lo siguiente a httpd.conf: LoadModule wsgi_module modules/mod_wsgi.so La técnica exacta para habilitar el módulo WSGI variará según la instalación de Apache. Una vez que tenga los módulos proxy habilitados, agregue las siguientes reglas a httpd.conf (o, si está usando servidores virtuales, en el archivo conf para el servidor virtual en cuestión): WSGIScriptAlias /calibre /var/www/localhost/cgi-bin/calibre-wsgi-adapter.py Cambie la ruta de calibre-wsgi-adapter.py a la ubicación donde lo haya guardado previamente (asegúrese de que Apache tenga acceso). Eso es todo, ahora podrá acceder al servidor de contenidos de calibre bajo la dirección /calibre en su servidor Apache. Nota: Para más ayuda en el uso de mod_wsgi en Apache, vea mod_wsgi 98 (en inglés) Capítulo 1. Secciones

217 1.9.7 Escribir sus propios complementos para extender la funcionalidad de calibre calibre tiene un diseño muy modular. Casi todas las funciones de calibre vienen en forma de complementos. Los complementos se utilizan para la conversión, para la descarga de noticias (aunque éstos se llaman fórmulas), para diversos componentes de la interfaz de usuario, para conectarse a diferentes dispositivos, para procesar archivos cuando se añaden a calibre, etcétera. Puede obtener una lista completa de todos los complementos integrados en calibre en Preferencias > Complementos. Aquí le enseñaremos como crear sus propios complementos para agregar funciones a calibre. Índice Anatomía de un complemento de calibre (Página 213) Un complemento de interfaz de usuario (Página 214) init.py (Página 215) ui.py (Página 216) main.py (Página 217) Obtener recursos del archivo zip del complemento (Página 220) Habilitar la configuración de usuario para el complemento (Página 220) Complementos para modificar libros (Página 222) main.py (Página 223) Añadir traducciones al complemento (Página 225) La API del complemento (Página 226) Depurar complementos (Página 226) Más ejemplos de complementos (Página 226) Compartir sus complementos con otros (Página 226) Nota: Esto sólo se aplica a versiones calibre >= Anatomía de un complemento de calibre Un complemento de calibre es muy sencillo, no es más que un archivo zip que contiene algo de código python y otros recursos, como archivos de imagen, que necesite el complemento. Sin más preámbulos, vamos a ver un ejemplo básico. Supongamos que está usando una instalación de calibre publicar sus propios documentos electrónicos en formatos EPUB y MOBI. Le gustaría que todos los archivos generados por calibre establecieran la editorial como «Hello World», he aquí cómo hacerlo. Cree un archivo llamado init.py (éste es un nombre especial y siempre debe ser el del archivo principal del complemento) e introduzca el siguiente código Python en él: import os from calibre.customize import FileTypePlugin class HelloWorld(FileTypePlugin): name = 'Hello World Plugin' # Name of the plugin description = 'Set the publisher to Hello World for all new conversions' supported_platforms = ['windows', 'osx', 'linux'] # Platforms this plugin will run on author = 'Acme Inc.' # The author of this plugin version = (1, 0, 0) # The version number of this plugin file_types = set(['epub', 'mobi']) # The file types that this plugin will be applied to on_postprocess = True # Run this plugin after conversion is complete minimum_calibre_version = (0, 7, 53) 1.9. Cursillos 213

218 def run(self, path_to_ebook): from calibre.ebooks.metadata.meta import get_metadata, set_metadata file = open(path_to_ebook, 'r+b') ext = os.path.splitext(path_to_ebook)[-1][1:].lower() mi = get_metadata(file, ext) mi.publisher = 'Hello World' set_metadata(file, mi, ext) return path_to_ebook Eso es todo. Para agregar este código a calibre como un complemento, simplemente ejecute lo siguiente en el directorio donde reside el archivo init.py: calibre-customize -b. Nota: En OS X, las herramientas de línea de órdenes están dentro del paquete calibre, por ejemplo, si ha instalado calibre en /Aplicaciones las herramientas de línea de órdenes están en /Aplicaciones/calibre.app/Contents/console.app/Contents/MacOS Puede descargar el complemento Hello World en helloworld_plugin.zip 99. Cada vez que utilice calibre para convertir un libro, el método run() del complemento se ejecutará y el libro convertido tendrá como editorial predeterminada «Hello World». Éste es un complemento intranscendente, veamos un ejemplo más complejo que agrega un componente a la interfaz de usuario. Un complemento de interfaz de usuario Este complemento ocupará unos pocos archivos (para mantener el código más limpio). Le mostrará cómo obtener recursos (imágenes o archivos de datos) desde el archivo zip del complemento, cómo permitir a los usuarios configurar el complemento, cómo crear elementos en la interfaz de usuario de calibre y cómo acceder y consultar la base de datos de libros de calibre. Puede descargar este complemento desde interface_demo_plugin.zip 100 Lo primero que hay que tener en cuenta es que este archivo zip tiene muchos más archivos en su interior, explicados a continuación, preste especial atención a plugin-import-name-interface_demo.txt. plugin-import-name-interface_demo.txt Un archivo de texto vacío utilizado para activar la gestión de múltiples archivos en el complemento. Este archivo debe estar presente en todos los complementos que utilicen más de un archivo.py. Debe quedar vacío y su nombre debe ser de la forma: pluginimport-name-some_name.txt. La presencia de este archivo le permite importar código de los archivos.py presentes dentro del archivo zip, usando una sentencia como ésta: from calibre_plugins.some_name.some_module import some_object El prefijo calibre_plugins siempre debe estar presente. some_name proviene del nombre del archivo de texto vacío. some_module se refiere al archivo some_module.py dentro del archivo zip. Tenga en cuenta que esta importación es tan potente como las importaciones normales en python. Puede crear paquetes y subpaquetes de módulos.py dentro del archivo zip, igual que lo haría normalmente (definiendo init.py en cada subdirectorio), y todo debería funcionar. El nombre que utilice para some_name entra en un espacio global de nombres compartido por todos los complementos, así que hágalo tan único como sea posible. Pero recuerde que debe ser un identificador python válido (sólo letras, números y guión bajo). init.py Como antes, el archivo que define la clase del complemento Capítulo 1. Secciones

219 main.py Este archivo contiene el código real que realiza alguna operación útil ui.py Este archivo define la interfaz del complemento images/icon.png El icono para este complemento about.txt Un archivo de texto con información acerca de este complemento translations Una carpeta que contiene archivos.mo con las traducciones de la interfaz de usuario del complemento a diferentes idiomas. Ver más adelante para más detalles. Ahora veamos el código. init.py Primero, el init.py obligatorio para definir los metadatos del complemento: # The class that all Interface Action plugin wrappers must inherit from from calibre.customize import InterfaceActionBase class InterfacePluginDemo(InterfaceActionBase): ''' This class is a simple wrapper that provides information about the actual plugin class. The actual interface plugin class is called InterfacePlugin and is defined in the ui.py file, as specified in the actual_plugin field below. The reason for having two classes is that it allows the command line calibre utilities to run without needing to load the GUI libraries. ''' name = 'Interface Plugin Demo' description = 'An advanced plugin demo' supported_platforms = ['windows', 'osx', 'linux'] author = 'Kovid Goyal' version = (1, 0, 0) minimum_calibre_version = (0, 7, 53) #: This field defines the GUI plugin class that contains all the code #: that actually does something. Its format is module_path:class_name #: The specified class must be defined in the specified module. actual_plugin = 'calibre_plugins.interface_demo.ui:interfaceplugin' def is_customizable(self): ''' This method must return True to enable customization via Preferences->Plugins ''' return True def config_widget(self): ''' Implement this method and :meth:`save_settings` in your plugin to use a custom configuration dialog. This method, if implemented, must return a QWidget. The widget can have an optional method validate() that takes no arguments and is called immediately after the user clicks OK. Changes are applied if and only if the method returns True Cursillos 215

220 If for some reason you cannot perform the configuration at this time, return a tuple of two strings (message, details), these will be displayed as a warning dialog to the user and the process will be aborted. The base class implementation of this method raises NotImplementedError so by default no user configuration is possible. ''' # It is important to put this import statement here rather than at the # top of the module as importing the config class will also cause the # GUI libraries to be loaded, which we do not want when using calibre # from the command line from calibre_plugins.interface_demo.config import ConfigWidget return ConfigWidget() def save_settings(self, config_widget): ''' Save the settings specified by the user with config_widget. :param config_widget: The widget returned by :meth:`config_widget`. ''' config_widget.save_settings() # Apply the changes ac = self.actual_plugin_ if ac is not None: ac.apply_settings() La única característica notable es el campo actual_plugin. Puesto que calibre posee tanto una interfaz gráfica como de línea de órdenes, los complementos con interfaz gráfica como éste no cargan ninguna biblioteca gráfica en init.py. El campo actual_plugin se encargad de esto, informando a calibre de que el complemento real se encuentra en otro archivo dentro del archivo zip, que sólo se cargará en un contexto de interfaz gráfica. Recuerde que para que esto funcione, debe tener un archivo plugin-import-name-some_name.txt en el archivo zip del complemento, como se discutió anteriormente. También hay un par de métodos para permitir la configuración por parte del usuario del complemento. Éstos se discuten más adelante. ui.py Veamos ahora ui.py, que define la interfaz gráfica del complemento. El código fuente está explícitamente comentado y se explica por sí mismo: # The class that all interface action plugins must inherit from from calibre.gui2.actions import InterfaceAction from calibre_plugins.interface_demo.main import DemoDialog class InterfacePlugin(InterfaceAction): name = 'Interface Plugin Demo' # Declare the main action associated with this plugin # The keyboard shortcut can be None if you dont want to use a keyboard # shortcut. Remember that currently calibre has no central management for # keyboard shortcuts, so try to use an unusual/unused shortcut. action_spec = ('Interface Plugin Demo', None, 216 Capítulo 1. Secciones

221 'Run the Interface Plugin Demo', 'Ctrl+Shift+F1') def genesis(self): # This method is called once per plugin, do initial setup here # Set the icon for this interface action # The get_icons function is a builtin function defined for all your # plugin code. It loads icons from the plugin zip file. It returns # QIcon objects, if you want the actual data, use the analogous # get_resources builtin function. # # Note that if you are loading more than one icon, for performance, you # should pass a list of names to get_icons. In this case, get_icons # will return a dictionary mapping names to QIcons. Names that # are not found in the zip file will result in null QIcons. icon = get_icons('images/icon.png') # The qaction is automatically created from the action_spec defined # above self.qaction.seticon(icon) self.qaction.triggered.connect(self.show_dialog) def show_dialog(self): # The base plugin object defined in init.py base_plugin_object = self.interface_action_base_plugin # Show the config dialog # The config dialog can also be shown from within # Preferences->Plugins, which is why the do_user_config # method is defined on the base plugin class do_user_config = base_plugin_object.do_user_config # self.gui is the main calibre GUI. It acts as the gateway to access # all the elements of the calibre user interface, it should also be the # parent of the dialog d = DemoDialog(self.gui, self.qaction.icon(), do_user_config) d.show() def apply_settings(self): from calibre_plugins.interface_demo.config import prefs # In an actual non trivial plugin, you would probably need to # do something based on the settings in prefs prefs main.py El código que implementa el cuadro de diálogo «Interface Plugin Demo». from PyQt5.Qt import QDialog, QVBoxLayout, QPushButton, QMessageBox, QLabel from calibre_plugins.interface_demo.config import prefs class DemoDialog(QDialog): def init (self, gui, icon, do_user_config): QDialog. init (self, gui) self.gui = gui self.do_user_config = do_user_config 1.9. Cursillos 217

222 # The current database shown in the GUI # db is an instance of the class LibraryDatabase2 from database.py # This class has many, many methods that allow you to do a lot of # things. self.db = gui.current_db self.l = QVBoxLayout() self.setlayout(self.l) self.label = QLabel(prefs['hello_world_msg']) self.l.addwidget(self.label) self.setwindowtitle('interface Plugin Demo') self.setwindowicon(icon) self.about_button = QPushButton('About', self) self.about_button.clicked.connect(self.about) self.l.addwidget(self.about_button) self.marked_button = QPushButton( 'Show books with only one format in the calibre GUI', self) self.marked_button.clicked.connect(self.marked) self.l.addwidget(self.marked_button) self.view_button = QPushButton( 'View the most recently added book', self) self.view_button.clicked.connect(self.view) self.l.addwidget(self.view_button) self.update_metadata_button = QPushButton( 'Update metadata in a book\'s files', self) self.update_metadata_button.clicked.connect(self.update_metadata) self.l.addwidget(self.update_metadata_button) self.conf_button = QPushButton( 'Configure this plugin', self) self.conf_button.clicked.connect(self.config) self.l.addwidget(self.conf_button) self.resize(self.sizehint()) def about(self): # Get the about text from a file inside the plugin zip file # The get_resources function is a builtin function defined for all your # plugin code. It loads files from the plugin zip file. It returns # the bytes from the specified file. # # Note that if you are loading more than one file, for performance, you # should pass a list of names to get_resources. In this case, # get_resources will return a dictionary mapping names to bytes. Names that # are not found in the zip file will not be in the returned dictionary. text = get_resources('about.txt') QMessageBox.about(self, 'About the Interface Plugin Demo', text.decode('utf-8')) def marked(self): ''' Show books with only one format ''' fmt_idx = self.db.field_map['formats'] 218 Capítulo 1. Secciones

223 matched_ids = set() for record in self.db.data.iterall(): # Iterate over all records fmts = record[fmt_idx] # fmts is either None or a comma separated list of formats if fmts and ',' not in fmts: matched_ids.add(record[0]) # Mark the records with the matching ids self.db.set_marked_ids(matched_ids) # Tell the GUI to search for all marked records self.gui.search.setedittext('marked:true') self.gui.search.do_search() def view(self): ''' View the most recently added book ''' most_recent = most_recent_id = None timestamp_idx = self.db.field_map['timestamp'] for record in self.db.data: # Iterate over all currently showing records timestamp = record[timestamp_idx] if most_recent is None or timestamp > most_recent: most_recent = timestamp most_recent_id = record[0] if most_recent_id is not None: # Get the row number of the id as shown in the GUI row_number = self.db.row(most_recent_id) # Get a reference to the View plugin view_plugin = self.gui.iactions['view'] # Ask the view plugin to launch the viewer for row_number view_plugin._view_books([row_number]) def update_metadata(self): ''' Set the metadata in the files in the selected book's record to match the current metadata in the database. ''' from calibre.ebooks.metadata.meta import set_metadata from calibre.gui2 import error_dialog, info_dialog # Get currently selected books rows = self.gui.library_view.selectionmodel().selectedrows() if not rows or len(rows) == 0: return error_dialog(self.gui, 'Cannot update metadata', 'No books selected', show=true) # Map the rows to book ids ids = list(map(self.gui.library_view.model().id, rows)) for book_id in ids: # Get the current metadata for this book from the db mi = self.db.get_metadata(book_id, index_is_id=true, get_cover=true, cover_as_data=true) fmts = self.db.formats(book_id, index_is_id=true) if not fmts: continue for fmt in fmts.split(','): fmt = fmt.lower() 1.9. Cursillos 219

224 # Get a python file object for the format. This will be either # an in memory file or a temporary on disk file ffile = self.db.format(book_id, fmt, index_is_id=true, as_file=true) # Set metadata in the format set_metadata(ffile, mi, fmt) ffile.seek(0) # Now replace the file in the calibre library with the updated # file. We dont use add_format_with_hooks as the hooks were # already run when the file was first added to calibre. ffile.name = 'xxx' # add_format() will not work if the file # path of the file being added is the same # as the path of the file being replaced self.db.add_format(book_id, fmt, ffile, index_is_id=true) info_dialog(self, 'Updated files', 'Updated the metadata in the files of %d book(s)'%len(ids), show=true) def config(self): self.do_user_config(parent=self) # Apply the changes self.label.settext(prefs['hello_world_msg']) Obtener recursos del archivo zip del complemento El sistema de carga de complementos de calibre tiene predefinidas un par de funciones que permiten obtener archivos desde el archivo zip del complemento de manera práctica. get_resources(nombre_o_lista_de_nombres) Esta función debe ejecutarse con una lista de rutas de acceso a archivos dentro del archivo zip. Por ejemplo, para acceder al archivo icon.png en la images del archivo zip, utilizaría: images/icon.png. Use siempre una barra inclinada a la derecha como separador de ruta, incluso en windows. Cuando se pasa un solo nombre, la función devolverá los bytes en bruto de ese archivo o None si el nombre no se encuentra en el archivo zip. Si se pasa más de un nombre, entonces devuelve un diccionario de mapeo de nombres a bytes. Si no se encuentra un nombre, no estará presente en el diccionario devuelto. get_icons(nombre_o_lista_de_nombres) Una envoltura práctica para get_resources() que crea objetos QIcon a partir de los bytes devueltos por get_resources. Si un nombre no se encuentra en el archivo zip, el QIcon correspondiente será nulo. Habilitar la configuración de usuario para el complemento Para permitir a los usuarios configurar el complemento, debe definir tres métodos en la clase base del complemento, is_customizable, config_widget y save_settings como se muestra a continuación: def is_customizable(self): ''' This method must return True to enable customization via Preferences->Plugins ''' return True def config_widget(self): ''' 220 Capítulo 1. Secciones

225 Implement this method and :meth:`save_settings` in your plugin to use a custom configuration dialog. This method, if implemented, must return a QWidget. The widget can have an optional method validate() that takes no arguments and is called immediately after the user clicks OK. Changes are applied if and only if the method returns True. If for some reason you cannot perform the configuration at this time, return a tuple of two strings (message, details), these will be displayed as a warning dialog to the user and the process will be aborted. The base class implementation of this method raises NotImplementedError so by default no user configuration is possible. ''' # It is important to put this import statement here rather than at the # top of the module as importing the config class will also cause the # GUI libraries to be loaded, which we do not want when using calibre # from the command line from calibre_plugins.interface_demo.config import ConfigWidget return ConfigWidget() def save_settings(self, config_widget): ''' Save the settings specified by the user with config_widget. :param config_widget: The widget returned by :meth:`config_widget`. ''' config_widget.save_settings() # Apply the changes ac = self.actual_plugin_ if ac is not None: ac.apply_settings() calibre tiene muchas maneras diferentes de almacenar los datos de configuración (un legado de su larga historia). El método recomendado es usar la clase JSONConfig, que almacena la información de configuración en un archivo.json. El código para gestionar los datos de configuración en el complemento de demostración está en config.py: from PyQt5.Qt import QWidget, QHBoxLayout, QLabel, QLineEdit from calibre.utils.config import JSONConfig # This is where all preferences for this plugin will be stored # Remember that this name (i.e. plugins/interface_demo) is also # in a global namespace, so make it as unique as possible. # You should always prefix your config file name with plugins/, # so as to ensure you dont accidentally clobber a calibre config file prefs = JSONConfig('plugins/interface_demo') # Set defaults prefs.defaults['hello_world_msg'] = 'Hello, World!' class ConfigWidget(QWidget): def init (self): QWidget. init (self) 1.9. Cursillos 221

226 self.l = QHBoxLayout() self.setlayout(self.l) self.label = QLabel('Hello world &message:') self.l.addwidget(self.label) self.msg = QLineEdit(self) self.msg.settext(prefs['hello_world_msg']) self.l.addwidget(self.msg) self.label.setbuddy(self.msg) def save_settings(self): prefs['hello_world_msg'] = unicode(self.msg.text()) El objeto prefs está ahora disponible en todo el código del complemento simplemente con: from calibre_plugins.interface_demo.config import prefs Puede observar que el objeto prefs se usa en main.py: def config(self): self.do_user_config(parent=self) # Apply the changes self.label.settext(prefs['hello_world_msg']) Complementos para modificar libros Vamos a cambiar de tercio y enfocarnos en la creación de un complemento para añadir herramientas al editor de libros de calibre. El complemento está disponible aquí: editor_demo_plugin.zip 101. El primer paso, como para todos los complementos es crear el archivo vacío con el nombre de importación descrito anteriormente (Página 214). Vamos a nombrar el archivo plugin-import-name-editor_plugin_demo.txt. Ahora creamos el archivo obligatorio init.py que contiene los metadatos del complemento: nombre, autor, versión, etc. from calibre.customize import EditBookToolPlugin class DemoPlugin(EditBookToolPlugin): name = 'Edit Book plugin demo' version = (1, 0, 0) author = 'Kovid Goyal' supported_platforms = ['windows', 'osx', 'linux'] description = 'A demonstration of the plugin interface for the ebook editor' minimum_calibre_version = (1, 46, 0) Un solo complemento del editor puede proporcionar múltiples herramientas; cada herramienta corresponde a un único botón en la barra de herramientas y entrada en el menú Complementos del editor. Éstos pueden tener submenús en el caso de que la herramienta posea múltiples acciones relacionadas. Todas las herramientas deben estar definidas en el archivo main.py del complemento. Cada herramienta es una clase que hereda de la clase calibre.gui2.tweak_book.plugin.tool (Página 357). Echemos un vistazo al main.py del complemento de demostración; el código fuente está profusamente comentado y se explica por sí mismo. Lea la documentación de la API de la clase :clase: calibre.gui2.tweak_book.plugin.tool para más detalles Capítulo 1. Secciones

227 main.py Aquí veremos la definición de una herramienta que multiplicará todos los tamaños de letra en el libro por un número proporcionado por el usuario. Esta herramienta demuestra varios conceptos importantes que se necesitarán para desarrollar otros complementos, por lo que debe leer el código fuente (muy comentado) cuidadosamente. import re from PyQt5.Qt import QAction, QInputDialog from cssutils.css import CSSRule # The base class that all tools must inherit from from calibre.gui2.tweak_book.plugin import Tool from calibre import force_unicode from calibre.gui2 import error_dialog from calibre.ebooks.oeb.polish.container import OEB_DOCS, OEB_STYLES, serialize class DemoTool(Tool): #: Set this to a unique name it will be used as a key name = 'demo-tool' #: If True the user can choose to place this tool in the plugins toolbar allowed_in_toolbar = True #: If True the user can choose to place this tool in the plugins menu allowed_in_menu = True def create_action(self, for_toolbar=true): # Create an action, this will be added to the plugins toolbar and # the plugins menu ac = QAction(get_icons('images/icon.png'), 'Magnify fonts', self.gui) # noqa if not for_toolbar: # Register a keyboard shortcut for this toolbar action. We only # register it for the action created for the menu, not the toolbar, # to avoid a double trigger self.register_shortcut(ac, 'magnify-fonts-tool', default_keys=('ctrl+shift+alt+d',)) ac.triggered.connect(self.ask_user) return ac def ask_user(self): # Ask the user for a factor by which to multiply all font sizes factor, ok = QInputDialog.getDouble( self.gui, 'Enter a magnification factor', 'Allow font sizes in the book will be multiplie value=2, min=0.1, max=4 ) if ok: # Ensure any in progress editing the user is doing is present in the container self.boss.commit_all_editors_to_container() try: self.magnify_fonts(factor) except Exception: # Something bad happened report the error to the user import traceback error_dialog(self.gui, _('Failed to magnify fonts'), _( 'Failed to magnify fonts, click "Show details" for more info'), det_msg=traceback.format_exc(), show=true) # Revert to the saved restore point 1.9. Cursillos 223

228 self.boss.revert_requested(self.boss.global_undo.previous_container) else: # Show the user what changes we have made, allowing her to # revert them if necessary self.boss.show_current_diff() # Update the editor UI to take into account all the changes we # have made self.boss.apply_container_update_to_gui() def magnify_fonts(self, factor): # Magnify all font sizes defined in the book by the specified factor # First we create a restore point so that the user can undo all changes # we make. self.boss.add_savepoint('before: Magnify fonts') container = self.current_container # The book being edited as a container object # Iterate over all style declarations in the book, this means css # stylesheets, <style> tags and style="" attributes for name, media_type in container.mime_map.iteritems(): if media_type in OEB_STYLES: # A stylesheet. Parsed stylesheets are cssutils CSSStylesheet # objects. self.magnify_stylesheet(container.parsed(name), factor) container.dirty(name) # Tell the container that we have changed the stylesheet elif media_type in OEB_DOCS: # A HTML file. Parsed HTML files are lxml elements for style_tag in container.parsed(name).xpath('//*[local-name="style"]'): if style_tag.text and style_tag.get('type', None) in {None, 'text/css'}: # We have an inline CSS <style> tag, parse it into a # stylesheet object sheet = container.parse_css(style_tag.text) self.magnify_stylesheet(sheet, factor) style_tag.text = serialize(sheet, 'text/css', pretty_print=true) container.dirty(name) # Tell the container that we have changed the styleshe for elem in container.parsed(name).xpath('//*[@style]'): # Process inline style attributes block = container.parse_css(elem.get('style'), is_declaration=true) self.magnify_declaration(block, factor) elem.set('style', force_unicode(block.getcsstext(separator=' '), 'utf-8')) def magnify_stylesheet(self, sheet, factor): # Magnify all fonts in the specified stylesheet by the specified # factor. for rule in sheet.cssrules.rulesoftype(cssrule.style_rule): self.magnify_declaration(rule.style, factor) def magnify_declaration(self, style, factor): # Magnify all fonts in the specified style declaration by the specified # factor val = style.getpropertyvalue('font-size') if not val: return # see if the font-size contains a number num = re.search(r'[0-9.]+', val) if num is not None: num = num.group() 224 Capítulo 1. Secciones

229 val = val.replace(num, '%f' % (float(num) * factor)) style.setproperty('font-size', val) # We should also be dealing with the font shorthand property and # font sizes specified as non numbers, but those are left as exercises # for the reader Vamos a analizar main.py. Vemos que define una única herramienta, llamada Magnify fonts. Esta herramienta le pediráá al usuario un número y multiplicará todos los tamaños de letra en el libro por dicho número. La primera cosa importante es el nombre de la herramienta que debe establecer a algún texto relativamente único, ya que se utilizará como clave para esta herramienta. El siguiente punto de entrada importante es calibre.gui2.tweak_book.plugin.tool.create_action() (Página 358). Este método crea los objetos QAction que aparecen en la barra de herramientas y en el menú de complementos. También, opcionalmente, asigna un atajo de teclado que el usuario puede personalizar. La señal que se genera en el objeto QAction está conectada con el método ask_user() que pide al usuario el multiplicador del tamaño de letra, y luego ejecuta el código de ampliación. El código de aumento está bien comentado y es bastante simple. Lo principal que hay que destacar es que se obtiene una referencia a la ventana del editor como self.gui y al Boss del editor como self.boss. El Boss es el objeto que controla la interfaz de usuario del editor. Tiene muchos métodos útiles, que se documentan en la clase calibre.gui2.tweak_book.boss.boss (Página 358). Finalmente está self.current_container, que es una referencia al libro que se está editando como un objeto calibre.ebooks.oeb.polish.container.container (Página 350). Éste representa el libro como una colección de archivos HTML, CSS e imágenes y posee diversos métodos prácticos para hacer varias cosas útiles. El objeto contenedor y varias funciones utilitarias que se pueden reutilizar en el código de los complementos están documentados en Documentación de la API para las herramientas de modificación de libros electrónicos (Página 350). Añadir traducciones al complemento Puede traducir todos los textos de la interfaz de usuario del complemento y mostrarlos en el idioma en que está configurada la interfaz principal de calibre. El primer paso es ir al código fuente del complemento y marcar todos los textos visibles por el usuario como traducibles, encerrándolos con _(). Por ejemplo: action_spec = (_('My plugin'), None, _('My plugin is cool'), None) Después utilice algún programa para generar archivos.po para el código fuente del complemento. Debe haber un archivo.po para cada idioma al que lo quiera traducir. Por ejemplo: de.po para el alemán, fr.po para el francés, etc. Puede utilizar el programa poedit 102 para esto. Envíe estos archivos.po a los traductores. Cuando reciba los archivos traducidos, compílelos en archivos.mo. Puede utilizar nuevamente poedit para ello, o simplemente ejecutar: calibre-debug -c "from calibre.translations.msgfmt import main; main()" filename.po Ponga los archivos.mo en la carpeta translations del complemento. El último paso es simplemente ejecutar la función load_translations() al principio de los archivos.py del complemento. Por motivos de rendimiento, sólo debe llamar a esta función en aquellos archivos.py que realmente poseen textos traducibles. Así que en un complemento de interfaz de usuario típico, la ejecutaría en ui.py pero no en init.py. Puede probar las traducciones del complemento cambiando el idioma de la interfaz de usuario en calibre bajo Preferencias > Apariencia o ejecutando calibre así: Cursillos 225

230 CALIBRE_OVERRIDE_LANG=de calibre Sustituya de por el código del idioma que desea probar. La API del complemento Como ya se habrá dado cuenta, un complemento en calibre es una clase. Hay diferentes clases para los diferentes tipos de complementos en calibre. Los detalles de cada clase, incluyendo la clase base de todos los complementos, se pueden encontrar en Documentación de la API para complementos (Página 320). Es casi seguro que el complemento va a usar el código de calibre. Para saber cómo encontrar los distintos elementos de funcionalidad en el código base de calibre, lea la sección Estructura del código (Página 304). Depurar complementos El primer paso, el más importante, es ejecutar calibre en modo de depuración. Puede hacer esto desde la línea de órdenes con: calibre-debug -g O desde el mismo calibre, pulsando con el botón derecho en Preferencias o usando el atajo de teclado Ctrl+Shift+R. Cuando se ejecuta desde la línea de órdenes, la salida de depuración se enviará a la consola, si se ejecuta dentro de calibre, la salida irá a un archivo txt. Puede insertar sentencias de impresión en cualquier lugar en el código fuente del complemento, tendrán efecto en el modo de depuración. Recuerde, esto es python, no debe necesitar más que sentencias de impresión para depurar ;) He desarrollado todo calibre usando sólo esta técnica de depuración. Puede probar rápidamente los cambios en el complemento con la siguiente orden: calibre-debug -s; calibre-customize -b /path/to/your/plugin/directory; calibre Esto cerrará calibre, espere hasta que se cierre completamente, después actualice el complemento en calibre y vuelva a iniciar calibre. Más ejemplos de complementos Puede encontrar una lista muchos complementos de calibre más complejos aqui 103. Compartir sus complementos con otros Si desea compartir los complementos que ha creado con otros usuarios de calibre, inicie un nuevo hilo adjuntando el complemento en el foros de complementos de calibre 104 (en inglés) Escribir fórmulas matemáticas en libros electrónicos El visor de libros de calibre tiene la capacidad de mostrar fórmulas matemáticas incrustadas en libros electrónicos (archivos epub y HTML). Puede escribir las fórmulas directamente con TeX, MathML o ASCIIMath. El visor de calibre usa la excelente biblioteca MathJax 105 para procesar las fórmulas. Esto es un breve cursillo para crear libros con fórmulas que funcionen con el visor de calibre Capítulo 1. Secciones

231 Un archivo HTML sencillo con fórmulas Puede escribir fórmulas matemáticas directamente en el texto de un archivo HTML sencillo y el visor de calibre las mostrará con una composición matemática adecuada. En el ejemplo de abajo, usamos la notación de TeX para las fórmulas. Verá que puede usar las órdenes normales de TeX, con la pequeña precaución de que los signos &, < y > deben escrbirse como &, < y &gt respectivamente. El primer paso es informar a calibre de que este documento contiene fórmulas. Para ello se añade el siguiente fragmente do código a la sección <head> del archivo HTML: <script type="text/x-mathjax-config"></script> Eso es todo, ahora ya se pueden escribir formulas igual que se haría en un archivo.tex. Por ejemplo, éstas son las ecuaciones de Lorentz: <h2>the Lorenz Equations</h2> <p> \begin{align} \dot{x} & = \sigma(y-x) \\ \dot{y} & = \rho x - y - xz \\ \dot{z} & = -\beta z + xy \end{align} </p> Este fragmento aparece como la siguiente captura de pantalla en el visor de calibre. Figura 1.2: Las ecuaciones de Lorentz El archivo HTML completo, con más ecuaciones y fórmulas en el texto se reproduce más abajo. Puede convertir este archivo HTML a EPUB con calibre para obtener un libro electrónico fácilmente distribuible a otras personas. <!DOCTYPE html> <html> <!-- Copyright (c) 2012 Design Science, Inc. --> <head> <title>math Test Page</title> <meta http-equiv="content-type" content="text/html; charset=utf-8" /> <!-- This script tag is needed to make calibre's ebook-viewer recpgnize that this file needs math typ <script type="text/x-mathjax-config"> // This line adds numbers to all equations automatically, unless explicitly suppressed. MathJax.Hub.Config({ TeX: { equationnumbers: {autonumber: "all"} } }); </script> <style> h1 {text-align:center} h2 { font-weight: bold; background-color: #DDDDDD; 1.9. Cursillos 227

232 padding:.2em.5em; margin-top: 1.5em; border-top: 3px solid #666666; border-bottom: 2px solid #999999; } </style> </head> <body> <h1>sample Equations</h1> <h2>the Lorenz Equations</h2> <p> \begin{align} \dot{x} & = \sigma(y-x) \label{lorenz}\\ \dot{y} & = \rho x - y - xz \\ \dot{z} & = -\beta z + xy \end{align} </p> <h2>the Cauchy-Schwarz Inequality</h2> <p>\[ \left( \sum_{k=1}^n a_k b_k \right)^{\!\!2} \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right) \]</p> <h2>a Cross Product Formula</h2> <p>\[ \mathbf{v}_1 \times \mathbf{v}_2 = \begin{vmatrix} \mathbf{i} & \mathbf{j} & \mathbf{k} \\ \frac{\partial X}{\partial u} & \frac{\partial Y}{\partial u} & 0 \\ \frac{\partial X}{\partial v} & \frac{\partial Y}{\partial v} & 0 \\ \end{vmatrix} \]</p> <h2>the probability of getting \(k\) heads when flipping \(n\) coins is:</h2> <p>\[p(e) = {n \choose k} p^k (1-p)^{ n-k} \]</p> <h2>an Identity of Ramanujan</h2> <p>\[ \frac{1}{(\sqrt{\phi \sqrt{5}}-\phi) e^{\frac25 \pi}} = 1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}} {1+\frac{e^{-8\pi}} {1+\ldots} } } } \]</p> <h2>a Rogers-Ramanujan Identity</h2> <p>\[ 1 + \frac{q^2}{(1-q)}+\frac{q^6}{(1-q)(1-q^2)}+\cdots = \prod_{j=0}^{\infty}\frac{1}{(1-q^{5j+2})(1-q^{5j+3})}, \quad\quad \text{for $ q <1$}. \]</p> 228 Capítulo 1. Secciones

233 <h2>maxwell's Equations</h2> <p> \begin{align} \nabla \times \vec{\mathbf{b}} -\, \frac1c\, \frac{\partial\vec{\mathbf{e}}}{\partial t} & = \f \nabla \cdot \vec{\mathbf{e}} & = 4 \pi \rho \\ \nabla \times \vec{\mathbf{e}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{b}}}{\partial t} & = \nabla \cdot \vec{\mathbf{b}} & = 0 \end{align} </p> <h2>in-line Mathematics</h2> <p>while display equations look good for a page of samples, the ability to mix math and text in a paragraph is also important. This expression \(\sqrt{3x-1}+(1+x)^2\) is an example of an inline equation. you see, equations can be used this way as well, without unduly disturbing the spacing between lines.</p> As <h2>references to equations</h2> <p>here is a reference to the Lorenz Equations (\ref{lorenz}). Clicking on the equation number will t </body> </html> Más información Puesto que el visor de calibre usa la biblioteca MathJax para mostrar las fórmulas, el mejor lugar para encontrar más información sobre fórmulas matemáticas en libros electrónicos y obtener ayuda es la página web de MathJax Crear catálogos AZW3 EPUB MOBI Catalogs La función «Crear catálogo» de calibre le permite crear un catálogo de la biblioteca en diferentes formatos. Este archivo de ayuda describe las opciones para generar catálogos en los formatos AZW3, EPUB y MOBI. Seleccionar libros para catalogar (Página 229) Secciones incluidas (Página 230) Prefijos (Página 231) Libros excluidos (Página 231) Géneros excluidos (Página 232) Otras opciones (Página 232) Portadas personalizadas para catálogos (Página 233) Otras fuentes de ayuda (Página 233) Seleccionar libros para catalogar Si quiere catalogar todos los libros de la biblioteca, elimine cualquier criterio de búsqueda o filtrado en la ventana principal. Si sólo hay un libro seleccionado, todos los libros de la biblioteca se considerarán para el catálogo generado Cursillos 229

234 Pueden excluirse libros individuales según distintos criterios; véase la sección Géneros excluidos (Página 232) más adelante para más información. Si sólo desea catalogar algunos libros de la biblioteca, tiene dos opciones: Crear una selección múltiple de los libros que quiera catalogar. Si hay más de un libro seleccionado en la ventana principal de calibre, sólo se catalogarán los libros seleccionados Usar el campo de búsqueda o el explorador de etiquetas para filtrar los libros mostrados. Sólo se catalogarán los libros que se muestran en la ventana principal. Para comenzar la generación del catálogo, seleccione el elemento de menú Convertir libros > Crear un catálogo de los libros en la biblioteca de calibre. También puede añadir un botón Crear catálogo a una barra de herramientas en Preferencias > Interfaz > Barra de herramientas para tener un acceso más cómo al diálogo para generar catálogos. En Opciones del catálogo, seleccione AZW3, EPUB o MOBI como formato del catálogo. En el campo Título del catálogo escriba un nombre para el catálogo que se genere. Si ya existe un catálogo con ese nombre será sustutuido por el nuevo catálogo generado. Si se activa Enviar el catálogo automáticamente al dispositivo, el catálogo generado se copiará al dispositivo conectado una vez completado. Secciones incluidas Las secciones con la casilla marcada se incluirán en el catálogo generado: Autores todos los libros, ordenados por autor, presentados como una lista. Los libros que no corresponden a ninguna serie se muestran antes de los que sí pertenecen. Títulos todos los libros, ordenados por título, presentados como una lista. Series todos los libros que forman parte de alguna serie, ordenados por serie, presentados como una lista. 230 Capítulo 1. Secciones

235 Géneros géneros individuales presentados como una lista, ordenados por autor y serie. Recently Added - all books, sorted in reverse chronological order. List includes books added in the last 30 days, then a month-by-month listing of added books. Descripciones una página de descripción detallada para cada libro, incluyendo una miniatura de portada y comentaries. Ordenados por autor, con los libros que no pertenecen a ninguna serie antes de los que sí pertenecen. Prefijos Las reglas de prefijo le permiten añadir un prefijo a las listas de libros cuando se satisfacen ciertos criterios. Por ejemplo, puede querer señalar con una marca los libros ya leídos, o los libros en la lista de deseos con una X. La casilla en la primera columna activa la regla. Nombre es el nombre que prefiera para la regla. Campo puede ser Etiquetas o una columna personalizada de la biblioteca. Valor es el contenido de Campo que debe coincidir. Cuando se satisface una regla de prefijo, el libro se marcará con el Prefijo seleccionado. El el ejemplo anterior se han especificado tres reglas de prefijo: 1. Libro leído especifica que un libro con una fecha cualquiera en una columna personalizada llamada Leído por última vez estará preferido por una marca de verificación. 2. Deseado especifica que cualquier libron la etiqueta Deseado estará precedido por una cruz. 3. Biblioteca especifica que cualquier libro con un valor «True» (o Sí) en una columna personalizada Disponible en la biblioteca estará precedido por una flecha doble. El prefijo se toma de la primera regla que coincida. Las reglas desactivadas o incompletas no se tienen en cuenta. Libros excluidos Las reglas de exclusión le permiten especificar los libros que no se incluirán en el catálogo Cursillos 231

236 La casilla en la primera columna activa la regla. Nombre es el nombre que prefiera para la regla. Campo puede ser Etiquetas o una columna personalizada de la biblioteca. Valor es el contenido de Campo que debe coincidir. Cuando se satisface una regla de exclusión, el libro se excluirá del catálogo que se genere. En el ejemplo anterior se han especificado dos reglas de exclusión: 1. La regla Catálogos especifica que cualquier libro con la etiqueta Catálogo se excluirá del catálogo generado. 2. La regla Libros archivados especifica que cualquier libro con un valor de Archivado en la columna personalizada Estado será excluido del catálogo generado. Todas las reglas se evalúan par cada libro. Las reglas desactivadas o incompletas no se tienen en cuenta. Géneros excluidos Cuando se genera el catálogo, las etiquetas en la base de datos se usan como géneros. Por ejemplo, puede usar las etiquetas «Ficción» y «No ficción». Estas etiquetas aparecen como géneros en el catálogo generado, con los libros en sus respectivas listas de género según las etiquetas que tengan asignadas. Cada libro estará en la lista de todos los generos para los que tenga la correspondiente etiqueta. Puede usar algunas etiquetas con diferentes propósitos, quizá un + para indicar un libro leído, o una etiqueta entre corchetes como «[Promoción de Amazon]» para recoger el origen de un libro. La expresión regular :gilabel: Géneros excluidos le permite especificar las etiquetas que no quiere que se usen como géneros en el catálogo generado. La expresión predeterminada «[.+] +» excluye todas las etiquetas de la forma «[etiqueta]», así como «+», la etiqueta predeterminada para los libros leídos, de la lista de géneros en el catálogo generado. También puede usar un nombre exacto de etiqueta en una expresión regular. Por ejemplo, «[Promoción de Amazon]» o «[Proyecto Gutenberg]». Si quiere introducir una lista de varias etiquetas exactas para la exclusión, ponga un carácter de barra vertical entre ellas: «[Promoción de Amazon] [Proyecto Gutenberg]». Resultado de expresión regular muestra qué etiquetas se excluirán cuando se genere el catálogo, según las etiquetas presentes en la base de datos y la expresión regular introducida. El resultado se actualiza al modificar la expresión regular. Otras opciones Portada del catálogo especifica si se generará una nueva portada o se usará una portada existente. Es posible crear una portada personalizada para los catálogos, véase Portadas personalizadas para catálogos (Página 233) para más 232 Capítulo 1. Secciones

237 información. Si ha creado una portada personalizada que quiere volver a usar, seleccione Utilizar portada actual. En caso contrario seleccione Generar nueva portada. Nota de descripción extra especifica una columna personalizada cuyo contenido se incluirá en la página de descripción, junto a la miniatura de portada. Por ejemplo, puede querer mostrar la fecha de última lectura del libro usando una columna personalizada Leído por última vez. Para un uso avanzado de la opción de nota de descripción, véase este mensaje en el foro de calibre 107 (en inglés). Ancho de la miniatura especifica la anchura preferida para las miniaturas de portada incluidas en las páginas de descripción. Las miniaturas se mantienen en caché para mejorar el rendimiento. Para experimentar con distintos tamaños, pruebe a generar un catálogo con unos pocos libros hasta que determine la anchura preferida, después genere el catálogo completo. La primera vez que se genera un catálogo con una nueva anchura de miniaturas el rendimiento será menor, pero las veces siguientes se aprovechará el caché de miniaturas. Unir con comentarios especifica una columna personalizada cuyo contenido se unirá, sin alterarlo, con el campo de metadatos de comentarios durante la generación del catálogo. Por ejemplo, puede tener una columna personalizada Biografía del autor que desee agregar a los metadatos de comentarios. Puede elegir insertar el contenido de la columna personalizada antes o después de la sección de comentarios y, opcionalmente, separar el contenido adicional con una línea horizontal. Los tipos de columna personalizada que se pueden seleccionar son texto, comentarios y compuesta. Portadas personalizadas para catálogos Con el complemento Generate Cover 108 instalado, puede crear portadas personalizadas para los catálogos. Para instalar el complemento, vaya a Preferencias > Avanzado > Complementos > Obtener nuevos complementos. Otras fuentes de ayuda Para más información sobre las funciones de catálogo de calibre, véase el tema fijo del foro de MobileRead Creating Catalogs - Start here 109 (en inglés), donde encontrará información sobre cómo personalizar las plantillas de catálogo Cursillos 233

238 y cómo enviar informes de errores. Para preguntar o discutir sobre las funciones de catálogos de calibre con otros usuarios, visite el foro de MobileRead Calibre Catalogs 110 (en inglés) Bibliotecas virtuales En calibre, una biblioteca virtual es una manera de hacer que calibre abra sólo un subconjunto de una biblioteca normal. Por ejemplo, es posible que desee trabajar únicamente con los libros de un determinado autor, o sólo con libros que tengan una cierta etiqueta. El uso de las bibliotecas virtuales es la mejor forma de dividir una colección de libros grande en subcolecciones más pequeñas. Es mejor que dividir la biblioteca en múltiples bibliotecas más pequeñas, pues cuando quiera buscar en toda la biblioteca puede simplemente volver a la biblioteca completa. No hay manera de buscar a través de múltiples bibliotecas separadas simultáneamente en calibre. Una biblioteca virtual es diferente a una simple búsqueda. Una búsqueda sólo restringirá la lista de los libros que aparecen en la lista de libros. Una biblioteca virtual hace eso, y además también restringe las entradas incluidas en Explorador de etiquetas a la izquierda. El explorador de etiquetas sólo mostrará las etiquetas, autores, series, editores, etc, que provienen de los libros en la biblioteca virtual. Por tanto, una biblioteca virtual se comporta como la biblioteca real, pero contiene un conjunto restringido de libros. Crear bibliotecas virtuales Para utilizar una biblioteca virtual, pulse en el botón Biblioteca virtual situado a la izquierda de la barra de búsqueda y seleccione la opción Crear biblioteca virtual. Como primer ejemplo, vamos a crear una biblioteca virtual que nos muestre sólo los libros de un autor concreto. Pulse en el enlace Autores como se muestra en la imagen de abajo, elija el autor que desee utilizar y pulse en Aceptar. El cuadro de diálogo Crear biblioteca virtual ha sido rellenado automáticamente. Pulse en Aceptar y verá que se ha creado y activado una nueva biblioteca virtual, que muestra únicamente los libros del autor seleccionado. En lo que se refiere a calibre, es como si la biblioteca contuviera sólo los libros del autor seleccionado. Puede volver a la biblioteca completa en cualquier momento, pulsando en Biblioteca virtual y seleccionando la entrada denominada :guilabel: <Ninguna> Capítulo 1. Secciones