[PATCH v2 0/3] Documentation: Link man pages to https://man7.org/

[PATCH v2 0/3] Documentation: Link man pages to https://man7.org/

[Petr Vorel]

Changes v1->v2:
* Use :manpages_url: (a proper sphinx syntax)
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-manpages_url
* 2 new cleanup commits
  -  Documentation: sp_SP: Add missing man page section
  - Documentation: Remove :manpage: from non-existing man pages

Link to v1:
https://lore.kernel.org/linux-doc/20260109183012.114372-1-pvorel@suse.cz/

Petr Vorel (3):
  Documentation: sp_SP: Add missing man page section
  Documentation: Remove :manpage: from non-existing man pages
  Documentation: Link man pages to https://man7.org/

 Documentation/conf.py                              |  3 +++
 Documentation/process/adding-syscalls.rst          | 14 +++++++-------
 .../translations/it_IT/process/adding-syscalls.rst | 14 +++++++-------
 .../translations/sp_SP/process/adding-syscalls.rst | 14 +++++++-------
 4 files changed, 24 insertions(+), 21 deletions(-)

-- 
2.51.0

[PATCH v2 1/3] Documentation: sp_SP: Add missing man page section

[Petr Vorel]

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
New in v2.

 Documentation/translations/sp_SP/process/adding-syscalls.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/translations/sp_SP/process/adding-syscalls.rst b/Documentation/translations/sp_SP/process/adding-syscalls.rst
index f21504c612b25..28f680652383d 100644
--- a/Documentation/translations/sp_SP/process/adding-syscalls.rst
+++ b/Documentation/translations/sp_SP/process/adding-syscalls.rst
@@ -172,7 +172,7 @@ describiendo un describiendo un movimiento dentro de un archivo, ponga de
 tipo ``loff_t`` para que movimientos de 64-bit puedan ser soportados
 incluso en arquitecturas de 32-bit.
 
-Si su nueva llamada de sistema  :manpage:`xyzzy` involucra una
+Si su nueva llamada de sistema :manpage:`xyzzy(2)` involucra una
 funcionalidad privilegiada, esta necesita ser gobernada por la capability
 bit linux apropiada (revisado con una llamada a ``capable()``), como se
 describe en el man page :manpage:`capabilities(7)`. Elija una parte de
-- 
2.51.0

[PATCH v2 2/3] Documentation: Remove :manpage: from non-existing man pages

[Petr Vorel]

Removing :manpage: from non-existing man pages (xyzzy(2), xyzzyat(2),
fxyzzy(3) in adding-syscalls.rst, including translations) prevent
adding link to nonexisting man pages when using manpages_url in next
commit.

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
New in v2.

 Documentation/process/adding-syscalls.rst          | 14 +++++++-------
 .../translations/it_IT/process/adding-syscalls.rst | 14 +++++++-------
 .../translations/sp_SP/process/adding-syscalls.rst | 14 +++++++-------
 3 files changed, 21 insertions(+), 21 deletions(-)

diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst
index fc0b0bbcd34df..1f61d0b114120 100644
--- a/Documentation/process/adding-syscalls.rst
+++ b/Documentation/process/adding-syscalls.rst
@@ -111,7 +111,7 @@ should use a file descriptor as the handle for that object -- don't invent a
 new type of userspace object handle when the kernel already has mechanisms and
 well-defined semantics for using file descriptors.
 
-If your new :manpage:`xyzzy(2)` system call does return a new file descriptor,
+If your new `xyzzy(2)` system call does return a new file descriptor,
 then the flags argument should include a value that is equivalent to setting
 ``O_CLOEXEC`` on the new FD.  This makes it possible for userspace to close
 the timing window between ``xyzzy()`` and calling
@@ -127,11 +127,11 @@ descriptor. Making a file descriptor ready for reading or writing is the
 normal way for the kernel to indicate to userspace that an event has
 occurred on the corresponding kernel object.
 
-If your new :manpage:`xyzzy(2)` system call involves a filename argument::
+If your new `xyzzy(2)` system call involves a filename argument::
 
     int sys_xyzzy(const char __user *path, ..., unsigned int flags);
 
-you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate::
+you should also consider whether an `xyzzyat(2)` version is more appropriate::
 
     int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags);
 
@@ -147,11 +147,11 @@ giving an :manpage:`fxyzzy(3)` operation for free::
 :manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the
 :manpage:`fstatat(2)` man page.)
 
-If your new :manpage:`xyzzy(2)` system call involves a parameter describing an
+If your new `xyzzy(2)` system call involves a parameter describing an
 offset within a file, make its type ``loff_t`` so that 64-bit offsets can be
 supported even on 32-bit architectures.
 
