From ec5161e651b95e9c45eaa674e83162aef420adc2 Mon Sep 17 00:00:00 2001
From: lacatoire <la.catoire@gmail.com>
Date: Wed, 2 Sep 2026 09:50:46 +0200
Subject: [PATCH] sync: document readline functions unavailable where feature
 is not supported

- Add readline.system-callback-support entity to language-snippets.ent
- Update book.xml and setup.xml with availability details
- Add entity reference to callback handler install/remove/read-char
- Add entity reference + seealso to readline_on_new_line and readline_redisplay
- Add availability simpara to readline_list_history
- Update EN-Revision to 8648d1cda141537b5dbd403a0bf0e6eb8c086e9d
---
 language-snippets.ent                           | 10 +++++++++-
 reference/readline/book.xml                     |  7 ++++---
 .../readline-callback-handler-install.xml       |  4 ++--
 .../readline-callback-handler-remove.xml        |  4 ++--
 .../functions/readline-callback-read-char.xml   |  4 ++--
 .../functions/readline-list-history.xml         |  8 ++++++--
 .../readline/functions/readline-on-new-line.xml | 16 +++++++---------
 .../readline/functions/readline-redisplay.xml   | 11 +++++++++--
 reference/readline/setup.xml                    | 17 +++++++++++++++--
 9 files changed, 56 insertions(+), 25 deletions(-)

diff --git a/language-snippets.ent b/language-snippets.ent
index 192107853d..8816669f77 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 1ab1069cdd60b4ec4c18c0832924e20109159902 Maintainer: argosback Status: ready -->
+<!-- EN-Revision: 8648d1cda141537b5dbd403a0bf0e6eb8c086e9d Maintainer: argosback Status: ready -->
 
 <!ENTITY installation.enabled.disable 'Esta extensión está activada por defecto. Puede ser desactivada utilizando la opción de configuración: '>
 
@@ -4593,6 +4593,14 @@ xmlns="http://docbook.org/ns/docbook"><simpara>Esta función ha sido
   </informaltable>
 '>
 
+<!-- readline -->
+<!ENTITY readline.system-callback-support '
+  <simpara xmlns="http://docbook.org/ns/docbook">
+   Esta función solo está disponible si la biblioteca readline con la que se compiló
+   PHP la admite. No está disponible en Windows.
+  </simpara>
+'>
+
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
diff --git a/reference/readline/book.xml b/reference/readline/book.xml
index 8ca7fcdb44..b39f43fe80 100644
--- a/reference/readline/book.xml
+++ b/reference/readline/book.xml
@@ -1,7 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 53208f9bd0a035a4e1409ba700106540474c9ef1 Maintainer: PhilDaiguille Status: ready -->
-<!-- Reviewed: yes -->
+<!-- EN-Revision: 8648d1cda141537b5dbd403a0bf0e6eb8c086e9d Maintainer: PhilDaiguille Status: ready -->
 <book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="book.readline">
  <?phpdoc extension-membership="bundledexternal" ?>
  <title>GNU Readline</title>
@@ -19,7 +18,9 @@
    <link linkend="features.commandline">línea de comandos</link>.
   </simpara>
   <simpara>
-   A partir de PHP 7.1.0 esta extensión es soportada en Windows.  </simpara>
+   A partir de PHP 7.1.0 esta extensión es soportada en Windows, donde está compilada
+   contra libedit. No todas las funciones están presentes en esa compilación; véase
+   <link linkend="readline.requirements">los requisitos</link>.</simpara>
   <caution>
    <simpara>
     ¡La extensión readline no es thread-safe! Por consiguiente, el uso de esta
