Skip to content

Commit a8b6f4d

Browse files
nielsdosnielsdos
authored
Document Dom\HTMLDocument methods (#4314)
1 parent d75036c commit a8b6f4d

12 files changed

+719
-13
lines changed

‎language-snippets.ent

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1743,6 +1743,28 @@ it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNo
17431743
of the <link linkend="libxml.constants">libxml option constants</link>.
17441744
</para>'>
17451745

1746+
<!ENTITY dom.parameter.compliant.options '&dom.parameter.options;
1747+
<simpara xmlns="http://docbook.org/ns/docbook">
1748+
It is also possible to pass <constant>Dom\HTML_NO_DEFAULT_NS</constant>
1749+
to disable the use of the HTML namespace and the template element.
1750+
This should only be used if the implications are properly understood.
1751+
</simpara>'>
1752+
1753+
<!ENTITY dom.parameter.compliant.encoding '<simpara xmlns="http://docbook.org/ns/docbook">
1754+
The encoding that the document was created in.
1755+
If not provided, it will attempt to determine the encoding that is most likely used.
1756+
</simpara>'>
1757+
1758+
<!ENTITY dom.parser.compliant.note.whitespace '<refsect1 role="notes" xmlns="http://docbook.org/ns/docbook">
1759+
&reftitle.notes;
1760+
<note>
1761+
<simpara>
1762+
Whitespace in the <literal>html</literal> and <literal>head</literal> tags
1763+
is not considered significant and may lose formatting.
1764+
</simpara>
1765+
</note>
1766+
</refsect1>'>
1767+
17461768
<!ENTITY dom.parameters.register_node_ns '<varlistentry xmlns="http://docbook.org/ns/docbook">
17471769
<term><parameter>registerNodeNS</parameter></term>
17481770
<listitem>
@@ -1754,6 +1776,14 @@ it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNo
17541776
</listitem>
17551777
</varlistentry>'>
17561778

1779+
<!ENTITY dom.parameters.serialize.options '<simpara xmlns="http://docbook.org/ns/docbook">
1780+
Additional Options.
1781+
The <constant>LIBXML_NOEMPTYTAG</constant>
1782+
and <constant>LIBXML_NOXMLDECL</constant> options are supported.
1783+
Prior to PHP 8.3.0, only the <constant>LIBXML_NOEMPTYTAG</constant>
1784+
option is supported.
1785+
</simpara>'>
1786+
17571787
<!ENTITY dom.errors.hierarchy.parent '<varlistentry xmlns="http://docbook.org/ns/docbook">
17581788
<term><constant>DOM_HIERARCHY_REQUEST_ERR</constant></term>
17591789
<listitem>
@@ -1786,6 +1816,27 @@ it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNo
17861816
</listitem>
17871817
</varlistentry>'>
17881818

1819+
<!ENTITY dom.errors.compliant.wrong_document '<listitem xmlns="http://docbook.org/ns/docbook">
1820+
<simpara>
1821+
Throws a <exceptionname>Dom\DOMException</exceptionname> with code
1822+
<constant>Dom\WRONG_DOCUMENT_ERR</constant> if <parameter>node</parameter>
1823+
is from another document.
1824+
</simpara>
1825+
</listitem>'>
1826+
1827+
<!ENTITY dom.errors.compliant.common '<listitem xmlns="http://docbook.org/ns/docbook">
1828+
<simpara>
1829+
Throws a <exceptionname>ValueError</exceptionname> if
1830+
<parameter>options</parameter> contains an invalid option.
1831+
</simpara>
1832+
</listitem>
1833+
<listitem>
1834+
<simpara>
1835+
Throws a <exceptionname>ValueError</exceptionname> if
1836+
<parameter>overrideEncoding</parameter> is an unknown encoding.
1837+
</simpara>
1838+
</listitem>'>
1839+
17891840
<!ENTITY dom.changelog.previous_hierarchy_exception 'Previously this threw a
17901841
<classname xmlns="http://docbook.org/ns/docbook">DOMException</classname> with code
17911842
<constant xmlns="http://docbook.org/ns/docbook">DOM_HIERARCHY_REQUEST_ERR</constant>.'>

‎reference/dom/constants.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -251,9 +251,9 @@
251251
</row>
252252
</thead>
253253
<tbody>
254-
<row xml:id="constant.dom-no-default-ns">
254+
<row xml:id="constant.dom-html-no-default-ns">
255255
<entry>
256-
<constant>Dom\NO_DEFAULT_NS</constant>
256+
<constant>Dom\HTML_NO_DEFAULT_NS</constant>
257257
(<type>int</type>)
258258
</entry>
259259
<entry>

‎reference/dom/dom/dom-htmldocument.xml

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,10 +41,9 @@
4141
</xi:include>
4242

4343
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
44-
<classsynopsisinfo role="comment">Not documented yet</classsynopsisinfo>
45-
<!--<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dom-htmldocument')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='Dom\\HTMLDocument'])">
44+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dom-htmldocument')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='Dom\\HTMLDocument'])">
4645
<xi:fallback/>
47-
</xi:include>-->
46+
</xi:include>
4847

4948
<classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
5049
<classsynopsisinfo role="comment">Not documented yet</classsynopsisinfo>
@@ -64,6 +63,6 @@
6463

6564
</partintro>
6665

67-
<!-- &reference.dom.dom.entities.htmldocument; -->
66+
&reference.dom.dom.entities.htmldocument;
6867

6968
</reference>

‎reference/dom/dom/htmldocument/createempty.xml

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<refentry xml:id="dom-htmldocument.createempty" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3+
<refnamediv>
4+
<refname>Dom\HTMLDocument::createEmpty</refname>
5+
<refpurpose>Creates an empty <acronym>HTML</acronym> document</refpurpose>
6+
</refnamediv>
7+
8+
<refsect1 role="description">
9+
&reftitle.description;
10+
<methodsynopsis role="Dom\\HTMLDocument">
11+
<modifier>public</modifier> <modifier>static</modifier> <type>Dom\HTMLDocument</type><methodname>Dom\HTMLDocument::createEmpty</methodname>
12+
<methodparam choice="opt"><type>string</type><parameter>encoding</parameter><initializer>"UTF-8"</initializer></methodparam>
13+
</methodsynopsis>
14+
<simpara>
15+
Creates an empty <acronym>HTML</acronym> document without any elements.
16+
</simpara>
17+
</refsect1>
18+
19+
<refsect1 role="parameters">
20+
&reftitle.parameters;
21+
<variablelist>
22+
<varlistentry>
23+
<term><parameter>encoding</parameter></term>
24+
<listitem>
25+
<simpara>
26+
The character encoding of the document, used for serialization when
27+
calling the save methods.
28+
</simpara>
29+
</listitem>
30+
</varlistentry>
31+
</variablelist>
32+
</refsect1>
33+
34+
<refsect1 role="returnvalues">
35+
&reftitle.returnvalues;
36+
<simpara>
37+
An empty <acronym>HTML</acronym> document.
38+
</simpara>
39+
</refsect1>
40+
41+
<refsect1 role="examples">
42+
&reftitle.examples;
43+
<example xml:id="dom-htmldocument.createempty.example.basic">
44+
<title><methodname>Dom\HTMLDocument::createEmpty</methodname> example</title>
45+
<simpara>
46+
Creates an empty document and serializes it.
47+
</simpara>
48+
<programlisting role="php">
49+
<![CDATA[
50+
<?php
51+
$dom = Dom\HTMLDocument::createEmpty();
52+
var_dump($dom->saveHtml());
53+
?>
54+
]]>
55+
</programlisting>
56+
&example.outputs;
57+
<screen>
58+
<![CDATA[
59+
string(0) ""
60+
]]>
61+
</screen>
62+
</example>
63+
</refsect1>
64+
65+
<refsect1 role="seealso">
66+
&reftitle.seealso;
67+
<simplelist>
68+
<member><methodname>Dom\HTMLDocument::createFromString</methodname></member>
69+
<member><methodname>Dom\HTMLDocument::createFromFile</methodname></member>
70+
</simplelist>
71+
</refsect1>
72+
73+
</refentry>
74+
<!-- Keep this comment at the end of the file
75+
Local variables:
76+
mode: sgml
77+
sgml-omittag:t
78+
sgml-shorttag:t
79+
sgml-minimize-attributes:nil
80+
sgml-always-quote-attributes:t
81+
sgml-indent-step:1
82+
sgml-indent-data:t
83+
indent-tabs-mode:nil
84+
sgml-parent-document:nil
85+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
86+
sgml-exposed-tags:nil
87+
sgml-local-catalogs:nil
88+
sgml-local-ecat-files:nil
89+
End:
90+
vim600: syn=xml fen fdm=syntax fdl=2 si
91+
vim: et tw=78 syn=sgml
92+
vi: ts=1 sw=1
93+
-->

‎reference/dom/dom/htmldocument/createfromfile.xml

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<refentry xml:id="dom-htmldocument.createfromfile" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3+
<refnamediv>
4+
<refname>Dom\HTMLDocument::createFromFile</refname>
5+
<refpurpose>Parses an <acronym>HTML</acronym> document from a file</refpurpose>
6+
</refnamediv>
7+
8+
<refsect1 role="description">
9+
&reftitle.description;
10+
<methodsynopsis role="Dom\\HTMLDocument">
11+
<modifier>public</modifier> <modifier>static</modifier> <type>Dom\HTMLDocument</type><methodname>Dom\HTMLDocument::createFromFile</methodname>
12+
<methodparam><type>string</type><parameter>path</parameter></methodparam>
13+
<methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>
14+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>overrideEncoding</parameter><initializer>&null;</initializer></methodparam>
15+
</methodsynopsis>
16+
<simpara>
17+
Parses an <acronym>HTML</acronym> document from a file,
18+
according to the living standard.
19+
</simpara>
20+
</refsect1>
21+
22+
<refsect1 role="parameters">
23+
&reftitle.parameters;
24+
<variablelist>
25+
<varlistentry>
26+
<term><parameter>path</parameter></term>
27+
<listitem>
28+
<simpara>
29+
The path to the file to parse.
30+
</simpara>
31+
</listitem>
32+
</varlistentry>
33+
<varlistentry>
34+
<term><parameter>options</parameter></term>
35+
<listitem>
36+
&dom.parameter.compliant.options;
37+
</listitem>
38+
</varlistentry>
39+
<varlistentry>
40+
<term><parameter>overrideEncoding</parameter></term>
41+
<listitem>
42+
&dom.parameter.compliant.encoding;
43+
</listitem>
44+
</varlistentry>
45+
</variablelist>
46+
</refsect1>
47+
48+
<refsect1 role="returnvalues">
49+
&reftitle.returnvalues;
50+
<simpara>
51+
The parsed document as an <classname>Dom\HTMLDocument</classname> instance.
52+
</simpara>
53+
</refsect1>
54+
55+
<refsect1 role="errors">
56+
&reftitle.errors;
57+
<itemizedlist>
58+
<listitem>
59+
<simpara>
60+
Throws a <exceptionname>ValueError</exceptionname> if
61+
<parameter>path</parameter> contains null bytes or contains
62+
<literal>"%00"</literal>.
63+
</simpara>
64+
</listitem>
65+
&dom.errors.compliant.common;
66+
<listitem>
67+
<simpara>
68+
Throws an <exceptionname>Exception</exceptionname> if
69+
the file could not be opened.
70+
</simpara>
71+
</listitem>
72+
</itemizedlist>
73+
</refsect1>
74+
75+
&dom.parser.compliant.note.whitespace;
76+
77+
<refsect1 role="seealso">
78+
&reftitle.seealso;
79+
<simplelist>
80+
<member><methodname>Dom\HTMLDocument::createEmpty</methodname></member>
81+
<member><methodname>Dom\HTMLDocument::createFromString</methodname></member>
82+
</simplelist>
83+
</refsect1>
84+
85+
</refentry>
86+
<!-- Keep this comment at the end of the file
87+
Local variables:
88+
mode: sgml
89+
sgml-omittag:t
90+
sgml-shorttag:t
91+
sgml-minimize-attributes:nil
92+
sgml-always-quote-attributes:t
93+
sgml-indent-step:1
94+
sgml-indent-data:t
95+
indent-tabs-mode:nil
96+
sgml-parent-document:nil
97+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
98+
sgml-exposed-tags:nil
99+
sgml-local-catalogs:nil
100+
sgml-local-ecat-files:nil
101+
End:
102+
vim600: syn=xml fen fdm=syntax fdl=2 si
103+
vim: et tw=78 syn=sgml
104+
vi: ts=1 sw=1
105+
-->

0 commit comments

Comments
 (0)