@@ -32,9 +32,26 @@
 ``latexwalker`` was designed to extract useful text for indexing for text
 database searches of LaTeX content.)
 
+Since `pylatexenc 3`, the parsing work itself is carried out by *parser
+objects*, which are specialized in parsing a given LaTeX construct and which
+are provided by :py:mod:`pylatexenc.latexnodes.parsers`.  A
+:py:class:`LatexWalker` instance holds the LaTeX code along with the
+information required to parse it (the "latex context", see below), and it runs
+such parser objects on that code with
+:py:meth:`LatexWalker.parse_content()`.
+
+The result of the parsing is a node tree, along with any information about
+parsing state changes that the parsed code caused (say, a ``\newcommand``).
+The nodes are instances of the classes provided in
+:py:mod:`pylatexenc.latexnodes.nodes`, and lists of nodes are wrapped in a
+:py:class:`~pylatexenc.latexnodes.nodes.LatexNodeList` object.  (For
+compatibility with earlier versions, the node classes can also be imported
+directly from :py:mod:`pylatexenc.latexwalker`.)
+
 Simple example usage::
 
-    >>> from pylatexenc.latexwalker import LatexWalker, LatexEnvironmentNode
+    >>> from pylatexenc.latexwalker import LatexWalker
+    >>> from pylatexenc.latexnodes.nodes import LatexEnvironmentNode
     >>> w = LatexWalker(r"""
     ... \textbf{Hi there!} Here is \emph{a list}:
     ... \begin{enumerate}[label=(i)]
@@ -43,37 +60,52 @@
     ... \end{enumerate}
     ... and $x$ is a variable.
     ... """)
-    >>> (nodelist, pos, len_) = w.get_latex_nodes(pos=0)
-    >>> nodelist[0]
-    LatexCharsNode(pos=0, len=1, chars='\n')
-    >>> nodelist[1]
-    LatexMacroNode(pos=1, len=18, macroname='textbf',
-    nodeargd=ParsedMacroArgs(argnlist=[LatexGroupNode(pos=8, len=11,
-    nodelist=[LatexCharsNode(pos=9, len=9, chars='Hi there!')],
-    delimiters=('{', '}'))], argspec='{'), macro_post_space='')
+    >>> nodelist, parsing_state_delta = w.parse_content()
+    >>> nodelist[1].macroname
+    'textbf'
+    >>> (nodelist[1].pos, nodelist[1].pos_end)
+    (1, 19)
+    >>> nodelist[1].latex_verbatim()
+    '\\textbf{Hi there!}'
     >>> nodelist[5].isNodeType(LatexEnvironmentNode)
     True
     >>> nodelist[5].environmentname
     'enumerate'
-    >>> nodelist[5].nodeargd.argspec
-    '['
-    >>> nodelist[5].nodeargd.argnlist
-    [LatexGroupNode(pos=60, len=11, nodelist=[LatexCharsNode(pos=61, len=9,
-    chars='label=(i)')], delimiters=('[', ']'))]
     >>> nodelist[7].latex_verbatim()
     '$x$'
 
-You can also use `latexwalker` directly in command-line, producing JSON or a
-human-readable node tree::
+Macro, environment and specials arguments are collected in a
+:py:class:`pylatexenc.latexnodes.ParsedArguments` object stored as the node's
+`nodeargd` attribute.  Use
+:py:class:`pylatexenc.latexnodes.ParsedArgumentsInfo` to inspect them, by
+position or by argument name::
+
+    >>> from pylatexenc.latexnodes import ParsedArgumentsInfo
+    >>> arguments = ParsedArgumentsInfo(node=nodelist[5]).get_all_arguments_info()
+    >>> arguments[0].get_content_nodelist().latex_verbatim()
+    'label=(i)'
+
+You can also use `latexwalker` directly in command-line, producing a
+human-readable node tree or JSON::
+
+    $ latexwalker --code '\textit{italic} text'
+    --- NODES ---
+
+    * \textit
+        {.}: Group:
+            * 'italic'
+    * ' text'
 
