From 81a705b6ae451c5158c94631f1c0910328b5cdf1 Mon Sep 17 00:00:00 2001
From: Sebastian Pipping <sebastian@pipping.org>
Date: Tue, 3 Oct 2023 21:15:33 +0200
Subject: [PATCH 1/2] doc/reference.html: Wrap paragraphs by <p> for function
 XML_Parse

---
 expat/doc/reference.html | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/expat/doc/reference.html b/expat/doc/reference.html
index c5ba4392..82cdc96d 100644
--- a/expat/doc/reference.html
+++ b/expat/doc/reference.html
@@ -1103,6 +1103,7 @@ enum XML_Status {
 };
 </pre>
 <div class="fcndef">
+<p>
 Parse some more of the document. The string <code>s</code> is a buffer
 containing part (or perhaps all) of the document. The number of bytes of s
 that are part of the document is indicated by <code>len</code>. This means
@@ -1112,12 +1113,16 @@ memory that <code>s</code> points at, then a memory fault is likely. The
 <code>isFinal</code> parameter informs the parser that this is the last
 piece of the document. Frequently, the last piece is empty (i.e.
 <code>len</code> is zero.)
+</p>
+
+<p>
 If a parse error occurred, it returns <code>XML_STATUS_ERROR</code>.
 Otherwise it returns <code>XML_STATUS_OK</code> value.
 Note that regardless of the return value, there is no guarantee that all
 provided input has been parsed; only after <a href="#isFinal">the
 concluding call</a> will all handler callbacks and parsing errors have
 happened.
+</p>
 </div>
 
 <h4 id="XML_ParseBuffer">XML_ParseBuffer</h4>

From 1d3ee5133e75214595da28fe79da370e1319353d Mon Sep 17 00:00:00 2001
From: Sebastian Pipping <sebastian@pipping.org>
Date: Tue, 3 Oct 2023 21:16:41 +0200
Subject: [PATCH 2/2] doc/reference.html: Make XML_Parse promote
 XML_ParseBuffer

---
 expat/doc/reference.html | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/expat/doc/reference.html b/expat/doc/reference.html
index 82cdc96d..f20dc0f9 100644
--- a/expat/doc/reference.html
+++ b/expat/doc/reference.html
@@ -1123,6 +1123,30 @@ provided input has been parsed; only after <a href="#isFinal">the
 concluding call</a> will all handler callbacks and parsing errors have
 happened.
 </p>
+
+<p>
+Simplified, <code>XML_Parse</code> can be considered a convenience wrapper
+that is pairing calls
+to <code><a href="#XML_GetBuffer">XML_GetBuffer</a></code>
+and <code><a href="#XML_ParseBuffer">XML_ParseBuffer</a></code>
+(when Expat is built with macro <code>XML_CONTEXT_BYTES</code>
+defined to a positive value, which is both common and default).
+<code>XML_Parse</code> is then functionally equivalent to calling
+<code><a href="#XML_GetBuffer">XML_GetBuffer</a></code>,
+<code>memcpy</code>, and
+<code><a href="#XML_ParseBuffer">XML_ParseBuffer</a></code>.
+</p>
+
+<p>
+To avoid double copying of the input, direct use of functions
+<code><a href="#XML_GetBuffer">XML_GetBuffer</a></code> and
+<code><a href="#XML_ParseBuffer">XML_ParseBuffer</a></code> is advised
+for most production use, e.g.
+if you're using <code>read</code> or similar functionality to fill your
+buffers, fill directly into the buffer from
+<code><a href="#XML_GetBuffer">XML_GetBuffer</a></code>,
+then parse with <code><a href="#XML_ParseBuffer">XML_ParseBuffer</a></code>.
+</p>
 </div>
 
 <h4 id="XML_ParseBuffer">XML_ParseBuffer</h4>