man-pages(7)
man-pages(7) – Konventioner för att skriva Linux man-sidor
NAMN
man-pages – konventioner för att skriva Linux man-sidor
SYNOPSIS
man [sektion] titel
BESKRIVNING
Denna sida beskriver de konventioner som bör användas när man skriver man-sidor för Linux man-pages-projektet, vilket dokumenterar användarutrymmets API som tillhandahålls av Linux-kärnan och GNU C-biblioteket. Projektet tillhandahåller således de flesta sidor i sektion 2, många av sidorna som visas i sektionerna 3, 4 och 7, och några av sidorna som visas i sektionerna 1, 5 och 8 på ett Linux-system. De konventioner som beskrivs på denna sida kan också vara användbara för författare som skriver man-sidor för andra projekt.
Sektioner i man-sidor
Manuella sektioner definieras traditionellt enligt följande:
1. **Användarkommandon (Program)**
Kommandon som kan exekveras av användaren från en shell.
2. **Systemanrop**
Funktioner som omsluter operationer utförda av kärnan.
3. **Biblioteksanrop**
Alla biblioteksfunktioner exklusive systemanropsomslag (de flesta libc-funktioner).
4. **Speciella filer (enheter)**
Filer som finns i /dev som ger åtkomst till enheter via kärnan.
5. **Filformat och konfigurationsfiler**
Beskriver olika läsbara filformat och konfigurationsfiler.
6. **Spel**
Spel och roliga små program som finns tillgängliga på systemet.
7. **Översikter, konventioner och diverse**
Översikter eller beskrivningar av olika ämnen, konventioner och protokoll, teckenuppsättningsstandarder, standardfilsystemlayout och diverse andra saker.
8. **Systemhanteringskommandon**
Kommandon som mount(8), varav många endast root kan exekvera.
Makropaket
Nya man-sidor bör märkas upp med groff an.tmac-paketet som beskrivs i man(7). Detta val är främst för konsekvensens skull: den stora majoriteten av befintliga Linux man-sidor är markerade med dessa makron.
Konventioner för källkodsstruktur
Begränsa gärna källkodens linjelängd till högst cirka 75 tecken där det är möjligt. Detta hjälper till att undvika radbrytning i vissa e-postklienter när patchar skickas in inline.
Titelrad
Det första kommandot i en man-sida bör vara ett TH-kommando:
.TH titel sektion datum källa manual-sektion
Argumenten för kommandot är följande:
- titel: Titeln på man-sidan, skriven med versaler (t.ex. MAN-PAGES). - sektion: Sektionsnumret där man-sidan ska placeras (t.ex. 7). - datum: Datum för den senaste icke-triviala ändringen som gjordes i man-sidan. Datum bör skrivas i formatet ÅÅÅÅ-MM-DD. - källa: Namnet och versionen på projektet som tillhandahåller man-sidan (nödvändigtvis inte paketet som tillhandahåller funktionaliteten). - manual-sektion: Normalt bör detta vara tomt, eftersom standardvärdet kommer att vara bra.
Sektioner inom en man-sida
Nedan visas konventionella eller föreslagna sektioner. De flesta man-sidor bör inkludera åtminstone de markerade sektionerna. Ordna en ny man-sida så att sektionerna placeras i den ordning som visas i listan.
- NAME - LIBRARY [Normalt endast i sektionerna 2, 3] - SYNOPSIS - CONFIGURATION [Normalt endast i sektion 4] - DESCRIPTION - OPTIONS [Normalt endast i sektionerna 1, 8] - EXIT STATUS [Normalt endast i sektionerna 1, 8] - RETURN VALUE [Normalt endast i sektionerna 2, 3] - ERRORS [Vanligen endast i sektionerna 2, 3] - ENVIRONMENT - FILES - ATTRIBUTES [Normalt endast i sektionerna 2, 3] - VERSIONS [Normalt endast i sektionerna 2, 3] - STANDARDS - HISTORY - NOTES - CAVEATS - BUGS - EXAMPLES - AUTHORS [Avrådes] - REPORTING BUGS [Används inte i man-pages] - COPYRIGHT [Används inte i man-pages] - SEE ALSO
Där en traditionell rubrik skulle vara lämplig, vänligen använd den; denna typ av konsekvens kan göra informationen lättare att förstå. Om du måste kan du skapa egna rubriker om de gör saker lättare att förstå (detta kan vara särskilt användbart för sidor i sektionerna 4 och 5). Men innan du gör detta, överväg om du kan använda de traditionella rubrikerna, med några undersektioner (.SS) inom dessa sektioner.
Följande lista utvecklar innehållet i var och en av ovanstående sektioner.
NAME
Namnet på denna man-sida.
Se man(7) för viktiga detaljer om raden/raderna som ska följa efter .SH NAME-kommandot. Alla ord i denna rad (inklusive ordet omedelbart efter "\-") bör vara med gemener, förutom där engelska eller tekniska terminologiska konventioner dikterar annat.
LIBRARY
Biblioteket som tillhandahåller en symbol.
Det visar det vanliga namnet på biblioteket, och inom parentes namnet på biblioteksfilen och, om det behövs, länkarflaggan som behövs för att länka ett program mot det: (libfoo[, -lfoo]).
SYNOPSIS
En kort sammanfattning av kommandots eller funktionens gränssnitt.
För kommandon visar detta syntaxen för kommandot och dess argument (inklusive alternativ); fetstil används för text som den är och kursiv används för att indikera utbytbara argument. Hakparenteser ([]) omger valfria argument, vertikala streck (|) separerar val, och ellipser (...) kan upprepas. För funktioner visar det eventuella nödvändiga datadeklarationer eller #include-direktiv, följt av funktionsdeklarationen.
Där en funktionsmakro måste definieras för att få deklarationen av en funktion (eller en variabel) från en header-fil, bör SYNOPSIS indikera detta, som beskrivs i feature_test_macros(7).
CONFIGURATION
Konfigurationsdetaljer för en enhet.
Denna sektion förekommer normalt endast i sektion 4.
DESCRIPTION
En förklaring av vad programmet, funktionen eller formatet gör.
Diskutera hur det interagerar med filer och standard indata, och vad det producerar på standard utdata eller standard fel. Uteslut interna detaljer och implementationsdetaljer om de inte är kritiska för att förstå gränssnittet. Beskriv det vanliga fallet; för information om kommandoradsalternativ för ett program, använd sektionen OPTIONS.
När du beskriver nytt beteende eller nya flaggor för ett systemanrop eller biblioteksfunktion, var noga med att notera kärn- eller C-biblioteksversionen som introducerade förändringen. Den föredragna metoden att notera denna information för flaggor är som en del av en .TP-lista, i följande form (här för en ny systemanropsflagga):
XYZ_FLAG (sedan Linux 3.7)
Beskrivning av flaggan...
Att inkludera versionsinformation är särskilt användbart för användare som är begränsade till att använda äldre kärn- eller C-biblioteksversioner (vilket är typiskt i inbyggda system, till exempel).
OPTIONS
En beskrivning av kommandoradsalternativ som accepteras av ett program och hur de ändrar dess beteende.
Denna sektion bör endast förekomma för man-sidor i sektionerna 1 och 8.
EXIT STATUS
En lista över möjliga utgångsstatusvärden för ett program och de villkor som orsakar att dessa värden returneras.
Denna sektion bör endast förekomma för man-sidor i sektionerna 1 och 8.
RETURN VALUE
För man-sidor i sektionerna 2 och 3 ger denna sektion en lista över de värden som biblioteksrutinen kommer att returnera till anroparen och de villkor som orsakar att dessa värden returneras.
ERRORS
För man-sidor i sektionerna 2 och 3 är detta en lista över de värden som kan placeras i errno vid ett fel, tillsammans med information om orsaken till felen.
Där flera olika villkor producerar samma fel, är den föredragna metoden att skapa separata listposter (med dubbla felnamn) för var och en av villkoren. Detta gör de separata villkoren tydliga, kan göra listan lättare att läsa, och tillåter metainformation (t.ex. kärnversion där villkoret först blev tillämpligt) att lättare markeras för varje villkor.
Fellistan bör vara i alfabetisk ordning.
ENVIRONMENT
En lista över alla miljövariabler som påverkar programmet eller funktionen och hur de påverkar det.
FILES
En lista över de filer som programmet eller funktionen använder, såsom konfigurationsfiler, startfiler och filer som programmet direkt arbetar på.
Ange hela sökvägen till dessa filer, och använd installationsprocessen för att modifiera katalogdelen så att den matchar användarpreferenser. För många program är standardinstallationsplatsen i /usr/local, så din basman-sida bör använda /usr/local som bas.
ATTRIBUTES
En sammanfattning av olika attribut för funktionen/funktionerna som dokumenteras på denna sida. Se attributes(7) för ytterligare detaljer.
VERSIONS
En sammanfattning av system där API:et fungerar annorlunda, eller där det finns ett liknande API.
STANDARDS
En beskrivning av eventuella standarder eller konventioner som relaterar till funktionen eller kommandot som beskrivs av man-sidan.
De föredragna termerna att använda för de olika standarderna listas som rubriker i standards(7).
Denna sektion bör notera de aktuella standarder som API:et följer.
Om API:et inte styrs av några standarder men vanligtvis finns på andra system, notera dem. Om anropet är Linux-specifikt eller GNU-specifikt, notera detta. Om det är tillgängligt i BSD-systemen, notera det.
Om denna sektion endast består av en lista över standarder (vilket den ofta gör), avsluta listan med en punkt ('.').
HISTORY
En kort sammanfattning av Linux-kärnans eller glibc-versionerna där ett systemanrop eller en biblioteksfunktion dök upp, eller förändrades avsevärt i sin funktion.
Som en allmän regel bör varje nytt gränssnitt inkludera en HISTORY-sektion i sin man-sida. Tyvärr inkluderar många befintliga man-sidor inte denna information (eftersom det inte fanns någon policy för att göra det när de skrevs). Patchar för att åtgärda detta är välkomna, men ur perspektivet för programmerare som skriver ny kod spelar denna information förmodligen bara roll i fallet med kärngränssnitt som har lagts till i Linux 2.4 eller senare (d.v.s. förändringar sedan Linux 2.2), och biblioteksfunktioner som har lagts till i glibc sedan glibc 2.1 (d.v.s. förändringar sedan glibc 2.0).
Man-sidan syscalls(2) ger också information om kärnversioner där olika systemanrop först dök upp.
Gamla versioner av standarder bör nämnas här, snarare än i STANDARDS, till exempel SUS, SUSv2 och XPG, eller SVr4 och 4.xBSD-implementationsstandarder.
NOTES
Diverse anteckningar.
För man-sidor i sektionerna 2 och 3 kan det vara användbart att inkludera undersektioner (.SS) med namnen "Linux Notes" och "glibc Notes".
I sektion 2, använd rubriken "C library/kernel differences" för att markera anteckningar som beskriver skillnaderna (om några) mellan C-bibliotekets omslagsfunktion för ett systemanrop och det råa systemanropsgränssnittet som tillhandahålls av kärnan.
CAVEATS
Varningar om typiska användarmisstag av ett API, som inte utgör en API-bugg eller designfel.
BUGS
En lista över begränsningar, kända defekter eller olägenheter, och andra tveksamma aktiviteter.
EXAMPLES
Ett eller flera exempel som demonstrerar hur denna funktion, fil eller kommando används.
För detaljer om att skriva exempelprogram, se avsnittet "Example programs" nedan.
AUTHORS
En lista över författare av dokumentationen eller programmet.
Användning av en AUTHORS-sektion avråds starkt. Generellt är det bättre att inte belamra varje sida med en lista över (över tid potentiellt många) författare; om du skriver eller avsevärt ändrar en sida, lägg till en copyright-notis som en kommentar i källfilen. Om du är författaren av en drivrutin och vill inkludera en adress för att rapportera buggar, placera detta under sektionen BUGS.
REPORTING BUGS
Man-pages-projektet använder inte en REPORTING BUGS-sektion i man-sidor. Information om att rapportera buggar tillhandahålls istället i den skriptgenererade COLOPHON-sektionen. Dock använder olika projekt en REPORTING BUGS-sektion. Det rekommenderas att placera den nära foten av sidan.
COPYRIGHT
Man-pages-projektet använder inte en COPYRIGHT-sektion i man-sidor. Copyright-information underhålls istället i sidans källkod. På sidor där denna sektion finns, rekommenderas det att placera den nära foten av sidan, precis ovanför SEE ALSO.
SEE ALSO
En kommaseparerad lista över relaterade man-sidor, eventuellt följt av andra relaterade sidor eller dokument.
Listan bör ordnas efter sektionsnummer och sedan alfabetiskt efter namn. Avsluta inte denna lista med en punkt.
Där SEE ALSO-listan innehåller många långa man-sidnamn, för att förbättra det visuella resultatet av utskriften kan det vara användbart att använda direktiven .ad l (justera inte höger) och .nh (avaktivera avstavning). Avstavning av individuella sidnamn kan förhindras genom att föregå ord med strängen "\%".
Med tanke på den distribuerade, autonoma naturen av FOSS-projekt och deras dokumentation, är det ibland nödvändigt—och i många fall önskvärt—att SEE ALSO-sektionen inkluderar referenser till man-sidor som tillhandahålls av andra projekt.
FORMATERINGS- OCH SPRÅKKONVENTIONER
Följande undersektioner noterar några detaljer för föredragna formaterings- och språkkonventioner i olika sektioner av sidorna i man-pages-projektet.
SYNOPSIS
Omslut funktionsprototyperna i ett .nf/.fi-par för att förhindra textfyllning.
Generellt, där mer än en funktionsprototyp visas i SYNOPSIS, bör prototyperna inte separeras av tomma rader. Dock kan tomma rader (åstadkomna med .P) läggas till i följande fall:
- För att separera långa listor av funktionsprototyper i relaterade grupper (se till exempel list(3)); - I andra fall som kan förbättra läsbarheten.
I SYNOPSIS kan en lång funktionsprototyp behöva fortsättas på nästa rad. Fortsättningsraden indenteras enligt följande regler:
1. Om det finns en enda sådan prototyp som behöver fortsättas, justera fortsättningsraden så att när sidan renderas på en fastbreddsteckensnittsenhet (t.ex. på en xterm) börjar fortsättningsraden precis under början av argumentlistan på raden ovan. (Undantag: indenteringen kan justeras om det behövs för att förhindra en mycket lång fortsättningsrad eller en ytterligare fortsättningsrad där funktionsprototypen är mycket lång.) Exempel:
int tcsetattr(int fd, int optional_actions,
const struct termios *termios_p);
2. Men där flera funktioner i SYNOPSIS kräver fortsättningsrader, och funktionsnamnen har olika längder, justera alla fortsättningsrader så att de börjar i samma kolumn. Detta ger en trevligare rendering i PDF-utskrift (eftersom SYNOPSIS använder ett variabelt breddteckensnitt där mellanslag renderas smalare än de flesta tecken). Exempel:
int getopt(int argc, char * const argv[],
const char *optstring);
int getopt_long(int argc, char * const argv[],
const char *optstring,
const struct option *longopts, int *longindex);
RETURN VALUE
Den föredragna formuleringen för att beskriva hur errno ställs in är "errno sätts för att indikera felet" eller liknande. Denna formulering är konsekvent med den som används i både POSIX.1 och FreeBSD.
ATTRIBUTES
Observera följande:
- Omslut tabellen i denna sektion med ett .ad l/.ad-par för att inaktivera textfyllning och ett .nh/.hy-par för att inaktivera avstavning. - Se till att tabellen upptar hela sidbredden genom att använda en lbx-beskrivning för en av kolumnerna (vanligtvis den första kolumnen, men i vissa fall den sista kolumnen om den innehåller mycket text). - Använd T{/T}-makropar flitigt för att tillåta tabellceller att brytas över flera rader (tänk också på att sidor ibland kan renderas till en bredd på mindre än 80 kolumner).
För exempel på allt ovanstående, se källkoden för olika sidor.
STILGUIDE
Följande undersektioner beskriver den föredragna stilen för man-pages-projektet. För detaljer som inte täcks nedan är "Chicago Manual of Style" vanligtvis en bra källa; försök också att greppa efter befintlig användning i projektets källträd.
Användning av könsneutralt språk
Så långt som möjligt, använd könsneutralt språk i texten i man-sidor. Användning av "de" ("dem", "deras") som ett könsneutralt singularpronomen är acceptabelt.
Formateringskonventioner för man-sidor som beskriver kommandon
För man-sidor som beskriver ett kommando (typiskt i sektionerna 1 och 8), specificeras argumenten alltid med kursiv stil, även i SYNOPSIS-sektionen.
Namnet på kommandot och dess alternativ bör alltid formateras i fetstil.
Formateringskonventioner för man-sidor som beskriver funktioner
För man-sidor som beskriver funktioner (typiskt i sektionerna 2 och 3), specificeras argumenten alltid med kursiv stil, även i SYNOPSIS-sektionen, där resten av funktionen specificeras i fetstil:
int myfunction(int argc, char **argv);
Variabelnamn bör, liksom argumentnamn, specificeras i kursiv stil.
Alla referenser till ämnet för den aktuella man-sidan bör skrivas med namnet i fetstil följt av ett par parenteser i normal stil. Till exempel, i man-sidan fcntl(2), skulle referenser till sidans ämne skrivas som: fcntl(). Det föredragna sättet att skriva detta i källfilen är:
.BR fcntl ()
(Genom att använda detta format, snarare än att använda "\fB...\fP()", blir det lättare att skriva verktyg som analyserar man-sidans källfiler.)
Använd semantiska radbrytningar
I källan till en man-sida bör nya meningar påbörjas på nya rader, långa meningar bör delas upp i rader vid klausulbrytningar (kommatecken, semikolon, kolon osv.), och långa klausuler bör delas upp vid frasgränser. Denna konvention, ibland känd som "semantiska radbrytningar", gör det lättare att se effekten av patchar, som ofta verkar på nivån av enskilda meningar, klausuler eller fraser.
Listor
Det finns olika typer av listor:
- Märkta stycken
Dessa används för en lista över etiketter och deras beskrivningar. När etiketterna är konstanter (antingen makron eller nummer) är de i fetstil. Använd .TP-makrot.
Ett exempel är denna undersektion "Märkta stycken" själv.
- Ordnade listor
Element föregås av ett nummer inom parentes (1), (2). Dessa representerar en uppsättning steg som har en ordning.
När det finns delsteg kommer de att numreras som (4.2).
- Positionslistor
Element föregås av ett nummer (index) inom hakparenteser [4], [5]. Dessa representerar fält i en uppsättning. Det första indexet blir:
- 0: När det representerar fält i en C-datastruktur, för att vara konsekvent med arrayer. - 1: När det representerar fält i en fil, för att vara konsekvent med verktyg som cut(1).
- Alternativlistor
Element föregås av en bokstav inom parentes (a), (b). Dessa representerar en uppsättning (normalt) exklusiva alternativ.
- Punktlistor
Element föregås av punktsymboler (\[bu]). Allt som inte passar in någon annanstans täcks vanligtvis av denna typ av lista.
- Numrerade noter
Inte riktigt en lista, men syntaxen är identisk med "positionslistor".
Det bör alltid vara exakt 2 mellanslag mellan listsymbolen och elementen. Detta gäller inte för "märkta stycken", som använder standardindenteringsreglerna.
Formateringskonventioner (allmänna)
Stycken bör separeras med lämpliga markörer (vanligtvis antingen .P eller .IP). Separera inte stycken med tomma rader, eftersom detta resulterar i dålig rendering i vissa utskriftsformat (såsom PostScript och PDF).
Filnamn (vare sig det är sökvägar eller referenser till header-filer) är alltid i kursiv stil (t.ex. <stdio.h>), förutom i SYNOPSIS-sektionen, där inkluderade filer är i fetstil (t.ex. #include <stdio.h>). När du hänvisar till en standardheader-fil inkludera, specificera header-filen omgiven av vinkelparenteser, på det vanliga C-sättet (t.ex. <stdio.h>).
Speciella makron, som vanligtvis är i versaler, är i fetstil (t.ex. MAXINT). Undantag: använd inte fetstil för NULL.
När du upprättar en lista över felkoder är koderna i fetstil (denna lista använder vanligtvis .TP-makrot).
Kompletta kommandon bör, om de är långa, skrivas som en indenterad rad för sig själva, med en tom rad före och efter kommandot, till exempel
man 7 man-pages
Om kommandot är kort kan det inkluderas inline i texten, i kursiv stil, till exempel, man 7 man-pages. I detta fall kan det vara värt att använda icke-brytande mellanslag (\~) på lämpliga ställen i kommandot. Kommandoalternativ bör skrivas i kursiv stil (t.ex. -l).
Uttryck, om de inte skrivs på en separat indenterad rad, bör specificeras i kursiv stil. Återigen kan användningen av icke-brytande mellanslag vara lämplig om uttrycket är inlinat med normal text.
När du visar exempel på shell-sessioner bör användarinmatning formateras i fetstil, till exempel
$ date Thu Jul 7 13:01:27 CEST 2016
Alla referenser till en annan man-sida bör skrivas med namnet i fetstil, alltid följt av sektionsnumret, formaterat i normal stil, utan några mellanliggande mellanslag (t.ex. intro(2)). Det föredragna sättet att skriva detta i källfilen är:
.BR intro (2)
(Genom att inkludera sektionsnumret i korsreferenser kan verktyg som man2html(1) skapa korrekt hyperlänkade sidor.)
Kontrolltecken bör skrivas i fetstil, utan citattecken; till exempel, ^X.
Stavning
Från och med version 2.59 följer man-pages amerikanska stavningskonventioner (tidigare fanns det en slumpmässig blandning av brittisk och amerikansk stavning); vänligen skriv alla nya sidor och patchar enligt dessa konventioner.
Förutom de välkända stavningsskillnaderna finns det några andra subtiliteter att vara uppmärksam på:
- Amerikansk engelska tenderar att använda formerna "backward", "upward", "toward" osv. snarare än de brittiska formerna "backwards", "upwards", "towards" osv.
- Åsikterna är delade om "acknowledgement" vs "acknowledgment". Den senare är dominerande, men inte universell användning i amerikansk engelska. POSIX och BSD-licensen använder den tidigare stavningen. I Linux man-pages-projektet använder vi "acknowledgement".
BSD versionsnummer
Den klassiska ordningen för att skriva BSD-versionsnummer är x.yBSD, där x.y är versionsnumret (t.ex. 4.2BSD). Undvik former som BSD 4.3.
Versalisering
I undersektioner (.SS) bör du versalisera det första ordet i rubriken, men annars använda gemener, förutom där engelsk användning (t.ex. egennamn) eller programmeringsspråkskrav (t.ex. identifierarnamn) dikterar annat. Till exempel:
.SS Unicode under Linux
Indentering av strukturdefinitioner, shell-sessionloggar och så vidare
När strukturdefinitioner, shell-sessionloggar osv. inkluderas i löpande text, indenteras de med 4 mellanslag (d.v.s. ett block inneslutet av .in +4n och .in), formateras de med .EX och .EE-makron, och omges av lämpliga styckemarkörer (antingen .P eller .IP). Till exempel:
.P
.in +4n
.EX
int
main(int argc, char *argv[])
{
return 0;
}
.EE
.in
.P
Föredragna termer
Följande tabell listar några föredragna termer att använda i man-sidor, främst för att säkerställa konsekvens över sidor.
| Term | Undvik att använda | Noteringar | |---------------------|-------------------------|--------------------------------------------------| | bit mask | bitmask | | | built-in | builtin | | | Epoch | epoch | För UNIX Epoch (00:00:00, 1 jan 1970 UTC) | | filename | file name | | | filesystem | file system | | | hostname | host name | | | inode | i-node | | | lowercase | lower case, lower-case | | | nonzero | non-zero | | | pathname | path name | | | pseudoterminal | pseudo-terminal | | | privileged port | reserved port, system port | | | real-time | realtime, real time | | | run time | runtime | | | saved set-group-ID | saved group ID, saved set-GID | | | saved set-user-ID | saved user ID, saved set-UID | | | set-group-ID | set-GID, setgid | | | set-user-ID | set-UID, setuid | | | superuser | super user, super-user | | | superblock | super block, super-block| | | symbolic link | symlink | | | timestamp | time stamp | | | timezone | time zone | | | uppercase | upper case, upper-case | | | usable | useable | | | user space | userspace | | | username | user name | | | x86-64 | x86_64 | Förutom när man refererar till resultatet av "uname -m" eller liknande | | zeros | zeroes | |
Se även diskussionen om "Bindestreckning av attributiva sammansättningar" nedan.
Termer att undvika
Följande tabell listar några termer att undvika att använda i man-sidor, tillsammans med några föreslagna alternativ, främst för att säkerställa konsekvens över sidor.
| Undvik | Använd istället | Noteringar | |--------------------|--------------------------|---------------------------------------------------| | 32bit | 32-bit | Samma för 8-bit, 16-bit osv. | | current process | calling process | Ett vanligt misstag gjort av kärnprogrammerare när de skriver man-sidor | | manpage | man-sida, manual sida | | | minus infinity | negative infinity | | | non-root | unprivileged user | | | non-superuser | unprivileged user | | | nonprivileged | unprivileged | | | OS | operating system | | | plus infinity | positive infinity | | | pty | pseudoterminal | | | tty | terminal | | | Unices | UNIX systems | | | Unixes | UNIX systems | |
Varumärken
Använd korrekt stavning och skiftläge för varumärken. Följande är en lista över de korrekta stavningarna av olika relevanta varumärken som ibland stavas fel:
- DG/UX - HP-UX - UNIX - UnixWare
NULL, NUL, nullpekare och nullbyte
En nullpekare är en pekare som pekar på ingenting, och indikeras normalt av konstanten NULL. Å andra sidan är NUL nullbyten, en byte med värdet 0, representerad i C via teckenkonstanten '\0'.
Den föredragna termen för pekaren är "nullpekare" eller helt enkelt "NULL"; undvik att skriva "NULL-pekare".
Den föredragna termen för byten är "nullbyte". Undvik att skriva "NUL", eftersom det är för lätt att förväxla med "NULL". Undvik också termerna "zerobyte" och "nulltecken". Byten som terminerar en C-sträng bör beskrivas som "det terminerande nullbytet"; strängar kan beskrivas som "nullterminerade", men undvik användningen av "NUL-terminerade".
Hyperlänkar
För hyperlänkar, använd .UR/.UE-makropar (se groff_man(7)). Detta producerar korrekta hyperlänkar som kan användas i en webbläsare när man renderar en sida med, säg:
BROWSER=firefox man -H sidnamn
Användning av t.ex., dvs., osv., alias och liknande
Generellt bör användningen av förkortningar såsom "t.ex.", "dvs.", "osv.", "jfr.", och "alias" undvikas, till förmån för lämpliga fullständiga formuleringar ("till exempel", "det vill säga", "och så vidare", "jämför med", "även känd som").
Den enda platsen där sådana förkortningar kan vara acceptabla är i korta parentetiska inskjutningar (t.ex. som denna).
Inkludera alltid punkter i sådana förkortningar, som visas här. Dessutom bör "t.ex." och "dvs." alltid följas av ett kommatecken.
Tankstreck
Sättet att skriva ett tankstreck—tecknet som visas i vardera änden av denna fras—i *roff är med makrot "\[em]". (På en ASCII-terminal renderas ett tankstreck typiskt som två bindestreck, men i andra typografiska sammanhang renderas det som ett långt streck.) Tankstreck bör skrivas utan omgivande mellanslag.
Bindestreckning av attributiva sammansättningar
Sammansatta termer bör bindestreckas när de används attributivt (d.v.s. för att kvalificera ett efterföljande substantiv). Några exempel:
- 32-bitars värde - kommandoradsargument - flyttal - körtidskontroll - användarutrymmesfunktion - bredteckensträng
Bindestreckning med multi, non, pre, re, sub, och så vidare
Den allmänna tendensen i modern engelska är att inte använda bindestreck efter prefix som "multi", "non", "pre", "re", "sub" och så vidare. Man-sidor bör generellt följa denna regel när dessa prefix används i naturliga engelska konstruktioner med enkla suffix. Följande lista ger några exempel på de föredragna formerna:
- interprocess - multithreaded - multiprocess - nonblocking - nondefault - nonempty - noninteractive - nonnegative - nonportable - nonzero - preallocated - precreate - prerecorded - reestablished - reinitialize - rearm - reread - subcomponent - subdirectory - subsystem
Bindestreck bör behållas när prefixen används i icke-standardiserade engelska ord, med varumärken, egennamn, akronymer eller sammansatta termer. Några exempel:
- non-ASCII - non-English - non-NULL - non-real-time
Slutligen, notera att "re-create" och "recreate" är två olika verb, och det förra är förmodligen vad du vill ha.
Generera optimala tecken
Där ett riktigt minustecken krävs (t.ex. för tal som -1, för man-sidkorsreferenser som utf-8(7), eller när man skriver alternativ som har ett ledande streck, som i ls -l), använd följande form i man-sidans källkod:
\-
Denna riktlinje gäller också för kodexempel.
Användningen av riktiga minustecken tjänar följande syften:
- Att ge bättre renderingar på olika mål än ASCII-terminaler, särskilt i PDF och på Unicode/UTF-8-kapabla terminaler. - Att generera tecken som när de kopieras från renderade sidor kommer att producera riktiga minustecken när de klistras in i en terminal.
För att producera osnedställda enkla citattecken som renderar väl i ASCII, UTF-8 och PDF, använd "\[aq]" ("apostrof-citattecken"); till exempel
\[aq]C\[aq]
där C är det citerade tecknet. Denna riktlinje gäller också för teckenkonstanter som används i kodexempel.
Där ett riktigt cirkumflex (^) som renderar väl både i en terminal och i PDF krävs, använd "\[ha]". Detta är särskilt nödvändigt i kodexempel för att få ett snyggt renderat cirkumflex när man renderar till PDF.
Att använda ett naket "~"-tecken resulterar i en dålig rendering i PDF. Använd istället "\[ti]". Detta är särskilt nödvändigt i kodexempel för att få en snyggt renderad tilde när man renderar till PDF.
Exempelprogram och shell-sessioner
Man-sidor kan inkludera exempelprogram som demonstrerar hur man använder ett systemanrop eller en biblioteksfunktion. Notera dock följande:
- Exempelprogram bör skrivas i C. - Ett exempelprogram är nödvändigt och användbart endast om det demonstrerar något utöver vad som lätt kan tillhandahållas i en textuell beskrivning av gränssnittet. Ett exempelprogram som inte gör något annat än att anropa ett gränssnitt tjänar vanligtvis lite syfte. - Exempelprogram bör idealt vara korta (t.ex. ett bra exempel kan ofta tillhandahållas på mindre än 100 rader kod), även om längre program i vissa fall kan vara nödvändiga för att ordentligt illustrera användningen av ett API. - Uttrycksfull kod uppskattas. - Kommentarer bör inkluderas där de är hjälpsamma. Fullständiga meningar i fristående kommentarer bör avslutas med en punkt. Punkter bör generellt utelämnas i "tagg"-kommentarer (d.v.s. kommentarer som placeras på samma kodrad); sådana kommentarer är i alla fall vanligtvis korta fraser snarare än fullständiga meningar. - Exempelprogram bör göra felkontroller efter systemanrop och biblioteksfunktionsanrop. - Exempelprogram bör vara kompletta och kompilera utan varningar när de kompileras med cc -Wall. - Där det är möjligt och lämpligt bör exempelprogram tillåta experimentering genom att variera deras beteende baserat på indata (idealiskt från kommandoradsargument eller alternativt via indata som läses av programmet). - Exempelprogram bör vara utformade enligt Kernighan och Ritchie-stil, med 4 mellanslags indragningar. (Undvik användning av TAB-tecken i källkoden!) Följande kommando kan användas för att formatera din källkod till något nära den föredragna stilen:
indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
- För konsekvens bör alla exempelprogram avslutas med antingen:
exit(EXIT_SUCCESS); exit(EXIT_FAILURE);
Undvik att använda följande former för att avsluta ett program:
exit(0); exit(1); return n;
- Om det finns omfattande förklarande text före programkällkoden, markera av källkoden med en undersektion med rubriken "Program source", som i:
.SS Program source
Gör alltid detta om den förklarande texten inkluderar en shell-sessionlogg.
Om du inkluderar en shell-sessionlogg som demonstrerar användningen av ett program eller annan systemfunktion:
- Placera sessionloggen ovanför källkodlistan. - Indentera sessionloggen med fyra mellanslag. - Fetstila användarinmatningstexten för att skilja den från utdata producerad av systemet.
För några exempel på hur exempelprogram bör se ut, se wait(2) och pipe(2).
EXEMPEL
För kanoniska exempel på hur man-sidor i man-pages-paketet bör se ut, se pipe(2) och fcntl(2).
SEE ALSO
man(1), man2html(1), attributes(7), groff(7), groff_man(7), man(7), mdoc(7)
COLOFON
Denna sida är en del av man-sidorna (Linux-kärnans och C-bibliotekets användarutrymmesgränssnitts-dokumentation) projekt. Information om projektet finns på man-pages-projektet. Om du har en felrapport för denna man-sida, se CONTRIBUTING. Denna sida erhölls från tarballen man-pages-6.9.1.tar.gz hämtad från [1] den 2024-06-26. Om du upptäcker några återgivningsproblem i denna HTML-version av sidan, eller om du tror att det finns en bättre eller mer uppdaterad källa för sidan, eller om du har korrigeringar eller förbättringar av informationen i denna COLOFON (som inte är en del av den ursprungliga man-sidan), skicka ett mail till man-pages@man7.org.
Linux man-sidor 6.9.1 2024-06-15 man-pages(7)
Sidor som hänvisar till denna sida
attributes(7), intro(2), man(1), man(7), mdoc(7), pthreads(7), signal(7), signal-safety(7), syscalls(2), wait(2), waitid(2)