Pravidla formátování textu

Konzistentní a správné použití tučného písma, kurzívy a stylu kódu u textových prvků zlepšuje čitelnost a pomáhá vyhnout se nedorozuměním.

Tučné

Používá se pro prvky uživatelského rozhraní, jako jsou například možnosti v nabídkách, názvy dialogových oken a názvy vstupních polí.

Příklady

• Správně: V Průzkumník řešení klikněte pravým tlačítkem na uzel projektu a pak vyberte Přidat > novou položku.
• Není to tak: V Průzkumník řešení klikněte pravým tlačítkem na uzel projektu a pak vyberte Přidat > novou položku.
• Není to tak: V Průzkumník řešení klikněte pravým tlačítkem na uzel projektu a pak vyberte Přidat > novou položku.

Kurzíva

Kurzíva se používá pro:

• Představení nových termínů společně s definicí nebo vysvětlením
• Názvy souborů, názvy složek, cesty
• Vstup uživatele

Příklady

• Správně: Ve službě App Service běží aplikace v plánu služby App Service. Plán služby App Service definuje sadu výpočetních prostředků, ve které má běžet webová aplikace.
• Ne: V App Service běží aplikace v "plánu App Service". Plán App Service definuje sadu výpočetních prostředků, na kterých má webová aplikace běžet.
• Správně: Nahraďte kód v souboru HttpTriggerCSharp.cs následujícím kódem.
• Špatně: Nahraďte kód v HttpTriggerCSharp.cs následujícím kódem.
• Správně: Jako Název zadejte ContosoUniversity a potom vyberte Přidat.
• Špatně: Jako Název zadejte „ContosoUniversity“ a potom vyberte Přidat.

Styl kódu

Styl kódu se používá pro:

• Prvky kódu, jako jsou názvy metod, názvy vlastností a klíčová slova jazyka
• SQL příkazy
• Názvy balíčků NuGet
• Příkazy příkazového řádku*
• Názvy tabulek a sloupců databáze
• Názvy prostředků, které se nemají lokalizovat (například názvy virtuálních počítačů)
• Adresy URL, na které nemá být možné kliknout

Proč? Ve starších pokynech ke stylu je u mnoha těchto textových prvků uvedené, že se mají psát tučně. Většina dokumentace Microsoftu se ale lokalizuje (překládá do jiných jazyků) a styl kódu napovídá překladateli, že má danou část textu nechat nepřeloženou.

Styl kódu může být vložený (obklopený znakem ) nebo oplocený blok kódu (obklopený znakem ), které překlenují více řádků. Delší fragmenty kódu a cesty umístěte do ohraničených bloků kódu.

* V příkazech příkazového řádku používejte lomítka v cestách k souborům, pokud jsou podporovaná na všech platformách. Pomocí zpětných lomítek můžete ilustrovat příkazy, které běží ve Windows, když jsou podporována pouze zpětná lomítka. Například lomítka fungují v rozhraní .NET CLI na všech platformách, takže byste použili dotnet build foldername/filename.csproj místo dotnet build foldername\filename.csproj.

Příklady použití přiřazených stylů

• Správně: Ve výchozím nastavení interpretuje Entity Framework vlastnost s názvem Id nebo ClassnameID jako primární klíč.
• Špatně: Ve výchozím nastavení interpretuje Entity Framework vlastnost s názvem Id nebo ClassnameID jako primární klíč.
• Správně: Balíček Microsoft.EntityFrameworkCore podporuje runtime pro jádro EF Core.
• Špatně: Balíček Microsoft.EntityFrameworkCore podporuje runtime jádra EF Core.

Příklady ohraničených bloků kódu

• Správně: Do databáze se neposílají žádné příkazy na základě výrazů, které mění pouze IQueryable, jako například následující kód:

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

• Není to tak: Do databáze se neposílají žádné příkazy pomocí příkazů, které mění pouze IQueryable, například var students = context. Students.Where(s => s.LastName == "Davolio").

• Správně: Pokud chcete například spustit skript Get-ServiceLog.ps1 v adresáři C:\Scripts, zadejte:

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

• Špatně: Pokud chcete například spustit skript Get-ServiceLog.ps1 v adresáři C:\Scripts, zadejte: „C:\Scripts\Get-ServiceLog.ps1.“

• Všechnyohraničené bloky kódu musí mít schválenou značku jazyka. Seznam podporovaných značek najdete v tématu Jak do dokumentů vkládat kód.

Zástupné symboly

Pokud chcete, aby uživatel nahradil část vstupního řetězce vlastními hodnotami, použijte zástupný text označený lomenými závorkami (menší než < a větší než > znaky).

Možnost 1: Použijte styl kódu k ohraničení zástupného slova nebo zahrnující fráze. Můžete například použít jednoduchá zpětná zaškrtnutí pro formátování vloženého kódu pro jednu frázi nebo trojitá zaškrtnutí pro formátování ohraničené kódem.

