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. Ha egy szövegformázási elemet nem fed le ez az útmutató, tekintse meg a Microsoft írásstílus-útmutatóját. Az alábbi cikkek részletes útmutatást nyújtanak a szövegformázáshoz:

• Gyakori szövegelemek formázása

• Szöveg formázása utasításokban

• Gyakori fejlesztői elemek formázása

Felhasználói felület elemei

A felhasználói felület elemeinek, például a menüelemeknek, a párbeszédpanelek neveinek és a szövegdobozok nevének félkövér szövegnek kell lenniük.

• Ez: A Megoldáskezelőben kattintson a jobb gombbal a projektcsomópontra, majd válassza azÚj elem>.

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

Git-adattár és ágnevek

A Git-adattár vagy ágnevek félkövér szöveggel jelölhetők ki vagy írhatók be az utasításokba.

• Ez: Az ág menüben válassza a fő lehetőséget.

• Nem ez: Az ág menüben válassza a "fő" lehetőséget.

Új kifejezésbevezetések

Dőlt szöveggel új kifejezést és definíciót vagy magyarázatot is bevezethet. Az első használatkor dőlt betűvel formázza az új kifejezést, majd használjon normál szöveget a definícióhoz vagy a magyarázathoz.

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

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? Néhány stíluskalauz félkövér szöveget ad meg sok ilyen szöveges elemhez. 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.csprojdotnet 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

Bekezdésszövegben vagy eljárási lépésekben dőlt betűvel írja be a helyőrző szöveget, amelyet a felhasználók a saját adataikkal helyettesítenek.

• Ez: Adja meg a jelszót

• Nem ez: Adja meg a "jelszó" kifejezést

• Ez: Adja meg a -pjelszót

• Nem ez: Adja meg a -p jelszót

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: A helyőrző példákat megelőző szövegben magyarázza el az olvasónak, hogy a 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.

Figyelemfelhívás

A Microsoft Learn webhely nem jeleníti meg <a szögletes zárójeleket használó helyőrző> szöveget olyan esetekben, amikor a szögletes zárójelek nem kerülnek ki megfelelően, vagy a szöveg nem kódformátumú. A Microsoft Learn összeállítási folyamata a <helyőrző> kifejezést HTML-címkeként értelmezi, amely veszélyes lehet az olvasó böngészőjére, és letiltott html-címkeként jelöli meg. A buildjelentésben megjelenik egy javaslat, és a helyőrző szó nem jelenik meg a Microsoft Learn lap kimenetében, ha ez történik.

A helyőrzők tartalomvesztésének elkerülése érdekében használja code a korábban ismertetett formázási vagy feloldó karaktereket (\<\>).

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. A teljes nagybetűs írásmód használata számos nyelven ütközhet az elnevezett állandókkal, bár felhívhatja a figyelmet a helyőrző névre is.

<Resource-Group-Name> vagy <ResourceGroupName>

Fejezetek

Ne alkalmazzon beágyazott stílust, például dőlt, félkövér vagy beágyazott kódstílust a címsorokra.

Miért? A címsorok saját stílusokkal rendelkeznek, és más stílusok keveredése inkonzisztenciákat eredményez.

• Ez: A Microsoft.NET.Sdk.Functions csomag importálása

• Nem ez: A Microsoft.NET.Sdk.Functions csomag importálása

Hivatkozás szövege

Ne alkalmazzon beágyazott stílust, például dőlt vagy félkövér stílust, a link szövegére.

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őltként formáz egy hivatkozást, az elhomályosíthatja azt a tényt, hogy a szöveg hivatkozás.

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

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

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 következetes stílus irányelvei megbízható ügyfélélményt hoznak létre, és leegyszerűsítik a létrehozási folyamatot. Az irányelvek alóli kivételeket körültekintően kell figyelembe venni.

Ha a kivétel olyan alternatív szövegstílust használ, amely általában kódot hív meg, győződjön meg arról, hogy a szöveg lefordítása a cikk honosított verzióiban rendben van. Olyan helyzetekben, amelyekben a kód stílusa nélkül szeretné megakadályozni a honosítást, lásd: Nem honosított sztringek.