Hello,
so I've created https://manpath.be - a site that provides access to the man pages of several distributions - including several Fedora and CentOS versions.
See also its about page https://manpath.be/about for some of its features (e.g. permalinks, short links, reverse links ...).
While working on this project I noticed a few issues with the man pages of Fedora packages:
Some packages include man pages auto-generated by doxygen. In my experience, those man pages are usually pretty human un-readable and thus quite useless. Thus, I exclude them from manpath.be.
Example: LAPACKE_cgges3_work(3) from the lapack package
That package contains 10 thousand or so auto-generated man pages.
Perhaps it makes sense to recommend packagers to exclude doxygen generated man pages from Fedora packages. For example, as part of the packaging policy.
Perhaps it also makes sense to add some man-page related checks to rpmlint or fedora-review (?), e.g. to check
- if a package creates sub-directories under /usr/share/man/man*/ Example: https://bugzilla.redhat.com/show_bug.cgi?id=1722350 - if a man page is empty - if a man page redirects to itself Example: https://bugzilla.redhat.com/show_bug.cgi?id=1720942 - if a man page has non-standard suffixes like 1.orig.gz instead of 1.gz - if the suffix of a man page matches the one of its subdirectory Examples: https://bugzilla.redhat.com/show_bug.cgi?id=1722440 https://bugzilla.redhat.com/show_bug.cgi?id=1722447 - if a man page contains verbatim escape sequences Example: https://bugzilla.redhat.com/show_bug.cgi?id=1725301 - if the man page display produces groff/grotty warnings/errors Example: https://bugzilla.redhat.com/show_bug.cgi?id=1725402
Thoughts?
Best regards Georg
On Sat, Jul 13, 2019 at 04:19:02PM +0200, Georg Sauthoff wrote:
Hello,
so I've created https://manpath.be - a site that provides access to the man pages of several distributions - including several Fedora and CentOS versions.
See also its about page https://manpath.be/about for some of its features (e.g. permalinks, short links, reverse links ...).
Looks interesting. One thing that seems missing at first sight is search: it'd be great to have interactive search across sections. Right now, it's only easy to find a page is one knows the section and the exact name.
One issue that I had before with similar services was that it was never possible to rely on any given one to provide _all_ man pages. In systemd we link to man pages online from online versions of our pages under http://www.freedesktop.org/software/systemd/man/index.html, and we have to link to a bunch of different services (man7.org, linux.die.net, mankier.com), because we need to link to kernel man pages, and various fringe tools, some distro-specific man pages, etc. Two suggestions: 1. pull pages from many different sources, 2. include a suggestion box for people to mention what they can't find.
I don't have any comment on the issues you listed. It'd be useful to diagnose such issues automatically. That'd probably help to cut down on the number of issues.
Zbyszek
On Sun, Jul 14, 2019 at 04:49:40PM +0000, Zbigniew Jędrzejewski-Szmek wrote:
On Sat, Jul 13, 2019 at 04:19:02PM +0200, Georg Sauthoff wrote:
[..]
See also its about page https://manpath.be/about for some of its features (e.g. permalinks, short links, reverse links ...).
Looks interesting. One thing that seems missing at first sight is search: it'd be great to have interactive search across sections. Right now, it's only easy to find a page is one knows the section and the exact name.
Right now you can google search the site like this:
memory management site:manpath.be/f30
This turns up the malloc and fork man pages, for example.
I plan to add a search feature to the site. Probably first a search form in the left column that redirects the query to a google search like in the above example. In a second step perhaps I'll also add some internal search functionality.
One issue that I had before with similar services was that it was never possible to rely on any given one to provide _all_ man pages. In systemd we link to man pages online from online versions of our pages under http://www.freedesktop.org/software/systemd/man/index.html, and we have to link to a bunch of different services (man7.org, linux.die.net, mankier.com), because we need to link to kernel man pages, and various fringe tools, some distro-specific man pages, etc. Two suggestions: 1. pull pages from many different
My approach for Fedora/CentOS is to import all valid man pages from all available packages (i.e. what is available if you just enable the fedora/base + updates repositories).
Thus, with respect to Fedora/CentOS the man page repository should be pretty complete.
I plan to add more distributions/versions in the future.
sources, 2. include a suggestion box for people to mention what they can't find.
There is a suggestion feature when a requested page isn't found but is available in another section. For example:
https://manpath.be/f30/2/popen
yields:
Page not found (404) No such man page: popen(2) Similar pages:
popen(3) popen(3p)
(where the alternatives are linked)
If you navigate to a page that is available in a certain section but also in others the right column lists the alternatives - in case one wasn't aware of the alternatives - and/or used a suboptimal section. Example:
https://manpath.be/f30/1/write
lists the alternatives: write(1p), write(2) and write(3p)
Best regards Georg