Getting started with "man": a few questions

Question

I'm having problems with man:

1. How can I display sections of a man-page? How can I figure out what sections a man page offers? According to man man -S is the parameter I need to get a list of "sections" available of a man page. But if I try to display available sections of git, ls, or pwd with: man -S git. I would expect a list but all I get is: What manual page do you want?

2. I also have a second question: How can I display a short version/preview of a man page? It's also my task to figure this out. I couldn't find a parameter that sounds like the thing I want to do.

PS: I'm using a shell on MacOS Sierra

Answer 1

The simple answer:

Man pages don't contain sections; sections contain man pages.

This refers to the numbered sections that you are talking about. There can be two man pages with the same name, but in two different (numbered) sections—for example, printf. The printf(1) man page covers the command line tool. The printf(3) man page covers the C function call.

You can view both man pages in sequence by running:

man -a printf

When you quit the first, you will see the second.

You can see which sections it appears in, without opening either, by running:

man -aw printf

---

Besides the numbered sections in which man pages exist, individual man pages are also divided up visually with separate headers and subheaders, such as "Name," "Synopsis," "Description," etc.

These are also called "sections," but it is a distinctly different usage of the word "section" from the numbered sections described above.

Answer 2

Back in the old days the online manual ("online" in contrast to "printed") used to have eight sections, but there were some more added later. These sections are 1, 2, ..., 8, so you would type something like

man -S 4 xyz

to get the man page for xyz in Section 4.

Actually, specifying a section is only important, if there are man pages for the same keyword in more than one section.

For instance:

man printf

yields

PRINTF(1)                                                         User Commands

NAME
       printf - format and print data

SYNOPSIS
       printf FORMAT [ARGUMENT]...
       printf OPTION

DESCRIPTION
       Print ARGUMENT(s) according to FORMAT, or execute according to OPTION
...

while

man -S 3 printf

yields

PRINTF(3)                                                   Linux Programmer's Manual

NAME
       printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, vsprintf, vsnprintf - formatted output conversion

SYNOPSIS
       #include <stdio.h>

       int printf(const char *format, ...);
       int fprintf(FILE *stream, const char *format, ...);
       int dprintf(int fd, const char *format, ...);
       int sprintf(char *str, const char *format, ...);
       int snprintf(char *str, size_t size, const char *format, ...);
...

Try man -S x intro with x = 1,2,3,... to get an introduction to the various sections.

Sometimes you find statements like: ... fork(2) is used to create a new process; this is often followed by execl(3)... This indicates that the man page for fork is in Section 2 and the man page for execl is in Section 3.

How can I display a short version/preview of a man page?

I'm not sure what you mean by this. man does not provide something like Get-Help in PowerShell. whatis gives you a very short description, like

whatis man
man                  (1)  - format and display the on-line manual pages
man                  (1p)  - display system documentation
man                  (7)  - macros to format man pages
man []               (1)  - format and display the on-line manual pages
man []               (1p)  - display system documentation
man []               (7)  - macros to format man pages
man []               (7)  - pages - conventions for writing Linux man pages
man-pages            (7)  - conventions for writing Linux man pages
man.conf []          (5)  - configuration data for man
man.conf [man]       (5)  - configuration data for man

Answer 3

The -S argument does not do what you want. It's for specifying which categories of man pages you want to look in.

If there is an automated method of displaying the sections of a man page, I do not know it. I would look to tools such as grep/sed/awk to parse the man page and extract the text I was interested in, i.e.:

man ls|grep -v -e '^$' -e '^[[:space:]]'

The above code isn't a complete solution. For one, it also prints the header and footer of the man page. I trust you can modify it to fully meet your requirements, or come up with a better implementation ;)

Similarly, the request to get a man page "preview" can easily be accomplished by piping the output of man into another tool. I'd recommend head for that task.

Answer 4

[1.]

I would expect a list but all I get is: What manual page do you want?

-S is not use to display list of sections, instead it ask you to pass list of section in your desired section search order. E.g.

xb@dnxb:/tmp$ man -S=7,6,5,4,3,2 ls
No manual entry for ls
See 'man 7 undocumented' for help when manual pages are not available.
xb@dnxb:/tmp$ 

