Partilhar via

Diretrizes de formatação de texto

  • Artigo

A utilização consistente e adequada dos estilos negrito, itálico e código em elementos de texto melhora a legibilidade e ajuda a evitar confusões.

Negrito

Utilize-o em elementos da IU, tais como seleções de menu, nomes de caixas de diálogo e nomes de campos de texto.

Exemplos

  • Isto: No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Adicionar > Novo Item.
  • Não é isso: no Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Adicionar > Novo Item.
  • Não é isso: no Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Adicionar > Novo Item.

Itálico

Utilize-o para:

  • apresentar novos termos, juntamente com uma definição ou explicação.
  • Nomes de ficheiros, pastas e caminhos.
  • Introdução do utilizador.

Exemplos

  • Faça isto: no Serviço de Aplicações, as aplicações são executadas num plano do Serviço de Aplicações. Os planos do Serviços de Aplicações definem um conjunto de recursos de computação para a execução de aplicações Web.
  • Não é isso: no Serviço de Aplicativo, um aplicativo é executado em um "Plano do Serviço de Aplicativo". Um plano do Serviço de Aplicativo define um conjunto de recursos de computação para execução de um aplicativo Web.
  • Isto: Substitua o código no HttpTriggerCSharp.cs pelo código a seguir.
  • Não é isso: substitua o código in HttpTriggerCSharp.cs pelo código a seguir.
  • Isto: Digite ContosoUniversity para o Nome e selecione Adicionar.
  • Não é isso: digite "ContosoUniversity" para o Nome e selecione Adicionar.

Estilo de código

Utilize-o para:

  • Elementos de código, tais como nomes de métodos, nomes de propriedades e palavras-chave de idiomas.
  • Comandos de SQL
  • Nomes de pacotes NuGet
  • Comandos de linha de comando*
  • Nomes de tabelas e colunas de bases de dados
  • Nomes de recursos que não devem ser traduzidos (por ex., nomes de máquinas virtuais)
  • URLs que não pretende que sejam clicáveis

Porquê? Os guias de estilo mais antigos especificam a utilização de negrito para muitos destes elementos de texto. No entanto, a maioria dos artigos são traduzidos e o estilo de código diz ao tradutor para deixar essa parte do texto sem tradução.

O estilo de código pode ser embutido (cercado por ') ou blocos de código cercados (cercado por ''') que abrangem várias linhas. Coloque fragmentos de código e caminhos maiores em blocos de código vedados.

* Em comandos de linha de comando, use barras em caminhos de arquivo se eles forem suportados em todas as plataformas. Use barras invertidas para ilustrar comandos executados no Windows, quando apenas barras invertidas são suportadas. Por exemplo, as barras para frente funcionam na CLI do .NET em todas as plataformas, portanto, você usaria dotnet build foldername/filename.csproj em vez de dotnet build foldername\filename.csproj.

Exemplos que utilizam estilos inline

  • Faça isto: por predefinição, o Entity Framework interpreta uma propriedade com o nome Id ou ClassnameID como a chave primária.
  • Não faça isto: por predefinição, o Entity Framework interpreta uma propriedade com o nome Id ou ClassnameID como a chave primária.
  • Faça isto: o pacote Microsoft.EntityFrameworkCore fornece suporte de runtime para EF Core.
  • Não faça isto: o pacote Microsoft.EntityFrameworkCore fornece suporte de runtime para EF Core.

Exemplos de blocos de código vedados

  • Faça isto: não são enviados comandos para a base de dados cujas instruções alteram apenas um método IQueryable, tal como o seguinte código:

        ```csharp
    var students = context.Students.Where(s => s.LastName == "Davolio")
    ```

  • Não é isso: nenhum comando é enviado para o banco de dados por instruções que apenas alteram um IQueryable, como var students = context. Students.Where(s => s.LastName == "Davolio").

  • Faça isto: por exemplo, para executar o script Get-ServiceLog.ps1 no diretório C:\Scripts, escreva:

        ```powershell
    C:\Scripts\Get-ServiceLog.ps1
    ```

  • Não faça isto: por exemplo, para executar o script Get-ServiceLog.ps1 no diretório C:\Scripts, escreva: "C:\Scripts\Get-ServiceLog.ps1".

  • Todos os blocos de código vedados têm de ter uma etiqueta de linguagem aprovada. Para obter uma lista de etiquetas de linguagem de suporte, veja How to include code in docs (Como incluir código no Docs).

Marcadores de Posição

Se desejar que o usuário substitua parte de uma cadeia de caracteres de entrada por seus próprios valores, use texto de espaço reservado marcado por colchetes angulares (menor e < maior que > caracteres).

