Instructions de mise en forme du texte

  • Article

L’utilisation cohérente et appropriée du style gras, italique et code pour les éléments de texte améliore la lisibilité et permet d’éviter les confusions.

Gras

Utilisez le gras pour les éléments de l’interface utilisateur, comme les sélections de menu, les noms de boîte de dialogue et les noms de champ d’entrée.

Exemples

  • Appliquez : Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le nœud du projet et sélectionnez Ajouter > Nouvel élément.
  • N’appliquez pas : Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le nœud du projet et sélectionnez Ajouter > Nouvel élément.
  • N’appliquez pas : Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le nœud du projet et sélectionnez Ajouter > Nouvel élément.

Italique

Utilisez l’italique pour :

  • Présentation de nouveaux termes avec une définition ou une explication.
  • Les noms de fichier, les noms de dossier, les chemins.
  • Entrée utilisateur.

Exemples

  • Appliquez : Dans App Service, une application s’exécute dans un plan App Service. Un plan App Service définit un ensemble de ressources de calcul nécessaires à l’exécution d’une application web.
  • N’appliquez pas : dans App service, une application s’exécute dans un « plan App Service ». Un plan App Service définit un ensemble de ressources de calcul sur lequel une application web s’exécute.
  • Appliquez : Remplacez le code dans HttpTriggerCSharp.cs par le code suivant.
  • N’appliquez pas : Remplacez le code présent dans HttpTriggerCSharp.cs par le code suivant.
  • Appliquez : Entrez ContosoUniversity pour Nom, puis sélectionnez Ajouter.
  • N’appliquez pas : Entrez « ContosoUniversity » pour Nom, puis sélectionnez Ajouter.

Style code

Utiliser le style code pour :

  • Les éléments de code, comme les noms de méthode, les noms de propriétés et les mots clés du langage.
  • Commandes SQL
  • Les noms de package NuGet
  • Commandes en ligne de commande*
  • Les noms de table et de colonne des bases de données
  • Noms de ressources qui ne doivent pas être localisés (tels que les noms de machine virtuelle)
  • Les URL que vous ne souhaitez pas cliquables

Pourquoi ? Les anciens guides de style spécifient le gras pour la plupart de ces éléments de texte. Toutefois, la plupart des articles sont localisés et le style code indique au traducteur de conserver cette partie du texte non traduite.

Le style de code peut apparaître inline (entouré de `) ou dans des blocs de code délimités (entouré de ```) englobant plusieurs lignes. Placez les extraits de code et les chemins plus longs dans des blocs de code délimités.

* Dans les commandes en ligne de commande, utilisez des barres obliques dans les chemins de fichiers si elles sont prises en charge sur toutes les plateformes. Recourez à des barres obliques inverses pour illustrer les commandes qui s’exécutent sur Windows, lorsque seules les barres obliques inverses sont acceptées. Par exemple, les barres obliques fonctionnent dans l’interface CLI .NET sur toutes les plateformes. Privilégiez donc dotnet build foldername/filename.csproj plutôt que dotnet build foldername\filename.csproj.

Exemples utilisant des styles intralignes

  • Appliquez : Par défaut, Entity Framework interprète une propriété nommée Id ou ClassnameID comme étant la clé primaire.
  • N’appliquez pas : Par défaut, Entity Framework interprète une propriété nommée Id ou ClassnameID comme étant la clé primaire.
  • Appliquez : Le package Microsoft.EntityFrameworkCore prend en charge l’exécution d’EF Core.
  • N’appliquez pas : Le package Microsoft.EntityFrameworkCore prend en charge l’exécution d’EF Core.

Exemples de blocs de code délimités

  • Appliquez : Aucune commande n’est envoyée à la base de données par des instructions qui changent juste IQueryable, comme le code suivant :

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

  • N’appliquez pas : Aucune commande n’est envoyée à la base de données par des instructions qui changent juste IQueryable, comme var students = context.Students.Where(s => s.LastName == "Davolio").

  • Appliquez : Par exemple, pour exécuter le script Get-ServiceLog.ps1 dans le répertoire C:\Scripts, tapez :

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

  • N’appliquez pas : Par exemple, pour exécuter le script Get-ServiceLog.ps1 dans le répertoire C:\Scripts, tapez : "C:\Scripts\Get-ServiceLog.ps1."

  • Tous les blocs de code délimités doivent avoir une balise de langue approuvée. Pour obtenir la liste des balises de langue de prise en charge, consultez Inclure du code dans la documentation.

Espaces réservés

Si vous souhaitez que l’utilisateur remplace une partie d’une chaîne d’entrée par ses propres valeurs, utilisez un texte de l’espace réservé marqué par des crochets pointus (inférieur à < et supérieur à > caractères).

Option 1 : utilisez un style de code pour entourer le mot de l’espace réservé ou la phrase englobante. Par exemple, vous pouvez utiliser des accents graves uniques ` pour la mise en forme du code inline pour une seule expression, ou trois accents graves ``` pour la mise en forme du code délimité.