-    $ echo '\textit{italic} text' | latexwalker --output-format=json
+    -------------
+
+    $ latexwalker --output-format=json --code '\textit{italic} text'
     {
       "nodelist": [
         {
           "nodetype": "LatexMacroNode",
           "pos": 0,
-          "len": 15,
-          "macroname": "textit",
+          "pos_end": 15,
+          "parsing_state": {
     [...]
 
     $ latexwalker --help
@@ -85,6 +117,20 @@
 :py:class:`pylatexenc.macrospec.EnvironmentSpec` objects in a
 :py:class:`pylatexenc.macrospec.LatexContextDb` object.  See the doc of the
 module :py:mod:`pylatexenc.macrospec` for more information.
+
+.. versionchanged:: 3.0
+
+   Parsing is now carried out by parser objects that are invoked via
+   :py:meth:`LatexWalker.parse_content()`, in a significant API redesign.  See
+   :doc:`What's new in pylatexenc 3 <new-in-pylatexenc-3>` for the differences
+   between the two interfaces, and the :ref:`list of changes that might affect
+   existing code <new-in-pylatexenc-3-possible-pitfall-changes>`.
+
+   The `pylatexenc 2` interface of :py:class:`LatexWalker` —
+   `get_latex_nodes()`, `get_token()`, `get_latex_expression()`,
+   `get_latex_braced_group()`, `get_latex_environment()` and
+   `get_latex_maybe_optional_arg()` — remains fully supported and should work in
+   the vast majority of cases without code changes.
 '''
 
 
 
@@ -128,31 +128,33 @@ class LatexWalker(latexnodes.LatexWalkerBase):
         generally won't need to specify this flag, use `tolerant_parsing`
         instead.
 
-    The methods provided in this class perform various parsing of the given
-    string `s`.  These methods typically accept a `pos` parameter, which must be
-    an integer, which defines the position in the string `s` to start parsing.
-
-    These are the ``get_***()`` methods inherited from `pylatexenc 2`
-    (:py:meth:`get_latex_nodes()`, :py:meth:`get_latex_expression()`,
-    :py:meth:`get_latex_braced_group()`, :py:meth:`get_latex_environment()`,
-    :py:meth:`get_latex_maybe_optional_arg()`).  Unless otherwise documented,
-    they return a tuple `(node, pos, len)`, where node is a
-    :py:class:`LatexNode` describing the parsed content, `pos` is the position
+    
+    The main entry point for parsing is the :py:meth:`parse_content()` method.
+    It parses the string `s` you provided in the class' constructor, using the
+    provided parser (or the default parser, if no parser is provided).  It
+    returns a node tree, along with information about how the parsing state was
+    updated during the parsing (e.g., new macro definitions).
+
+    This class also provides the ``get_***()`` methods inherited from
+    `pylatexenc 2` (:py:meth:`get_latex_nodes()`,
+    :py:meth:`get_latex_expression()`, :py:meth:`get_latex_braced_group()`,
+    :py:meth:`get_latex_environment()`,
+    :py:meth:`get_latex_maybe_optional_arg()`).  While these methods remain
+    supported, they are subject to a SOFT DEPRECATION notice — avoid their use
+    in new code, as they are likely to become eventually deprecated.  Unless
+    otherwise documented, they return a tuple `(node, pos, len)`, where node is
+    a :py:class:`LatexNode` describing the parsed content, `pos` is the position
     at which the LaTeX element of interest was encountered, and `len` is the
     length of the string that is considered to be part of the `node`.  That is,
     the position in the string that is immediately after the node is `pos+len`.
-
-    These ``get_***()`` methods are the interface that `pylatexenc 2` offered,
-    and they remain fully supported; you can keep using them.  Since
-    `pylatexenc 3` there is a second, more flexible way of parsing content:
-    :py:meth:`parse_content()` together with a parser object from
-    :py:mod:`pylatexenc.latexnodes.parsers`.  Be aware that switching over is
-    not a simple substitution of one call for another, because the return value
-    is different: :py:meth:`parse_content()` returns a tuple `(nodes,
-    parsing_state_delta)`, and the position information is carried by the nodes
-    themselves in their `pos` and `pos_end` attributes rather than being
-    returned alongside them.  The documentation of each of the ``get_***()``
-    methods points to the corresponding parser object.
+    New code should avoid the ``get_***`` methods in favor of `pylatexenc 3`'s
+    :py:meth:`parse_content()`, which is more powerful and more flexible.  If
+    you're porting code, note the return value is slighlty different:
+    :py:meth:`parse_content()` returns a tuple `(nodes, parsing_state_delta)`,
+    and the position information is carried by the nodes themselves in their
+    `pos` and `pos_end` attributes rather than being returned alongside them.
+    See the documentation of each of the ``get_***()`` methods for more
+    information on migration to the new scheme.
 
     The following obsolete flag is accepted by the constructor for backwards
     compatibility with `pylatexenc 1.x`:
@@ -475,19 +477,33 @@ def make_token_reader(self, pos=None):
             token_reader.move_to_pos_chars(pos)
         return token_reader
 
-    def parse_content(self, parser, token_reader=None, parsing_state=None,
+    def parse_content(self, parser=None, token_reader=None, parsing_state=None,
                       open_context=None):
         r"""
         The main entry point to parse the stored LaTeX code into a node structure.
 
         Arguments:
-        
+
         - The `parser` must be a callable object that can be called with the
           keyword arguments `latex_walker`, `token_reader` and `parsing_state`.
           The return value of `parser(...)` should be a :py:class:`LatexNode` or
-          :py:class:`LatexNodeList` instance.
-
-        - `token_reader` is a :py:class:`LatexTokenReader` instance that is
+          :py:class:`~pylatexenc.latexnodes.nodes.LatexNodeList` instance.
+
+          If `parser` is `None`, then a plain
+          :py:class:`~pylatexenc.latexnodes.parsers.LatexGeneralNodesParser`
+          instance is used.  That parser reads general LaTeX content until the
+          end of the stream, which is what one usually wants when parsing an
+          entire document; so ``lw.parse_content()`` parses all the LaTeX code
+          that was given to the constructor.
+
+          This default is a convenience offered by this class, and not part of
+          the :py:class:`pylatexenc.latexnodes.LatexWalkerBase` interface.  A
+          latex walker class that is derived directly from
+          :py:class:`~pylatexenc.latexnodes.LatexWalkerBase` is not required to
+          accept `parser=None`.
+
+        - `token_reader` is a
+          :py:class:`~pylatexenc.latexnodes.LatexTokenReader` instance that is
           tasked with converting the raw string into tokens.  If `None`, then
           :py:meth:`make_token_reader()` is called to create a token reader
           instance.
@@ -505,15 +521,22 @@ def parse_content(self, parser, token_reader=None, parsing_state=None,
 
         The return value is a tuple `(result, parser_parsing_state_delta)` where
         `result` is the return value of the parser, which is expected to be a
-        :py:class:`LatexNode` or :py:class:`LatexNodeList` instance, and where
-        `parsing_state_delta`, if non-`None`, is a parsing state delta object,
-        see :py:class:`pylatexenc.latexnodes.ParsingStateDelta`.  It represents
-        changes to the parsing state for parsing subsequent content.
+        :py:class:`LatexNode` or
+        :py:class:`~pylatexenc.latexnodes.nodes.LatexNodeList` instance, and
+        where `parsing_state_delta`, if non-`None`, is a parsing state delta
+        object, see :py:class:`pylatexenc.latexnodes.ParsingStateDelta`.  It
+        represents changes to the parsing state for parsing subsequent content.
         """
 
+        the_parser = None
         the_token_reader = None
         the_parsing_state = None
 
+        if parser is None:
+            the_parser = parsers.LatexGeneralNodesParser()
+        else:
+            the_parser = parser
+
         if token_reader is None:
             the_token_reader = self.make_token_reader()
         else:
@@ -533,29 +556,29 @@ def parse_content(self, parser, token_reader=None, parsing_state=None,
 
         start_pos = the_token_reader.cur_pos()
         logger.debug(":: Parsing content (%s @ %r) - %r [%r]::",
-                     open_context_name, start_pos, parser, the_parsing_state)
+                     open_context_name, start_pos, the_parser, the_parsing_state)
 
         with self.new_parsing_open_context(open_context_name, open_context_tok) as pc:
 
             try:
 
-                nodes, info = parser.parse(
+                nodes, info = the_parser.parse(
                     latex_walker=self,
                     token_reader=the_token_reader,
                     parsing_state=the_parsing_state,
                 )
 
             except LatexWalkerEndOfStream:
                 logger.warning("End of stream encountered when parsing content with %s (%s)",
-                               parser.__class__.__name__, open_context_name)
+                               the_parser.__class__.__name__, open_context_name)
                 nodes, info = None, None
 
         if pc.recovery_from_exception is not None:
             nodes, info = \
                 pc.perform_recovery_nodes_and_parsing_state_delta(the_token_reader)
 
         logger.debug(":: PARSED content (%s @ %r) - %r - result %r + %r DONE ::",
-                     open_context_name, start_pos, parser, nodes, info)
+                     open_context_name, start_pos, the_parser, nodes, info)
 
         return nodes, info
 
@@ -761,13 +784,13 @@ def _pyltxenc2_LatexWalker_get_token(
     starting at position `pos`, to parse a single "token", as defined by
     :py:class:`LatexToken`.
 
-    This method is the `pylatexenc 2` style interface and it remains fully
-    supported.  Since `pylatexenc 3` you can also read tokens with a token
-    reader object, see :py:meth:`make_token_reader()` and
-    :py:class:`LatexTokenReader`.  A token reader keeps track of its own
-    position in the string as it reads and it exposes several reading methods
-    (`peek_token()`, `next_token()`, ...), so moving to it is not simply a
-    matter of replacing one call by another.
+    This method is the `pylatexenc 2` style interface and it remains supported;
+    it is subject to SOFT DEPRECATION - AVOID USE IN NEW CODE.  Since
+    `pylatexenc 3` you can also read tokens with a token reader object, see
+    :py:meth:`make_token_reader()` and :py:class:`LatexTokenReader`.  A token
+    reader keeps track of its own position in the string as it reads and it
+    exposes several reading methods (`peek_token()`, `next_token()`, ...), so
+    moving to it is not simply a matter of replacing one call by another.
 
     Parse the token in the stream pointed to at position `pos`.
 
@@ -861,8 +884,9 @@ def _pyltxenc2_LatexWalker_get_latex_nodes(
     Parses the latex content given to the constructor (and stored in `self.s`)
     into a list of nodes.
 
-    This method is the `pylatexenc 2` style interface and it remains fully
-    supported.  Since `pylatexenc 3` you can also parse the same content with
+    This method is the `pylatexenc 2` style interface and it remains supported;
+    it is subject to SOFT DEPRECATION - AVOID USE IN NEW CODE.  Since
+    `pylatexenc 3` you can also parse the same content with
     :py:meth:`parse_content()` and a parser object.  The two calls do not return
     the same thing, so this is not a mechanical substitution; you'd write::
 
@@ -881,6 +905,9 @@ def _pyltxenc2_LatexWalker_get_latex_nodes(
         npos = nodelist.pos
         nlen = nodelist.len # or nodelist.pos_end - nodelist.pos
 
+    The `LatexGeneralNodesParser()` instance shown here is also
+    :py:meth:`parse_content()`'s default parser, so it can simply be omitted.
+
     See the documentation for
     :py:class:`~latexnodes.parsers.LatexGeneralNodesParser` for information
     on how to implement similar behavior as with the `stop_upon_*=`
@@ -1096,8 +1123,9 @@ def _pyltxenc2_LatexWalker_get_latex_expression(
     Returns a tuple `(node, pos, len)`, where `pos` is the position of the
     first char of the expression and `len` the length of the expression.
 
-    This method is the `pylatexenc 2` style interface and it remains fully
-    supported.  Since `pylatexenc 3` you can also parse the same content with
+    This method is the `pylatexenc 2` style interface and it remains supported;
+    it is subject to SOFT DEPRECATION - AVOID USE IN NEW CODE.  Since
+    `pylatexenc 3` you can parse the same content with
     ``LatexWalker.parse_content(LatexExpressionParser(), ...)``.  That call
     returns a tuple `(nodes, parsing_state_delta)` instead of `(node, pos,
     len)`, with the positions carried by the node itself, so it is not a
@@ -1231,8 +1259,9 @@ def _pyltxenc2_LatexWalker_get_latex_braced_group(
     distinct single characters providing the opening and closing brace
     chars (e.g., ``("<", ">")``).
 
-    This method is the `pylatexenc 2` style interface and it remains fully
-    supported.  Since `pylatexenc 3` you can also parse the same content with
+    This method is the `pylatexenc 2` style interface and it remains supported;
+    it is subject to SOFT DEPRECATION - AVOID USE IN NEW CODE Since `pylatexenc
+    3` you can parse the same content with
     ``LatexWalker.parse_content(LatexDelimitedGroupParser(), ...)``.  That call
     returns a tuple `(nodes, parsing_state_delta)` instead of `(node, pos,
     len)`, with the positions carried by the node itself, so it is not a
@@ -1327,8 +1356,9 @@ def _pyltxenc2_LatexWalker_get_latex_environment(
     Returns a tuple (node, pos, len) where node is a
     :py:class:`LatexEnvironmentNode`.
 
-    This method is the `pylatexenc 2` style interface and it remains fully
-    supported.  Since `pylatexenc 3` you can also parse the same content with
+    This method is the `pylatexenc 2` style interface and it remains supported;
+    it is subject to SOFT DEPRECATION - AVOID USE IN NEW CODE.  Since
+    `pylatexenc 3` you can parse the same content with
     ``LatexWalker.parse_content(LatexSingleNodeParser(), ...)`` positioned at
     the beginning of the environment.  That call returns a tuple `(nodes,
     parsing_state_delta)` instead of `(node, pos, len)`, with the positions
@@ -1389,9 +1419,10 @@ def _pyltxenc2_LatexWalker_get_latex_maybe_optional_arg(self, pos, parsing_state
     a tuple `(node, pos, len)` if success where `node` is a
     :py:class:`LatexGroupNode`.  Otherwise, this method returns None.
 
-    This method is the `pylatexenc 2` style interface and it remains fully
-    supported.  Since `pylatexenc 3` you can also parse the same content with
-    the more flexible parsers mechanism, e.g.,
+    This method is the `pylatexenc 2` style interface and it remains supported;
+    it is subject to SOFT DEPRECATION - AVOID USE IN NEW CODE.  Since
+    `pylatexenc 3` you can parse the same content with the more flexible parsers
+    mechanism, e.g.,
     ``LatexWalker.parse_content(LatexOptionalSquareBracketsParser(), ...)``.
     That call returns a tuple `(nodes, parsing_state_delta)` instead of `(node,
     pos, len)` or `None`, with the positions carried by the node itself, so it