- MacWorld:

Ta lärdom av din man

Av

Man kan argumentera om vilka kommandon som är viktigast på ett system. Fast för att alls kunna diskutera ämnet måste man veta vad de olika binärerna egentligen kan uträtta, och för att få reda på detta måste du titta i manual­sidorna. Något du gör med ”man”, vishetens källa.

Namnet är – inte oväntat– en förkortning av ”manual”. Som sig bör informerar det om vad efterfrågat kommando används till, vilka flaggor du kan använda och mycket mer. Inte sällan kan du dessutom få bra exempel på hur du effektivt kan utnyttja en funktion.
Det är inte bara kommandon du kan söka på – en del konfigurationsfiler är också dokumenterade, även om det är mindre vanligt. Tre exempel som ändå finns är ”rtadvd.conf”, ”hosts” och givetvis ”man.conf”. Om du kör ”man man.conf” får du reda på vad den används till, och av vad.

Största bristen med systemet är att det i regel oftast är tekniker som skrivit in informationen. Även om de kan programmet är de inte alltid duktiga pedagoger, och det kan vara knepigt att förstå vad de menar.

Få en snabbmanual
Vill du bara veta vad ett program gör tycker du kanske att det är jobbigt att behöva läsa en hel manualsida. Då kan du i stället använda kommandona ”apropos” eller ”whatis”. De använder samma grunddata som manual­sidorna – men visar bara namnet och den korta beskrivningen.

Standardläsaren för ”man”-sidor är programmet ”less”. Det kan därför vara bra att känna till en handfull av dess kommandon. För att stänga ner fönstret trycker du på ”q”. Vill du leta efter en term i texten skriver du först in ”/” och sedan ordet du söker. Med ”n” får du nästa träff, medan ”p” ger dig före­gående.

Att röra sig är också teckenbaserat. Bokstaven ”j” tar dig ner en rad, och ”k” upp lika mycket. Mellanslag flyttar dig framåt en sida i taget. Vill du gå till en viss rad kan du skriva in en siffra, till exempel 1 för att komma högst upp, följt av bokstaven ”g”. Matar du bara in stora g, ”G”, landar du på sista sidan.

Du kanske har tänkt på att kommandon i man skrivs ut med en siffra inom parentes, till exempel ”man(1)”. Numret representerar vilken sektion informationen ligger i. Det finns traditionellt åtta olika sektioner för manualsidor. OS X saknar nummer två, men har ändå nio olika. Alla är uppbyggda på ungefär samma sätt, men de innehåller olika information.

Ettan är allra vanligast och används av allmänna kommandon. Nästa grupp är framför allt till för systemanrop och saknas alltså i OS X. Trean är för C-bibliotek. Sedan fortsätter det med specialfiler i sektion fyra, filformat i femman och spel i nummer sex. Listan avslutas med blandat i sjuan, program för systemadministration i åttan, kernelrutiner i nian och tclbegrepp i den sista.

Om du bara skriver in ”man” rakt upp och ner kommer programmet att leta igenom alla sektionerna. Förekommer det i flera kör den enligt en lista som definieras i konfigurationsfilen, och första träffen visas.

Nämnda inställningar går att titta närmare på om du är nyfiken. Under katalogen ”/etc” finns filen ”man.conf” som definierar hur programmet ska jobba. Den innehåller bland annat hänvisningar till var manualsidorna finns, och vilken läsare som ska användas för att visa sidorna.

  • Vill du verkligen djupdyka i hur du kan formatera texter med kommandot groff, har du mycket att vältra dig i.

Justerar inte korrekta filer
I OS X ligger merparten av manualsidorna under ”/usr/share/man”. Tittar du i den katalogen kommer du att se en handfull under­mappar. De viktigaste är de mapparna som börjar med bokstäverna ”man” och följs av en siffra eller bokstaven ”n”. Det är i denna struktur som ovan nämnda sektioner gömmer sig.

Eftersom allting är ren text går det utmärkt att studera sidorna lite närmare, men givetvis ska du inte justera de korrekta filerna. Däremot kan du kopiera undan något intressant till din hemmamapp. Väl där kan du zippa upp den och titta på innehållet.

Du kommer se att det är taggat, men ändå ganska enkelt att läsa. Det är heller inte särskilt avancerat att skapa egna manualsidor, och det kan vara bra att känna till hur man gör. ­Skriver du till exempel ett skript på företagets server, eller distribuerar ett litet hjälpprogram till vänner, är det bra att ge dem instruktioner på traditionellt vis.

