Ubuntu technical problems and solutions reference, a modern cookbook.
Recently I was faced with a new issue/challenge: adding custom man pages for a custom/user defined command. This being said, I started to dig into the configuration and structure of the man command.
I will not go too deep into the man theory, there is always Google for it, or the official manual pages:
As I now know, after reading documentation, there are 9 section of documentation for each command. So, it means separate documentation file for each section.
In the following example I will create custom documentation for section 1 (Executable user programs and shell commands) and section 4 (Information on device files). I call the command dummy.
#The following commands create the default structure for custom man pages cd ~/ mkdir ownman; mkdir ownman/man1; mkdir ownman/man4 cd ownman/man1 vi dummy.1 # Add some documentation here. Example: 1) Documentation for section 1 cd ../man4 vi dummy.4 # Add some documentation here. Example: 1) Documentation for section 4
Now that the structure is in place, the man pages for the the dummy command can be called. The -M option has to be used in order to specify the location of the man pages for the specific command.
man -M ~/ownman dummy 1) Documentation for section 1 Manual page dummy(1) line 1/66 (END) (press h for help or q to quit)
The default section is 1, so it’s not necessary to be specified here. With specification, the command looks like this:
man -M ~/ownman 4 dummy 1) Documentation for section 4 Manual page dummy(4) line 1/66 (END) (press h for help or q to quit)
The structure and the call is in place now. But still, it could be tiresome sometimes to remember the path to the man pages, especially if one were to declare multiple locations.
To add the ~/ownman location to the locations man is looking at by default, the configuration file needs to be edited. On Ubuntu this file is: /etc/manpath.config (for Red Hat and Red Hat derivatives, like CentOS and Fedora, the configuration file for man is /etc/man.config)
# need sudo rights for this, as the owner of the file is root sudo vi /etc/manpath.config
Edit the file by adding a new entry in the MANDATORY_MANPATH section.
If there is a need to specify different man pages path for different command paths, another edit needs to be made, further down in the file. A new entry for MANPATH_MAP
MANPATH_MAP ~/custom_commands_location ~/ownman
Now the simple, straight forward command can be called:
man dummy 1) Documentation for section 1 Manual page dummy(1) line 1/66 (END) (press h for help or q to quit)
What if you want to add a new application in the “Open With Other Application…” section? Maybe you want to add that particular application as the default application to open certain type of files.
Here is an example of how I can add Vim as an option to open a text file. Vim will open the file in a new terminal session.
An .desktop file needs to be created in ~/.local/share/applications
So, let’s use vim for this purpose, it is just appropriate.
Press i to enter in edit mode and type in the following:
[Desktop Entry] Categories=; Comment=Edit file in Vim Exec=vim %f GenericName=Process Viewer Hidden=false Icon=vim Name=Vim Terminal=true Type=Application Version=1.0
after that, press ESC to exit the edit mode and type :wq to write to the file and quit.
That’s it. Now when you right click on a file, vim will be present in the list of Open With Other Application section, and you can add it as a default application.
Thanks for this answer to Marty Fried