diff --git a/reference/readline/functions/readline-callback-handler-install.xml b/reference/readline/functions/readline-callback-handler-install.xml
index 1dffd164b9..3f986feb76 100644
--- a/reference/readline/functions/readline-callback-handler-install.xml
+++ b/reference/readline/functions/readline-callback-handler-install.xml
@@ -1,7 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: be246a268d0d5ab0b215c429cb031e70c98327ef Maintainer: PhilDaiguille Status: ready -->
-<!-- Reviewed: yes -->
+<!-- EN-Revision: 8648d1cda141537b5dbd403a0bf0e6eb8c086e9d Maintainer: PhilDaiguille Status: ready -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.readline-callback-handler-install">
  <refnamediv>
   <refname>readline_callback_handler_install</refname>
@@ -28,6 +27,7 @@
    la interconexión IO / entrada de usuario, a diferencia de
    <function>readline</function>.
   </simpara>
+  &readline.system-callback-support;
  </refsect1>
 
  <refsect1 role="parameters">
diff --git a/reference/readline/functions/readline-callback-handler-remove.xml b/reference/readline/functions/readline-callback-handler-remove.xml
index 5771422855..2a52686e2f 100644
--- a/reference/readline/functions/readline-callback-handler-remove.xml
+++ b/reference/readline/functions/readline-callback-handler-remove.xml
@@ -1,7 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 53208f9bd0a035a4e1409ba700106540474c9ef1 Maintainer: PhilDaiguille Status: ready -->
-<!-- Reviewed: yes -->
+<!-- EN-Revision: 8648d1cda141537b5dbd403a0bf0e6eb8c086e9d Maintainer: PhilDaiguille Status: ready -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.readline-callback-handler-remove">
  <refnamediv>
   <refname>readline_callback_handler_remove</refname>
@@ -18,6 +17,7 @@
    Elimina un manejador de devolución de llamada instalado previamente y restaura
    los parámetros del terminal.
   </simpara>
+  &readline.system-callback-support;
  </refsect1>
 
  <refsect1 role="parameters">
diff --git a/reference/readline/functions/readline-callback-read-char.xml b/reference/readline/functions/readline-callback-read-char.xml
index ee340ed575..6fe07a01d5 100644
--- a/reference/readline/functions/readline-callback-read-char.xml
+++ b/reference/readline/functions/readline-callback-read-char.xml
@@ -1,7 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 53208f9bd0a035a4e1409ba700106540474c9ef1 Maintainer: PhilDaiguille Status: ready -->
-<!-- Reviewed: yes -->
+<!-- EN-Revision: 8648d1cda141537b5dbd403a0bf0e6eb8c086e9d Maintainer: PhilDaiguille Status: ready -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.readline-callback-read-char">
  <refnamediv>
   <refname>readline_callback_read_char</refname>
@@ -19,6 +18,7 @@
    función informa a la interfaz de devolución de llamada readline instalada mediante
    <function>readline_callback_handler_install</function> de que una línea está lista para ser ingresada.
   </simpara>
+  &readline.system-callback-support;
  </refsect1>
 
  <refsect1 role="parameters">
diff --git a/reference/readline/functions/readline-list-history.xml b/reference/readline/functions/readline-list-history.xml
index cb1ff239a9..8552d54bc7 100644
--- a/reference/readline/functions/readline-list-history.xml
+++ b/reference/readline/functions/readline-list-history.xml
@@ -1,7 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 53208f9bd0a035a4e1409ba700106540474c9ef1 Maintainer: PhilDaiguille Status: ready -->
-<!-- Reviewed: no Maintainer: Marqitos -->
+<!-- EN-Revision: 8648d1cda141537b5dbd403a0bf0e6eb8c086e9d Maintainer: PhilDaiguille Status: ready -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.readline-list-history">
  <refnamediv>
   <refname>readline_list_history</refname>
@@ -17,6 +16,11 @@
   <simpara>
    Lista el historial.
   </simpara>
