After writing previous blog entry I started to think about how to specify page section when opening manual page. It is simple but quite interesting issue so I quickly got curious and wrote this post to describe 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 ssh manual page as an example:
To get the location of the used source file use -w (--where, --location) parameter:
$ man -w ssh
/usr/share/man/man1/ssh.1.gz |
To display the gzipped source file use commands:
$ 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 if we 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 scope of this blog entry but further improvements should take section numbers into consideration. Just look at the example below to see why it 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 manual page and jump to the specified page heading
You can quickly open manual page and start reading at the first occurrence of the specific section name (ESCAPE CHARACTERS in this example) using command:
$ 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 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 usage of the above mentioned script look at 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 |