Szövegformázási útmutató

A félkövér, dőlt és kód stílusok megfelelő és egységes használata hozzájárul a szöveg jobb olvashatóságához, és segít a félreértések elkerülésében is.

Félkövér

A felhasználói felület különféle elemeinél, például menün belüli kiválasztásoknál, párbeszédablakok nevénél vagy beviteli mezőknél használjon félkövér formázást.

Példák

• Ez: A Megoldáskezelő kattintson a jobb gombbal a projektcsomópontra, majd válassza az Új elem hozzáadása > lehetőséget.
• Nem ez: A Megoldáskezelő kattintson a jobb gombbal a projektcsomópontra, majd válassza az Új elem hozzáadása > lehetőséget.
• Nem ez: A Megoldáskezelő kattintson a jobb gombbal a projektcsomópontra, majd válassza az Új elem hozzáadása > lehetőséget.

Dőlt

Használjon dőlt formázást a következőkhöz:

• Olyan új kifejezések bevezetésénél, amelyeket definícióval vagy magyarázattal is ellát.
• Fájlnevek, mappanevek, elérési útvonalak.
• Felhasználói bevitel.

Példák

• Így helyes: Az App Service-ben az alkalmazások az App Service-csomagban futnak. Az App Service-csomag az alkalmazás futtatásához használható számítási erőforrásokat határozza meg.
• Nem ez: Az App Service-ben egy alkalmazás egy "App Service-csomagban" fut. Az App Service-csomagok számítási erőforrások készletét határozzák meg egy webalkalmazás futtatásához.
• Ez: Cserélje le a HttpTriggerCSharp.cs kódját a következő kódra.
• Nem ez a következő: Cserélje le a kódot HttpTriggerCSharp.cs a következő kódra.
• Ez: Adja meg a ContosoUniversity nevet, majd válassza a Hozzáadás lehetőséget.
• Nem ez: Adja meg a "ContosoUniversity" nevet a névhez, majd válassza a Hozzáadás lehetőséget.

Kód stílus

A kód stílust használja a következőkhöz:

• Kódrészleteknél, például metódusok és tulajdonságok nevei vagy nyelvi kulcsszavak.
• SQL parancsok
• NuGet-csomagok nevei
• Parancssori parancsok*
• Adatbázisok tábláinak és oszlopainak a nevei
• Nem honosítandó erőforrásnevek (például virtuális gépek nevei)
• Nem kattinthatónak szánt URL-ek nevei

Miért? A régebbi stílusú útmutatók ezen szövegelemek közül számos esetében félkövér formázást határoznak meg. A legtöbb cikket azonban honosítják, és a kód stílus arra utasítja a fordítót, hogy a szöveg egy részét hagyja lefordítatlanul.

