Pokyny na formátovanie textu

Konzistentné a vhodné použitie tučného písma, kurzívy a štýlu kódu pre prvky textu zvyšuje čitateľnosť a pomáha predchádzať nedorozumeniam.

Tučné

Použite tučné písmo pre prvky používateľského rozhrania, ako sú napríklad výbery v ponuke, názvy dialógových okien a názvy vstupných polí.

Príklady

• Takto: V Prieskumník riešení kliknite pravým tlačidlom myši na uzol projektu a potom vyberte položku Pridať > novú položku.
• Nie takto: V Prieskumník riešení kliknite pravým tlačidlom myši na uzol projektu a potom vyberte položku Pridať > novú položku.
• Nie takto: V Prieskumník riešení kliknite pravým tlačidlom myši na uzol projektu a potom vyberte položku Pridať > novú položku.

Kurzíva

Kurzívu použite v týchto prípadoch:

• Uvedenie nových pojmov spolu s definíciou alebo vysvetlením.
• Názvy súborov, názvy priečinkov, cesty.
• Vstup používateľa.

Príklady

• Takto: V službe App Service sa aplikácia spustí v pláne služby App Service. Plán služby App Service definuje množinu výpočtových zdrojov, v ktorej sa spustí webová aplikácia.
• Nie takto: V službe App Service sa aplikácia spustí v pláne služby App Service. Plán služby App Service definuje množinu výpočtových prostriedkov, v prípade ktorú sa spustí webová aplikácia.
• Takto: Nahraďte kód v HttpTriggerCSharp.cs nasledujúcim kódom.
• Nie takto: Nahraďte kód v HttpTriggerCSharp.cs texte nasledujúcim kódom.
• Takto: Zadajte ContosoUniversity ako Názov a potom vyberte položku Pridať.
• Nie takto: Zadajte ContosoUniversity ako Názov a potom vyberte položku Pridať.

Štýl kódu

Štýl kódu použite v týchto prípadoch:

• Prvky kódu, ako sú napríklad názvy metód, názvy vlastností a kľúčové slová jazyka.
• Príkazy SQL
• Názvy balíkov NuGet
• Príkazy príkazového riadka*
• Názvy tabuľky databázy a stĺpcov
• Názvy zdrojov, ktoré by nemali byť lokalizované (napríklad názvy virtuálnych počítačov)
• URL adresy, ktoré nechcete, aby slúžili ako prepojenia na kliknutie

Prečo? Staršie príručky štýlov určujú pre mnohé z týchto prvkov textu tučné písmo. Väčšina článkov je však lokalizovaná a štýl kódu povie prekladateľovi, aby nechal túto časť textu nepreloženú.

Štýl kódu môže byť vnorený (obklopuje ho ohradený) alebo ohradený (obklopuje ho ' ' ), ktorý je rozložený vo viacerých riadkoch. Vložte dlhšie úryvky kódu a cesty do blokov ohradeného kódu.

* V príkazoch príkazového riadka používajte v cestách k súboru lomky dopredu, ak sú podporované na všetkých platformách. Na ilustráciu príkazov, ktoré sa spúšťajú v systéme Windows, použite opačné lomky, keď sú podporované iba opačné lomky. Napríklad na rozhraní .NET CLI fungujú na všetkých platformách lomky, takže by ste použili namiesto dotnet build foldername/filename.csproj dotnet build foldername\filename.csproj.

Príklady použitia vnorených štýlov

• Takto: V predvolenom nastavení Entity Framework interpretuje vlastnosť s názvom Id alebo ClassnameID ako primárny kľúč.
• Nie takto: V predvolenom nastavení Entity Framework interpretuje vlastnosť s názvom Id alebo ClassnameID ako primárny kľúč.
• Takto: Balík Microsoft.EntityFrameworkCore poskytuje podporu modulu runtime pre EF Core.
• Nie takto: Balík Microsoft.EntityFrameworkCore poskytuje podporu modulu runtime pre EF Core.

Príklady blokov ohradeného kódu

• Takto: Do databázy sa neodosielajú žiadne príkazy na základe príkazov, ktoré jednoducho zmenia IQueryable, ako napríklad tento kód:

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

• Nie takto: Do databázy sa neodosielajú žiadne príkazy prostredníctvom príkazov, ktoré jednoducho zmenia režim IQueryable, napríklad odchýlka študentov = kontext. Students.Where(s => s.LastName == "Davolio").

• Takto: Ak chcete napríklad spustiť Get-ServiceLog.ps1 skript v adresári C:\Scripts , zadajte:

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

• Nie takto: Ak chcete napríklad spustiť skript Get-ServiceLog.ps1 v adresári C:\Scripts , zadajte: "C:\Scripts\Get-ServiceLog.ps1."

• Všetky bloky ohradeného kódu musia mať schválenú značku jazyka. Zoznam podporovaných značiek jazyka nájdete v téme Zahrnutie kódu na lokalite Docs.

Zástupné objekty