-If your new :manpage:`xyzzy(2)` system call involves privileged functionality,
+If your new `xyzzy(2)` system call involves privileged functionality,
 it needs to be governed by the appropriate Linux capability bit (checked with
 a call to ``capable()``), as described in the :manpage:`capabilities(7)` man
 page.  Choose an existing capability bit that governs related functionality,
@@ -160,7 +160,7 @@ under the same bit, as this goes against capabilities' purpose of splitting
 the power of root.  In particular, avoid adding new uses of the already
 overly-general ``CAP_SYS_ADMIN`` capability.
 
-If your new :manpage:`xyzzy(2)` system call manipulates a process other than
+If your new `xyzzy(2)` system call manipulates a process other than
 the calling process, it should be restricted (using a call to
 ``ptrace_may_access()``) so that only a calling process with the same
 permissions as the target process, or with the necessary capabilities, can
@@ -196,7 +196,7 @@ be cc'ed to linux-api@vger.kernel.org.
 Generic System Call Implementation
 ----------------------------------
 
-The main entry point for your new :manpage:`xyzzy(2)` system call will be called
+The main entry point for your new `xyzzy(2)` system call will be called
 ``sys_xyzzy()``, but you add this entry point with the appropriate
 ``SYSCALL_DEFINEn()`` macro rather than explicitly.  The 'n' indicates the
 number of arguments to the system call, and the macro takes the system call name
diff --git a/Documentation/translations/it_IT/process/adding-syscalls.rst b/Documentation/translations/it_IT/process/adding-syscalls.rst
index df8c652d004b1..b8151daf02195 100644
--- a/Documentation/translations/it_IT/process/adding-syscalls.rst
+++ b/Documentation/translations/it_IT/process/adding-syscalls.rst
@@ -124,7 +124,7 @@ descrittore di file per accesso all'oggetto - non inventatevi nuovi tipi di
 accesso da spazio utente quando il kernel ha già dei meccanismi e una semantica
 ben definita per utilizzare i descrittori di file.
 
-Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` ritorna un nuovo
+Se la vostra nuova chiamata di sistema `xyzzy(2)` ritorna un nuovo
 descrittore di file, allora l'argomento *flags* dovrebbe includere un valore
 equivalente a ``O_CLOEXEC`` per i nuovi descrittori.  Questo rende possibile,
 nello spazio utente, la chiusura della finestra temporale fra le chiamate a
@@ -140,13 +140,13 @@ della famiglia di :manpage:`poll(2)`. Rendere un descrittore di file pronto
 per la lettura o la scrittura è il tipico modo del kernel per notificare lo
 spazio utente circa un evento associato all'oggetto del kernel.
 
-Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` ha un argomento
+Se la vostra nuova chiamata di sistema `xyzzy(2)` ha un argomento
 che è il percorso ad un file::
 
     int sys_xyzzy(const char __user *path, ..., unsigned int flags);
 
 dovreste anche considerare se non sia più appropriata una versione
-:manpage:`xyzzyat(2)`::
+`xyzzyat(2)`::
 
     int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags);
 
@@ -163,12 +163,12 @@ funzionalità su un descrittore di file già aperto utilizzando il *flag*
 man :manpage:`openat(2)`; per un esempio di AT_EMPTY_PATH, leggere la pagina
 man :manpage:`fstatat(2)`).
 
-Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` prevede un parametro
+Se la vostra nuova chiamata di sistema `xyzzy(2)` prevede un parametro
 per descrivere uno scostamento all'interno di un file, usate ``loff_t`` come
 tipo cosicché scostamenti a 64-bit potranno essere supportati anche su
 architetture a 32-bit.
 
-Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` prevede l'uso di
+Se la vostra nuova chiamata di sistema `xyzzy(2)` prevede l'uso di
 funzioni riservate, allora dev'essere gestita da un opportuno bit di privilegio
 (verificato con una chiamata a ``capable()``), come descritto nella pagina man
 :manpage:`capabilities(7)`.  Scegliete un bit di privilegio già esistente per
@@ -178,7 +178,7 @@ principio di *capabilities* di separare i poteri di root.  In particolare,
 evitate di aggiungere nuovi usi al fin-troppo-generico privilegio
 ``CAP_SYS_ADMIN``.
 
-Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` manipola altri
+Se la vostra nuova chiamata di sistema `xyzzy(2)` manipola altri
 processi oltre a quello chiamato, allora dovrebbe essere limitata (usando
 la chiamata ``ptrace_may_access()``) di modo che solo un processo chiamante
 con gli stessi permessi del processo in oggetto, o con i necessari privilegi,
@@ -219,7 +219,7 @@ Implementazione di chiamate di sistema generiche
 ------------------------------------------------
 
 Il principale punto d'accesso alla vostra nuova chiamata di sistema
-:manpage:`xyzzy(2)` verrà chiamato ``sys_xyzzy()``; ma, piuttosto che in modo
+`xyzzy(2)` verrà chiamato ``sys_xyzzy()``; ma, piuttosto che in modo
 esplicito, lo aggiungerete tramite la macro ``SYSCALL_DEFINEn``. La 'n'
 indica il numero di argomenti della chiamata di sistema; la macro ha come
 argomento il nome della chiamata di sistema, seguito dalle coppie (tipo, nome)
diff --git a/Documentation/translations/sp_SP/process/adding-syscalls.rst b/Documentation/translations/sp_SP/process/adding-syscalls.rst
index 28f680652383d..4765aa8d58d9f 100644
--- a/Documentation/translations/sp_SP/process/adding-syscalls.rst
+++ b/Documentation/translations/sp_SP/process/adding-syscalls.rst
@@ -128,7 +128,7 @@ manipulador de ese objeto -- no invente un nuevo tipo de objeto manipulador
 userspace cuando el kernel ya tiene mecanismos y semánticas bien definidas
 para usar los descriptores de archivos.
 
-Si su nueva llamada a sistema :manpage:`xyzzy(2)` retorna un nuevo
+Si su nueva llamada a sistema `xyzzy(2)` retorna un nuevo
 descriptor de archivo, entonces el argumento flag debe incluir un valor que
 sea equivalente a definir ``O_CLOEXEC`` en el nuevo FD. Esto hace posible
 al userspace acortar la brecha de tiempo entre ``xyzzy()`` y la llamada a
@@ -145,12 +145,12 @@ archivo listo para leer o escribir es la forma normal para que el kernel
 indique al espacio de usuario que un evento ha ocurrido en el
 correspondiente objeto del kernel.
 
-Si su nueva llamada de sistema :manpage:`xyzzy(2)` involucra algún nombre
+Si su nueva llamada de sistema `xyzzy(2)` involucra algún nombre
 de archivo como argumento::
 
     int sys_xyzzy(const char __user *path, ..., unsigned int flags);
 
-debería considerar también si una versión :manpage:`xyzzyat(2)` es mas
+debería considerar también si una versión `xyzzyat(2)` es mas
 apropiada::
 
     int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags);
@@ -167,12 +167,12 @@ efectivamente dando una operación :manpage:`fxyzzy(3)` gratis::
 revise el man page :manpage:`openat(2)`; para un ejemplo de AT_EMPTY_PATH,
 mire el man page :manpage:`fstatat(2)` manpage.)
 
-Si su nueva llamada de sistema :manpage:`xyzzy(2)` involucra un parámetro
+Si su nueva llamada de sistema `xyzzy(2)` involucra un parámetro
 describiendo un describiendo un movimiento dentro de un archivo, ponga de
 tipo ``loff_t`` para que movimientos de 64-bit puedan ser soportados
 incluso en arquitecturas de 32-bit.
 
-Si su nueva llamada de sistema :manpage:`xyzzy(2)` involucra una
+Si su nueva llamada de sistema `xyzzy(2)` involucra una
 funcionalidad privilegiada, esta necesita ser gobernada por la capability
 bit linux apropiada (revisado con una llamada a ``capable()``), como se
 describe en el man page :manpage:`capabilities(7)`. Elija una parte de
@@ -182,7 +182,7 @@ misma sección, ya que va en contra de los propósitos de las capabilities de
 dividir el poder del usuario root. En particular, evite agregar nuevos usos
 de la capacidad ya demasiado general de la capabilities ``CAP_SYS_ADMIN``.
 
-Si su nueva llamada de sistema :manpage:`xyzzy(2)` manipula un proceso que
+Si su nueva llamada de sistema `xyzzy(2)` manipula un proceso que
 no es el proceso invocado, este debería ser restringido (usando una llamada
 a ``ptrace_may_access()``) de forma que el único proceso con los mismos
 permisos del proceso objetivo, o con las capacidades (capabilities)
@@ -221,7 +221,7 @@ kernel, debería siempre ser copiado a linux-api@vger.kernel.org.
 Implementation de Llamada de Sistema Generica
 ---------------------------------------------
 
-La entrada principal a su nueva llamada de sistema :manpage:`xyzzy(2)` será
+La entrada principal a su nueva llamada de sistema `xyzzy(2)` será
 llamada ``sys_xyzzy()``, pero incluya este punto de entrada con la macro
 ``SYSCALL_DEFINEn()`` apropiada en vez de explicitamente. El 'n' indica el
 numero de argumentos de la llamada de sistema, y la macro toma el nombre de
-- 
2.51.0

[PATCH v2 3/3] Documentation: Link man pages to https://man7.org/

[Petr Vorel]

Configure manpages_url to link man pages to https://man7.org/.
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-manpages_url

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
Completely rewritten in v2.

 Documentation/conf.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 1ea2ae5c6276c..16d025af1f304 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -51,6 +51,9 @@ else:
     dyn_exclude_patterns.append("devicetree/bindings/**.yaml")
     dyn_exclude_patterns.append("core-api/kho/bindings/**.yaml")
 
+# Link to man pages
+manpages_url = 'https://man7.org/linux/man-pages/man{section}/{page}.{section}.html'
+
 # Properly handle directory patterns and LaTeX docs
 # -------------------------------------------------
 
-- 
2.51.0

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

[Alejandro Colomar]

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

Hi Petr,

On Mon, Jan 12, 2026 at 12:35:32AM +0100, Petr Vorel wrote:
> Configure manpages_url to link man pages to https://man7.org/.
> https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-manpages_url
> 
> Signed-off-by: Petr Vorel <pvorel@suse.cz>
> ---
> Completely rewritten in v2.
> 
>  Documentation/conf.py | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 1ea2ae5c6276c..16d025af1f304 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -51,6 +51,9 @@ else:
>      dyn_exclude_patterns.append("devicetree/bindings/**.yaml")
>      dyn_exclude_patterns.append("core-api/kho/bindings/**.yaml")
>  
> +# Link to man pages
> +manpages_url = 'https://man7.org/linux/man-pages/man{section}/{page}.{section}.html'

Nice!

Acked-by: Alejandro Colomar <alx@kernel.org>


Cheers,
Alex

> +
>  # Properly handle directory patterns and LaTeX docs
>  # -------------------------------------------------
>  
> -- 
> 2.51.0
> 

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

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

Re: [PATCH v2 1/3] Documentation: sp_SP: Add missing man page section

[Alejandro Colomar]

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

On Mon, Jan 12, 2026 at 12:35:30AM +0100, Petr Vorel wrote:
> Signed-off-by: Petr Vorel <pvorel@suse.cz>
> ---
> New in v2.
> 
>  Documentation/translations/sp_SP/process/adding-syscalls.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/translations/sp_SP/process/adding-syscalls.rst b/Documentation/translations/sp_SP/process/adding-syscalls.rst
> index f21504c612b25..28f680652383d 100644
> --- a/Documentation/translations/sp_SP/process/adding-syscalls.rst
> +++ b/Documentation/translations/sp_SP/process/adding-syscalls.rst
> @@ -172,7 +172,7 @@ describiendo un describiendo un movimiento dentro de un archivo, ponga de
>  tipo ``loff_t`` para que movimientos de 64-bit puedan ser soportados
>  incluso en arquitecturas de 32-bit.
>  
> -Si su nueva llamada de sistema  :manpage:`xyzzy` involucra una
> +Si su nueva llamada de sistema :manpage:`xyzzy(2)` involucra una

Reviewed-by: Alejandro Colomar <alx@kernel.org>

>  funcionalidad privilegiada, esta necesita ser gobernada por la capability
>  bit linux apropiada (revisado con una llamada a ``capable()``), como se
>  describe en el man page :manpage:`capabilities(7)`. Elija una parte de
> -- 
> 2.51.0
> 

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

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

Re: [PATCH v2 2/3] Documentation: Remove :manpage: from non-existing man pages

[Alejandro Colomar]

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

On Mon, Jan 12, 2026 at 12:35:31AM +0100, Petr Vorel wrote:
> Removing :manpage: from non-existing man pages (xyzzy(2), xyzzyat(2),
> fxyzzy(3) in adding-syscalls.rst, including translations) prevent
> adding link to nonexisting man pages when using manpages_url in next
> commit.
> 
> Signed-off-by: Petr Vorel <pvorel@suse.cz>

Reviewed-by: Alejandro Colomar <alx@kernel.org>

> ---
> New in v2.
> 
>  Documentation/process/adding-syscalls.rst          | 14 +++++++-------
>  .../translations/it_IT/process/adding-syscalls.rst | 14 +++++++-------
>  .../translations/sp_SP/process/adding-syscalls.rst | 14 +++++++-------
>  3 files changed, 21 insertions(+), 21 deletions(-)
> 
> diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst
> index fc0b0bbcd34df..1f61d0b114120 100644
> --- a/Documentation/process/adding-syscalls.rst
> +++ b/Documentation/process/adding-syscalls.rst
> @@ -111,7 +111,7 @@ should use a file descriptor as the handle for that object -- don't invent a
>  new type of userspace object handle when the kernel already has mechanisms and
>  well-defined semantics for using file descriptors.
>  
> -If your new :manpage:`xyzzy(2)` system call does return a new file descriptor,
> +If your new `xyzzy(2)` system call does return a new file descriptor,
>  then the flags argument should include a value that is equivalent to setting
>  ``O_CLOEXEC`` on the new FD.  This makes it possible for userspace to close
>  the timing window between ``xyzzy()`` and calling
> @@ -127,11 +127,11 @@ descriptor. Making a file descriptor ready for reading or writing is the
>  normal way for the kernel to indicate to userspace that an event has
>  occurred on the corresponding kernel object.
>  
> -If your new :manpage:`xyzzy(2)` system call involves a filename argument::
> +If your new `xyzzy(2)` system call involves a filename argument::
>  
>      int sys_xyzzy(const char __user *path, ..., unsigned int flags);
>  
> -you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate::
> +you should also consider whether an `xyzzyat(2)` version is more appropriate::
>  
>      int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags);
>  
> @@ -147,11 +147,11 @@ giving an :manpage:`fxyzzy(3)` operation for free::
>  :manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the
>  :manpage:`fstatat(2)` man page.)
>  
> -If your new :manpage:`xyzzy(2)` system call involves a parameter describing an
> +If your new `xyzzy(2)` system call involves a parameter describing an
>  offset within a file, make its type ``loff_t`` so that 64-bit offsets can be
>  supported even on 32-bit architectures.
>  
> -If your new :manpage:`xyzzy(2)` system call involves privileged functionality,
> +If your new `xyzzy(2)` system call involves privileged functionality,
>  it needs to be governed by the appropriate Linux capability bit (checked with
>  a call to ``capable()``), as described in the :manpage:`capabilities(7)` man
>  page.  Choose an existing capability bit that governs related functionality,
> @@ -160,7 +160,7 @@ under the same bit, as this goes against capabilities' purpose of splitting
>  the power of root.  In particular, avoid adding new uses of the already
>  overly-general ``CAP_SYS_ADMIN`` capability.
>  
> -If your new :manpage:`xyzzy(2)` system call manipulates a process other than
> +If your new `xyzzy(2)` system call manipulates a process other than
>  the calling process, it should be restricted (using a call to
>  ``ptrace_may_access()``) so that only a calling process with the same
>  permissions as the target process, or with the necessary capabilities, can
> @@ -196,7 +196,7 @@ be cc'ed to linux-api@vger.kernel.org.
>  Generic System Call Implementation
>  ----------------------------------
>  
> -The main entry point for your new :manpage:`xyzzy(2)` system call will be called
> +The main entry point for your new `xyzzy(2)` system call will be called
>  ``sys_xyzzy()``, but you add this entry point with the appropriate
>  ``SYSCALL_DEFINEn()`` macro rather than explicitly.  The 'n' indicates the
>  number of arguments to the system call, and the macro takes the system call name
> diff --git a/Documentation/translations/it_IT/process/adding-syscalls.rst b/Documentation/translations/it_IT/process/adding-syscalls.rst
> index df8c652d004b1..b8151daf02195 100644
> --- a/Documentation/translations/it_IT/process/adding-syscalls.rst
> +++ b/Documentation/translations/it_IT/process/adding-syscalls.rst
> @@ -124,7 +124,7 @@ descrittore di file per accesso all'oggetto - non inventatevi nuovi tipi di
>  accesso da spazio utente quando il kernel ha già dei meccanismi e una semantica
>  ben definita per utilizzare i descrittori di file.
>  
> -Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` ritorna un nuovo
> +Se la vostra nuova chiamata di sistema `xyzzy(2)` ritorna un nuovo
>  descrittore di file, allora l'argomento *flags* dovrebbe includere un valore
>  equivalente a ``O_CLOEXEC`` per i nuovi descrittori.  Questo rende possibile,
>  nello spazio utente, la chiusura della finestra temporale fra le chiamate a
> @@ -140,13 +140,13 @@ della famiglia di :manpage:`poll(2)`. Rendere un descrittore di file pronto
>  per la lettura o la scrittura è il tipico modo del kernel per notificare lo
>  spazio utente circa un evento associato all'oggetto del kernel.
>  
> -Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` ha un argomento
> +Se la vostra nuova chiamata di sistema `xyzzy(2)` ha un argomento
>  che è il percorso ad un file::
>  
>      int sys_xyzzy(const char __user *path, ..., unsigned int flags);
>  
>  dovreste anche considerare se non sia più appropriata una versione
> -:manpage:`xyzzyat(2)`::
> +`xyzzyat(2)`::
>  
>      int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags);
>  
> @@ -163,12 +163,12 @@ funzionalità su un descrittore di file già aperto utilizzando il *flag*
>  man :manpage:`openat(2)`; per un esempio di AT_EMPTY_PATH, leggere la pagina
>  man :manpage:`fstatat(2)`).
>  
> -Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` prevede un parametro
> +Se la vostra nuova chiamata di sistema `xyzzy(2)` prevede un parametro
>  per descrivere uno scostamento all'interno di un file, usate ``loff_t`` come
>  tipo cosicché scostamenti a 64-bit potranno essere supportati anche su
>  architetture a 32-bit.
>  
> -Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` prevede l'uso di
> +Se la vostra nuova chiamata di sistema `xyzzy(2)` prevede l'uso di
>  funzioni riservate, allora dev'essere gestita da un opportuno bit di privilegio
>  (verificato con una chiamata a ``capable()``), come descritto nella pagina man
>  :manpage:`capabilities(7)`.  Scegliete un bit di privilegio già esistente per
> @@ -178,7 +178,7 @@ principio di *capabilities* di separare i poteri di root.  In particolare,
>  evitate di aggiungere nuovi usi al fin-troppo-generico privilegio
>  ``CAP_SYS_ADMIN``.
>  
> -Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` manipola altri
> +Se la vostra nuova chiamata di sistema `xyzzy(2)` manipola altri
>  processi oltre a quello chiamato, allora dovrebbe essere limitata (usando
>  la chiamata ``ptrace_may_access()``) di modo che solo un processo chiamante
>  con gli stessi permessi del processo in oggetto, o con i necessari privilegi,
> @@ -219,7 +219,7 @@ Implementazione di chiamate di sistema generiche
>  ------------------------------------------------
>  
>  Il principale punto d'accesso alla vostra nuova chiamata di sistema
> -:manpage:`xyzzy(2)` verrà chiamato ``sys_xyzzy()``; ma, piuttosto che in modo
> +`xyzzy(2)` verrà chiamato ``sys_xyzzy()``; ma, piuttosto che in modo
>  esplicito, lo aggiungerete tramite la macro ``SYSCALL_DEFINEn``. La 'n'
>  indica il numero di argomenti della chiamata di sistema; la macro ha come
>  argomento il nome della chiamata di sistema, seguito dalle coppie (tipo, nome)
> diff --git a/Documentation/translations/sp_SP/process/adding-syscalls.rst b/Documentation/translations/sp_SP/process/adding-syscalls.rst
> index 28f680652383d..4765aa8d58d9f 100644
> --- a/Documentation/translations/sp_SP/process/adding-syscalls.rst
> +++ b/Documentation/translations/sp_SP/process/adding-syscalls.rst
> @@ -128,7 +128,7 @@ manipulador de ese objeto -- no invente un nuevo tipo de objeto manipulador
>  userspace cuando el kernel ya tiene mecanismos y semánticas bien definidas
>  para usar los descriptores de archivos.
>  
> -Si su nueva llamada a sistema :manpage:`xyzzy(2)` retorna un nuevo
> +Si su nueva llamada a sistema `xyzzy(2)` retorna un nuevo
>  descriptor de archivo, entonces el argumento flag debe incluir un valor que
>  sea equivalente a definir ``O_CLOEXEC`` en el nuevo FD. Esto hace posible
>  al userspace acortar la brecha de tiempo entre ``xyzzy()`` y la llamada a
> @@ -145,12 +145,12 @@ archivo listo para leer o escribir es la forma normal para que el kernel
>  indique al espacio de usuario que un evento ha ocurrido en el
>  correspondiente objeto del kernel.
>  
> -Si su nueva llamada de sistema :manpage:`xyzzy(2)` involucra algún nombre
> +Si su nueva llamada de sistema `xyzzy(2)` involucra algún nombre
>  de archivo como argumento::
>  
>      int sys_xyzzy(const char __user *path, ..., unsigned int flags);
>  
> -debería considerar también si una versión :manpage:`xyzzyat(2)` es mas
> +debería considerar también si una versión `xyzzyat(2)` es mas
>  apropiada::
>  
>      int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags);
> @@ -167,12 +167,12 @@ efectivamente dando una operación :manpage:`fxyzzy(3)` gratis::
>  revise el man page :manpage:`openat(2)`; para un ejemplo de AT_EMPTY_PATH,
>  mire el man page :manpage:`fstatat(2)` manpage.)
>  
> -Si su nueva llamada de sistema :manpage:`xyzzy(2)` involucra un parámetro
> +Si su nueva llamada de sistema `xyzzy(2)` involucra un parámetro
>  describiendo un describiendo un movimiento dentro de un archivo, ponga de
>  tipo ``loff_t`` para que movimientos de 64-bit puedan ser soportados
>  incluso en arquitecturas de 32-bit.
>  
> -Si su nueva llamada de sistema :manpage:`xyzzy(2)` involucra una
> +Si su nueva llamada de sistema `xyzzy(2)` involucra una
>  funcionalidad privilegiada, esta necesita ser gobernada por la capability
>  bit linux apropiada (revisado con una llamada a ``capable()``), como se
>  describe en el man page :manpage:`capabilities(7)`. Elija una parte de
> @@ -182,7 +182,7 @@ misma sección, ya que va en contra de los propósitos de las capabilities de
>  dividir el poder del usuario root. En particular, evite agregar nuevos usos
>  de la capacidad ya demasiado general de la capabilities ``CAP_SYS_ADMIN``.
>  
> -Si su nueva llamada de sistema :manpage:`xyzzy(2)` manipula un proceso que
> +Si su nueva llamada de sistema `xyzzy(2)` manipula un proceso que
>  no es el proceso invocado, este debería ser restringido (usando una llamada
>  a ``ptrace_may_access()``) de forma que el único proceso con los mismos
>  permisos del proceso objetivo, o con las capacidades (capabilities)
> @@ -221,7 +221,7 @@ kernel, debería siempre ser copiado a linux-api@vger.kernel.org.
>  Implementation de Llamada de Sistema Generica
>  ---------------------------------------------
>  
> -La entrada principal a su nueva llamada de sistema :manpage:`xyzzy(2)` será
> +La entrada principal a su nueva llamada de sistema `xyzzy(2)` será
>  llamada ``sys_xyzzy()``, pero incluya este punto de entrada con la macro
>  ``SYSCALL_DEFINEn()`` apropiada en vez de explicitamente. El 'n' indica el
>  numero de argumentos de la llamada de sistema, y la macro toma el nombre de
> -- 
> 2.51.0
> 

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

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

