docs/c1/1-parse.md: Add buffering section.

1 files changed, 15 insertions, 0 deletions

diff --git a/docs/c1/1-parse.md b/docs/c1/1-parse.md
index f6d677a..31e340a 100644
--- a/docs/c1/1-parse.md
+++ b/docs/c1/1-parse.md
@@ -131,6 +131,21 @@ next file header appears.  (The header data need to be terminated with a blank
 ASCII character such as a newline.  The reason why the closing parenthesis does
 not act as a terminator unto itself will become apparent later.)
 
+#### Buffering
+
+To enable the aforementioned stream parsing strategy, the parser does not use
+automatic buffering.  If it did, it might inadvertently consume some bytes
+beyond the currently parsed datum, leaving the stream inconsistent.
+
+The parser could provide access to its buffer, such that one could access the
+unused bytes, but it's simpler and more flexible to let buffering be handled
+externally from the parser.
+
+In other words: If the parser is meant to be used on an I/O stream connected to
+expensive system calls, such as a file handle or network socket, it's best to
+wrap that stream in some intermediate object which asks the system for large
+chunks of data at once, and stores the data in a buffer.
+
 
 ### Datum labels