better document caveats on quoting/escaping

note: GH does not support rendering rst admonitions

github/markup#68

README.rst

@@ -124,6 +124,12 @@ Save and render and view the result:
     :align: center
     :alt: round-table.svg
 
+**Caveat:**
+Backslash-escapes and strings of the form ``<...>``
+have a special meaning in the DOT language.
+If you need to render arbitrary strings (e.g. from user input),
+check the details in the `user guide`_.
+
 
 See also
 --------
@@ -174,6 +180,8 @@ Development
 .. _conda-forge-graphviz: https://anaconda.org/conda-forge/graphviz
 .. _conda-forge-graphviz-feedstock: https://github.com/conda-forge/graphviz-feedstock
 
+.. _user guide: https://graphviz.readthedocs.io/en/stable/manual.html
+
 .. _pygraphviz: https://pypi.org/project/pygraphviz/
 .. _graphviz-python: https://pypi.org/project/graphviz-python/
 .. _graphviz-python-docs: https://www.graphviz.org/pdf/gv.3python.pdf

docs/basic_usage.rst

@@ -88,3 +88,12 @@ for the rendered file type.
 
 
 .. include:: _links.rst
+
+.. attention::
+
+    Backslash-escapes and strings of the form ``<...>``
+    have a special meaning in the DOT_ language
+    and are currently passed on as is by this library.
+    If you need to render arbitrary strings literally (e.g. from user input),
+    consider wraping them with the :func:`graphviz.escape` function first.
+    See the sections on :ref:`Escapes` and :ref:`Quoting` below for details.

docs/manual.rst

@@ -28,9 +28,13 @@ User Guide
 .. include:: node_ports.rst
 
 
+.. _Escapes:
+
 .. include:: escapes.rst
 
 
+.. _Quoting:
+
 .. include:: quoting.rst