Re: [PATCH v2 1/3] Documentation: sp_SP: Add missing man page section

[Jonathan Corbet]

Petr Vorel <pvorel@suse.cz> writes:

> Signed-off-by: Petr Vorel <pvorel@suse.cz>
> ---
> New in v2.
>
>  Documentation/translations/sp_SP/process/adding-syscalls.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/translations/sp_SP/process/adding-syscalls.rst b/Documentation/translations/sp_SP/process/adding-syscalls.rst
> index f21504c612b25..28f680652383d 100644
> --- a/Documentation/translations/sp_SP/process/adding-syscalls.rst
> +++ b/Documentation/translations/sp_SP/process/adding-syscalls.rst
> @@ -172,7 +172,7 @@ describiendo un describiendo un movimiento dentro de un archivo, ponga de
>  tipo ``loff_t`` para que movimientos de 64-bit puedan ser soportados
>  incluso en arquitecturas de 32-bit.
>  
> -Si su nueva llamada de sistema  :manpage:`xyzzy` involucra una
> +Si su nueva llamada de sistema :manpage:`xyzzy(2)` involucra una
>  funcionalidad privilegiada, esta necesita ser gobernada por la capability

I would just fix that while changing the line in the next patch anyway,
but whatever...

jon

Re: [PATCH v2 2/3] Documentation: Remove :manpage: from non-existing man pages

