Del via

Retningslinjer for tekstformatering

  • Artikel

Ensartet og passende brug af fed, kursiv og kodetypografi til tekstelementer forbedrer læsevenligheden og hjælper med at undgå misforståelser.

Bold

Brug fed til elementer i brugergrænsefladen, f.eks. menupunkter samt navne på dialogbokse og inputfelter.

Eksempler

  • Dette: I Løsningsoversigt skal du højreklikke på projektnoden og derefter vælge Tilføj > nyt element.
  • Ikke dette: I Løsningsoversigt skal du højreklikke på projektnoden og derefter vælge Tilføj > nyt element.
  • Ikke dette: I Løsningsoversigt skal du højreklikke på projektnoden og derefter vælge Tilføj > nyt element.

Kursiv

Brug kursiv til følgende:

  • Introduktion af nye begreber sammen med en definition eller forklaring.
  • Filnavne, mappenavne, stier.
  • Brugerinput.

Eksempler

  • Dette: I App Service kører en app i en App Service-plan. En App Service-plan definerer en række beregningsressourcer, som en webapp skal køre på.
  • Ikke dette: I App Service kører en app i en "App Service-plan". En App Service-plan definerer et sæt beregningsressourcer, som en webapp skal køre på.
  • Dette: Erstat koden i HttpTriggerCSharp.cs med følgende kode.
  • Ikke dette: Erstat koden i HttpTriggerCSharp.cs med følgende kode.
  • Dette: Angiv ContosoUniversity som navn, og vælg derefter Tilføj.
  • Ikke dette: Angiv "ContosoUniversity" som Navn, og vælg derefter Tilføj.

Kodetypografi

Brug kodetypografi til følgende:

  • Kodeelementer, f.eks. navne på metoder og egenskaber samt nøgleord for computersproget.
  • SQL-kommandoer
  • Navne på NuGet-pakker
  • Kommandolinjekommandoer*
  • Navne på databasetabeller og -kolonner
  • Ressourcenavne, der ikke skal lokaliseres, såsom navne på virtuelle maskiner
  • URL-adresser, som man ikke skal kunne klikke på

Hvorfor? I ældre stilvejledninger angives fed for mange af disse tekstelementer. Men de fleste artikler lokaliseres, og kodetypografi fortæller oversætteren, hvilke dele af teksten der ikke skal oversættes.

Kodetypografien kan være indbygget (omgivet af ') eller indhegnede kodeblokke (omgivet af '''), der strækker sig over flere linjer. Placer længere kodestykker og stier i indhegnede kodeblokke.

* Brug skråstreger i filstier i kommandolinjekommandoer, hvis de understøttes på alle platforme. Brug omvendte skråstreger til at illustrere kommandoer, der kører på Windows, når kun omvendte skråstreger understøttes. Skråstreger fungerer f.eks. på kommandolinjegrænsefladen .NET på alle platforme, så du vil bruge dotnet build foldername/filename.csproj i stedet dotnet build foldername\filename.csprojfor .

Eksempler på brug af indbyggede typografier

  • Dette: Entity Framework fortolker som standard en egenskab med navnet Id eller ClassnameID som den primære nøgle.
  • Ikke dette: Entity Framework fortolker som standard en egenskab med navnet Id eller ClassnameID som den primære nøgle.
  • Dette: Pakken Microsoft.EntityFrameworkCore understøtter kørsel af EF Core.
  • Ikke dette: Microsoft.EntityFrameworkCore-pakken understøtter kørsel af EF Core.

Eksempler på indhegnede kodeblokke

  • Dette: Der sendes ingen kommandoer til databasen af sætninger, der blot ændrer en IQueryable, f.eks. følgende kode:

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

  • Ikke dette: Der sendes ingen kommandoer til databasen af sætninger, der blot ændrer en IQueryable, f.eks . var students = context. Students.Where(s => s.LastName == "Davolio")..

  • Dette: Hvis du f.eks. vil køre scriptet Get-ServiceLog.ps1 C:\Scripts i mappen, skal du skrive:

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

  • Ikke dette: Hvis du f.eks. vil køre Get-ServiceLog.ps1-scriptet i mappen C:\Scripts , skal du skrive: "C:\Scripts\Get-ServiceLog.ps1."

  • Alle indhegnede kodeblokke skal have en godkendt sprogkode. Du kan se en liste over understøttede sprogkoder i Sådan inkluderes kode i dokumenter.

Pladsholdere

Hvis brugeren skal erstatte en del af en inputstreng med sine egne værdier, skal du bruge pladsholdertekst, der er markeret af vinkelparenteser (mindre end < og større end > tegn).

Mulighed 1: Brug kodetypografi til at omgive pladsholderordet eller det omsluttende udtryk. Du kan f.eks. bruge enkelt backticks ' til indbygget kodeformatering for et enkelt udtryk eller tredobbelt aksemærker ''' til kodeindhegnet formatering.

