hacking-howto: Update 'files' section

Instead of sorting alphanumerically, use a more opinionated order,
listing more "important" files towards the beginning.

Info in this section was a bit outdated. First of all, i3 contains many
more files that were not mentioned. Instead of trying to include
everything, I deleted some files with very obvious descriptions. We can
always re-add something if we want to add more details to it.

docs/hacking-howto

@@ -151,63 +151,67 @@ example.
 
 == Files
 
-include/atoms.xmacro::
+i3's source code is in the +src+ folder while header files reside in +include+.
-A file containing all X11 atoms which i3 uses. This file will be included
+Other tools such as i3bar and i3-nagbar have their own folders. i3 and its tools
-various times (for defining, requesting and receiving the atoms), each time
+share an internal library called ``libi3'' which also has its own folder.
-with a different definition of xmacro().
+
+The following list gives an overview of the codebase, explaining the
+functionality of the most important, core source code files. Other files in the
+tree that are not mentioned here implement specific functionalities: for example,
++src/scratchpad.c+ is obviously about the scratchpad functionality.
 
 include/data.h::
-Contains data definitions used by nearly all files. You really need to read
+Contains data definitions used by nearly all files.
-this first.
 
 include/*.h::
 Contains forward definitions for all public functions, as well as
 doxygen-compatible comments (so if you want to get a bit more of the big
 picture, either browse all header files or use doxygen if you prefer that).
 
-src/config_parser.c::
+src/config_directives.c::
-Contains a custom configuration parser. See src/command_parser.c for rationale
+src/commands.c::
- on why we use a custom parser.
+Contain the definitions for all high-level config and command directives. These
-
+are excellent places to start with a top-to-bottom approach to understand
-src/click.c::
+specific i3 behavior. For example, if you want to investigate a bug that happens
-Contains all functions which handle mouse button clicks (right mouse button
+for the +move to mark+ command, you can use gdb to pause in
-clicks initiate resizing and thus are relatively complex).
++cmd_move_con_to_mark+ and then work your way from there, stepping into
-
+lower-level functions.
-src/command_parser.c::
-Contains a hand-written parser to parse commands (commands are what
-you bind on keys and what you can send to i3 using the IPC interface, like
-'move left' or 'workspace 4').
 
 src/con.c::
-Contains all functions which deal with containers directly (creating
+Contains all functions which deal with containers directly (creating containers,
-containers, searching containers, getting specific properties from containers,
+searching containers, getting specific properties from containers, …). Contains
-…).
+abstractions and auxiliary functions necessary to work with the container
+structure which is used in almost all parts of the codebase.
 
-src/config.c::
+src/tree.c::
-Contains all functions handling the configuration file (calling the parser
+Contains functions which deal with the tree abstraction. However, be aware that
-src/config_parser.c) with the correct path, switching key bindings mode).
++src/con.c+ also contains functions that heavily interact with the tree
+structure. Some functions that are included in +str/tree.c+ are those that handle
+opening and closing containers in the tree, finding the container that should be
+focused next and flattening the tree. See also +src/move.c+ for other
+move-specific functions that interact with the tree, which were moved into their
+own file because they are so long.
 
-src/ewmh.c::
+src/workspace.c::
-Functions to get/set certain EWMH properties easily.
+Contains functions which deal with workspaces. Includes code that creates new
-
+workspaces, shows existing ones and deals with workspace assignments.
-src/floating.c::
-Contains functions for floating mode (mostly resizing/dragging).
 
 src/handlers.c::
 Contains all handlers for all kinds of X events (new window title, new hints,
-unmapping, key presses, button presses, …).
+unmapping, key presses, button presses, …). This is a very important file to
+understand how i3 interacts with changes to its environment.
 
-src/ipc.c::
+src/command_parser.c::
-Contains code for the IPC interface.
+src/config_parser.c::
+Contain a hand-written parser to parse commands and configuration (commands are what
+you bind on keys and what you can send to i3 using the IPC interface, like
++move left+ or +workspace 4+). +src/config.c+ is responsible for calling the
+configuration parser.
 
-src/load_layout.c::
+src/click.c::
-Contains code for loading layouts from JSON files.
+src/resize.c::
-
+Contain functions which handle mouse button clicks (right mouse button
-src/log.c::
+clicks initiate resizing and thus are relatively complex).
-Contains the logging functions.
-
-src/main.c::
-Initializes the window manager.
 
 src/manage.c::
 Looks at existing or new windows and decides whether to manage them. If so, it
@@ -216,62 +220,32 @@ reparents the window and inserts it into our data structures.
 src/match.c::
 A "match" is a data structure which acts like a mask or expression to match
 certain windows or not. For example, when using commands, you can specify a
-command like this: [title="*Firefox*"] kill. The title member of the match
+command like this: +[title="*Firefox*"] kill+. The title member of the match
 data structure will then be filled and i3 will check each window using
-match_matches_window() to find the windows affected by this command.
++match_matches_window()+ to find the windows affected by this command.
-
-src/move.c::
-Contains code to move a container in a specific direction.
-
-src/output.c::
-Functions to handle CT_OUTPUT cons.
 
 src/randr.c::
 The RandR API is used to get (and re-query) the configured outputs (monitors,
-…).
+…). Legacy Xinerama support resides in +src/xinerama.c+.
 
 src/render.c::
 Renders the tree data structure by assigning coordinates to every node. These
 values will later be pushed to X11 in +src/x.c+.
 
-src/resize.c::
-Contains the functions to resize containers.
-
-src/restore_layout.c::
-Everything for restored containers that is not pure state parsing (which can be
-found in load_layout.c).
-
 src/sighandler.c::
 Handles +SIGSEGV+, +SIGABRT+ and +SIGFPE+ by showing a dialog that i3 crashed.
-You can chose to let it dump core, to restart it in-place or to restart it
+You can choose to let it dump core and restart i3 in-place (either trying to
-in-place but forget about the layout.
+preserve layout or forget about it).
-
-src/tree.c::
-Contains functions which open or close containers in the tree, change focus or
-cleanup ("flatten") the tree. See also +src/move.c+ for another similar
-function, which was moved into its own file because it is so long.
-
-src/util.c::
-Contains useful functions which are not really dependent on anything.
 
 src/window.c::
 Handlers to update X11 window properties like +WM_CLASS+, +_NET_WM_NAME+,
 +CLIENT_LEADER+, etc.
 
-src/workspace.c::
+include/atoms.xmacro::
-Contains all functions related to workspaces (displaying, hiding, renaming…)
+A file containing all X11 atoms which i3 uses. This file will be included
+various times (for defining, requesting and receiving the atoms), each time
+with a different definition of xmacro().
 
-src/x.c::
-Transfers our in-memory tree (see +src/render.c+) to X11.
-
-src/xcb.c::
-Contains wrappers to use xcb more easily.
-
-src/xcursor.c::
-XCursor functions (for cursor themes).
-
-src/xinerama.c::
-Legacy support for Xinerama. See +src/randr.c+ for the preferred API.
 
 == Data structures