[Jonathan Corbet]

Petr Vorel <pvorel@suse.cz> writes:

> Removing :manpage: from non-existing man pages (xyzzy(2), xyzzyat(2),
> fxyzzy(3) in adding-syscalls.rst, including translations) prevent
> adding link to nonexisting man pages when using manpages_url in next
> commit.
>
> Signed-off-by: Petr Vorel <pvorel@suse.cz>
> ---
> New in v2.
>
>  Documentation/process/adding-syscalls.rst          | 14 +++++++-------
>  .../translations/it_IT/process/adding-syscalls.rst | 14 +++++++-------
>  .../translations/sp_SP/process/adding-syscalls.rst | 14 +++++++-------
>  3 files changed, 21 insertions(+), 21 deletions(-)
>
> diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst
> index fc0b0bbcd34df..1f61d0b114120 100644
> --- a/Documentation/process/adding-syscalls.rst
> +++ b/Documentation/process/adding-syscalls.rst
> @@ -111,7 +111,7 @@ should use a file descriptor as the handle for that object -- don't invent a
>  new type of userspace object handle when the kernel already has mechanisms and
>  well-defined semantics for using file descriptors.
>  
> -If your new :manpage:`xyzzy(2)` system call does return a new file descriptor,
> +If your new `xyzzy(2)` system call does return a new file descriptor,

