x <- c(4.1, 6.5, 4.8, 3.5, 2.7, 3.0, 5.9, 2.3)
var(x)4 Referenciación
Una de las características que hace tan versátiles los documentos generados mediante Quarto es la navegación fluida. Esta se logra gracias a la referenciación de sus elementos.
La referenciación más evidente es la que se realiza a sus diferentes capítulos y secciones, pero también pueden referenciarse tablas, figuras, ecuaciones, ejemplos y cajas de llamado. Incluso es posible referenciar cualquier ubicación particular del documento, sin que pertenezca a ninguna categoría especial.
¿¡Es obligatoria!?
La referenciación, aunque optativa en todos los casos, es definitivamente recomendada.
El proceso de referenciación involucra dos elementos:
Identificación. Se le asigna un identificador al elemento que se quiere referenciar.
Referencia. Se invoca algún elemento que haya sido marcado con un identificador.
¿¡Y el orden!?
El proceso de identificación y referencia puede realizarse en cualquier orden.
Es posible referenciar cualquier elemento al que se le haya asignado un identificador, sea que aparezca antes o después en el documento.
En (casi) todos los casos, el identificador se escribe dentro de llaves, iniciando con el símbolo #, seguido de una cadena de caracteres.
Cualquiera de los siguientes es un identificador válido:
{#sec-ref}{#tbl-atributos}{#fig-concep}{#eq-var}{#tip-nombres}{#div1}
La referencia a los elementos a los que se les hubieran asignado los anteriores identificadores se realizarían cambiando el símbolo # por @, así:
@sec-ref@tbl-atributos@fig-concep@eq-var@tip-nombres@div1
La tabla 4.1 presenta el esquema general de identificación y referenciación para diferentes categorías.
| Categoría | Id | Referencia por defecto | Referencia sin nombre | Referencia con nombre personalizado |
|---|---|---|---|---|
| Sección | #sec-intro |
@sec-intro |
-@sec-intro |
[apartado -@sec-intro] |
| Tabla | #tbl-datos |
@tbl-datos |
-@tbl-datos |
[cuadro -@tbl-datos] |
| Figura | #fig-esquema |
@fig-esquema |
-@fig-esquema |
[gráfico -@fig-esquema] |
| Ecuación | #eq-varianza |
@eq-varianza |
-@eq-varianza |
[expresión -@eq-varianza] |
| Callout tip | #tip-nemot |
@tip-nemot |
-@tip-nemot |
[Sugerencia -@tip-nemot] |
| Callout note | #nte-nota2 |
@nte-nota2 |
-@nte-nota2 |
[nota -@nte-nota2] |
| Callout warning | #wrn-congl |
@wrn-congl |
-@wrn-congl |
[advertencia -@wrn-congl] |
| Callout caution | #cau-uso-fun |
@cau-uso-fun |
-@cau-uso-fun |
[alerta -@cau-uso-fun] |
| Callout important | #imp-nunca |
@imp-nunca |
-@imp-nunca |
[conminación -@imp-nunca] |
¡El prefijo clave!
Hay un prefijo clave que debe usarse al comienzo de cada identificador, según su categoría, así:
secpara secciones y capítulostblpara tablasfigpara figuraseqpara ecuacionestippara callouts de la clase tipntepara callouts de la clase notewrnpara callouts de la clase warningcaupara callouts de la clase cautionimppara callouts de la clase important
¿¡Y los identificadores!? ¿¡Son obligatorios!?
Aunque ningún identificador es obligatorio per se, sí lo sería si se deseara referenciar el correspondiente elemento.
En las siguientes secciones se detalla el proceso de identificación y referencia de diferentes categorías de elementos.
La sección 4.1 es la que presenta el proceso de identificación y referencia con mayor detalle. Y puesto que este proceso se aplica de manera análoga para las demás categorías, se presenta de manera simplificada en las secciones subsiguientes.
4.1 Referenciación de capítulos y secciones
Los libros se dividen en capítulos y secciones. Los pequeños documentos únicamente tienen secciones.
Tanto los capítulos como las secciones tienen un título, que se introduce con el símbolo # (cf. sección 2.1.1.3.1). No obstante, el elemento de vínculo para la posterior referencia no es el título, sino el identificador. Estos se ubican entre llaves después del título.
Los identificadores de los capítulos y las secciones deben iniciar con el prefijo sec. Esto hace que se reconozcan como miembros del grupo de las secciones y, al momento de referenciarlos, aparezcan con la nomenclatura que les corresponde.
A continuación se muestran algunos de los identificadores usados para las secciones y capítulos de este libro:
{#sec-que-es}{#sec-doc-qmd}{#sec-yaml}{#sec-tools}{#sec-id-all-lin-cod}
Las correspondientes referencias pueden realizarse en cualquier punto del documento así:
@sec-que-es@sec-doc-qmd@sec-yaml@sec-tools@sec-id-all-lin-cod.
En el documento renderizado aparecerían como vínculos, así:
¡Y funcionan!
Haciendo clic sobre cualquiera de los vínculos anteriores, puede verificarse que conducen a la sección o capítulo correspondiente.
Advertencia 4.1: ¡Los nombres pueden personalizarse!
Los elementos en cuya identificación se haya usado un prefijo clave, entran a formar parte de la correspondiente categoría: sección, tabla, figura, ecuación…
Cuando son referenciados, se genera un vínculo con el nomenclador de la correspondiente categoría, antecedido de un nombre genérico, acorde con el idioma elegido en el YAML (cf. sección 2.1.1.1).
Estos nombres pueden personalizarse de manera global en el YAML, tal y como se indica al final de la sección 5.3.
Esta es la razón por la que este documento podría exhibir nombres diferentes a los que se obtendrían en un documento en cuyo YAML no se hubieran incluido estas opciones.
El vínculo que se genera tiene dos elementos: un nombre genérico (Sección o Capítulo en este caso) y un nomenclador.
El nomenclador se asigna automáticamente, acorde con la posición de las secciones y con la jerarquía que se les haya asignado, en función del número de símbolos # (cf. sección 2.1.1.3.1).
El nombre es genérico y se asigna según el idioma elegido en el YAML (cf. sección 2.1.1.1).
En el presente documento en el que el YAML incorpora la opción lang: es, el nombre genérico de las secciones es Sección para los títulos de rango 2 o superior, y Capítulo para los de rango1. Bajo otra configuración de idioma, se usarían otros nombres genéricos.
Si se desea que en el vínculo únicamente aparezca el nomenclador, sin el nombre genérico, se antecede la referencia con un guion, así:
-@sec-que-es-@sec-doc-qmd-@sec-yaml-@sec-tools-@sec-id-all-lin-cod
En el documento renderizado aparecerían los vínculos con los nomencladores únicamente, así:
¡Y funcionan!
La eliminación del nombre genérico en el vínculo deja la información incompleta, al no saberse si se está haciendo referencia a una sección, una tabla, una figura…
Esto resultaría útil, sin embargo, si se se deseara cambiar el nombre genérico por algún otro nombre personalizado.
Para personalizar los nombres que anteceden al nomenclador, se escriben antes de la referencia, encerrando nombre y referencia dentro de corchetes.
Considérense las siguientes referencias:
[apartado -@sec-que-es][Numeral -@sec-doc-qmd][sección -@sec-yaml][Cap. -@sec-tools]
En el documento renderizado aparecerían como vínculos, así:
¡Inclúyalo!
Para que el nombre genérico forme parte del vínculo, debe quedar incluido en los corchetes.
¡Aplica la misma lógica!
El procedimiento de identificación y referencia de la secciones y capítulos aplica de manera análoga para cualquiera de los otros elementos referenciables.
4.2 Referenciación de tablas
Los identificadores de las tablas deben iniciar con el prefijo tbl. Esto hace que se reconozcan como miembros del grupo de las tablas y, al momento de referenciarlas, aparezcan con la nomenclatura que les corresponde.
A continuación se muestran algunos de los identificadores usados para las tablas de este documento:
{#tbl-t1}{#tbl-t4}
Las correspondientes referencias se harían así:
@tbl-t1@tbl-t4
En el documento renderizado aparecerían como vínculos, así:
El vínculo que se genera tiene dos elementos: un nombre genérico (Tabla, cuando se ha elegido la opción lang: es en el YAML) y un nomenclador.
Para que el vínculo aparezca únicamente con el nomenclador, sin el nombre genérico, se antecede la referencia con un guion, así:
-@tbl-t1-@tbl-t4
En el documento renderizado aparecerían los vínculos con los nomencladores de las tablas únicamente, así:
También es posible personalizar los nombres que anteceden al nomenclador. Considérense las siguientes referencias:
[tabla -@tbl-t1][cuadro -@tbl-t4].
En el documento renderizado aparecerían como vínculos, así:
4.3 Referenciación de figuras
Los identificadores de las figuras deben iniciar con el prefijo fig. Esto hace que se reconozcan como miembros del grupo de las figuras y, al momento de referenciarlas aparezcan con la nomenclatura que les corresponde.
A continuación se muestra el identificador para la primera figura de este documento:
{#fig-esquema}
La correspondiente referencia se haría así:
@fig-esquema
En el documento renderizado aparecería como vínculo, así:
El vínculo que se genera tiene dos elementos: un nombre genérico (Figura, cuando se ha elegido la opción lang: es en el YAML) y un nomenclador.
Si se desea que en el vínculo únicamente aparezca el nomenclador, sin el nombre genérico, se antecede la referencia con un guion, así:
-@fig-esquema
En el documento renderizado aparecería el vínculo con el nomenclador de las figura únicamente, así:
También es posible personalizar los nombres que anteceden al nomenclador. Considérese la siguiente referencia:
[imagen -@fig-esquema]
En el documento renderizado aparecería como vínculo, así:
4.4 Referenciación de ecuaciones
Los identificadores de las ecuaciones deben iniciar con el prefijo eq. Esto hace que se reconozcan como miembros del grupo de las ecuaciones y, al momento de referenciarlas aparezcan con la nomenclatura que les corresponde.
El identificador se agrega en la línea de cierre de la expresión LaTeX, así:
$$
S^2=\frac{\sum\limits_{i=1}^{n}{\left(X_i-\overline{X}\right)^2}}{n-1}
$$ {#eq-var}La correspondiente referencia se hace así:
@eq-var
En el documento renderizado aparece como vínculo, así:
El vínculo que se genera tiene dos elementos: un nombre genérico (Ecuación, cuando se ha elegido la opción lang: es en el YAML) y un nomenclador.
Si se desea que en el vínculo únicamente aparezca el nomenclador, sin el nombre genérico, se antecede la referencia con un guion, así:
-@eq-var
En el documento renderizado aparecería el vínculo con el nomenclador de las ecuación únicamente, así:
También es posible personalizar los nombres que anteceden al nomenclador. Considérese la siguiente referencia:
[expresión -@eq-var]
En el documento renderizado aparecería como vínculo, así:
4.5 Referenciación de callouts
Los identificadores de las callouts deben iniciar con un prefijo particular, según su clase:
tippara callouts de la clase tipntepara callouts de la clase notewrnpara callouts de la clase warningcaupara callouts de la clase cautionimppara callouts de la clase important
A continuación se muestra el identificador de un callout que aparece en el capítulo 2:
{#cau-bool}
La correspondiente referencia se haría así:
@cau-bool
En el documento renderizado aparecería como vínculo, así:
El vínculo que se genera tiene dos elementos: un nombre genérico (Caution) y un nomenclador.
¿¡Caution!?
Es extraño que aunque se use la opción lang: es en el YAML, aparece este nombre genérico en inglés.
Posiblemente se trate de un bug que se corrija en futuras versiones.
Si se desea que en el vínculo únicamente aparezca el nomenclador, sin el nombre genérico, se antecede la referencia con un guion, así:
-@cau-bool
En el documento renderizado aparecería el vínculo con el nomenclador de las figura únicamente, así:
También es posible personalizar los nombres que anteceden al nomenclador. Considérese la siguiente referencia:
[Llamado de atención -@cau-bool]
En el documento renderizado aparecería como vínculo, así:
4.6 Referenciación de otras categorías
La tabla 3.2 presenta los prefijos clave que definen una serie de grupos particulares, susceptibles de referenciación. Tales prefijos deben tenerse en cuenta al momento de definir los identificadores. La referencia se realiza de manera análoga a la ilustrada en las anteriores secciones.
4.7 Referenciación de elementos que no pertenecen a ninguna categoría
El usuario podría querer referenciar algún punto o elemento particular del documento que no se ajuste a ninguna de las categorías consideradas anteriormente.
Este tipo de ‘referenciación’, aunque se sale del esquema expuesto anteriormente, también es posible.
En estos casos, puesto que el punto o elemento no pertenece a ninguna categoría particular, su identificador no llevaría ningún prefijo clave. Tampoco estaría nomenclado.
En ese sentido, más que una verdadera referencia, se trata de establecer un vínculo a un punto o elemento particular.
Para establecer el identificador del punto o elemento, basta con incluirlo dentro de una div (cf. 3.6). Este identificador sería invisible en el documento renderizado.
Para ilustrarlo, se ha introducido el identificador {#id} en el tercer párrafo de la sección 4.1, usando una div, así:
::: {#id}
Los identificadores de los capítulos y las secciones...
:::Para ir al sitio marcado, se incluye un vínculo, así:
Debe incluirse un [identificador](#id)…
En el documento renderizado aparecerá así:
Debe incluirse un identificador…
¡Solo dentro de un mismo capítulo!
Esta forma de referencia funciona en documentos que no tienen capítulos o cuando se realiza dentro de un mismo capítulo (para libros).
Para referenciar a otro capítulo, es necesario incluir el capítulo en la referencia.
Considérese ahora un identificador que se ha introducido en el segundo párrafo de la sección 2.1.1.2, usando una div, así:
::: {#comillas}
Cada fragmento de código debe iniciarse con tres comillas invertidas...
:::Para incluir un vínculo en otro capítulo, se usa una referencia que incluya el nombre del documento contenedor, así:
Debe tenerse presente lo indicado sobre las [comillas](02-docs.qmd#comillas).
En el documento renderizado aparecerá así:
Debe tenerse presente lo indicado sobre las comillas.
¡Hay que adaptar el YAML!
Para que la referencia entre capítulos funcione adecuadamente, es necesario incluir la siguiente opción en el YAML:
crossref:
chapters: true
Previsualización
Al pasar el puntero por encima de un vínculo de referencia, se previsualiza el correspondiente elemento.
La previsualización no aplica, sin embargo, cuando la ‘referencia’ se hace sobre elementos que no corresponden a ninguna categoría.
4.8 Referenciación de fragmentos de código
Aunque hay varias formas de referenciar fragmentos de código, todas ellas se basan en su identificación y posterior referencia como listado, usando el prefijo lst.
Opción 1. Incluyendo las opciones lst-label y lst-cap en el fragmento de código.
En el documento fuente de Quarto se escribe así:
```{r}
#| lst-label: lst-cod1
#| lst-cap: "Cálculo de la varianza"
x <- c(4.1, 6.5, 4.8, 3.5, 2.7, 3.0, 5.9, 2.3)
var(x)
```Mediante la opción lst-label se introduce el identificador que se usa para la referencia. Este identificador debe iniciar con el prefijo lst.
En este caso, es obligatorio agregar la opción lst-cap con un título para el fragmento de código (No acepta un título en blanco: lst-cap: "").
En el documento renderizado aparece así:
Para su referencia, pueden usarse el formato con el nombre ‘Listado’ —que aparece por defecto—, la salida sin nombre y la salida con un nombre personalizado:
Al escribir @lst-cod1, se renderiza como código 4.1.
Si se escribe -@lst-cod1, se renderiza como 4.1.
O puede personalizarse el nombre, escribiendo, por ejemplo, [script -@lst-cod1], que se renderiza como script 4.1.
Opción 2. Mediante una div en la que se incluya un identificador que inicie con el prefijo lst. En este caso, no es posible agregar título.
En el documento fuente de Quarto se escribiría así:
::: {#lst-cod2}
```{r}
x <- c(4.1, 6.5, 4.8, 3.5, 2.7, 3.0, 5.9, 2.3)
var(x)
```
:::En el documento renderizado aparece así:
x <- c(4.1, 6.5, 4.8, 3.5, 2.7, 3.0, 5.9, 2.3)
var(x)Nótese que en este caso, el código no lleva título en el documento renderizado.
La referencia se realiza igual que en el caso anterior.
Al escribir: El cálculo de la varianza se ilustra en el @lst-cod2, aparece así en el documento renderizado:
El cálculo de la varianza se ilustra en el código 4.2.
¡¿Porque aparece “Listado 4.1”, en lugar de “Código 4.1”?!
La etiqueta en español para los listados es “Listado”. No obstante, es posible cambiarla mediante las siguientes instrucciones en el YAML (cf. sección 5.3):
crossref:
lst-title: Código
lst-prefix: código
Mediante lst-title se especifica la cadena de caracteres que aparece encima del código (en este ejemplo “Código”). La clave lst-prefix permite definir la cadena de carateres que se usan cuando se hace la referencia interna (en este ejemplo “código”).
¡Cuidado con las incompatibilidades!
El uso de la Opción 1 de identificación es incompatible con la identificación de líneas del código (cf. sección 3.1.1).
Si se requiere identificar líneas de código e identifcar el código, solo queda disponible la Opción 2.
La tabla 4.2 resume los aspectos diferenciadores de las dos opciones expuestas:
Opción 1: Incluyendo las opciones
lst-labelylst-capen el fragmento de códigoOpción 2: Mediante una div en la que se incluya un identificador que inicie con el prefijo
lst
| Identificación de fragmentos de código | Título | Compatible con identificación de líneas |
|---|---|---|
| Opción 1 | Sí (obligatorio) | No |
| Opción 2 | No | Sí |