5

Is there an easy way to quickly view a condensed summary of a man page: just the description description, or intro? I don't see an option/flag that does this, is there another tool that does this for you?

Gilles 'SO- stop being evil'
  • 829,060
Oscalation
  • 1,139

6 Answers6

6

The condensed summary referred to by OP is likely the NAME section, which is treated specially by mandb or makewhatis (to prepare data for whatis and apropos.

By convention, this is a single line in those tools (although it may be wrapped due to length in the actual manpage). Also (still convention), there is a dash between the topic (on the left) and the short description.

Further reading (Linux):

man -k printf
Search the short descriptions and manual page names for the keyword printf as regular expression. Print out any matches. Equivalent to apropos printf.

man -f smail
Lookup the manual pages referenced by smail and print out the short descriptions of any found. Equivalent to whatis smail.

The apropos listing gives more results since it shows matches on any part of the line in the short description. For example, apropos printf might show

asprintf (3)         - print to allocated string
dprintf (3)          - print to a file descriptor
fprintf (3)          - formatted output conversion
fwprintf (3)         - formatted wide-character output conversion
printf (1)           - format and print data
printf (3)           - formatted output conversion
snprintf (3)         - formatted output conversion
sprintf (3)          - formatted output conversion
swprintf (3)         - formatted wide-character output conversion
vasprintf (3)        - print to allocated string
vdprintf (3)         - print to a file descriptor
vfprintf (3)         - formatted output conversion
vfwprintf (3)        - formatted wide-character output conversion
vprintf (3)          - formatted output conversion
vsnprintf (3)        - formatted output conversion
vsprintf (3)         - formatted output conversion
vswprintf (3)        - formatted wide-character output conversion
vwprintf (3)         - formatted wide-character output conversion
wprintf (3)          - formatted wide-character output conversion
XtAsprintf (3)       - memory management functions

But whatis looks for pages with the given topic name:

printf (1)           - format and print data  
printf (3)           - formatted output conversion

Other systems can differ:

  • OSX manual page for man(1), option -k is equivalent to apropos. In turn, apropos DESCRIPTION says "apropos searches a set of database files containing short descriptions of system commands for key-words keywords words and displays the result on the standard output.", while its NAME section says "apropos - search the whatis database for strings".
  • OSX manual page for manpages(5) gives the structure of manpages.

While the man program in each case can have options corresponding to apropos and whatis, the separate programs are more commonly used across various Unix-like systems.

Interestingly, POSIX has only man (and the -k option), with no match for whatis. In the rationale, it is noted

The -f option was considered, but due to implementation differences, it was not included in this volume of POSIX.1-2008.

Also, POSIX does not use the term apropos, but describes it. Likewise POSIX does not (in that section, at least) attempt to describe the structure of individual manpages nor how they are organized into sections. Those are system-dependent features.

Thomas Dickey
  • 76,765
5

These couple of functions show subsection and extract specific subsection, I'm sure they can be improved though:

Use:

mansubs < command >
manedit < command > < subsection >

mansubs() {
 man "$1" |col -bx|awk '/^[A-Z ]+$/ {print}'
}

manedit() {
 man "$1" |col -bx|awk -v S="$2" '$0 ~ S {cap="true"; print} $0 !~ S && /^[A-Z ]+$/ {cap="false"} $0 !~ S && !/^[A-Z ]+$/ {if(cap == "true")print}'
}

For instance:

$ mansubs grep
NAME
SYNOPSIS
DESCRIPTION
OPTIONS
REGULAR EXPRESSIONS
ENVIRONMENT VARIABLES
EXIT STATUS
COPYRIGHT
BUGS
SEE ALSO
NOTES

$ manedit grep SYNOPSIS
SYNOPSIS
       grep [OPTIONS] PATTERN [FILE...]
       grep [OPTIONS] [-e PATTERN | -f FILE] [FILE...]
XAVI
  • 166
2

Some commands support `--help or -h' which can give brief usage.

For specifically the man pages, I would suggest as an "easy" way is 

man | head -15 #Number of lines can be different for each man page

There are some other ways, such as writing a small function and setting as an alias.

Something to get you started:

function readManDesc() {
manPage="$1"
if [ -z "$2" ]; then
count="10"
else
count="$2"
fi
man $manPage | grep -A$count "^DESCRIPTION" #This will get the DESCRIPTION + the 10 lines that come after.
}

readManDesc $@

alias mandesc="bash manPageDesc.sh"

Usage: mandesc <command> <lines to count after DESCRIPTION>
J L
  • 121
2

Depending on what you mean by "description", man has an option:

-f, --whatis
      Equivalent to whatis.  Display a short description from the man‐
      ual page, if available.  See whatis(1) for details.

So:

$ man -f man                                   
man (7)              - macros to format man pages
man (1)              - an interface to the on-line reference manuals
man (1p)             - display system documentation
$ whatis man 
man (7)              - macros to format man pages
man (1)              - an interface to the on-line reference manuals
man (1p)             - display system documentation
muru
  • 72,889
0

if you mean just the description part of the man page before getting into the command line switches

man <command> | col -b > /tmp/randomtempfile

then using grep and sed you can extract however much information you need from the randomtempfile. As far as I know, man doesn't have an option to display summary pages.

MelBurslan
  • 6,966
0

How about something like below.

man <command> | grep -a1 "NAME\|Description"; echo ""

PS: The echo "" at the end is just added to add a newline at the end of output for cleaner output :)

Jatsui
  • 95
  • 3