Here, once again, you're retaining the backticks.  If we need to mark up
those references at all, they should be ``literal``.

(If you simply remove the backticks, you might run into conflict with
automarkup, though I *think* that the section number will evade its
regexp).

Thanks,

jon

Re: [PATCH v2 2/3] Documentation: Remove :manpage: from non-existing man pages

[Petr Vorel]

> Petr Vorel <pvorel@suse.cz> writes:

> > Removing :manpage: from non-existing man pages (xyzzy(2), xyzzyat(2),
> > fxyzzy(3) in adding-syscalls.rst, including translations) prevent
> > adding link to nonexisting man pages when using manpages_url in next
> > commit.

> > Signed-off-by: Petr Vorel <pvorel@suse.cz>
> > ---
> > New in v2.

> >  Documentation/process/adding-syscalls.rst          | 14 +++++++-------
> >  .../translations/it_IT/process/adding-syscalls.rst | 14 +++++++-------
> >  .../translations/sp_SP/process/adding-syscalls.rst | 14 +++++++-------
> >  3 files changed, 21 insertions(+), 21 deletions(-)

> > diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst
> > index fc0b0bbcd34df..1f61d0b114120 100644
> > --- a/Documentation/process/adding-syscalls.rst
> > +++ b/Documentation/process/adding-syscalls.rst
> > @@ -111,7 +111,7 @@ should use a file descriptor as the handle for that object -- don't invent a
> >  new type of userspace object handle when the kernel already has mechanisms and
> >  well-defined semantics for using file descriptors.

