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] 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>