A kódstílus lehet beágyazott (") vagy több sorra kiterjedő ( "" körülvett) kódblokk. A hosszabb kódrészleteket és elérési útvonalakat körülhatárolt kódtömbökben jelenítse meg.

* A parancssori parancsokban használjon perjeleket a fájlelérési utakban, ha azokat minden platform támogatja. Fordított perjelekkel szemléltetheti a Windowson futó parancsokat, ha csak fordított perjelek támogatottak. A perjelek például minden platformon működnek a .NET CLI-n, ezért ahelyett, hogy használná dotnet build foldername/filename.csproj dotnet build foldername\filename.csproj.

Beágyazott stílusokat használó példák

• Így helyes: Az Entity Framework alapbeállítás szerint elsődleges kulcsként értelmezi azt a tulajdonságot, amelynek a neve Id vagy ClassnameID.
• Így nem helyes: Az Entity Framework alapbeállítás szerint elsődleges kulcsként értelmezi azt a tulajdonságot, amelynek a neve Id vagy ClassnameID.
• Így helyes: A Microsoft.EntityFrameworkCore csomag futásidejű támogatást biztosít az EF Core számára.
• Így nem helyes: a Microsoft.EntityFrameworkCore csomag futásidejű támogatást biztosít az EF Core számára.

Példák körülhatárolt kódblokkokra

• Így helyes: Az adatbázisba nem lesznek parancsok küldve olyan kifejezések használatakor, amelyek csupán egy IQueryable-t módosítanak, mint például az alábbi kód:

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

• Nem ez: A rendszer nem küld parancsokat az adatbázisnak olyan utasítások alapján, amelyek egyszerűen módosítanak egy IQueryable-t, például var students = context. Students.Where(s => s.LastName == "Davolio").

• Így helyes: Ha például a Get-ServiceLog.ps1 szkriptet szeretné a C:\Scripts könyvtárban futtatni, írja be az alábbi szöveget:

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

• Így nem helyes: Ha például a Get-ServiceLog.ps1 szkriptet szeretné futtatni a C:\Scripts könyvtárban, akkor ezt írja be: "C:\Scripts\Get-ServiceLog.ps1."

• Az összes körülhatárolt kódrészletnek jóváhagyott nyelvcímkével kell rendelkeznie. A támogatott nyelvcímkék listáját lásd: Kód beágyazása dokumentumokba.

Helyőrzők

Ha azt szeretné, hogy a felhasználó lecserélje egy bemeneti sztring egy részét a saját értékeire, használjon szögletes zárójelekkel jelölt helyőrző szöveget (karakternél < > kisebb és nagyobb).

1. lehetőség: Használjon kódformázást a helyőrző szó vagy az azt magában foglaló kifejezés körül. Használhat például egyetlen háttértűt egyetlen kifejezés beágyazott kódjának formázásához, vagy a kódkerítésű formázáshoz háromjeles """ jelölést.

`az group delete -n <ResourceGroupName>`

A következő módon jelenik meg:

az group delete -n <ResourceGroupName>

vagy

2. lehetőség: Használjon fordított perjel karaktert \ a Markdown szögletes zárójelkarakterek ( például \< és \>. Bár a bal oldali szögletes zárójelen \< csak az első kimenekítés szükséges, a záró zárójel \> elhagyása a konzisztencia szempontjából is működik. A renderelt HTML nem jeleníti meg a feloldó karaktert az olvasónak:

az group delete -n \<ResourceGroupName\>

A következő módon jelenik meg:

az group delete -n <ResourceGroupName>

Tájékoztassa az olvasót a helyőrzőről: Az ilyen helyőrző példákat megelőző szövegben magyarázza el az olvasónak, hogy a szögletes zárójelben lévő szöveget el kell távolítani, és valós értékekkel kell helyettesíteni. A dőlt betűs írásjelek használatát javasoljuk a felhasználói bevitelhez. Dőlt betűket formázhat szögletes zárójeles beágyazott kódban:

Az alábbi példában cserélje le a helyőrző szöveget <ResourceGroupName> a saját erőforráscsoport nevére.

Nem javasoljuk a kapcsos zárójelek { } használatát szintaktikai helyőrzőkként. Az olvasók összekeverhetik a kapcsos zárójelek helyőrzőit ugyanazzal a jelöléssel, amelyet a következőben használnak:

• Cserélhető szöveg
• Sztringek formázása
• Sztring interpolációja
• Szövegsablonok
• Hasonló programozási szerkezetek

Burkolat és térköz: Elválaszthatja a helyőrző neveket kötőjelekkel ("kebab-eset") vagy aláhúzásjelekkel, vagy Pascal-esettel is megteheti. A Kebab-eset szintaxishibákat okozhat, és az aláhúzások ütközhetnek az aláhúzással. Az all-caps számos nyelven ütközhet az elnevezett állandókkal, de felhívhatja a figyelmet a helyőrző nevére is.

<Resource-Group-Name> vagy <ResourceGroupName>

Címsorok és hivatkozásszövegek

Ne alkalmazzon beágyazott stílust, például dőlt vagy félkövér stílust címsorokra vagy hivatkozásszövegekre.

Hogy miért?

Az emberek a hiperhivatkozások szokásos megjelenése alapján ismerik fel, hogy mely szövegrész kattintható hivatkozás. Ha például dőlt betűsként formáz egy hivatkozást, az elhomályosíthatja azt a tényt, hogy a szöveg hivatkozás. A címsorok saját stílussal rendelkeznek, így zavaró lehet, ha másféle stílust is felhasznál bennük.

Példák címsorokra és hivatkozásszövegekre

• Ez: A function.json fájlt a Microsoft.NET.Sdk.Functions NuGet-csomag hozza létre.

• Nem ez: A function.json fájlt a Microsoft.NET.Sdk.Functions NuGet-csomag hozza létre.

• Így helyes:

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

• Így nem helyes:

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

Billentyűk és billentyűparancsok

Billentyűkre vagy billentyűkombinációkra való hivatkozáskor kövesse az alábbi konvenciókat:

• A billentyűk neveinek első betűje legyen nagybetű.
• Vegye körül a kulcsneveket és </kbd> a <kbd> HTML-címkéket.
• A "+" billentyűkombinációval összekapcsolhatja a felhasználó által egyidejűleg kiválasztott kulcsokat.

Példák billentyűkre és billentyűparancsokra

• Ez: Válassza az Alt Ctrl S billentyűkombinációt++.
• Nem ez a következő: Nyomja le az ALT+CTRL+S billentyűkombinációt.
• Nem ez: Hit ALT+CTRL+S.

Kivételek

A stílusirányelvek nem merev szabályok. Olyan kontextusban, ahol az olvashatóság rovására mennek, járjon el másként. Egy többnyire kódrészleteket tartalmazó HTML-táblázat például túlzsúfoltnak tűnhet, ha mindenütt kód stílust alkalmaz benne. Ebben a kontextusban félkövér stílust is választhat.

Ha ott alkalmaz helyettesítő stílust, ahol normális esetben a kód stílus indokolt, ügyeljen rá, hogy ez nem okoz problémát a cikk honosított verzióiban fordítandó szövegében. A kód stílus ugyanis az egyetlen olyan stílus, amely automatikusan megakadályozza a fordítást. Olyan helyzetekben, amelyekben a kód stílusa nélkül szeretné megakadályozni a honosítást, lásd: Nem honosított sztringek.