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

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 3770 bytes --]

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.

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"]

[...]

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]