Config: updates

docs/NEW-CONFIG.md

@@ -4,6 +4,19 @@ New Configuration Format
 Introduction
 ============
 
+FVWM is completely governed by how it reads in commands, and hence at the
+moment, each command is responsible for parsing its values.  There's been
+twenty years of this idea; organically growing out of control.  Adding or even
+changing existing options to commands is a nightmare; there's no state being
+kept between commands (which would be good), and hence there's a lot of the
+same sorts of information being gathered separately, leading to a lot of
+duplication at the code-level.
+
+Changing the format is a great way of getting a clean break, and being able to
+rationalise the commands we have now, and need; moving functionality into
+other commands in an extensible way, which will also reduce the code
+complexity somewhat.  You can't easily do this with the format we have now.
+
 FVWM's configuration format is line-based.  This means, each line is parsed by
 itself, without any structure.  This means, groups of commands such as
 *functions* have no structural representation, other than to end with a blank
@@ -29,31 +42,53 @@ A new configuration file therefore must accept structural data, and have it
 represented appropriately.  Commands should receive information rather than
 having to parse it itself.
 
+If the syntax were like mini-CLI programs, this would make scripting a lot
+easier; reducing the need for FvwmCommand/FvwmConsole (or rather making it
+easier to implement replacements for them.)
+
+Migration
+=========
+
+There will be a means of going from the current FVWM format to whatever new
+one is put in place, via conversion script(s).  It is doubtful theser scripts
+will be able to convert everything, but they will do their best.  This is no
+different to the current set of conversion scripts that have been written for
+previous versions of FVWM.
+
 Syntax
 ======
 
 **[These are rough ideas for now...]**:
 
 * Still line-based.
-* Structured information can be represented like this:
+
+* Functions:
 
   ```
-  Function -n func_name -i DoImmediate -c DoClick -h DoHold
+  i:Immediate Action
+  c:Click Action
+  m:Motion Action
+  h:Hold Action
+  d:Double-click Action
   ```
 
-  **But this doesn't take into account the ordering of the commands to run.**
+  Example:
 
-  Maybe:
 
   ```
-  Function -n func_name "i:DoImmediate,c:DoClick,i:DoImmediate,h:DoHold"
+  Function -n func_name " \
+	  i:DoImmediate, \
+	  c:DoClick, \
+	  i:DoImmediate, \
+	  i:TestRc (NoMatch) Break, \
+	  h:DoHold"
   ```
 
 * Ways of referring to windows/desks/monitors, etc:
 
   ```
   -t: screen:desk.page
-  -w: n:name, c:class, r:resource|<win_id>|*
+  -w: n:name, c:class, r:resource|<win_id>|*|-<NUM>|+<NUM>
   -g  (global)
   ```
 
@@ -67,6 +102,20 @@ Syntax
   Hence, `-t` and `-w` are consistent throughout the entirety of the command
   set in FVWM.
 
+  Relative positional arguments can be specified:
+
+  ```
+  -t :+1 -- goto next desk
+  -t :-1 -- goto previous desk
+  -t +1  -- goto next monitor
+
+  -w -1  -- the previous window (stack ring)
+  -w +3  -- the third window (stack ring)
+  -w c:XTerm,+3 -- the third XTerm window
+  ```
+
+  **TODO:** What happens if there's more than one match?  Menu popup?
+
 * Setting options:
 
   ```
@@ -79,14 +128,15 @@ Syntax
   ```
   -k: key
   -m: mouse
+  -c: context (A|W|M|F|S|etc...)
   cmd
   ```
 
   Example:
 
   ```
-  bind -k CSM-w Close
-  bind -m 1 Close -t ...
+  bind -k CSM-w -cAll Close
+  bind -m 1 -cW Close -t ...
   ```
 
 * Menus:
@@ -139,6 +189,11 @@ Syntax
   Colorset -nwindows -fwhite -bgreen -t
   ```
 
+* Modules:
+
+  Unclear -- likely not going to change, since that's orthogonal to how they
+  could work; the "*" syntax for modules can still be line-based as it is now.
+
 Rough Example
 =============
 
@@ -156,11 +211,29 @@ Style -t 0:1 -w* Colorset 1
 Style -g -w c:XTerm Colorset 2
 
 # Focus next window on current monitor.
-Focus -t+1
+Focus -w+1
 
 # Focus next window on monitor 1.
-Focus -t1:+1
+Focus -t1 -w+1
 
 # Focus third window on monitor 1
-Focus -t1:+3
+Focus -t1 -w+3
+
+# Focus previous window
+Focus -w-1
+
+# Focus the next XTerm window on the previous desk
+Focus -t:-1 -wc:XTerm
 ```
+
+Reference Implementation
+========================
+
+There's the beginnings of a CLI application to show how the parsing would
+work, without needing to change FVWM just yet.
+
+This is just a means of fleshing out the data structures and behaviour would
+be, and to start to amalgamate functionality between duplicate commands.
+
+* [Refence Program](../config/config.c)
+* [Sample Config](../config/config_file)