Find contents of a man page

Question

Can I find the contents of a man page?

man bash is almost 6000 lines long, and I would like to know the section headings within the page.

Answer 1

If you just want the section headings, grep for them. They are in ALLCAPS and are the only lines that have no leading spaces:

$ man bash | grep '^[A-Z]'
BASH(1)                                General Commands         Manual                                BASH(1)
NAME
SYNOPSIS
COPYRIGHT
DESCRIPTION
OPTIONS
ARGUMENTS
INVOCATION
DEFINITIONS
RESERVED WORDS
SHELL GRAMMAR
COMMENTS
QUOTING
PARAMETERS
EXPANSION
REDIRECTION
ALIASES
FUNCTIONS
ARITHMETIC EVALUATION
CONDITIONAL EXPRESSIONS
SIMPLE COMMAND EXPANSION
COMMAND EXECUTION
COMMAND EXECUTION ENVIRONMENT
ENVIRONMENT
EXIT STATUS
SIGNALS
JOB CONTROL
PROMPTING
READLINE
HISTORY
HISTORY EXPANSION
SHELL BUILTIN COMMANDS
RESTRICTED SHELL
SEE ALSO
FILES
AUTHORS
BUG REPORTS
BUGS
GNU Bash 4.3                               2014 February 2                                    BASH(1)

Answer 2

• run man as usual, which ought to run less to display the content, as evidenced by this kind of status line (at the bottom of the terminal window):

    Manual page man(1) line 1 (press h for help or q to quit)
  

• type &^( )?[^ ] (with 3 spaces between the parentheses), then hit return, which should get you this:

    MAN(1)                        Manual pager utils                        MAN(1)
    NAME
    SYNOPSIS
    DESCRIPTION
    EXAMPLES
    OVERVIEW
    DEFAULTS
    OPTIONS
       General options
       Main modes of operation
       Finding manual pages
       Controlling formatted output
       Getting help
    EXIT STATUS
    ENVIRONMENT
    FILES
    SEE ALSO
    HISTORY
    2.8.3                             2018-04-05                            MAN(1)
  

  (bonus: with this method you get subsections as well)

• scroll so the section or subsection of interest sits in the first line. You might have to use shift-J to allow less to scroll the bottom of the screen beyond the end of file:

       Controlling formatted output
       Getting help
    EXIT STATUS
    ENVIRONMENT
    FILES
    SEE ALSO
    HISTORY
    2.8.3                             2018-04-05                            MAN(1)
    ~
    ~
    ~
    ~
    ~
    ~
    ~
    ~
    ~
    ~
    ~
  

• type &, then hit return, which should get you this:

       Controlling formatted output
           -P pager, --pager=pager
                  Specify which output pager to use.  By default, man uses  pager,
                  falling  back to cat if pager is not found or is not executable.
                  This option overrides the $MANPAGER environment variable,  which
                  in  turn  overrides  the $PAGER environment variable.  It is not
                  used in conjunction with -f or -k.
  
                  The value may be a simple command name or a command  with  argu‐
                  ments, and may use shell quoting (backslashes, single quotes, or
                  double quotes).  It may not use pipes to connect  multiple  com‐
                  mands;  if  you  need that, use a wrapper script, which may take
                  the file to display either as an argument or on standard input.
  
           -r prompt, --prompt=prompt
                  If a recent version of less is  used  as  the  pager,  man  will
                  attempt  to  set  its  prompt  and  some  sensible options.  The
                  default prompt looks like
  

  Note how the first line on screen remains the same.

• Browse the contents

• Repeat as necessary

Answer 3

Convert it to html. You will have table of contents with links:

bunzip2 -c $(man -w bash) | groff -mandoc -Thtml > /tmp/bash.html && \
firefox -remote "openURL(file:///tmp/bash.html, new-tab)"

You can create a function which will do it automatically for all man pages if you like.

Answer 4

