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 permite generar vínculos que apuntan a elementos o fragmentos particulares del documento. 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, definiciones y cajas de llamado, entre otros. 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 o fragmento que se quiere referenciar.
Referencia. Se invoca algún elemento o fragmento 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 las categorías más comunes.
| 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] |
| Código | #lst-ciclo |
@lst-ciclo |
-@lst-ciclo |
[script -@lst-ciclo] |
Tip 4.1: ¡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 importantlstpara fragmentos de códigodefpara definicionesexmpara ejemplosexrpara ejerciciosthmpara teoremaslempara lemascorpara corolariosprppara proposicionescnjpara conjeturasrempara observaciones (remarks)
El manejo de categorías diferenciadas da lugar a la generación automática y dinámica de una nomenclatura numérica para identificar cada uno de los elementos dentro de cada categoría.
¡El dinamismo hace la vida más sencilla!
El hecho de que cada uno de los diferentes elementos o fragmentos estén identificados con una etiqueta, en lugar de estarlo con un nomenclador numérico le permite al usuario desentenderse de la posición relativa de estos, pudiendo incluir, eliminar o mover elementos, sin que se vea afectada las referencias que se hagan a estos desde otros lugares del documento.
Quarto actualiza la nomenclatura de cada elemento o fragmento, acorde con su categoría y su posición relativa con respecto a los demás elementos de la misma categoría.
¿¡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 ilustra con mayor nivel de detalle el proceso de identificación y referencia. 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 (el mismo prefijo, sin importar si se trata de un capítulo o de una sección). 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 contiene 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” de rango 1 es Capítulo, y Sección para las de rango 2 o superior. 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-yaml
En el documento renderizado aparecerían los vínculos con los nomencladores únicamente, así:
¡Podría parecer confuso!
Aunque a primera vista podría considerarse que esta forma de presentación es poco útil, dado que al eliminar el nombre genérico en el vínculo, la información queda incompleta, sin que pueda saberse si se está haciendo referencia a una sección, una tabla, una figura…, resulta útil para referenciar varias secciones simultáneamente, así:
…Estos aspectos se discuten en las secciones -@sec-que-es, -@sec-doc-qmd, -@sec-yaml y -@sec-id-all-lin-cod.
En el documento renderizado aparece así:
Estos aspectos se discuten en las secciones 1.1, 2.1, 2.1.1.1 y 3.7.1.1.
Asimismo, la eliminación del nombre genérico permite remplazarlo 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 ilustrado para la 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 fragmentos de código
Hay dos formas de referenciar fragmentos de código. Ambas 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 en mi documento aparece “Listado 4.1”, en lugar de “Código 4.1”?!
La etiqueta en español para los elementos de esta categoría 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.7.1).
Si se requiere identificar líneas de código e identificar 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í |
4.7 Referenciación de otras categorías
En adición a las secciones (cf. sección 4.1), tablas (cf. sección 4.2), figuras (cf. sección 4.3), ecuaciones (cf. sección 4.4) y callouts (cf. sección 4.5), Quarto maneja otras categorías, que se definen con base en los prefijos reservados que se presentan en el tip 4.1.
Tales prefijos deben tenerse en cuenta al momento de definir los identificadores, con lo cual, los elementos adquieren la membresía a una categoría determinada, lo que determina su nombre genérico y su nomenclatura.
La referencia se realiza de manera análoga a la ilustrada en las anteriores secciones.
4.8 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. sección 3.5). 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 a este párrafo 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.
¡O mejor aun, combínelas!
La estrategia de referenciar un punto cualquiera del documento mediante su identificación a través de una div, aunque cumple su objetivo, puede no ser la más elegante, dado que presenta un mero vínculo sin incluir el contexto.
Por su parte, la referenciación estructurada puede resultar imprecisa para apuntar a un aspecto particular de una sección grande, sobre todo si el fragmento al que se desea hacer referencia se encuentra bastante alejando del comienzo de la sección. Para ello, basta con incluir el referenciador de la sección (con lo cual aparecerá la correspondiente nomenclatura), seguido del referenciador de la div.
Así, por ejemplo, para generar una referencia al tercer párrafo de la sección 4.1, se escribe así en el documento fuente:
…debe incluirse un identificador, acorde con lo señalado en la [sección -@sec-ref-cap-sec](#id).
En el documento renderizado aparecerá así:
…debe incluirse un identificador, acorde con lo señalado en la sección 4.1
Puede observarse que aunque el vínculo aparece identificado con el nombre de la sección, lo cual agrega contexto, al hacer clic sobre el mismo dirige al tercer párrafo de la sección, en lugar de hacerlo al comienzo de la misma.
Esta fue la estrategia utilizada en la advertencia 4.1 para apuntar a un fragmento particular ubicado al final de la sección 5.3.