1
0
mirror of https://github.com/php/doc-en.git synced 2026-03-23 23:32:18 +01:00

readline: fix XML by converting para to simpara tags via script

This commit is contained in:
Gina Peter Banyard
2026-01-26 15:26:32 +00:00
parent 3c4eb41f47
commit 53208f9bd0
17 changed files with 111 additions and 122 deletions

View File

@@ -1,15 +1,14 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<book xml:id="book.readline" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<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>
<titleabbrev>Readline</titleabbrev>
<!-- {{{ preface -->
<preface xml:id="intro.readline">
&reftitle.intro;
<para>
<simpara>
The readline functions implement an interface
to the GNU Readline library. These are functions that provide
editable command lines. An example being the way Bash allows you
@@ -18,25 +17,24 @@
library, it will be of little use for writing Web applications,
but may be useful when writing scripts used from a
<link linkend="features.commandline">command line</link>.
</para>
<para>
</simpara>
<simpara>
As of PHP 7.1.0 this extension is supported on Windows.
</para>
</simpara>
<caution>
<para>
<simpara>
The readline extension is not thread-safe! Thus, the usage of it with any
true thread safe SAPI (like Apache mod_winnt) is strongly discouraged.
</para>
</simpara>
</caution>
</preface>
<!-- }}} -->
&reference.readline.setup;
&reference.readline.constants;
&reference.readline.reference;
</book>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
@@ -57,4 +55,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View File

@@ -1,19 +1,18 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<section xml:id="readline.installation" xmlns="http://docbook.org/ns/docbook">
<section xmlns="http://docbook.org/ns/docbook" xml:id="readline.installation">
&reftitle.install;
<para>
<simpara>
To use these functions you must compile the CGI or CLI version of PHP
with readline support. You need to configure PHP
<option role="configure">--with-readline[=DIR]</option>.
If you want to use the libedit readline replacement, configure PHP
<option role="configure">--with-libedit[=DIR]</option>.
</para>
<para>
</simpara>
<simpara>
On Windows this extension is available by default as of PHP 7.1.0.
</para>
</simpara>
</section>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
@@ -34,4 +33,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View File

@@ -12,9 +12,9 @@
<type>true</type><methodname>readline_add_history</methodname>
<methodparam><type>string</type><parameter>prompt</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
This function adds a line to the command line history.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -23,9 +23,9 @@
<varlistentry>
<term><parameter>prompt</parameter></term>
<listitem>
<para>
<simpara>
The line to be added in the history.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -33,9 +33,9 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.true.always;
</para>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

View File

@@ -13,18 +13,18 @@
<methodparam><type>string</type><parameter>prompt</parameter></methodparam>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
Sets up a readline callback interface then prints
<parameter>prompt</parameter> and immediately returns.
Calling this function twice without removing the previous
callback interface will automatically and conveniently overwrite the old
interface.
</para>
<para>
</simpara>
<simpara>
The callback feature is useful when combined with
<function>stream_select</function> as it allows interleaving of IO and
user input, unlike <function>readline</function>.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -33,18 +33,18 @@
<varlistentry>
<term><parameter>prompt</parameter></term>
<listitem>
<para>
<simpara>
The prompt message.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>callback</parameter></term>
<listitem>
<para>
<simpara>
The <parameter>callback</parameter> function takes one parameter; the
user input returned.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -52,9 +52,9 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.true.always;
</para>
</simpara>
</refsect1>
<refsect1 role="examples">

View File

@@ -12,10 +12,10 @@
<type>bool</type><methodname>readline_callback_handler_remove</methodname>
<void/>
</methodsynopsis>
<para>
<simpara>
Removes a previously installed callback handler and restores terminal
settings.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -25,18 +25,18 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Returns &true; if a previously installed callback handler was removed, or
&false; if one could not be found.
</para>
</simpara>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<simpara>
See <function>readline_callback_handler_install</function> for an example
of how to use the readline callback interface.
</para>
</simpara>
</refsect1>
<refsect1 role="seealso">

View File

@@ -12,12 +12,12 @@
<type>void</type><methodname>readline_callback_read_char</methodname>
<void/>
</methodsynopsis>
<para>
<simpara>
Reads a character of user input. When a line is received, this function
informs the readline callback interface installed using
<function>readline_callback_handler_install</function> that a line
is ready for input.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -27,17 +27,17 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.void;
</para>
</simpara>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<simpara>
See <function>readline_callback_handler_install</function> for an example
of how to use the readline callback interface.
</para>
</simpara>
</refsect1>
<refsect1 role="seealso">

View File

@@ -1,20 +1,20 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.readline-clear-history" xmlns="http://docbook.org/ns/docbook">
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.readline-clear-history">
<refnamediv>
<refname>readline_clear_history</refname>
<refpurpose>Clears the history</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>true</type><methodname>readline_clear_history</methodname>
<void/>
</methodsynopsis>
<para>
<simpara>
This function clears the entire command line history.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -24,9 +24,9 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.true.always;
</para>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

View File

@@ -12,10 +12,10 @@
<type>bool</type><methodname>readline_completion_function</methodname>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
This function registers a completion function. This is the same kind of
functionality you'd get if you hit your tab key while using Bash.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -24,10 +24,10 @@
<varlistentry>
<term><parameter>callback</parameter></term>
<listitem>
<para>
<simpara>
You must supply the name of an existing function which accepts a
partial command line and returns an array of possible matches.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -35,9 +35,9 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.success;
</para>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

