-- * Differences from Parsec
-- * Performance considerations
-- * Much of the performance advantage of Attoparsec is gained via
-- high-performance parsers such as 'I.takeWhile' and 'I.string'.
-- If you use complicated combinators that return lists of bytes or
--- characters, there really isn't much performance difference the
+-- characters, there is less performance difference between the two
-- * Unlike Parsec 3, Attoparsec does not support being used as a
--- monad transformer. This is mostly a matter of the implementor
--- not having needed that functionality.
-- * Attoparsec is specialised to deal only with strict 'B.ByteString'
-- input. Efficiency concernts rule out both lists and lazy
-- allow consumption of very large input without a large footprint.
-- For this need, Attoparsec's incremental input provides an
-- excellent substitute, with much more control over when input
+-- takes place. If you must use lazy bytestrings, see the 'Lazy'
+-- module, which feeds lazy chunks to a regular parser.
-- * Parsec parsers can produce more helpful error messages than
-- Attoparsec parsers. This is a matter of focus: Attoparsec avoids
-- the extra book-keeping in favour of higher performance.
+-- Attoparsec supports incremental input, meaning that you can feed it
+-- a bytestring that represents only part of the expected total amount
+-- of data to parse. If your parser reaches the end of a fragment of
+-- input and could consume more input, it will suspend parsing and
+-- return a 'Partial' continuation.
+-- Supplying the 'Partial' continuation with another bytestring will
+-- resume parsing at the point where it was suspended. You must be
+-- prepared for the result of the resumed parse to be another
+-- 'Partial' continuation.
+-- To indicate that you have no more input, supply the 'Partial'
+-- continuation with an empty bytestring.
+-- Remember that some parsing combinators will not return a result
+-- until they reach the end of input. They may thus cause 'Partial'
+-- results to be returned.
+-- If you do not need support for incremental input, consider using
+-- the 'I.parseOnly' function to run your parser. It will never
+-- prompt for more input.
-- If you write an Attoparsec-based parser carefully, it can be