`az group delete -n <ResourceGroupName>`

Gengivet som:

az group delete -n <ResourceGroupName>

or

Mulighed 2: Brug et omvendt skråstregstegn \ til at undgå vinkelparenteser i Markdown, f.eks \< . og \>. Selvom det kun er den første escape-pil i venstre vinkelparentes \< , der kræves, fungerer det også at undslippe den afsluttende parentes \> for at sikre ensartethed. Den gengivne HTML viser ikke escape-tegnet til læseren:

az group delete -n \<ResourceGroupName\>

Gengivet som:

az group delete -n <ResourceGroupName>

Giv læseren besked om pladsholderen: I teksten før sådanne pladsholdereksempler skal du forklare læseren, at teksten i kantede parenteser skal fjernes og erstattes med reelle værdier. Vi anbefaler, at der bruges kursiv til brugerinput. Du kan formatere kursiv i vinkelparenteser med indbygget kode:

I følgende eksempel skal du erstatte pladsholderteksten <ResourceGroupName> med navnet på din egen ressourcegruppe.

Advarsel

Microsoft Learn-webstedet gengiver <ikke pladsholdertekst> , der bruger vinkelparenteser i tilfælde, hvor kantede parenteser ikke er escape-korrekt, eller teksten ikke er kodeformateret. Microsoft Learn-buildprocessen fortolker <pladsholderudtrykket> som et HTML-mærke, der kan være farligt for læserens browser, og markerer det som et ikke-tilladt html-tag. Du får vist et forslag i buildrapporten, og pladsholderordet gengives ikke i Microsoft Learn-sideoutputtet, når det sker.

Hvis du vil undgå tab af indhold på pladsholdere, skal du bruge code formaterings- eller escapetegn (\< \>) som beskrevet tidligere.

Vi fraråder at bruge krøllede klammeparenteser { } som syntaktiske pladsholdere. Læserne kan forveksle krøllede klammeparenteser med den samme notation, der bruges i:

  • Tekst, der kan erstattes
  • Formatstrenge
  • Indskudt streng
  • Tekstskabeloner
  • Lignende programmeringskonstruktioner

Casing and spacing: Du kan adskille pladsholdernavne med bindestreger ("kebab case") eller med understregningstegn, eller du kan gøre det ved hjælp af Pascal-sag. Kebab-tilfælde kan generere syntaksfejl, og understregningstegn kan være i konflikt med understregning. Store bogstaver kan være i konflikt med navngivne konstanter på mange sprog, selvom det også kan henlede opmærksomheden på pladsholdernavnet.

<Resource-Group-Name> eller <ResourceGroupName>

Overskrifter og linktekst

Anvend ikke en indbygget typografi, f.eks. kursiv eller fed, på overskrifter eller linktekst.

Hvorfor?

Folk regner med standardhyperlinktekst, når de skal identificere elementer som klikbare links. Formatering af et link som kursiv kan f.eks. skjule det faktum, at teksten er et link. Overskrifter har deres egne typografier, og det ser ikke godt ud, hvis man blander andre typografier med dem.

Eksempler på overskrifter og linktekst

  • Dette: Filen function.json genereres af NuGet-pakken Microsoft.NET.Sdk.Functions.

  • Ikke dette: Filen function.json genereres af NuGet-pakken Microsoft.NET.Sdk.Functions.

  • Brug dette:

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

  • Ikke dette:

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

Taster og tastaturgenveje

Når du refererer til taster eller tastekombinationer, bør du følge disse konventioner:

  • Skriv det første bogstav i navnet på en tast med stort.
  • Omgiv nøglenavnene med <kbd> og </kbd> HTML-koder.
  • Brug "+" til at joinforbinde nøgler, som brugeren vælger på samme tid.

Eksempler på taster og tastaturgenveje

  • Dette: Vælg Alt+Ctrl+S.
  • Ikke dette: Tryk på ALT+CTRL+S.
  • Ikke dette: Hit ALT+CTRL+S.

Undtagelser

Stilvejledninger er ikke strenge regler. I en kontekst, hvor de skader læsevenligheden, skal du gøre noget andet. En HTML-tabel, der primært indeholder kodeelementer, kan f.eks. se rodet ud med kodetypografi overalt. Du kan vælge fed i denne kontekst.

Hvis du vælger en alternativ teksttypografi, hvor kode normalt ville bruges, skal du sørge for, at det er okay, at teksten oversættes i lokaliserede versioner af artiklen. Kode er den eneste typografi, der normalt forhindrer oversættelse. Til scenarier, hvor du vil forhindre lokalisering uden at bruge kodetypografi, skal du se Ikke-lokaliserede strenge.