Sdílet prostřednictvím

Pravidla formátování textu

  • Článek

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.

Bold

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

  • Toto: V Průzkumník řešení klikněte pravým tlačítkem myši na uzel projektu a pak vyberte Přidat > novou položku.
  • Není to: V Průzkumník řešení klikněte pravým tlačítkem myši na uzel projektu a pak vyberte Přidat > novou položku.
  • Ne: V Průzkumník řešení klikněte pravým tlačítkem myši 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: Ve službě App Service se aplikace spouští v plánu služby App Service. Plán služby App Service definuje sadu výpočetních prostředků pro spuštění webové aplikace.
  • Toto: Nahraďte kód v HttpTriggerCSharp.cs následujícím kódem.
  • Není to: Nahraďte kód HttpTriggerCSharp.cs následujícím kódem.
  • Toto: Jako název zadejte ContosoUniversity a pak vyberte Přidat.
  • Není to: Jako název zadejte ContosoUniversity a pak 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ý ") nebo ohraničenými bloky kódu (obklopené ''' ), které pokrývají 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žijte lomítka v cestách k souborům, pokud jsou podporovány na všech platformách. Pomocí zpětných lomítek můžete ilustrovat příkazy, které běží ve Windows, pokud se podporují jenom zpětná lomítka. Například lomítka fungují na rozhraní .NET CLI na všech platformách, takže byste místo dotnet build foldername/filename.csproj 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")
    ```

  • Ne toto: Do databáze se neposílají žádné příkazy pomocí příkazů, které pouze mění 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ý úhlovými závorkami (menší než a větší než < > znaky).

Možnost 1: K ohraničení zástupného slova nebo zahrnující fráze použijte styl kódu. Můžete například použít jednoduché backticky 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: Pomocí znaku \ zpětného lomítka uvozujte znaky úhlové závorky v Markdownu, například \< a \>. Zatímco je vyžadován pouze první řídicí znak levé hranaté závorky \< , uzavírací hranatá závorka \> funguje také pro konzistenci. Vykreslený kód HTML nezobrazuje řídicí znak pro čtenáře:

az group delete -n \<ResourceGroupName\>

Vykresleno jako:

az group delete -n <ResourceGroupName>

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

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

Upozornění

Web Microsoft Learn nevykreslí <zástupný> text, který používá úhlové závorky v případech, kdy hranaté závorky nejsou správně uchycené nebo text není formátovaný kódem. Proces sestavení Microsoft Learn interpretuje <zástupnou> frázi jako značku HTML, která může být pro prohlížeč čtenáře nebezpečná, a označí ji jako nepovolenou značku html-tag. V sestavě sestavení se zobrazí návrh a v případě, že k tomu dojde, se ve výstupu stránky Microsoft Learn nevykreslí zástupné slovo.

Pokud se chcete vyhnout ztrátě obsahu u zástupných symbolů, použijte code formátování nebo řídicí znaky (\<\>) popsané výše.

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

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

Velikost písmen a mezery: Zástupné názvy můžete oddělit pomocí pomlček ("velká písmena kebab") nebo podtržítka, nebo to můžete udělat pomocí písmen Pascal. Případ Kebabu může generovat chyby syntaxe a podtržítka můžou být v konfliktu s podtržením. All-caps může kolidovat s pojmenovanými konstantami v mnoha jazycích, i když může 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, jako je kurzíva 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. Styling odkazu jako kurzívy může například 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

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íčů ohraniujte značkami <kbd> HTML.</kbd>
  • Pomocí klávesy +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.
  • Ne toto: Stiskněte kombinaci kláves ALT+CTRL+S.
  • Ne tohle: Hit 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.