> > -If your new :manpage:`xyzzy(2)` system call does return a new file descriptor,
> > +If your new `xyzzy(2)` system call does return a new file descriptor,

> Here, once again, you're retaining the backticks.  If we need to mark up
> those references at all, they should be ``literal``.

I'm sorry to keep the same mistake. BTW I did not notice because both real man
pages a) without manpages_url:

<em class="manpage">read(2)</em>

b) with manpages_url:

<em class="manpage">
<a class="manpage reference external" href="https://man7.org/linux/man-pages/man8/auditctl.8.html">auditctl(8)</a>
</em>

don't have specified CSS. And because my browser default has font-style: italic
for <em>, I don't see any difference for :manpage:`read(2)` and `read(2)`.

BTW I'll add in v3 CSS font-family: ..., monospace for manpages.

> (If you simply remove the backticks, you might run into conflict with
> automarkup, though I *think* that the section number will evade its
> regexp).

In my local build plain fxyzzy(3) without backticks works. I slightly prefer to
not use double ``.

Kind regards,
Petr

> Thanks,

> jon

Re: [PATCH v2 2/3] Documentation: Remove :manpage: from non-existing man pages

[Alejandro Colomar]

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

Hi Petr,

On Tue, Jan 13, 2026 at 12:00:53PM +0100, Petr Vorel wrote:
[...]
> > > -If your new :manpage:`xyzzy(2)` system call does return a new file descriptor,
> > > +If your new `xyzzy(2)` system call does return a new file descriptor,
> 
> > Here, once again, you're retaining the backticks.  If we need to mark up
> > those references at all, they should be ``literal``.
> 
> I'm sorry to keep the same mistake. BTW I did not notice because both real man
> pages a) without manpages_url:
> 
> <em class="manpage">read(2)</em>
> 
> b) with manpages_url:
> 
> <em class="manpage">
> <a class="manpage reference external" href="https://man7.org/linux/man-pages/man8/auditctl.8.html">auditctl(8)</a>
> </em>
> 
> don't have specified CSS. And because my browser default has font-style: italic
> for <em>, I don't see any difference for :manpage:`read(2)` and `read(2)`.
> 
> BTW I'll add in v3 CSS font-family: ..., monospace for manpages.

FWIW, in the Linux man-pages project, we currently use bold with
proportional font for manual page references, and will soon change to
italics with proportional font.  We don't use monospace (when formatting
in PDF, of course).


Have a lovely day!
Alex

> > (If you simply remove the backticks, you might run into conflict with
> > automarkup, though I *think* that the section number will evade its
> > regexp).
> 
> In my local build plain fxyzzy(3) without backticks works. I slightly prefer to
> not use double ``.
> 
> Kind regards,
> Petr
> 
> > Thanks,
> 
> > jon

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

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