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:
- Användarkommandon (Program): Kommandon som kan exekveras av användaren från en shell.
- Systemanrop: Funktioner som omsluter operationer utförda av kärnan.
- Biblioteksanrop: Alla biblioteksfunktioner exklusive systemanropsomslag (de flesta libc-funktioner).
- Speciella filer (enheter): Filer som finns i /dev som ger åtkomst till enheter via kärnan.
- Filformat och konfigurationsfiler: Beskriver olika läsbara filformat och konfigurationsfiler.
- Spel: Spel och roliga små program som finns tillgängliga på systemet.
- Översikter, konventioner och diverse: Översikter eller beskrivningar av olika ämnen, konventioner och protokoll, teckenuppsättningsstandarder, standardfilsystemlayout och diverse andra saker.
- 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
EXEMPEL
För kanoniska exempel på hur man-sidor i man-pages-paketet bör se ut, se pipe(2) och fcntl(2).
SE ÄVEN
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 https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/ 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.