Hello, I have written a desktop app recently and packaged it as .rpm build.
Now I want to add a system level manual page for the application which could be easily searchable and presented by man <app-nam> command.
was wondering how it could be achieved?
how fedora manages app-level man pages?
which FHS location can I use?
On fedora the man pages are located under /usr/share/man with the file name including the section number. For example the section 1 pages are under /usr/share/man/man1 and the file name for all the mysql* pages are mysql*.1.gz
Additionally there is the info system which adds to the standard man pages but I have not researched the location of those files.
Yeah, for a packaged file, the Fedora Packaging Guidelines tell you what to do.
The rest of this is just for the curious…
For a local user-created file you’re not going to package, /usr/local/share/man is the place. (Or, specifically, /usr/local/share/man/man1 for an application, following the normal Linux man pages convention that user commands go in the “1” section.)
See man 5 manpath for details, and the specific implementation in /etc/man_db.conf on your system. There you will see that the Fedora default file includes /usr/man (which we don’t use anymore), /usr/share/man (the default for packaged files — putting local files here is possible but bad practice), and /usr/local/share/man (for local files).
Once you drop the file into place, you’ll also need to refresh the man pages cache. You can run mandb manually, or you can do sudo systemctl start man-db-cache-update, which makes sure it runs with the normal options Fedora uses. This is triggered after a RPM transaction so new packages you install automatically get their docs into the cache, and I think maybe also on reboot. So for the RPM package situation, just follow the guidelines and it will all be taken care of.
In any case, you can look at man mandb and at /usr/lib/systemd/system/man-db-cache-update.service to see the details of what’s going on.
More for the curious: Each element of your PATH variable will be examined for the existence of ../man, ../share/man, man and share/man relative to it, and, if found, they’ll be added to the search path for man pages.
/*
* For each directory in the user's path, see if it is one of the
* directories listed in the man_db.config file. If so, and it is
* not already in the manpath, add it. If the directory is not listed
* in the man_db.config file, see if there is a subdirectory `../man' or
* `man', or, for FHS-compliance, `../share/man' or `share/man'. If so,
* and it is not already in the manpath, add it.
* Example: user has $HOME/bin in his path and the directory
* $HOME/man exists -- the directory $HOME/man will be added
* to the manpath.
*/
manpath --debug is helpful for seeing what is going on.
Here’s a quick test, assuming $HOME/bin is on your path:
mkdir -p "$HOME/man/man1" && cd "$_"
# Sample markdown file for man page
# Via https://eddieantonio.ca/blog/2015/12/18/authoring-manpages-in-markdown-with-pandoc/
wget https://gist.githubusercontent.com/eddieantonio/55752dd76a003fefb562/raw/38f6eb9de250feef22ff80da124b0f439fba432d/hello.1.md
pandoc --standalone --to man hello.1.md -o hello.1