Move structures overview to Structures-intro.rst and update/elaborate

docs/Dev-intro.rst

@@ -37,22 +37,6 @@ BSD licensed.  See the `license` for more information.
 Feel free to add your own extensions and plugins. Contributing back to
 the DFHack repository is welcome and the right thing to do :)
 
-DF data structure definitions
------------------------------
-DFHack uses information about the game data structures, represented via xml files
-in the ``library/xml/`` submodule.
-
-See https://github.com/DFHack/df-structures, and the documentation linked in the index.
-
-Data structure layouts are described in files following the ``df.*.xml`` name pattern.
-This information is transformed by a perl script into C++ headers describing the
-structures, and associated metadata for the Lua wrapper. These headers and data
-are then compiled into the DFHack libraries, thus necessitating a compatibility
-break every time layouts change; in return it significantly boosts the efficiency
-and capabilities of DFHack code.
-
-Global object addresses are stored in :file:`symbols.xml`, which is copied to the dfhack
-release package and loaded as data at runtime.
 
 Remote access interface
 -----------------------

docs/Structures-intro.rst

@@ -0,0 +1,34 @@
+===================================
+DF data definitions (DF-structures)
+===================================
+
+DFHack's information about DF's data structures is stored in XML files in the
+`df-structures repository <https://github.com/DFHack/df-structures>`_. If you
+have `obtained a local copy of the DFHack source <compile-how-to-get-the-code>`,
+DF-structures is included as a submodule in ``library/xml``.
+
+Data structure layouts are described in files named with the ``df.*.xml``
+pattern. This information is transformed by a Perl script (``codegen.pl``) into
+C++ headers, as well as metadata for the Lua wrapper. This ultimately allows
+DFHack code to access DF data directly, with the same speed and capabilities as
+DF itself, which is an  advantage over the older out-of-process approach (used
+by debuggers and utilities like Dwarf Therapist). The main disadvantage of this
+approach is that any compiled code relying on these layouts will break when DF's
+layout changes, and will need to be recompiled for every new DF version.
+
+Addresses of DF global objects and vtables are stored in a separate file,
+:file:`symbols.xml`. Since these are only absolute addresses, they do not need
+to be compiled in to DFHack code, and are instead loaded at runtime. This makes
+fixes and additions to global addresses possible without recompiling DFHack.
+In an installed copy of DFHack, this file can be found at the root of the
+``hack`` folder.
+
+The following pages contain more detailed information about various aspects
+of DF-structures:
+
+.. toctree::
+   :titlesonly:
+
+   /library/xml/SYNTAX
+   /library/xml/how-to-update
+

docs/index-dev.rst

@@ -13,8 +13,7 @@ These are pages relevant to people developing for DFHack.
    /docs/NEWS-dev
    /docs/Lua API
    /docs/Documentation
-   /library/xml/SYNTAX
-   /library/xml/how-to-update
+   /docs/Structures-intro
    /docs/Memory-research
    /docs/Binpatches