After writing the previous blog entry, I started to think about how to specify page section when opening the manual page. It is a simple but quite interesting issue, so I quickly got curious and wrote this post to describe a straight solution. Just to be clear – I need to mention that I am not writing about section numbers describing distinct subject areas but just page sections, such as NAME, SYNOPSIS, DESCRIPTION, AUTHORS, and so on.

How to read section headings

In short, you need to search for .SH "<text>" macro (quotes are not needed, can be empty) inside nroff source file.

I will start with the ssh manual page as an example.

$ man ssh

To get the used source file location, use -w (–where, –location) parameter.

$ man -w ssh
/usr/share/man/man1/ssh.1.gz

Display the gzipped source file.

$ gzip -c -d $(man -w ssh)

Now it is possible to read, modify (remove apostrophes and first four characters – i.e. ".SH ") and print section headings using sed.

$ gzip -d $(man -w ssh) -c | sed -n -e "/^\.S[hH]/{s/\"//g;s/^.\{4\}//;p}"

It works, but it would be easier to place the above-mentioned commands in a short shell script (man_sections.sh).

#!/bin/bash
# Simple shell script to print section headings for specific manual page
# Usage:   script.sh manual_page
# Example: script.sh ssh

if [ "$#" -eq "1" ]; then
  # use current locale and keep empty lines
  $(which gzip) -c -d $(man -w ${1}) 2>/dev/null | $(which sed) -n -e "/^\.S[hH]/{s/\"//g;s/^.\{4\}//;p}"
  # use C locale and delete empty lines
  # $(which gzip) -c -d $(man --locale=C -w ${1}) 2>/dev/null | $(which sed) -n -e "/^\.S[hH]/{s/\"//g;s/^.\{4\}//;/^$/d;p}"
else
  echo "\$ ${0} manual_page"
fi

Prepare the above script and check it out.

$ vi man_sections.sh
$ chmod +x man_sections.sh

$ ./man_sections.sh ssh
NAME
SYNOPSIS
DESCRIPTION
AUTHENTICATION
ESCAPE CHARACTERS
TCP FORWARDING
X11 FORWARDING
VERIFYING HOST KEYS
SSH-BASED VIRTUAL PRIVATE NETWORKS
ENVIRONMENT
FILES
EXIT STATUS
SEE ALSO
AUTHORS

$ ./man_sections.sh undocumented
NAME
SYNOPSIS
DESCRIPTION
COLOPHON

$ ./man_sections.sh xyz
No manual entry for xyz

$ ./man_sections.sh
Usage: man_sections.sh manual_page

This is out of this blog entry scope, but further improvements should take section numbers into consideration. Just look at the example below to see why this is an important matter.

$ man -w 1 mkdir
/usr/share/man/pl/man1/mkdir.1.gz

$ man -w 2 mkdir
/usr/share/man/man2/mkdir.2.gz

How to open the manual page and jump to the specified page heading

You can quickly open the manual page and start reading at the first occurrence of the specific section name (ESCAPE CHARACTERS in this example).

$ man -P 'less +/ESCAPE\ CHARACTERS' ssh
ESCAPE CHARACTERS
     When a pseudo-terminal has been requested, ssh supports a number of functions through the use of an escape character.
[..]

It would be easier to use a shell script (man_section.sh).

#!/bin/bash
# Simple shell script to open manual page and jump to specific section heading
# Usage:   script.sh section_heading manual_page
# Example: script.sh ESCAPE\ CHARACTERS ssh

# escape spaces for section name: "single param" -> "single\ param"
section=`echo ${1} | $(which sed) -e 's/ /\\\ /g'`

if [ "$#" -eq "2" ]; then
  # use current locale
  $(which man) -P "less +/${section}" ${2} 2>/dev/null
  # use C locale
  # $(which man) --locale=C -P "less +/${section}" ${2} 2>/dev/null
else
  echo "Usage: ${0} section_heading manual_page"
fi

To see the usage of the above-mentioned script, look at the examples below.

$ ./man_section.sh
Usage: man_section.sh section_heading manual_page

$ ./man_section.sh AUTHOR ls

$ ./man_section.sh ESCAPE\ CHAR ssh
$ ./man_section.sh "ESCAPE CHAR" ssh