Opção 1: Use o estilo de código para cercar a palavra do espaço reservado ou a frase abrangente. Por exemplo, você pode usar backticks únicos ' para formatação de código embutido para uma única frase, ou ticks triplos ''' para formatação cercada por código.

`az group delete -n <ResourceGroupName>`

Renderizado como:

az group delete -n <ResourceGroupName>

ou

Opção 2: Use um caractere \ de barra invertida para escapar dos caracteres de colchete angular em Markdown, como \< e \>. Embora apenas a primeira fuga no colchete \< angular esquerdo seja necessária, escapar do colchete \> de fechamento também funciona para consistência. O HTML renderizado não mostra o caractere de escape para o leitor:

az group delete -n \<ResourceGroupName\>

Renderizado como:

az group delete -n <ResourceGroupName>

Informe o leitor sobre o espaço reservado: No texto que precede esses exemplos de espaço reservado, explique ao leitor que o texto entre parênteses deve ser removido e substituído por valores reais. Recomendamos o uso de itálico para entrada do usuário. Você pode formatar itálico dentro do código embutido entre colchetes angulares:

No exemplo a seguir, substitua o texto <ResourceGroupName> do espaço reservado pelo seu próprio nome de grupo de recursos.

Atenção

O site do Microsoft Learn não processa <texto de espaço reservado> que usa colchetes angulares nos casos em que os colchetes não são escapados corretamente ou o texto não é formatado em código. O processo de compilação do Microsoft Learn interpreta a frase de espaço reservado <> como uma marca HTML que pode ser perigosa para o navegador do leitor e a sinaliza como uma marca html não permitida. Você verá uma sugestão no relatório de compilação e a palavra de espaço reservado não será processada na saída da página do Microsoft Learn quando isso acontecer.

Para evitar a perda de conteúdo em espaços reservados, use code caracteres de formatação ou escape (\< \>), conforme descrito anteriormente.

Desencorajamos o uso de chaves { } como espaços reservados sintáticos. Os leitores podem confundir os espaços reservados para chaves com a mesma notação usada em:

  • Texto substituível
  • Formatar cadeias de caracteres
  • Interpolação de cadeias
  • Modelos de texto
  • Construções de programação semelhantes

Invólucro e espaçamento: Você pode separar nomes de espaço reservado com hífenes ("caso de kebab") ou com sublinhados, ou pode fazê-lo usando maiúsculas e minúsculas Pascal. O caso do Kebab pode gerar erros de sintaxe e os sublinhados podem entrar em conflito com o sublinhado. Todas as letras maiúsculas podem entrar em conflito com constantes nomeadas em muitos idiomas, embora também possam chamar a atenção para o nome do espaço reservado.

<Resource-Group-Name> ou <ResourceGroupName>

Títulos e texto de ligações

Não aplique um estilo embutido, como itálico ou negrito, a títulos ou texto de hiperlink.

Porquê?

As pessoas recorrem a texto de hiperligação padrão para identificar elementos de texto como ligações clicáveis. Estilizar um link como itálico, por exemplo, pode obscurecer o fato de que o texto é um link. Os títulos têm os seus próprios estilos e, ao misturá-los com outros estilos, pode piorar o aspeto dos mesmos.

Exemplos de títulos e texto do link

Teclas e atalhos de teclado

Ao referir-se a teclas ou combinações de teclas, siga estas convenções:

  • Coloque a primeira letra dos nomes das teclas em letra maiúscula.
  • Envolva os nomes das chaves com <kbd> tags HTML e </kbd> .
  • Use "+" para unir teclas que o usuário seleciona ao mesmo tempo.

Exemplos de teclas e atalhos de teclado

  • Isto: Selecione Alt+Ctrl+S.
  • Não é isso: pressione ALT+CTRL+S.
  • Não é isso: Hit ALT+CTRL+S.

Exceções

As diretrizes de estilo não constituem regras rígidas. Em contextos em que prejudicam a legibilidade, proceda de outra forma. Por exemplo, uma tabela HTML que contenha maioritariamente elementos de código poderá parecer demasiado preenchida com estilos de código. Pode escolher um estilo com negrito nesse contexto.

Se escolher um estilo de texto alternativo para o qual é normalmente chamado código, certifique-se de que não há problema se o texto for traduzido em versões localizadas do artigo. O estilo de código é o único que automaticamente impede a tradução. Para cenários em que pretende evitar a localização sem utilizar o estilo de código, veja Cadeias de carateres não traduzidas.