Lendo a saída nestas páginas
A maioria das páginas desta seção mostra a saída além da entrada: um arquivo que o build gravou em dist/, o texto que o build imprimiu no seu terminal, ou o que uma ferramenta como tofu imprimiu quando você a executou sobre o que o build gravou.
Esses blocos são copiados de uma execução real, não escritos à mão. Faça você mesmo o build do exemplo e você poderá comparar a sua própria saída com a página linha por linha.
Essa comparação é o motivo de a saída estar aqui. Várias destas páginas pedem que você altere uma linha e refaça o build, ou que exclua um arquivo renderizado e execute a ferramenta de novo, e então leia a diferença. Uma instrução assim só vale a pena ser seguida se o bloco com o qual você compara for exato — caso contrário, você não tem como distinguir uma diferença que a página queria que você encontrasse de uma que ela simplesmente nunca mencionou.
Por isso, um bloco que mostra saída está sempre em um de dois estados, e nunca em algum ponto intermediário.
Completo
O bloco mostra a totalidade do que a página nomeou. Quando o texto introdutório diz o serviço web, todas as linhas desse serviço estão lá. Quando ele nomeia um arquivo, o arquivo inteiro está lá.
Um trecho, marcado onde está a omissão
A saída real costuma ser longa, e imprimi-la inteira enterraria a única linha que uma página está ensinando. Onde linhas são omitidas, o bloco diz isso, em uma linha própria, no ponto em que foram omitidas:
[… omitted: what was left out]Veja isso em uso. Este é um plano para o exemplo terraform-declared-sensitivity, em que o ponto em questão diz respeito a um único 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", ] }O seu próprio plano terá esses dois atributos. A marca é como você sabe que eles pertencem ali — que são linhas que a página escolheu não reproduzir, e não algo que o seu build fez de forma diferente. Há uma marca em cada lugar em que linhas foram retiradas, de modo que a sua posição é tão legível quanto a sua ausência.
A marca sempre diz o que foi retirado, nunca apenas que algo foi. “Um atributo id, informado como conhecido somente após o apply” diz o suficiente para você reconhecer a linha quando a encontrar; reticências sozinhas não diriam.
Os colchetes são deliberados. Uma linha que começa com [… não é conteúdo válido em YAML, HCL, JSON nem em nenhum dos outros formatos que estas páginas imprimem, e nenhuma das ferramentas mostradas aqui imprime uma. Então uma linha assim é sempre a página falando, nunca algo que o build produziu — ela não pode ser confundida com saída nem passar despercebida numa leitura rápida.
O que não é uma omissão
Quatro coisas mudam a aparência de um bloco sem deixar nada de fora, e nenhuma delas recebe marca:
- Nomear uma extensão menor. Uma página que diz “o serviço
web” e depois mostra esse serviço não deixou de fora nada do que nomeou. O resto do arquivo está fora da extensão, e não faltando nela. - Indentação. Um fragmento tirado de uma estrutura profundamente aninhada geralmente é mostrado a partir da margem esquerda, para que possa ser lido sozinho. As linhas são as linhas emitidas; só os espaços iniciais mudaram.
- Uma legenda ou uma nota. Uma linha
#que nomeia o arquivo de onde vieram as linhas, ou uma nota curta ao lado de um valor, é visivelmente a página falando, e não o build. - Um
#em cada linha de uma mensagem citada. Quando uma página mostra em um único bloco um comando e a mensagem que ele imprimiu, a mensagem fica comentada para que o bloco inteiro continue executável. Uma única linha impressa longa pode ser quebrada em várias linhas#para continuar legível nesta largura. De qualquer forma, as palavras são as palavras impressas, na ordem impressa.
A marca existe para o único caso que você não conseguiria detectar de outra forma: linhas que simplesmente não estão lá.
Um bloco que ilustra em vez de reproduzir
Algumas páginas aqui são roteiros passo a passo escritos, e não espaços de trabalho dos quais você possa fazer o build, e uma ou duas mostram a estrutura de um payload em vez de uma execução específica dele. Um bloco assim não traz nenhuma promessa contra a qual você possa fazer um diff, então ele diz isso nas palavras ao redor — ele nunca toma silenciosamente o lugar da coisa real. Se um bloco não disser isso, ele foi copiado de uma execução e os dois estados acima se aplicam a ele.
Se você adaptar uma destas páginas
Mantenha os mesmos dois estados. Quando a saída mudar — porque você alterou o exemplo, ou porque uma versão mais recente a renderiza de outra forma — substitua o bloco a partir de uma execução real em vez de editá-lo à mão, e marque as linhas que deixar de fora. Um bloco editado para parecer certo é exatamente o que esta convenção pretende evitar, já que ele se lê exatamente como um bloco que foi verificado.