[readme] explain default rules

README.org

@@ -19,35 +19,32 @@ Guile must be available at =/usr/bin/guile=
 3. In your project root, run -
    : ./mkly
 
-** Invocation
-mkly can be run without arguments -
+** Invocation and default rules
+=mkly= can be run without arguments -
 : mkly
-Doing so will execute the /action/ in the first (top-most) defined /rule/.
+This will compile =main.ly= and =part-*.ly=.
 
 You can pass one or more /targets/ -
 : mkly <target>*
-Each target will be checked against the defined patterns, and the actions for all matching patterns will be run.
+Each target will be checked against the /patterns/ defined in the rules, and the actions for all matching patterns will be run.
 
-If a subdirectory is supplied, mkly will descend to it for all following targets (until another subdirectory on the command line is encountered) -
+The default targets are
+1. =main.ly= - compiles the file without point-and-click. Emits a file to =output/<project-name>=.
+2. a file name matching =part-*.ly=, e.g. =part-foo.ly= - compiles the file without point-and-click. Emits a file to =output/<project-name>-part-foo=.
+3. =dev= - compiles =main.ly= with point-and-click enabled. Emits a file to =output/<project-name>-pacON=.
+4. =all= - compiles =main.ly= and all =part-*.ly= files, without point-and-click.
+
+If a subdirectory is supplied, =mkly= will descend to it for all following targets (until another subdirectory on the command line is encountered) -
 : mkly main foo/ dev bar/ main dev
 Here, target "main" will be run in the project root, target "dev" will be run in the subdirectory "foo/", and target "main" and "dev" will be run in subdirectory "bar/".
 
-If there is a mkly-rules.scm in the subdirectory, the targets following the subdirectory will be matched against patterns defined in that file. If there isn't such a file, the patterns from the directory mkly was called in will be used instead.
-
-** The defaults
-The default rules make certain assumptions about your project structure -
-1. You have a main.ly in the project root containing all musical parts
-2. Individual parts are contained in part-*.ly files
-3. Emitted PDF/MIDI/PNG files go into a directory called "output" (or "output-<current branch>" if you use a VCS)
-
-Of course, you can change the rules to suit whatever project structure you want.
-
-Some default variables are defined -
-1. project-name - by default, the basename of the parent directory
-2. shell-path - path to the shell you want to use for running your commands
-
 ** Defining rules
-Rules are returned as a list by the procedure =rules=, defined in the project-specific =mkly-rules.scm=.
+Rules are returned as a list by the procedure =rules=. This procedure can be redefined by loading your own Scheme file, by running =mkly= with the =--load=/ =-l= command line option.
+
+Some default variables are defined for use in defining rules -
+1. project-root - the project root directory
+2. project-name - by default, the basename of the parent directory
+3. shell-path - path to the shell you want to use for running your commands
 
 ** Built-in helper functions
 1. =(use-dir! DIR)= - creates DIR if it does not exist. DIR must be a string. Raises an error if DIR exists and is not a directory. Returns DIR.
@@ -69,7 +66,7 @@ Rules are returned as a list by the procedure =rules=, defined in the project-sp
 7. [ ] Multiple targets in one command e.g. to compile both the main score and the parts in one command.
 8. [X] Targets containing other targets.
    + I've tried calling the script itself with the required targets - not sure if that actually works. Especially considering that #7 - multiple targets in one command - isn't implemented yet.
-   + If mkly is not in the user's $PATH and is invoked as =./mkly=, the shell won't be able to find it if it calls itself. We can try constructing the path to the script (using =getcwd= - if =(first (command-line))= is "./mkly", it's in the current working directory)
+   + If =mkly= is not in the user's $PATH and is invoked as =./mkly=, the shell won't be able to find it if it calls itself. We can try constructing the path to the script (using =getcwd= - if =(first (command-line))= is "./mkly", it's in the current working directory)
 9. [-] Shell globs, both in targets and in actions.
    * [X] Document shell-path as a user variable
    * [ ] Use shell-path to run commands
@@ -86,6 +83,7 @@ Rules are returned as a list by the procedure =rules=, defined in the project-sp
 11. [ ] Expand branch detection to include more VCSs.
 12. [ ] Add -h/--help, and -d/--debug or -v/--verbose
 13. [ ] Warn users about ignored =mkly-rules.scm=, if detected
+14. [ ] Add command line option to load a Scheme file, serving as an extension point (e.g. to define custom rules)
 
 [fn:1] These are likely to happen if you have a compile-with-last-command-on-save setup, like in my Emacs.
 
@@ -100,6 +98,11 @@ Rules are returned as a list by the procedure =rules=, defined in the project-sp
 6. [ ] Replace regexp patterns with glob patterns?
    * more consistent (since targets and actions use globs too), but possibly less powerful.
 *** Bugs
-1. Barfs when placed in and run from directories with a path containing non-ASCII characters.
+1. [X] Barfs when placed in and run from directories with a path containing non-ASCII characters.
 
    This is a [[http://lists.gnu.org/archive/html/guile-user/2015-12/msg00054.html][Guile]] [[https://debbugs.gnu.org/cgi/bugreport.cgi?bug%3D22229][bug]].
+2. [ ] =./mkly= -> =sh: 1: main.ly: not found=
+   * [ ] Default rule (no pattern provided) and =else= seem to conflict - do we want to do different things when there's no pattern provided and when a provided pattern does not match, or the same thing?
+   * [ ] Meta-targets - if the command does not match another rule, run as shell command; otherwise treat as list of targets
+3. [ ] chdir to project root before descending into subdir
+4. [ ] Error on unmatched pattern