Diretrizes de formatação de texto

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 Explorador de Soluções, clique com o botão direito do rato no nó do projeto e, em seguida, selecione Adicionar > Novo Item.
• Não faça isto: no Explorador de Soluções, clique com o botão direito do rato no nó do projeto e, em seguida, selecione Adicionar > Novo Item.
• Não faça isto: no Explorador de Soluções, clique com o botão direito do rato no nó do projeto e, em seguida, 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 é o seguinte: no Serviço de Aplicações, uma aplicação é executada num "plano Serviço de Aplicações". Um plano de Serviço de Aplicações define um conjunto de recursos de computação para uma aplicação Web ser executada.
• Faça isto: Substitua o código em HttpTriggerCSharp.cs pelo seguinte código.
• Não faça isto: substitua o código em HttpTriggerCSharp.cs pelo seguinte código.
• Faça isto: insira ContosoUniversity no Nome e, em seguida, selecione Adicionar.
• Não faça isto: insira "ContosoUniversity" no Nome e, em seguida, 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 da linha de comandos*
• 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 inline (rodeado por ') ou blocos de código vedados (rodeados por '') que abrangem várias linhas. Coloque fragmentos de código e caminhos maiores em blocos de código vedados.

* Nos comandos da linha de comandos, utilize barras reencaminhadas em caminhos de ficheiro se forem suportadas em todas as plataformas. Utilize barras invertidas para ilustrar comandos que são executados no Windows, quando apenas são suportadas barras invertidas. Por exemplo, as barras reencaminhadas funcionam na CLI do .NET em todas as plataformas, pelo que utilizaria 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 é o seguinte: não são enviados comandos para a base de dados por instruções que apenas alteram um IQueryable, como estudantes de var = contexto. 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 quiser que o utilizador substitua parte de uma cadeia de entrada pelos seus próprios valores, utilize o texto do marcador de posição marcado por parênteses angulares (menores e maiores que <> os carateres).

Opção 1: Utilize o estilo de código para rodear a palavra do marcador de posição ou a expressão abrangente. Por exemplo, pode utilizar um único backticks para formatação de código inline para uma única expressão ou tiques triplos "" para formatação com cerca de código.

`az group delete -n <ResourceGroupName>`

Composto como:

az group delete -n <ResourceGroupName>

ou

Opção 2: Utilize um caráter \ de barra invertida para escapar aos carateres de parênteses angulares em Markdown, como \< e \>. Embora seja necessária apenas a primeira fuga no parêntese \< do ângulo esquerdo, escapar ao parêntese \> de fecho também funciona para consistência. O HTML composto não mostra o caráter de escape ao leitor:

az group delete -n \<ResourceGroupName\>

Composto como:

az group delete -n <ResourceGroupName>

Informe o leitor sobre o marcador de posição: No texto anterior a esses exemplos de marcador de posição, explique ao leitor que o texto entre parênteses tem de ser removido e substituído por valores reais. Recomendamos a utilização de itálico para a entrada do utilizador. Pode formatar itálicos no código inline entre ângulos:

No exemplo seguinte, substitua o texto <ResourceGroupName> do marcador de posição pelo seu próprio nome de grupo de recursos.

Atenção

O site do Microsoft Learn não compõe <texto de marcador> de posição que utilize parênteses angulares nos casos em que os parênteses não sejam corretamente escapados ou o texto não esteja formatado em código. O processo de compilação do Microsoft Learn interpreta a expressão de <marcador> de posição como uma etiqueta HTML que pode ser perigosa para o browser do leitor e sinaliza-a como uma etiqueta html não permitida. Verá uma sugestão no relatório de compilação e a palavra de marcador de posição não é composta na saída da página do Microsoft Learn quando isso acontece.

Para evitar a perda de conteúdo nos marcadores de posição, utilize code a formatação ou os carateres de escape (\<\>) conforme descrito anteriormente.

Desencorajamos a utilização de chavetas { } como marcadores de posição sintácticos. Os leitores podem confundir marcadores de posição de chavetas com a mesma notação utilizada em:

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

Casing e espaçamento: pode separar os nomes dos marcadores de posição com hífenes ("caso kebab") ou com carateres de sublinhado ou pode fazê-lo utilizando o caso Pascal. O caso Kebab pode gerar erros de sintaxe e os sublinhados podem entrar em conflito com o sublinhado. As maiúsculas podem entrar em conflito com constantes nomeadas em muitos idiomas, embora também possa chamar a atenção para o nome do marcador de posição.

<Resource-Group-Name> ou <ResourceGroupName>

Títulos e texto de ligações

Não aplique um estilo inline, como itálico ou negrito a cabeçalhos ou texto de hiperligação.

Porquê?

As pessoas recorrem a texto de hiperligação padrão para identificar elementos de texto como ligações clicáveis. O estilo de uma ligação como itálico, por exemplo, pode ocultar o facto de o texto ser uma ligação. 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 cabeçalhos e texto de ligação

• Isto: o ficheiro function.json é gerado pelo pacote NuGet Microsoft.NET.Sdk.Functions.

• Não é o seguinte: o ficheiro function.json é gerado pelo pacote NuGet Microsoft.NET.Sdk.Functions.

• Faça isto:

  ### The Microsoft.NET.Sdk.Functions package
  

• Não faça isto:

  ### The *Microsoft.NET.Sdk.Functions* package
  

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.
• Rodeie os nomes das chaves com <kbd> etiquetas HTML.</kbd>
• Utilize "+" para associar chaves que o utilizador selecione ao mesmo tempo.

Exemplos de teclas e atalhos de teclado

• Isto: selecione Alt+Ctrl+S.
• Não faça isto: prima Alt+Ctrl+S.
• Não faça isto: prima 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.