Ak chcete, aby používateľ nahradil časť vstupného reťazca vlastnými hodnotami, použite text zástupného objektu vyznačený lomenými zátvorkami (menšie ako < a väčšie ako > znaky).

Možnosť 1: Na ohraničenie zástupného slova alebo obsiahlych fráz použite štýl kódu. Môžete napríklad použiť jednoduché opačné apostrofy ' pre formátovanie vnoreného kódu pre jednu frázu alebo trojité zaškrtnutia "" pre formátovanie ohradené kódom.

`az group delete -n <ResourceGroupName>`

Vykreslené ako:

az group delete -n <ResourceGroupName>

alebo

Možnosť 2: Na to, aby ste sa vyhli znakom lomenej zátvorky v jazyku Markdown, napríklad \< a \>, použite znak \ opačnej lomky. Aj keď sa vyžaduje iba prvý únik na ľavom lomenej zátvorke \< , ukončovanie záverečnej zátvorky \> funguje príliš z dôvodu konzistencie. Vykreslený jazyk HTML nezobrazuje čitateľovi únikový znak:

az group delete -n \<ResourceGroupName\>

Vykreslené ako:

odstránenie skupiny az -n <ResourceGroupName>

Informujte čitateľa o zástupnom symbole: V texte, ktorý predchádza príkladom zástupného objektu, vysvetlite čitateľovi, že text v hranatých zátvorkách musí byť odstránený a nahradený skutočnými hodnotami. Odporúčame použiť kurzívu pre vstup používateľa. Kurzívu môžete formátovať v rámci vloženého kódu v lomenej zátvorke:

V nasledujúcom príklade nahraďte text <ResourceGroupName> zástupného objektu názvom vlastnej skupiny prostriedkov.

Ako syntaktické zástupné symboly neodporúčame používať zložené zátvorky { }. Čitatelia si môžu zmiasť zástupné symboly zložených zátvorok s rovnakým zápisom, ktorý sa používa v:

• Vymeniteľný text
• Formátovať reťazce
• Interpolácia reťazca
• Šablóny textu
• Podobné konštrukcie programovania

Puzdro a medzery: názvy zástupných symbolov môžete oddeliť spojovníkmi ("prípad kebab") alebo podčiarknutím, alebo to môžete urobiť pomocou písmen typu Pascal. Prípad kebab môže generovať syntaktické chyby a znaky podčiarknutia môžu byť v rozpore so podčiarknutím. Všetky kryty môžu byť v konflikte s pomenovanými konštantami v mnohých jazykoch, ale môžu tiež upriamiť pozornosť na názov zástupného objektu.

<Resource-Group-Name> alebo <ResourceGroupName>

Nadpisy a text prepojenia

Nepoužívajte vnorené štýly, ako je napríklad kurzíva alebo tučné písmo, na nadpisy alebo text hypertextového prepojenia.

Prečo?

Ľudia sa spoliehajú na štandardný text hypertextového prepojenia pri identifikácii textových prvkov ako prepojení na kliknutie. Napríklad štýl prepojenia ako kurzívy môže zakryť skutočnosť, že text je prepojením. Nadpisy majú vlastné štýly a ak do nich primiešate iné štýly, nevyzerá to dobre.

Príklady nadpisov a textu prepojenia

• Takto: Súbor function.json vygeneruje balík NuGet Microsoft.NET.Sdk.Functions.

• Nie takto: Súbor function.json vygeneruje balík NuGet Microsoft.NET.Sdk.Functions.

• Takto:

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

• Nie takto:

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

Klávesy a klávesové skratky

Pri odkazovaní na klávesy alebo kombinácie klávesov postupujte podľa týchto zásad:

• Prvé písmeno názvu klávesov zadávajte veľké.
• Pred názvami klávesov obklopte značky <kbd> HTML a </kbd> .
• Používajte označenie +na spojenie kľúčov, ktoré používateľ naraz vyberie.

Príklady klávesov a klávesových skratiek

• Takto: Vyberte kombináciu klávesov Alt+Ctrl+S.
• Nie takto: Stlačte kombináciu klávesov ALT + CTRL + S.
• Nie takto: Stlačte kláves ALT+CTRL+S.

Výnimky

Pokyny týkajúce sa štýlu nie sú pevné pravidlá. V kontextoch, v ktorých škodia čitateľnosti, použite iný postup. Napríklad tabuľka HTML s väčšinou prvkov kódu môže vyzerať príliš preplnene, ak v nej všade prevláda štýl kódu. V takomto kontexte môžete vybrať štýl tučného písma.

Ak vyberiete štýl alternatívneho textu tam, kde sa zvyčajne očakáva kód, uistite sa, či je v poriadku, aby sa text preložil do lokalizovaných verzií článku. Kód je jediný štýl, ktorý automaticky zabraňuje prekladu. V prípade, že chcete zabrániť lokalizácii bez použitia štýlu kódu, pozrite si tému Nelokalizované reťazce.