Leer la salida en estas páginas
La mayoría de las páginas de esta sección te muestran la salida además de la entrada: un archivo que la compilación escribió en dist/, el texto que la compilación imprimió en tu terminal, o lo que una herramienta como tofu imprimió cuando la ejecutaste sobre lo que escribió la compilación.
Esos bloques están copiados de una ejecución real, no escritos a mano. Compila el ejemplo tú mismo y podrás comparar tu propia salida con la página línea por línea.
Esa comparación es la razón por la que la salida está aquí. Varias de estas páginas te piden cambiar una línea y volver a compilar, o eliminar un archivo renderizado y ejecutar la herramienta otra vez, y luego leer la diferencia. Una instrucción así solo merece seguirse si el bloque con el que comparas es exacto — de lo contrario no tienes forma de distinguir una diferencia que la página quería que encontraras de una que simplemente nunca mencionó.
Así que un bloque que muestra salida está siempre en uno de dos estados, y nunca en algún punto intermedio.
Completo
El bloque muestra la totalidad de lo que nombró la página. Cuando el texto introductorio dice el servicio web, cada línea de ese servicio está ahí. Cuando nombra un archivo, el archivo entero está ahí.
Un extracto, marcado donde está la omisión
La salida real suele ser larga, e imprimirla entera enterraría la única línea que una página está enseñando. Donde se omiten líneas, el bloque lo dice, en una línea propia, en el punto donde se omitieron:
[… omitted: what was left out]Así se ve en uso. Este es un plan para el ejemplo terraform-declared-sensitivity, donde lo que se quiere mostrar se refiere a un solo atributo:
# module.store.terraform_data.reference will be created + resource "terraform_data" "reference" { [… omitted: an id attribute, reported as known only after apply] + input = (sensitive value) [… omitted: an output attribute, reported as known only after apply] + triggers_replace = [ + "app-artifacts", + "AKIAEXAMPLE0001", ] }Tu propio plan llevará esos dos atributos. La marca es lo que te indica que pertenecen ahí — que son líneas que la página eligió no reproducir, y no algo que tu compilación hizo de otra manera. Hay una marca en cada lugar donde se quitaron líneas, así que su posición es tan legible como su ausencia.
La marca siempre dice qué se quitó, nunca solo que se quitó algo. «Un atributo id, notificado como conocido solo después del apply» te dice lo suficiente para reconocer la línea cuando la encuentres; unos simples puntos suspensivos no.
Los corchetes son deliberados. Una línea que empieza por [… no es contenido válido en YAML, HCL, JSON ni en ninguno de los otros formatos que imprimen estas páginas, y ninguna de las herramientas mostradas aquí imprime una. Así que una línea así es siempre la página la que habla, nunca algo que produjo la compilación — no se puede confundir con salida ni pasar por alto al leer por encima.
Qué no es una omisión
Cuatro cosas cambian el aspecto de un bloque sin dejar nada fuera, y ninguna de ellas lleva marca:
- Nombrar un alcance más reducido. Una página que dice «el servicio
web» y luego muestra ese servicio no ha dejado fuera nada de lo que nombró. El resto del archivo queda fuera del alcance en lugar de faltar en él. - La sangría. Un fragmento extraído de una estructura profundamente anidada suele mostrarse desde el margen izquierdo para que se lea por sí solo. Las líneas son las líneas emitidas; solo cambiaron los espacios iniciales.
- Una leyenda o una nota. Una línea
#que nombra el archivo del que proceden las líneas, o una nota breve junto a un valor, es visiblemente la página la que habla y no la compilación. - Un
#en cada línea de un mensaje citado. Donde una página muestra en un solo bloque un comando y el mensaje que imprimió, el mensaje está comentado para que todo el bloque siga siendo ejecutable. Una sola línea impresa larga puede repartirse en varias líneas#para seguir siendo legible a este ancho. En cualquier caso, las palabras son las palabras impresas, en el orden impreso.
La marca existe para el único caso que de otro modo no podrías detectar: líneas que simplemente no están.
Un bloque que ilustra en lugar de reproducir
Algunas páginas aquí son recorridos guiados escritos en lugar de espacios de trabajo que puedas compilar, y una o dos muestran la estructura de una carga útil en lugar de una ejecución concreta de ella. Un bloque así no ofrece ninguna promesa con la que puedas hacer un diff, así que lo dice en las palabras que lo rodean — nunca ocupa en silencio el lugar de lo real. Si un bloque no lo dice, se copió de una ejecución y se le aplican los dos estados anteriores.
Si adaptas una de estas páginas
Mantén los mismos dos estados. Cuando la salida cambie — porque cambiaste el ejemplo, o porque una versión más reciente la renderiza de otra manera — sustituye el bloque a partir de una ejecución real en lugar de editarlo a mano, y marca las líneas que dejes fuera. Un bloque editado para que parezca correcto es justamente lo que esta convención pretende evitar, ya que se lee exactamente como un bloque que se comprobó.