man page

Ej att förväxla med huvudsidan .
Mansidan på man(1) , som ses i olika Linux-distributioner . Denna version är från man-db.

En man page (förkortning för manual page ) är en form av mjukvarudokumentation som vanligtvis finns på ett Unix- eller Unix-liknande operativsystem . Ämnen som behandlas inkluderar datorprogram (inklusive biblioteks- och systemsamtal ), formella standarder och konventioner och till och med abstrakta begrepp. En användare kan anropa en man-sida genom att utfärda kommandot man .

Som standard använder människan vanligtvis ett terminalsökprogram som mer eller mindre för att visa dess utdata.

Man-sidor hänvisas ofta till som en online- eller online -form av mjukvarudokumentation, även om man -kommandot inte kräver internetåtkomst, som går tillbaka till tiden då utskrivna manualer utanför bandet var normen.

Historia

xman , en tidig X11- applikation för att visa manuella sidor
OpenBSD avsnitt 8 intromansida, som visas i en textkonsol

Under de första två åren av Unix historia fanns ingen dokumentation. Unix Programmer's Manual publicerades första gången av programmerarens den 3 november 1971. De första faktiska mansidorna skrevs av Dennis Ritchie och Ken Thompson på begäran deras chef Doug McIlroy 1971. Förutom man-sidorna, manual samlade också en uppsättning korta uppsatser, några av dem handledningar (t.ex. för allmän Unix-användning, programmeringsspråket C och verktyg som Yacc ), och andra mer detaljerade beskrivningar av operativsystemets funktioner. Den tryckta versionen av manualen passade till en början i en enda pärm, men från och med PWB/UNIX och den 7:e upplagan av Research Unix delades den upp i två volymer med de tryckta mansidorna som bildar Volym 1.

Senare versioner av dokumentationen imiterade de första mansidornas konsistens. Ritchie lade till avsnittet "Hur man kommer igång" till introduktionen till den tredje upplagan , och Lorinda Cherry gav "Purple Card"-fickan för de sjätte och sjunde utgåvorna. Versioner av programvaran fick sitt namn efter revideringen av manualen; den sjunde upplagan av Unix Programmer's Manual kom till exempel med den 7:e upplagan eller version 7 av Unix.

För den fjärde upplagan formaterades man-sidorna med hjälp av troff- typsättningspaketet och dess uppsättning av -man -makron (som reviderades fullständigt mellan den sjätte och sjunde upplagan av manualen , men har sedan dess inte förändrats drastiskt). På den tiden ansågs tillgången till onlinedokumentation via manualsidesystemet som ett stort framsteg. Än idag har praktiskt taget varje Unix kommandoradsapplikation en man-sida, och många Unix-användare uppfattar ett programs brist på man-sidor som ett tecken på låg kvalitet; faktiskt, vissa projekt, som Debian , går ut ur deras sätt att skriva man-sidor för program som saknar en. De moderna ättlingarna till 4.4BSD distribuerar också man-sidor som en av de primära formerna av systemdokumentation (efter att ha ersatt de gamla -man- makron med det nyare -mdoc ).

Det fanns ett dolt påskägg i man-db-versionen av man-kommandot som skulle få kommandot att returnera "gimme gimme gimme" när det kördes kl. 00:30 (en referens till ABBA- låten Gimme ! Gimme! Gimme! (A Man) Efter midnatt) . Den introducerades 2011 men begränsades först och togs sedan bort 2017 efter att ha hittats.

Formatering

En del av FreeBSD man(1) manualsidan, inställd i PDF- format

Standardformatet för man-sidor är troff , med antingen makropaketet man (utseendeorienterat) eller mdoc (semantiskt orienterat). Detta gör det möjligt att sätta in en man-sida i PostScript , PDF och olika andra format för visning eller utskrift.

Vissa Unix- system har ett paket för kommandot man2html , som gör det möjligt för användare att bläddra på sina man-sidor med en HTML-webbläsare. System med groff och man-db bör istället använda den inbyggda HTML-utdata av högre kvalitet ( man --html ). GNU Emacs- programmet WoMan (från "WithOut man") gör det möjligt att bläddra i man-sidor från editorn.

