C++ manual pages

One of the great things about C is that its documentation is available locally via man command. That’s very convenient and one might expect to get the same for C++, but (say) man std::adjacent_difference will usually just print:

No manual entry for std::adjacent_difference

Luckily, there are ways to fix it.

libstdc++ man pages

A lot of places point to libstdc++ Doxygen files. And I think this is what I was trying to use several years ago (it was RPM package that needed to be converted to Slackware-friendly one via rpm2tgz), but removed afterwards because it ruined completion of man command as well as apropos by adding too many entries. It’s not an issue of the package itself, rather the way it was installed. Remembering that, this time everything will be installed in non-system directory to make it available only via separate command (this is why I’m giving it another try).

But. There is no versions for modern GCC. They probably just left building the packages to users. And that’s what one can do for sure, but this time I decided to try and use another option, which is described below. Building from GCC has the advantage that manual pages will correspond to installed implementation of standard library and I should definitely get back to this, but let’s see what the other option has to offer (it won’t harm to install both kinds of documentation, by the way).

cppreference.com archives

This is something that most of people use to get information about C++ API. There is also www.cplusplus.com, but at least in the past it was less complete and also slow at fixing bugs in the documentation.

So, cppreference.com provides its documentation in form of various archives. We’re particularly interested in manual pages, i.e., in cppman project.

Here’s one way to use it.

Installation

Install the pages at ~/.local/share/man/...:

git clone https://github.com/jeaye/stdman.git
cd stdman
./configure --prefix=$HOME/.local/
make install

Making whatis database

Original makewhatis available in Slackware didn’t work for all files due to somewhat non-standard names. Had to:

Remove check for special symbols in file names.
Use single quotes (') instead of double quotes (") around file names when invoking zcat (because names of some pages include double quotes, those that are about user-defined literals).

Version with these two small modifications is here.

Creating the database:

MANPATH="$HOME/.local/share/man/" bash makewhatis.sh -w

The -w option instructs makewhatis to query man for paths and man takes them from $MANPATH environment variable.

Commands to work with those manual pages

Below are command definitions for bash:

# c++ manual pages

# man for C++
function c()
{
    # colors
    local default=$(tput sgr0)
    local red=$(tput setaf 1)
    local green=$(tput setaf 2)
    local purple=$(tput setaf 218)
    local yellow=$(tput bold; tput setaf 230)

    # less colors for man pages
    PAGER=less \
    LESS_TERMCAP_mb=$red \
    LESS_TERMCAP_md=$yellow \
    LESS_TERMCAP_me=$default \
    LESS_TERMCAP_se=$default \
    LESS_TERMCAP_so=$purple \
    LESS_TERMCAP_ue=$default \
    LESS_TERMCAP_us=$green \
    MANPATH="$HOME/.local/share/man" \
    man "$@"
}
# apropos for C++ manual
function ca()
{
    MANPATH="$HOME/.local/share/man/" apropos "$@"
}
# completion wrapper for `c` command
function _complete_c()
{
    MANPATH="$HOME/.local/share/man" _man "$@"
}
# register completion for `c` command
complete -F _complete_c c

This assumes that bash-completion package is installed.

Two commands are:

c – man for C++.
ca – appropos for C++ (it won’t find for example std::string, which is why Doxygen files of GCC might be better, don’t remember how they handle this).

The code doesn’t require much explanation, it barely setups environment for man to see only custom pages. Colors used here are a bit different from those shown in the README of cppman, somewhat closer to normal man pages and a bit lighter.

cppman

This is a tool to automatically fetch articles from www.cplusplus.com or cppreference.com and convert them into manual pages. Default operational mode is to fetch them on request, which isn’t very nice, but there is a way to pre-cache everything, which is better.

This is another option to consider, but there is no real need for some intermediate tool like cppman if one can just install manual pages. Except maybe in case someone wants to use www.cplusplus.com pages, which might not be available in another form.

// load comments

reversed(top()) code tags rss about