Även om du kan skriva nästan vad som helst i din dokumentation, finns det en standard som de flesta följer. Den består av följande rubriker: ”Name”, ”Synopsis”, ”Description”, ”Environment”, ”Options”, ”Exit status”, ”Bugs”, ”Examples”,  ”Files”, ”History”, ”Author”, ”See also” och ”Copyright”. Du behöver givetvis inte skriva in något för de punkter där du inte har någon data. På samma sätt kan du lägga till egna vid behov.

Första fältet – namnet – är ganska själv­förklarande. Du ska mata in titeln på ditt skript och dessutom skicka med en kort beskrivning, en mening räcker. Det är denna information som kommer att läsas in i ”whatis”-databasen. Men mer om det senare.

Under rubriken ”Synopsis” ska du bara mata in hur man kör ditt kommando och vilka flaggor som är tillåtna. Följande fält, ”Description”, fyller du med lite mer utförlig information om vad programmet gör och ­vilket problem det löser.

Eventuella miljövariabler och hur de påverkar dokumenterar du under ”Environment”. Vad flaggor och inparametrar gör förklaras i ”Options”. Lägg gärna tid på just denna del då detta är ett populärt avsnitt.

Fyll på historiken
Returkoder och hur man ska tolka dessa listar du i ”Exit status”. Känner du till några fel beskriver du detta efter ”Bugs”. Om möjligt ska du lägga till exempel under sektionen med samma namn. Många hoppar över detta, men det uppskattas av de flesta som läser texten.

Har du konfigurationsfiler är det en god idé att beskriva var de ligger under ”Files”. Av­snittet ”History” kan du fylla på om du vill dokumentera hur ditt program har utvecklats över tid. Detta är intressant i en företagsmiljö, där du kan se vilka kollegor som gjort vad och när i tiden.

Vem du är, och hur man kommer i kontakt med dig, skriver du ner i ”Author”-delen. ­Relaterade kommandon hänvisar du till under ”See also”. Ha gärna en hänvisning för ­mycket än en för lite. Avslutningsvis kan du skriva ner eventuella upphovsrättsliga kommentarer på ”Copyright”-delen.

Nu vet du vad du ska skriva – men ännu inte hur. Som du sett har manualsidorna även grafiskt sett ett speciellt utseende. Detta fixar du genom att ­använda makron som programmet  ”groff” kan tolka. Med dem kan du helt styra forma­teringen av innehållet.

Språket är inte intuitivt, men är inte heller särskilt svårt att lära sig. Har du någon gång jobbat med till exempel html eller css ­kommer du snabbt in i det.

För att visa hur det kan se ut ska vi bygga en manualsida för det fiktiva programmet ”macworld”. Det kan ta emot en parameter. Resultatet ser du på bilden här bredvid.

Du kan skapa dokumentet i vilken text­editor som helst, om du använder en terminalbaserad eller grafisk variant spelar ingen roll. Men det är viktigt att resultatet sparas ner som ren text, annars kommer resultatet att fyllas med konstiga tecken.

  • Så här ser ­formateringen till programmet macworlds manualsida ut. Som du kan se är det inte så märkvärdigt att göra en korrekt dokumentation.

Makrokommandona börjar med en punkt och fortsätter med en eller flera bokstäver. Dessa måste alltid inleda en rad, så du kan ­alltså inte använda dem mitt i en mening. Detta gör att du kan få skriva ett ord du vill fetstila på en egen rad.

Det första du behöver är en rubrik – eller ”Title Header” på groffspråk. Du skriver ut detta som ”.TH”. Två parametrar ska skickas med. Den första är namnet och den andra vilken sektion det ska falla under. Det ser ut så här: ”.TH macworld 1”.

Om du vill kan du lägga till tre parametrar till efter de två ovan. De ger – i tur och ordning – en centrerad sidfot, en vänsterställd sidfot och ett centrerat sidhuvud. Det är inte jättevanligt att man använder dessa, men ibland kan du se att det datum som dokumentet skapades läggs in. Nästa kommando du ­behöver kunna hanterar sektionshuvudena. Detta förkortas ”.SH” och tar en parameter – namnet på den aktuella delen. Första ­stycket var, som du läste ovan, ”Name”. För att skriva ut detta matar du in: ”.SH NAME”. Detsamma gäller för alla andra mellanrubriker.

Vill du ha fetstil på första ordet använder du ”.B”. Notera att du måste radbryta och börja på en ny rad för att inte resten av ­meningen också ska få samma formatering. Om du ska skriva ”the macworld program looks through the digital version of MacWorld”, får du skriva det på tre rader. Första raden innehåller bara ”the”, nästa rad ”.B macworld” medan resten hamnar på sista raden. Behöver du ett nytt stycke skriver du in ”.PP” utan ­parametrar.