År 2010 utfasade OpenBSD troff för formatering av man-sidor till förmån för mandoc , en specialiserad kompilator/formaterare för man-sidor med inbyggt stöd för utdata i PostScript , HTML , XHTML och terminalen. Den är avsedd att endast stödja en delmängd av troff som används på manualsidor, speciellt de som använder mdoc-makron.

Online tjänster

En hel del webbplatser erbjuder onlineåtkomst till manuella sidor från olika Unix-liknande system.

I februari 2013 såg BSD- communityt lansera en ny mdoc.su -tjänst med öppen källkod, som förenade och förkortade åtkomsten till man.cgi-skripten för de stora moderna BSD-projekten genom en unik nginx -baserad deterministisk URL-förkortningstjänst för *BSD-mannen sidor.

För Linux har en man7.org-tjänst satts upp för att tillhandahålla manualer som är specifika för systemet. En ManKier-tjänst ger ett bredare urval och integrerar också TLDR-sidorna.

Kommandoanvändning

För att läsa en manualsida för ett Unix-kommando kan en användare skriva:

man<command_name>

Sidor hänvisas traditionellt till med beteckningen "namn(sektion)": till exempel ftp(1) . Avsnittet hänvisar till olika sätt som ämnet kan refereras på - till exempel som ett systemanrop, eller ett skal (kommandorad) kommando eller paket, eller ett pakets konfigurationsfil, eller som en kodningskonstruktion/huvud.

Samma sidnamn kan förekomma i mer än ett avsnitt i manualen, till exempel när namnen på systemanrop , användarkommandon eller makropaket sammanfaller . Exempel är man(1) och man(7) , eller exit(2) och exit(3) . Syntaxen för att komma åt den manuella delen som inte är standard varierar mellan olika man-implementationer.

är syntaxen för att läsa printf(3C) : 

 man -s 3c  printf

På Linux- och BSD-derivat skulle samma anrop vara:

  man  3  printf

som söker efter printf i avsnitt 3 på man-sidorna.

Manuella avsnitt

Manualen är vanligtvis uppdelad i åtta numrerade avsnitt, organiserade enligt följande (på Research Unix , BSD , macOS och Linux ):

Sektion Beskrivning
1 Allmänna kommandon
2 Systemsamtal
3 Biblioteksfunktioner , som i synnerhet omfattar C-standardbiblioteket
4 Specialfiler (vanligtvis enheter, de som finns i /dev) och drivrutiner
5 Filformat och konventioner
6 Spel och skärmsläckare
7 Diverse
8 Systemadministrationskommandon och demoner _

POSIX- systemanrop förekommer ofta i både avsnitt 2 och 3, där avsnitt 2 innehåller systemanropets dokumentation från det lokala operativsystemet och avsnitt 3 innehåller systemanropets dokumentation från POSIX-programmerarens manual. [ citat behövs ]

Unix System V använder ett liknande numreringsschema, förutom i en annan ordning:

Sektion Beskrivning
1 Allmänna kommandon
1M Systemadministrationskommandon och demoner _
2 Systemsamtal
3 C- biblioteksfunktioner
4 Filformat och konventioner
5 Miscellanea
6 Spel och skärmsläckare
7 Specialfiler (vanligtvis enheter, de som finns i /dev) och drivrutiner

På vissa system finns några av följande avsnitt tillgängliga:

Sektion Beskrivning
0 C-bibliotekshuvudfiler ( Unix v6)
9 Kärnrutiner (FreeBSD, SVR4, Linux)
l LAPACK biblioteksfunktioner
n Tcl / Tk kommandon
x X Window System

Vissa avsnitt är ytterligare indelade med hjälp av ett suffix; till exempel, i vissa system är avsnitt 3C för C-biblioteksanrop, 3M är för matematikbiblioteket och så vidare. En konsekvens av detta är att sektion 8 (systemadministrationskommandon) ibland förpassas till 1M undersektionen i huvudkommandonsektionen. Vissa underavsnittssuffix har en allmän betydelse över sektioner:

