doc-enの差分を反映(1) (#138)

* Add explicit warning about CSV function's escape parameterName php/doc-en@cef78b0 * Add title+titleabbrev to preface and reformat info box php/doc-en@dee52c0
php · Oct 31, 2024 · 5510f67 · 5510f67
1 parent cb4569b
commit 5510f67
Show file tree

Hide file tree

Showing 8 changed files with 42 additions and 22 deletions.
diff --git a/language-snippets.ent b/language-snippets.ent
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 1cdefe36cdfc0e3acaff6a0db918d4b037081aa8 Maintainer: takagi Status: working -->
+<!-- EN-Revision: cef78b0fbe0fbe02003699b027ab50200097e949 Maintainer: takagi Status: working -->
 <!-- Credits: hirokawa,haruki,shimooka,mumumu -->
 
 <!ENTITY installation.enabled.disable 'この拡張モジュールはデフォルトで有効になっています。無効にしたい場合は、次のオプションを指定してコンパイルします。'>
@@ -1028,6 +1028,18 @@ $font = 'SomeFont';
  </entry>
 </row>'>
 
+<!-- CSV -->
+<!ENTITY warning.csv.escape-parameter '<warning xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"><simpara>
+<parameter>escape</parameter>
+が空の文字列(<literal>""</literal>)以外に設定されているとき、
+<link xlink:href="&url.rfc;4180">RFC 4180</link>
+に準拠しない CSV が生成されたり、PHP の CSV
+関数を介してラウンドトリップ(往復変換)でデータが壊れる可能性があります。
+<parameter>escape</parameter>のデフォルト値は<literal>"\\"</literal>
+なので、明示的に空の文字列を指定すること推奨します。デフォルト値は、PHP 9.0
+以降の将来のバージョンで変更予定です。
+</simpara></warning>'>
+
 <!-- DBM notes -->
 
 <!ENTITY dbm.dbm-identifier.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>dbm_identifier</parameter></term><listitem><para><function>dbmopen</function> が返す DBM リンク識別子。</para></listitem></varlistentry>'>

diff --git a/preface.xml b/preface.xml
@@ -1,22 +1,24 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 9a10d863b9e6acde050f1d5a559927d12a4e65b0 Maintainer: hirokawa Status: ready -->
+<!-- EN-Revision: dee52c067be3be96a735f0c33cbcf0009a996b2e Maintainer: hirokawa Status: ready -->
 
 <preface xml:id="preface" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook">
- <info><title>序文</title>
- <abstract>
-  <simpara>
-   <acronym>PHP</acronym> は、<emphasis>PHP: Hypertext Preprocessor</emphasis>
-   を意味し、広く使用されているオープンソースの汎用スクリプト言語です。
-   HTML に埋め込むことができ、Web アプリケーションの開発に特に適しています。
-   PHP の構文の多くは C、Java、Perl 言語から転用したもので、
-   簡単に習得することができます。この言語は、動的に生成されるウェブページを 
-   Web 開発者が速やかに作成できるようにすることを主な目標として
-   つくられました。しかし、それだけにとどまらず、
-   もっと多くのことを PHP を使って行うことができます。
-  </simpara>
- </abstract>
-</info>
+  <info>
+    <titleabbrev>序文</titleabbrev>
+    <title>このマニュアルについて</title>
+    <abstract>
+      <simpara>
+        <acronym>PHP</acronym> は、<emphasis>PHP: Hypertext Preprocessor</emphasis>
+        を意味し、広く使用されているオープンソースの汎用スクリプト言語です。
+        HTML に埋め込むことができ、Web アプリケーションの開発に特に適しています。
+        PHP の構文の多くは C、Java、Perl 言語から転用したもので、
+        簡単に習得することができます。この言語は、動的に生成されるウェブページを
+        Web 開発者が速やかに作成できるようにすることを主な目標として
+        つくられました。しかし、それだけにとどまらず、
+        もっと多くのことを PHP を使って行うことができます。
+      </simpara>
+    </abstract>
+  </info>
 
  <para>
   このマニュアルは、

diff --git a/reference/filesystem/functions/fgetcsv.xml b/reference/filesystem/functions/fgetcsv.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 61374bbe228e8e9c55a24aba59a1e2bb2a871148 Maintainer: hirokawa Status: ready -->
+<!-- EN-Revision: cef78b0fbe0fbe02003699b027ab50200097e949 Maintainer: hirokawa Status: ready -->
 <!-- CREDITS: shimooka,mumumu -->
 <refentry xml:id="function.fgetcsv" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -104,6 +104,7 @@
     </varlistentry>
    </variablelist>
   </para>
+  &warning.csv.escape-parameter;
  </refsect1>
 
  <refsect1 role="returnvalues">

diff --git a/reference/filesystem/functions/fputcsv.xml b/reference/filesystem/functions/fputcsv.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 291d60430d25f2b508bebb5720b41cc68f9a6ec1 Maintainer: takagi Status: ready -->
+<!-- EN-Revision: cef78b0fbe0fbe02003699b027ab50200097e949 Maintainer: takagi Status: ready -->
 <!-- Credits: mumumu -->
 <refentry xml:id="function.fputcsv" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -84,6 +84,7 @@
     </varlistentry>
    </variablelist>
   </para>
+  &warning.csv.escape-parameter;
   <note>
    <para>
     <parameter>enclosure</parameter> がフィールド内に含まれる場合は、同じ文字を二度続けることでエスケープします。

diff --git a/reference/spl/splfileobject/fgetcsv.xml b/reference/spl/splfileobject/fgetcsv.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 61374bbe228e8e9c55a24aba59a1e2bb2a871148 Maintainer: masakielastic Status: ready -->
+<!-- EN-Revision: cef78b0fbe0fbe02003699b027ab50200097e949 Maintainer: masakielastic Status: ready -->
 <!-- Credits: mumumu -->
 <refentry xml:id="splfileobject.fgetcsv" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -78,6 +78,7 @@
     </varlistentry>
    </variablelist>
   </para>
+  &warning.csv.escape-parameter;
  </refsect1>
 
  <refsect1 role="returnvalues">

diff --git a/reference/spl/splfileobject/fputcsv.xml b/reference/spl/splfileobject/fputcsv.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: d51166ca16fda8e766849505b84f9306ef443f71 Maintainer: takagi Status: ready -->
+<!-- EN-Revision: cef78b0fbe0fbe02003699b027ab50200097e949 Maintainer: takagi Status: ready -->
 <!-- Credits: mumumu -->
 <refentry xml:id="splfileobject.fputcsv" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -78,6 +78,7 @@
     ただし、その直前に <parameter>escape</parameter> がある場合は別です。
    </para>
   </note> 
+  &warning.csv.escape-parameter;
  </refsect1>
 
  <refsect1 role="returnvalues">

diff --git a/reference/spl/splfileobject/setcsvcontrol.xml b/reference/spl/splfileobject/setcsvcontrol.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: d51166ca16fda8e766849505b84f9306ef443f71 Maintainer: masakielastic Status: ready -->
+<!-- EN-Revision: cef78b0fbe0fbe02003699b027ab50200097e949 Maintainer: masakielastic Status: ready -->
 <!-- Credits: mumumu -->
 <refentry xml:id="splfileobject.setcsvcontrol" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -52,6 +52,7 @@
     </varlistentry>
    </variablelist>
   </para>
+  &warning.csv.escape-parameter;
  </refsect1>
 
  <refsect1 role="returnvalues">

diff --git a/reference/strings/functions/str-getcsv.xml b/reference/strings/functions/str-getcsv.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 61374bbe228e8e9c55a24aba59a1e2bb2a871148 Maintainer: takagi Status: ready -->
+<!-- EN-Revision: cef78b0fbe0fbe02003699b027ab50200097e949 Maintainer: takagi Status: ready -->
 <!-- Credits: mumumu -->
 <refentry xml:id="function.str-getcsv" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -86,6 +86,7 @@
     </varlistentry>
    </variablelist>
   </para>
+  &warning.csv.escape-parameter;
  </refsect1>
 
  <refsect1 role="returnvalues">