The above-S=7,6,5,4,3,2 show that section search order start from left to right in this list. If manual of ls contains section 7, it will show it. If not, it will try to search section 6, and so on. If no section exist in the end of this list, it will said "No manual entry for ls" even though section 1 exist. But this one works because section 1 in the list:

xb@dnxb:/tmp$ man -S=7,6,5,4,3,2,1 ls
xb@dnxb:/tmp$ 

Play around with this two to prove the search order of -S is left to right:

xb@dnxb:/tmp$ man -S 1,1posix ls
xb@dnxb:/tmp$ man -S 1posix,1 ls
xb@dnxb:/tmp$ 

You can simply pass the exact section too, without -S:

xb@dnxb:/tmp$ man 5 ls
No manual entry for ls in section 5
See 'man 7 undocumented' for help when manual pages are not available.
xb@dnxb:/tmp$ man 1posix ls
xb@dnxb:/tmp$

The default ordering can be found here (This file path described in man man), search order from left to right:

xb@dnxb:/tmp$ \grep SECTION /etc/manpath.config
# the default is 1, n, l, 8, 3, 0, 2, 5, 4, 9, 6, 7. Multiple SECTION
SECTION         1 n l 8 3 2 3posix 3pm 3perl 5 4 9 6 7
xb@dnxb:/tmp$ 

How can I display sections of a man-page ? How can I figure out what sections a man page offers ?

Use apropos [-e], whatis, or man -k:

xb@dnxb:/tmp$ apropos statvfs #OR man -k statvfs
fstatvfs (2)         - get filesystem statistics
fstatvfs (3)         - get filesystem statistics
fstatvfs (3posix)    - get file system information
statvfs (2)          - get filesystem statistics
statvfs (3)          - get filesystem statistics
statvfs (3posix)     - get file system information
statvfs.h (7posix)   - VFS File System information structure
sys_statvfs.h (7posix) - VFS File System information structure
xb@dnxb:/tmp$ apropos -e statvfs #OR whatis statvfs
statvfs (2)          - get filesystem statistics
statvfs (3)          - get filesystem statistics
statvfs (3posix)     - get file system information
xb@dnxb:/tmp$ 

[2.]

How can I display a short version/preview of a man page ?

I always use --help to see shorten version of manual(Disclaimer: Not exactly equivalent), e.g.:

xb@dnxb:/tmp$ mplayer --help
Usage:   mplayer [options] [url|path/]filename

Basic options: (complete list in the man page)
 -vo <drv>        select video output driver ('-vo help' for a list)
 -ao <drv>        select audio output driver ('-ao help' for a list)
 vcd://<trackno>  play (S)VCD (Super Video CD) track (raw device, no mount)
 dvd://<titleno>  play DVD title from device instead of plain file
 -alang/-slang    select DVD audio/subtitle language (by 2-char country code)
 -ss <position>   seek to given (seconds or hh:mm:ss) position
 -nosound         do not play sound
 -fs              fullscreen playback (or -vm, -zoom, details in the man page)
 -x <x> -y <y>    set display resolution (for use with -vm or -zoom)
 -sub <file>      specify subtitle file to use (also see -subfps, -subdelay)
 -playlist <file> specify playlist file
 -vid x -aid y    select video (x) and audio (y) stream to play
 -fps x -srate y  change video (x fps) and audio (y Hz) rate
 -pp <quality>    enable postprocessing filter (details in the man page)
 -framedrop       enable frame dropping (for slow machines)

Basic keys: (complete list in the man page, also check input.conf)
 <-  or  ->       seek backward/forward 10 seconds
 down or up       seek backward/forward  1 minute
 pgdown or pgup   seek backward/forward 10 minutes
 < or >           step backward/forward in playlist
 p or SPACE       pause movie (press any key to continue)
 q or ESC         stop playing and quit program
 + or -           adjust audio delay by +/- 0.1 second
 o                cycle OSD mode:  none / seekbar / seekbar + timer
 * or /           increase or decrease PCM volume
 x or z           adjust subtitle delay by +/- 0.1 second
 r or t           adjust subtitle position up/down, also see -vf expand

 * * * SEE THE MAN PAGE FOR DETAILS, FURTHER (ADVANCED) OPTIONS AND KEYS * * *

MPlayer 1.3.0 (Debian), built with gcc-5.4.0 (C) 2000-2016 MPlayer Team
xb@dnxb:/tmp$