`az group delete -n <ResourceGroupName>`

Rendu comme suit :

az group delete -n <ResourceGroupName>

or

Option 2 : utilisez une barre oblique inverse \ pour placer les caractères d’échappement entre crochets pointus dans Markdown, par exemple \< et \>. Alors que seule la première séquence d’échappement sur le crochet pointu \< est requise, l’échappement du crochet fermant \> fonctionne également pour des besoins de cohérence. Le code HTML rendu n’affiche pas le caractère d’échappement au lecteur :

az group delete -n \<ResourceGroupName\>

Rendu comme suit :

az group delete -n <ResourceGroupName>

Informez le lecteur de la présence de l’espace réservé : dans le texte qui précède ces exemples d’espaces réservés, expliquez au lecteur que le texte entre crochets doit être supprimé et remplacé par de vraies valeurs. Nous vous recommandons d’utiliser l’italique pour les entrées utilisateur. Vous pouvez mettre en forme les caractères en italique dans le code inline entre crochets pointus :

Dans l’exemple suivant, remplacez le texte de l’espace réservé <ResourceGroupName> par le nom de votre propre groupe de ressources.

Attention

Le site Microsoft Learn ne rend <pas de texte d’espace réservé> qui utilise des crochets dans les cas où les crochets ne sont pas correctement placés dans une séquence d’échappement ou où le texte n’est pas au format code. Le processus de génération Microsoft Learn interprète l’expression <d’espace réservé> comme une balise HTML susceptible d’être dangereuse pour le navigateur du lecteur et la signale comme une balise non autorisée-html-tag. Vous verrez une suggestion dans le rapport de génération, et le mot d’espace réservé n’est pas affiché dans la sortie de la page Microsoft Learn lorsque cela se produit.

Pour éviter la perte de contenu sur les espaces réservés, utilisez des caractères de mise en forme ou d’échappement code (\<\>) comme décrit précédemment.

Nous déconseillons d’utiliser des accolades {} comme espaces réservés syntaxiques. Les lecteurs peuvent confondre des espaces réservés d’accolades avec la même notation utilisée dans :

  • Texte remplaçable
  • Chaînes de format
  • Interpolation de chaîne
  • Modèles de texte
  • Constructions de programmation similaires

Casse et espacement : vous pouvez séparer les noms d’espaces réservés par des traits d’union (casse « kebab ») ou par des traits de soulignement, ou vous pouvez le faire à l’aide de la casse Pascal. La casse kebab peut générer des erreurs de syntaxe et les traits de soulignement peuvent être en conflit avec le soulignement. Le tout en majuscules peut entrer en conflit avec des constantes nommées dans de nombreux langages, bien que cela puisse également attirer l’attention sur le nom de l’espace réservé.

<Resource-Group-Name> ou <ResourceGroupName>

Titres et texte des liens

N’appliquez pas de style intraligne (par exemple italique ou gras) aux titres ni aux liens hypertextes.

Pourquoi ?

Les personnes se fient au texte de lien hypertexte standard pour identifier les éléments de texte comme des liens cliquables. Par exemple, le style italique appliqué à un texte peut masquer le fait qu’il s’agit d’un lien. Les titres ont leur propre style et leur en ajouter d’autres ne donne pas un bon résultat.

Exemples de titres et de texte de lien

  • Appliquez : le fichier function.json est généré par le package NuGet Microsoft.NET.Sdk.Functions.

  • N’appliquez pas : le fichier function.json est généré par le package NuGet Microsoft.NET.Sdk.Functions.

  • Appliquez :

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

  • N’appliquez pas :

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

Touches et raccourcis clavier

Quand vous faites référence à des touches ou à des combinaisons de touches, respectez les conventions suivantes :

  • Mettez en majuscule la première lettre des noms de touches.
  • Entourez les noms des touches des balises HTML <kbd> et </kbd>.
  • Utilisez « + » pour combiner les touches que l’utilisateur sélectionne simultanément.

Exemples de raccourcis clavier

  • Appliquez : sélectionnez Alt+Ctrl+S.
  • N’appliquez pas : Appuyez sur ALT+CTRL+S.
  • N’appliquez pas : Appuyez sur ALT+CTRL+S.

Exceptions

Les instructions sur les styles ne sont pas des règles strictes. Dans les contextes où elles nuisent à la lisibilité, opérez différemment. Par exemple, un tableau HTML avec principalement des éléments de code peut paraître trop chargé avec du style code partout. Vous pouvez choisir le style gras dans ce contexte.

Si vous choisissez un style de texte de remplacement où le code est normalement appelé, assurez-vous que le texte peut être traduit dans les versions localisées de l’article. Le style code est le seul style qui empêche systématiquement la traduction du texte. Pour les scénarios où vous souhaitez empêcher la localisation sans utiliser le style code, consultez Chaînes non localisées.