Underavsnitt Beskrivning
sid POSIX- specifikationer
x X Window System dokumentation

(Avsnitt 3 brukar vara undantaget med de många suffixen för olika språk.)

Vissa versioner av man cachelagrar de formaterade versionerna av de senaste visade sidorna. En form är kattsidan , helt enkelt kopplad till personsökaren för visning.

Layout

Alla man-sidor följer en gemensam layout som är optimerad för presentation på en enkel ASCII -textdisplay, möjligen utan någon form av markering eller teckensnittskontroll. De aktuella avsnitten kan inkludera:

NAME
Namnet på kommandot eller funktionen, följt av en enradsbeskrivning av vad den gör.
SYNOPSIS
När det gäller ett kommando, en formell beskrivning av hur det körs och vilka kommandoradsalternativ som krävs. För programfunktioner, en lista över de parametrar som funktionen tar och vilken huvudfil som innehåller dess deklaration.
BESKRIVNING
En textbeskrivning av hur kommandot eller funktionen fungerar.
EXEMPEL
Några exempel på vanlig användning.
SE ÄVEN
En lista över relaterade kommandon eller funktioner.

Andra avsnitt kan finnas, men dessa är inte väl standardiserade över man-sidor. Vanliga exempel inkluderar: ALTERNATIV, UTSÄTTNINGSSTATUS, RETURVÄRDE, MILJÖ, BUGGAR, FILER, FÖRFATTARE, RAPPORTERING AV BUGGAR, HISTORIK och COPYRIGHT.

Författarskap

Manuella sidor kan skrivas antingen i de gamla manmakron , de nya dokumentmakron eller en kombination av båda ( mandoc ). Manmakrouppsättningen ger minimala funktioner för rik text , med direktiv för titelraden, avsnittsrubriker, (fet, små eller kursiv) typsnitt, stycken och att lägga till/minska indrag . Det nyare mdoc -språket är mer semantiskt till sin natur och innehåller specialiserade makron för de flesta standardavsnitt som programnamn, synopsis, funktionsnamn och författarnas namn. Denna information kan användas för att implementera en semantisk sökning efter manualer av program som mandoc . Även om det också innehåller direktiv för att direkt styra stylingen, förväntas det att de specialiserade makrona kommer att täcka de flesta användningsfallen. Både mandoc- och groffprojekten anser att mdoc är det föredragna formatet för nya dokument.

Även om man-sidor, för att säga, är text som läggs ut med 10-punkts romersk typ , är denna distinktion vanligtvis omtvistad eftersom man-sidor visas i terminalen (TTY) istället för att läggas ut på papper. Som ett resultat av detta används makrot "small font" sällan. Å andra sidan stöds fet och kursiv text av terminalen via ECMA-48 , och groffs grotty avger dem som efterfrågat när den upptäcker en stödjande terminal. BSD-mandoc stöder dock bara fet och understruken (som ersättning för kursiv stil) text via skrivmaskinens backsteg-sedan-överstreck-sekvens, som behöver översättas till ECMA-48 med mindre .

Man-sidor är vanligtvis skrivna på engelska, men översättningar till andra språk kan finnas tillgängliga i systemet. GNU man-db och mandoc man är kända för att söka efter lokaliserade manualsidor under underkataloger.

Alternativ

Få alternativ till människan har åtnjutit stor popularitet, möjligen med undantag för GNU Projects " info "-system, ett tidigt och enkelt hypertextsystem . Det finns också en tredjepartsinsats känd som TLDR-sidor ( tldr ) som ger enkla exempel för vanliga användningsfall, liknande ett fuskark .

Dessutom tillhandahåller vissa Unix GUI- program (särskilt de som är byggda med GNOME- och KDE- utvecklingsmiljöerna) nu slutanvändardokumentation i HTML och inkluderar inbäddade HTML-visare som tjut för att läsa hjälpen i programmet.

Se även

externa länkar

Hämtad från " https://en.wikipedia.org/w/index.php?title=Man_page&oldid=1136647215 "