Sdílet prostřednictvím

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. Pokud není prvek formátování textu popsaný v těchto doprovodných materiálech, přečtěte si průvodce správným stylem psaní microsoftu. Následující články obsahují podrobné pokyny k formátování textu:

Prvky uživatelského rozhraní

Prvky uživatelského rozhraní, jako jsou položky nabídky, názvy dialogů a názvy textových polí, by měly být tučné písmo.

  • Toto: V Průzkumníku ř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.

Názvy repozitářů a větví Gitu

Při výběru nebo zadání pokynů použijte tučný text pro úložiště Git nebo názvy větví.

  • Toto: V nabídce větve vyberte hlavní.

  • Toto ne: V nabídce větve vyberte „main“.

Nové představení termínů

K zavedení nového termínu spolu s definicí nebo vysvětlením použijte kurzívu. Při prvním použití použijte nový termín kurzívou a pak pro definici nebo vysvětlení použijte běžný text.

  • 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.

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č? Některá vodítka stylu určují tučné písmo pro mnoho z těchto textových prvků. 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.csprojdotnet 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

V textu odstavce nebo procedurálních krocích použijte kurzívu pro zástupný text, který uživatelé nahradí vlastními informacemi.

  • Toto: Zadejte heslo.

  • Ne toto: Zadejte „heslo“.

  • Toto: Zadejte heslo -p.

  • Toto není: Zadejte -p heslo

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ém textu: V textu, který předchází příkladům zástupných symbolů, vysvětlete čtenáři, že text v hranatých závorkách by měl být 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. Použití všech velkých písmen může kolidovat s pojmenovanými konstantami v mnoha jazycích, ale může také upoutat pozornost na název zástupce.

<Resource-Group-Name> nebo <ResourceGroupName>

Nadpisy

U nadpisů nepoužívejte vložený styl, jako je kurzíva, tučné písmo nebo vložený styl kódu.

Proč? Nadpisy mají vlastní styly a kombinování jiných stylů vytváří nekonzistence.

  • Toto: Importujte balíček Microsoft.NET.Sdk.Functions

  • Není to: Import balíčku Microsoft.NET.Sdk.Functions

Text odkazu

Text odkazu nestylizujte pomocí kurzívy nebo tučného písma.

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. Změna odkazu na kurzívu může například ztížit rozpoznání, že se jedná o odkaz.

Ne: Balíček NuGet Microsoft.NET.Sdk.Functions vygeneruje soubor function.json.

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

Konzistentní pokyny pro styl vytvářejí spolehlivé prostředí pro zákazníky a zjednodušují proces vytváření. Výjimky z těchto pokynů je nutné pečlivě zvážit.

Pokud výjimka zahrnuje použití alternativního stylu textu, který obvykle vyžaduje použití kódu, ověřte, zda je vhodné přeložit text v lokalizovaných verzích článku. Pokyny pro scénáře, v nichž se má zabránit lokalizaci bez použití stylu kódu, najdete v části Nelokalizované řetězce.