If you are comfortable with using Neovim as your man pager, it can do this. It has an interactive table of contents that can be activated with gO, as well as some other useful navigation shortcuts. It can be set as your default man pager by adding the following variable to your shell:

export MANPAGER='nvim +Man!'

---

From :help :Man:

MAN                 *ft-man-plugin* *:Man* *man.vim*

View manpages in Nvim. Supports highlighting, completion, locales, and
navigation. Also see |find-manpage|.

...

Local mappings:
K or CTRL-]               Jump to the manpage for the <cWORD> under the
                          cursor. Takes a count for the section.
CTRL-T                    Jump back to the location that the manpage was
                          opened from.
gO                        Show the manpage outline. |gO|
q                         :quit if invoked as $MANPAGER, otherwise :close.

...

To use Nvim as a manpager:
     export MANPAGER='nvim +Man!'

Answer 5

Assuming you haven't changed your pager, you will be viewing man pages in less.

To search in less, type /regex, e.g. /^SHELL BUILTIN COMMANDS, then press enter. Use n/N to navigate between multiple matches.

Answer 6

Manpage sections are in all-caps with no leading blanks, but subsections can also be distinguished, because they begin with a predictable number of blanks (3).

I use that fact in generating navigation links for manpages (such as xterm) with my version of man2html.

$ man bash | grep -E '^ {,3}[A-Z]'

gives

BASH(1)                     General Commands Manual                    BASH(1)
NAME
SYNOPSIS
COPYRIGHT
DESCRIPTION
OPTIONS
ARGUMENTS
INVOCATION
DEFINITIONS
RESERVED WORDS
SHELL GRAMMAR
   Simple Commands
   Pipelines
   Lists
   Compound Commands
   Coprocesses
   Shell Function Definitions
COMMENTS
QUOTING
PARAMETERS
   Positional Parameters
   Special Parameters
   Shell Variables
   Arrays
EXPANSION
   Brace Expansion
   Tilde Expansion
   Parameter Expansion
   Command Substitution
   Arithmetic Expansion
   Process Substitution
   Word Splitting
   Pathname Expansion
   Quote Removal
REDIRECTION
   Redirecting Input
   Redirecting Output
   Appending Redirected Output
   Redirecting Standard Output and Standard Error
   Appending Standard Output and Standard Error
   Here Documents
   Here Strings
   Duplicating File Descriptors
   Moving File Descriptors
   Opening File Descriptors for Reading and Writing
ALIASES
FUNCTIONS
ARITHMETIC EVALUATION
CONDITIONAL EXPRESSIONS
SIMPLE COMMAND EXPANSION
COMMAND EXECUTION
COMMAND EXECUTION ENVIRONMENT
ENVIRONMENT
EXIT STATUS
SIGNALS
JOB CONTROL
PROMPTING
READLINE
   Readline Notation
   Readline Initialization
   Readline Key Bindings
   Readline Variables
   Readline Conditional Constructs
   Searching
   Readline Command Names
   Commands for Moving
   Commands for Manipulating the History
   Commands for Changing Text
   Killing and Yanking
   Numeric Arguments
   Completing
   Keyboard Macros
   Miscellaneous
   Programmable Completion
HISTORY
HISTORY EXPANSION
   Event Designators
   Word Designators
   Modifiers
SHELL BUILTIN COMMANDS
RESTRICTED SHELL
SEE ALSO
FILES
AUTHORS
BUG REPORTS
BUGS
GNU Bash 5.0                    2018 December 7                        BASH(1)

Interestingly enough, xterm's manual page uses more lines than bash, but fewer characters. That's because xterm uses more whitespace, for readability:

But in either case (roughly 6000-7000 lines) that's 150-175 screen/pages in my xterm window, so some navigation aid is helpful. Some use an editor (as I did in the screenshot), and that allows displaying the section/subsection titles as done using grep. Others use a web browser. The comments about groff do not mention that it does not provide navigation for subsections, which may be important. Half of the outline for the bash manpage is at the subsection level.