Ler a saída nestas páginas
A maioria das páginas desta secção mostra a saída além da entrada: um ficheiro que a compilação escreveu em dist/, o texto que a compilação imprimiu no seu terminal, ou o que uma ferramenta como tofu imprimiu quando a executou sobre o que a compilação escreveu.
Esses blocos são copiados de uma execução real, não escritos à mão. Compile o exemplo e poderá comparar a sua própria saída com a página linha a linha.
Essa comparação é a razão de a saída estar aqui. Várias destas páginas pedem que altere uma linha e volte a compilar, ou que apague um ficheiro renderizado e execute a ferramenta de novo, e que depois leia a diferença. Uma instrução assim só vale a pena ser seguida se o bloco com que compara for exato — caso contrário, não tem forma de distinguir uma diferença que a página queria que encontrasse de uma que simplesmente nunca mencionou.
Por isso, um bloco que mostra saída está sempre num de dois estados, e nunca algures entre os dois.
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 nomeia um ficheiro, o ficheiro inteiro está lá.
Um excerto, marcado onde está a omissão
A saída real é muitas vezes longa, e imprimi-la toda enterraria a única linha que uma página está a ensinar. Onde há linhas omitidas, o bloco di-lo, numa linha própria, no ponto em que foram omitidas:
[… omitted: what was left out]Eis como isso fica na prática. 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 conterá esses dois atributos. A marca é o que lhe indica que pertencem ali — que são linhas que a página escolheu não reproduzir, e não algo que a sua compilação fez de forma diferente. Há uma marca em cada local onde foram retiradas linhas, pelo que a sua posição é tão legível como a sua ausência.
A marca diz sempre o que foi retirado, nunca apenas que algo o foi. «Um atributo id, comunicado como conhecido apenas após o apply» diz-lhe o suficiente para reconhecer a linha quando a encontrar; umas simples reticências não o fariam.
Os parênteses retos são deliberados. Uma linha que começa por [… 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 aqui mostradas imprime uma. Por isso, uma linha assim é sempre a página a falar, nunca algo que a compilação produziu — 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 o aspeto de um bloco sem deixar nada de fora, e nenhuma delas leva 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 ficheiro está fora da extensão, e não em falta nela. - Indentação. Um fragmento retirado de uma estrutura profundamente aninhada é normalmente mostrado a partir da margem esquerda, para que se leia por si só. As linhas são as linhas emitidas; só os espaços iniciais mudaram.
- Uma legenda ou uma nota. Uma linha
#que nomeia o ficheiro de onde vieram as linhas, ou uma nota curta junto a um valor, é visivelmente a página a falar, e não a compilação. - Um
#em cada linha de uma mensagem citada. Quando uma página mostra num único bloco um comando e a mensagem que ele imprimiu, a mensagem está comentada para que o bloco inteiro continue executável. Uma única linha impressa longa pode ser repartida por várias linhas#para se manter legível nesta largura. Em qualquer dos casos, as palavras são as palavras impressas, pela ordem impressa.
A marca existe para o único caso que não conseguiria detetar 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 guias passo a passo escritos, e não espaços de trabalho que possa compilar, e uma ou duas mostram a estrutura de um payload em vez de uma execução específica dele. Um bloco assim não contém nenhuma promessa com que possa fazer um diff, pelo que o diz nas palavras à sua volta — nunca toma silenciosamente o lugar da coisa real. Se um bloco não o disser, foi copiado de uma execução e os dois estados acima aplicam-se-lhe.
Se adaptar uma destas páginas
Mantenha os mesmos dois estados. Quando a saída mudar — porque 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 o editar à mão, e marque as linhas que deixar de fora. Um bloco editado para parecer correto é exatamente o que esta convenção pretende evitar, já que se lê exatamente como um bloco que foi verificado.