`az group delete -n <ResourceGroupName>`

Vykresleno jako:

az group delete -n <ResourceGroupName>

nebo

Možnost 2: Znak zpětného lomítka \ použijte k řídicímu znaku lomené závorky v Markdownu, například \< a \>. I když se vyžaduje pouze první řídicí závorka v levé úhlové závorce \< , pro zajištění konzistence funguje také uzavírací hranatá závorka \> . Vykreslený kód HTML nezobrazuje řídicí znak pro čtenáře:

az group delete -n \<ResourceGroupName\>

Vykresleno jako:

az group delete -n <Název_skupiny_prostředků>

Informujte čtenáře o zástupné znaméně: V textu předcházejícím příkladům zástupných symbolů vysvětlete čtenáři, že text v hranatých závorkách musí být odstraněn a nahrazen skutečnými hodnotami. Pro vstup uživatele doporučujeme používat kurzívu. Kurzívu můžete formátovat v kódu v šikmé závorce:

V následujícím příkladu nahraďte zástupný text <ResourceGroupName> názvem vlastní skupiny prostředků.

Upozornění

Web Microsoft Learn nevykresluje <zástupný> text, který používá ostré závorky, v případech, kdy nejsou správně uchycené závorky nebo text není formátován kódem. Proces sestavení Microsoft Learn interpretuje <zástupnou> frázi jako značku HTML, která by mohla být nebezpečná pro prohlížeč čtenáře, a označí ji jako disallowed-html-tag. V sestavě sestavení uvidíte návrh a v takovém případě se ve výstupu stránky Microsoft Learn nevykreslí zástupné slovo.

Pokud chcete předejít ztrátě obsahu u zástupných symbolů, použijte code formátování nebo řídicí znaky (\<\>), jak je popsáno výše.

Nedoporučujeme používat složené závorky { } jako syntaktické zástupné symboly. Čtenáři si můžou splést zástupné závorky se stejným zápisem, který se používá v:

• Nahraditelný text
• Formátování řetězců
• Interpolace řetězců
• Textové šablony
• Podobné programovací konstrukce

Velká písmena a mezery: Zástupné názvy můžete oddělit pomlčkami ("velká písmena kebabu") nebo podtržítky, nebo to můžete udělat pomocí velkých a malých písmen jazyka Pascal. Případ Kebabu může generovat chyby syntaxe a podtržítka můžou být v konfliktu s podtržením. Všechna velká písmena můžou být v konfliktu s pojmenovanými konstantami v mnoha jazycích, ale můžou také upoutat pozornost na název zástupného symbolu.

<Resource-Group-Name> nebo <ResourceGroupName>

Záhlaví a text odkazu

U nadpisů nebo textu hypertextového odkazu nepoužívejte vložený styl, například kurzívu nebo tučné písmo.

Proč?

Lidé očekávají, že textové prvky, jako jsou odkazy, na které se dá kliknout, budou mít podobu standardního hypertextového odkazu. Například styl odkazu jako kurzívy může zakrýt skutečnost, že text je odkaz. Nadpisy mají svoje vlastní styly a kombinace s jinými styly nevypadají v nadpisech dobře.

Příklady nadpisů a textu odkazu

• Správně: Soubor function.json je generován balíčkem NuGet Microsoft.NET.Sdk.Functions.

• Není to tak: Soubor function.json je vygenerovaný balíčkem NuGet Microsoft.NET.Sdk.Functions.

• Správně:

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

• Špatně:

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

Klávesy a klávesové zkratky

Při odkazování na klávesy nebo jejich kombinace se řiďte těmito zvyklostmi:

• První písmeno v názvu klávesy pište velké.
• Názvy klíčů ohraničte značkami <kbd> HTML a </kbd> .
• Pomocí symbolu + se připojte ke klíčům, které uživatel vybere současně.

Příklady kláves a klávesových zkratek

• Toto: Vyberte Alt+Ctrl+S.
• Špatně: Stiskněte ALT+CTRL+S.
• Špatně: Zmáčkněte ALT+CTRL+S.

Výjimky

Pokyny týkající se stylu nejsou pevně daná pravidla. Tam, kde by docházelo k horší čitelnosti, zvolte jiná řešení. Pokud například použijete tabulku HTML u převážně kódových prvků, může to být díky všudypřítomnému stylu kódu poněkud nepřehledné. V tomto kontextu můžete použít tučné písmo.

V případě, že zvolíte jiný styl tam, kde se běžně používá kód, je potřeba zajistit, že v lokalizovaných verzích článku nebudou potíže s přeložením textu. Kód je jediný styl, který automaticky brání překládání. Pokyny pro scénáře, v nichž se má zabránit lokalizaci bez použití stylu kódu, najdete v části Nelokalizované řetězce.