+  <simpara>
+   Esta función solo está disponible si la biblioteca readline con la que se compiló
+   PHP proporciona listado de historial. Esto siempre es el caso con GNU Readline
+   y en Windows.
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
diff --git a/reference/readline/functions/readline-on-new-line.xml b/reference/readline/functions/readline-on-new-line.xml
index d073a56806..54b8829f22 100644
--- a/reference/readline/functions/readline-on-new-line.xml
+++ b/reference/readline/functions/readline-on-new-line.xml
@@ -1,7 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 53208f9bd0a035a4e1409ba700106540474c9ef1 Maintainer: PhilDaiguille Status: ready -->
-<!-- Reviewed: yes -->
+<!-- EN-Revision: 8648d1cda141537b5dbd403a0bf0e6eb8c086e9d Maintainer: PhilDaiguille Status: ready -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.readline-on-new-line">
  <refnamediv>
   <refname>readline_on_new_line</refname>
@@ -17,6 +16,7 @@
   <simpara>
    Indica a readline que el cursor ha pasado a una nueva línea.
   </simpara>
+  &readline.system-callback-support;
  </refsect1>
 
  <refsect1 role="parameters">
@@ -31,13 +31,11 @@
   </simpara>
  </refsect1>
 
- <refsect1 role="notes">
-  &reftitle.notes;
-  <note>
-   <simpara>
-    Esta función solo está disponible si es soportada por la biblioteca readline subyacente. No es soportada en Windows.
-   </simpara>
-  </note>
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><function>readline_callback_handler_install</function></member>
+  </simplelist>
  </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/readline/functions/readline-redisplay.xml b/reference/readline/functions/readline-redisplay.xml
index cf662af4e7..91d261bf8c 100644
--- a/reference/readline/functions/readline-redisplay.xml
+++ b/reference/readline/functions/readline-redisplay.xml
@@ -1,7 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 53208f9bd0a035a4e1409ba700106540474c9ef1 Maintainer: PhilDaiguille Status: ready -->
-<!-- Reviewed: yes -->
+<!-- EN-Revision: 8648d1cda141537b5dbd403a0bf0e6eb8c086e9d Maintainer: PhilDaiguille Status: ready -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.readline-redisplay">
  <refnamediv>
   <refname>readline_redisplay</refname>
@@ -17,6 +16,7 @@
   <simpara>
    Solicita a readline que vuelva a mostrar la información.
   </simpara>
+  &readline.system-callback-support;
  </refsect1>
 
  <refsect1 role="parameters">
@@ -30,6 +30,13 @@
    &return.void;
   </simpara>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><function>readline_callback_handler_install</function></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/readline/setup.xml b/reference/readline/setup.xml
index fc141cfaaa..1b8e2ed333 100644
--- a/reference/readline/setup.xml
+++ b/reference/readline/setup.xml
@@ -1,7 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 53208f9bd0a035a4e1409ba700106540474c9ef1 Maintainer: PhilDaiguille Status: ready -->
-<!-- Reviewed: yes -->
+<!-- EN-Revision: 8648d1cda141537b5dbd403a0bf0e6eb8c086e9d Maintainer: PhilDaiguille Status: ready -->
 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="readline.setup">
  &reftitle.setup;
 
@@ -20,6 +19,20 @@
    y disponible para descarga en
    <link xlink:href="&url.libedit;">&url.libedit;</link>.
   </simpara>
+  <simpara>
+   Ambas bibliotecas no ofrecen las mismas funcionalidades, por lo que algunas funciones
+   están ausentes en ciertas compilaciones. Las funciones que gestionan la interfaz de
+   devolución de llamada,
+   <function>readline_callback_handler_install</function>,
+   <function>readline_callback_handler_remove</function>,
+   <function>readline_callback_read_char</function>,
+   <function>readline_redisplay</function> y
+   <function>readline_on_new_line</function>, solo están presentes cuando la biblioteca
+   subyacente las proporciona, y están ausentes en Windows. Llamar a una función ausente
+   lanza una <exceptionname>Error</exceptionname>.
+   <function>function_exists</function> permite comprobar si una función dada está disponible,
+   y la constante <constant>READLINE_LIB</constant> indica qué biblioteca se está utilizando.
+  </simpara>
  </section>
  <!-- }}} -->