View File

@@ -13,9 +13,9 @@
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>var_name</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>int</type><type>string</type><type>bool</type><type>null</type></type><parameter>value</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
<simpara>
Gets or sets various internal readline variables.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -24,17 +24,17 @@
<varlistentry>
<term><parameter>var_name</parameter></term>
<listitem>
<para>
<simpara>
A variable name.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
<simpara>
If provided, this will be the new value of the setting.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -42,7 +42,7 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
If called with no parameters, this function returns an array of
values for all the settings readline uses. The elements will
be indexed by the following values: <literal>done</literal>, <literal>end</literal>, <literal>erase_empty_line</literal>,
@@ -50,10 +50,10 @@
<literal>readline_name</literal>, and <literal>terminal_name</literal>.
The &array; will only contain those elements which are supported by the library
used to built the readline extension.
</para>
<para>
</simpara>
<simpara>
If called with one or two parameters, the old value is returned.
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

View File

@@ -1,20 +1,20 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.readline-list-history" xmlns="http://docbook.org/ns/docbook">
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.readline-list-history">
<refnamediv>
<refname>readline_list_history</refname>
<refpurpose>Lists the history</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>readline_list_history</methodname>
<void/>
</methodsynopsis>
<para>
<simpara>
Gets the entire command line history.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -24,14 +24,13 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Returns an array of the entire command line history. The elements are
indexed by integers starting at zero.
</para>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

View File

@@ -1,20 +1,20 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.readline-on-new-line" xmlns="http://docbook.org/ns/docbook">
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.readline-on-new-line">
<refnamediv>
<refname>readline_on_new_line</refname>
<refpurpose>Inform readline that the cursor has moved to a new line</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>readline_on_new_line</methodname>
<void/>
</methodsynopsis>
<para>
<simpara>
Tells readline that the cursor has moved to a new line.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -24,22 +24,21 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.void;
</para>
</simpara>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
<simpara>
This function is only available if supported by the underlying readline library.
It is not supported on Windows.
</para>
</simpara>
</note>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

View File

@@ -12,9 +12,9 @@
<type>bool</type><methodname>readline_read_history</methodname>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>filename</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
<simpara>
This function reads a command history from a file.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -23,9 +23,9 @@
<varlistentry>
<term><parameter>filename</parameter></term>
<listitem>
<para>
<simpara>
Path to the filename containing the command history.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -33,9 +33,9 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.success;
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

View File

@@ -1,20 +1,20 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.readline-redisplay" xmlns="http://docbook.org/ns/docbook">
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.readline-redisplay">
<refnamediv>
<refname>readline_redisplay</refname>
<refpurpose>Redraws the display</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>readline_redisplay</methodname>
<void/>
</methodsynopsis>
<para>
<simpara>
Redraws readline to redraw the display.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -24,12 +24,11 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.void;
</para>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

View File

@@ -12,9 +12,9 @@
<type>bool</type><methodname>readline_write_history</methodname>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>filename</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
<simpara>
This function writes the command history to a file.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -23,9 +23,9 @@
<varlistentry>
<term><parameter>filename</parameter></term>
<listitem>
<para>
<simpara>
Path to the saved file.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -33,9 +33,9 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
&return.success;
</para>
</simpara>
</refsect1>
<refsect1 role="changelog">

View File

@@ -12,10 +12,10 @@
<type class="union"><type>string</type><type>false</type></type><methodname>readline</methodname>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>prompt</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
<simpara>
Reads a single line from the user. You must add this line to the history
yourself using <function>readline_add_history</function>.
</para>
</simpara>
</refsect1>
<refsect1 role="parameters">
@@ -24,9 +24,9 @@
<varlistentry>
<term><parameter>prompt</parameter></term>
<listitem>
<para>
<simpara>
You may specify a string with which to prompt the user.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -34,11 +34,11 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Returns a single string from the user. The line returned has the ending
newline removed.
If there is no more data to read, then &false; is returned.
</para>
</simpara>
</refsect1>
<refsect1 role="examples">

View File

@@ -40,9 +40,9 @@
<type>string</type>
</term>
<listitem>
<para>
<simpara>
External tool to display output from <link linkend="features.commandline">command line</link>.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.cli.prompt">
@@ -51,9 +51,9 @@
<type>string</type>
</term>
<listitem>
<para>
<simpara>
<link linkend="features.commandline">Command line</link> prompt.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>

View File

@@ -1,24 +1,23 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="readline.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="readline.setup">
&reftitle.setup;
<!-- {{{ Requirements -->
<section xml:id="readline.requirements">
&reftitle.required;
<para>
<simpara>
To use the readline functions, you need to install libreadline. You can
find libreadline on the home page of the GNU Readline project, at
<link xlink:href="&url.readline;">&url.readline;</link>.
It's maintained by Chet Ramey, who's also the author of Bash.
</para>
<para>
</simpara>
<simpara>
You can also use these functions with the libedit library, a non-GPL
replacement for the readline library. The libedit library is BSD
licensed and available for download from
<link xlink:href="&url.libedit;">&url.libedit;</link>.
</para>
</simpara>
</section>
<!-- }}} -->
@@ -29,7 +28,6 @@
&reference.readline.ini;
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
@@ -50,4 +48,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->