Re: [PATCH 1/1] Documentation: Link man pages to https://man7.org/

[Petr Vorel <pvorel@suse.cz>]

> Hi Petr!

> On Fri, Jan 09, 2026 at 07:30:09PM +0100, Petr Vorel wrote:
> > Convert mentioned man pages in docs to pages online in
> > https://man7.org/. Use new extension sphinx.ext.extlinks + format
> > custom CSS.

> > NOTE: Keep :manpage: (plain text instead of link) for non-existing man
> > pages (xyzzy(2), xyzzyat(2), fxyzzy(3)) in adding-syscalls.rst
> > (including translations).

> > Signed-off-by: Petr Vorel <pvorel@suse.cz>
> > ---
> > Hi all,

> > @Michael @Alejandro (or whoever is responsible for man7.org),
> > feel free to shout if you don't like extra traffic from kernel.org doc.

> <man7.org> is Michael's website.

> > @Jonathan I chose man7.org as it looks as the most complete and the most
> > up to date man page collection.

> FWIW, Michael has been following recent releases of the project quite
> promptly (faster than distros), so it's reasonable to use it.


> > Kind regards,
> > Petr

> >  Documentation/admin-guide/LSM/landlock.rst    |  2 +-
> >  Documentation/admin-guide/initrd.rst          |  6 +--
> >  Documentation/arch/powerpc/dexcr.rst          |  6 +--
> >  Documentation/bpf/prog_lsm.rst                |  4 +-
> >  Documentation/conf.py                         |  9 ++++
> >  Documentation/dev-tools/kunit/start.rst       |  2 +-
> >  Documentation/process/adding-syscalls.rst     | 30 ++++++------
> >  Documentation/security/landlock.rst           |  2 +-
> >  Documentation/sphinx-static/custom.css        |  7 ++-
> >  .../it_IT/process/adding-syscalls.rst         | 30 ++++++------
> >  .../sp_SP/process/adding-syscalls.rst         | 30 ++++++------
> >  Documentation/userspace-api/check_exec.rst    | 10 ++--
> >  Documentation/userspace-api/landlock.rst      | 46 +++++++++----------
> >  Documentation/userspace-api/spec_ctrl.rst     |  6 +--
> >  14 files changed, 102 insertions(+), 88 deletions(-)

> > diff --git a/Documentation/admin-guide/LSM/landlock.rst b/Documentation/admin-guide/LSM/landlock.rst
> > index 9e61607def087..8b1e8ba36b719 100644
> > --- a/Documentation/admin-guide/LSM/landlock.rst
> > +++ b/Documentation/admin-guide/LSM/landlock.rst
> > @@ -143,7 +143,7 @@ filters to limit noise with two complementary ways:

> >  - with sys_landlock_restrict_self()'s flags if we can fix the sandboxed
> >    programs,
> > -- or with audit rules (see :manpage:`auditctl(8)`).
> > +- or with audit rules (see :man8:`auditctl`).

> >  Additional documentation
> >  ========================

> [...]

> > diff --git a/Documentation/conf.py b/Documentation/conf.py
> > index 1ea2ae5c6276c..e6b972f1f1b02 100644
> > --- a/Documentation/conf.py
> > +++ b/Documentation/conf.py
> > @@ -38,6 +38,14 @@ doctree = os.path.abspath(".")
> >  # Exclude of patterns that don't contain directory names, in glob format.
> >  exclude_patterns = []

> > +extlinks = {
> > +    # when adding new section update also custom.css
> > +    'man2': ('https://man7.org/linux/man-pages/man2/%s.2.html', '%s(2)'),
> > +    'man3': ('https://man7.org/linux/man-pages/man3/%s.3.html', '%s(3)'),
> > +    'man7': ('https://man7.org/linux/man-pages/man7/%s.7.html', '%s(7)'),
> > +    'man8': ('https://man7.org/linux/man-pages/man8/%s.8.html', '%s(8)'),
> > +}

> I wonder if this could be implemented in a way that wouldn't need
> changing any lines of documentation.

Good point. Yes, there is sphinx way to do it as one liner (no need for any
python scripting):
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-manpages_url

But the problem is that it creates links also for non-existing man pages
(xyzzy(2), xyzzyat(2), fxyzzy(3)) in adding-syscalls.rst. I'll convert them not
being man pages.

Kind regards,
Petr

> I'm thinking of something like this shell script (sorry, I don't speak
> python):

> 	$ echo 'syscall(2)' \
> 	| sed 's,\(.*\)(\([0-9]\)),https://man7.org/linux/man-pages/man\2/\1.\2.html &,';
> 	https://man7.org/linux/man-pages/man2/syscall.2.html syscall(2)


> Have a lovely night!
> Alex

> > +
> >  # List of patterns that contain directory names in glob format.
> >  dyn_include_patterns = []
> >  dyn_exclude_patterns = ["output"]

> [...]