Avsluta med whatis
För dina parametrar vill du ha ett namn och sedan texten indragen, vilket du får med ­kommandot ”.TP”. Om du vill välja själv hur ­mycket löptexten ska skjutas in kan du lägga till en siffra. Annars kommer du få standardvalet.

Det här är allt du behöver känna till för att få till ett riktigt snyggt dokument som ser riktigt professionellt ut. Vill du lära dig allting om antal groffs och makron, titta i sektion sju. Detta gör du med ”man 7 groff”.

När du är klar sparar du filen till <filnamn>.<sektion>, till exempel ”macworld.1”. Du kan dessutom komprimera filen med ”gzip macworld.1”. Det behövs inte, men görs nästan alltid ändå. Kopiera sedan in filen i rätt katalog. För sektion ett skriver du ”sudo cp macworld.1.gz /usr/share/man/man1”. Du måste använda ”sudo” då det bara är root som får skriva till mappen.

Avslutningsvis ska du också uppdatera ”whatis”. Detta gör du genom att köra ”sudo /usr/libexec/makewhatis”. Programmet går igenom alla manualsidor och fångar upp nödvändig information. När du gjort detta kan du prova ditt verk med ”man macworld” och ”whatis macworld”.

Detta är allt om ”man” för denna gång. Som du sett finns det en hel del att lära om detta till synes enkla kommando. Och vill du veta ännu mer vet du nu hur du ska hitta det – du kör givetvis bara ”man man”.



Sälj din Apple-pryl med MacWorld

Gratis guide: Så kopplar du mobilen till tv:n



Mer sånt? Fyll i din e-postadress så får du MacWorlds nyhetsbrev

Please don't insert text in the box below! Villkor



Frågor om vårt kommentarsystem, se vår FAQ: idg.se/faq

Artikelkommentatorerna ansvarar själva för sina inlägg.

OBS! Läs dessa regler som gäller vid postning av inlägg.

Regler för inlägg i artikelforumet

Kommentatorn ansvarar själv för sina inlägg. Inlägg som innehåller diskriminerande uttalanden, personliga påhopp eller språk som kan uppfattas som stötande, kommer att tas bort av tjänstgörande redaktör. Även datorkrigsinlägg och inlägg som är utanför ämnet, kan tas bort.

IDG förbehåller sig dessutom rätten att i varje enskilt fall bedöma huruvida ett inlägg ska tas bort, även om det inte faller under någon av reglerna ovan.

Upprepat postande av olämpliga inlägg kan medföra avstängning från artikelforumen.

Frågor? Mejla till redaktören, carl.grape@idg.se.

Läs mer om vår policy i diskussionsforum


iPhone 6 och iPhone 6 Plus
Missa inte

OS X Yosemite
 
Apple iWatch
Apple
 


- MacWorld:

iPhone 6

Förhandsboka iPhone 6 redan i natt


- MacWorld:

Apple

Apple uppdaterar Safari för Mavericks


- MacWorld:

Kina

Spänd väntan på iPhone 6 i Kina


7 funktioner i iOS 8 du inte kände till

iOS 8 kommer idag, och du har säkert sett stora nyheter som förändringarna i kameran och det nya gränssnittet för multitasking. Här är sju mindre kända godbitar.

MacWorld:

  1. Så förbereder du dig för iOS 8

    GUIDE I dag 17 september släpps iOS 8. Följ vår guide till vad du behöver göra innan du uppdaterar.

MacWorld:

  1. Bildspecial: Här är nyheterna i iOS 8

    Nu var det ett tag sedan iOS 8 presenterades, men i dag släpps det. Här kan du se nyheterna i din iPhone eller iPad.


- MacWorld:

Apple kan inte dekryptera iOS 8


- MacWorld:

iWork

Uppdateringar för iWork och iLife



Nyheter och tips från Teknik & Trender. ANNONS

5 system för smarta hem – del 1 av 3

5 smarta klockor som var före Apple Watch

Feta spel i tunn förpackning

9 saker som kostar lika mycket som nya Iphone 6







- MacWorld:

Var hittar jag Paint i min Mac?


- MacWorld:

Öppet brev från Tim Cook till användare


- MacWorld:

OS X Mavericks 10.9.5 har släppts


- MacWorld:

iOS 8

Skarp version av iOS 8 har släppts


- MacWorld:

Apple TV

Nytt gränssnitt för Apple TV


- MacWorld:

iOS 8

Apple anpassar sina appar för iOS 8


- MacWorld:

Så känns iPhone 6 och iPhone 6 Plus


- MacWorld:

Utvecklare: "Vänta med iCloud Drive"


- MacWorld:

Då släpps nästa omgång Apple-prylar

iPhone 6 och iPhone 6 Plus
Missa inte

OS X Yosemite
 
Apple iWatch
Apple