Docs: full syntax overview (#184)

README.md

@@ -55,23 +55,65 @@ CRON Expressions
 
 A CRON expression is a string representing the schedule for a particular command to execute.  The parts of a CRON schedule are as follows:
 
-    *    *    *    *    *
-    -    -    -    -    -
-    |    |    |    |    |
-    |    |    |    |    |
-    |    |    |    |    +----- day of week (0 - 7) (Sunday=0 or 7)
-    |    |    |    +---------- month (1 - 12)
-    |    |    +--------------- day of month (1 - 31)
-    |    +-------------------- hour (0 - 23)
-    +------------------------- min (0 - 59)
-
-This library also supports a few macros:
-
-* `@yearly`, `@annually` - Run once a year, midnight, Jan. 1 - `0 0 1 1 *`
-* `@monthly` - Run once a month, midnight, first of month - `0 0 1 * *`
-* `@weekly` - Run once a week, midnight on Sun - `0 0 * * 0`
-* `@daily`, `@midnight` - Run once a day, midnight - `0 0 * * *`
-* `@hourly` - Run once an hour, first minute - `0 * * * *`
+```
+*   *   *   *   *
+-   -   -   -   -
+|   |   |   |   |
+|   |   |   |   |
+|   |   |   |   +----- day of week (0-7) (Sunday = 0 or 7) (or SUN-SAT)
+|   |   |   +--------- month (1-12) (or JAN-DEC)
+|   |   +------------- day of month (1-31)
+|   +----------------- hour (0-23)
++--------------------- minute (0-59)
+```
+
+Each part of expression can also use wildcard, lists, ranges and steps:
+
+- wildcard - match always
+	- `* * * * *` - At every minute.
+	- day of week and day of month also support `?`, an alias to `*`
+- lists - match list of values, ranges and steps
+	- e.g. `15,30 * * * *` - At minute 15 and 30.
+- ranges - match values in range
+	- e.g. `1-9 * * * *` - At every minute from 1 through 9.
+- steps - match every nth value in range
+	- e.g. `*/5 * * * *` - At every 5th minute.
+	- e.g. `0-30/5 * * * *` - At every 5th minute from 0 through 30.
+- combinations
+	- e.g. `0-14,30-44 * * * *` - At every minute from 0 through 14 and every minute from 30 through 44.
+
+You can also use macro instead of an expression:
+
+- `@yearly`, `@annually` - At 00:00 on 1st of January. (same as `0 0 1 1 *`)
+- `@monthly` - At 00:00 on day-of-month 1. (same as `0 0 1 * *`)
+- `@weekly` - At 00:00 on Sunday. (same as `0 0 * * 0`)
+- `@daily`, `@midnight` - At 00:00. (same as `0 0 * * *`)
+- `@hourly` - At minute 0. (same as `0 * * * *`)
+
+Day of month extra features:
+
+- nearest weekday - weekday (Monday-Friday) nearest to the given day
+	- e.g. `* * 15W * *` - At every minute on a weekday nearest to the 15th.
+	- If you were to specify `15W` as the value, the meaning is: "the nearest weekday to the 15th of the month"
+	  So if the 15th is a Saturday, the trigger will fire on Friday the 14th.
+	  If the 15th is a Sunday, the trigger will fire on Monday the 16th.
+	  If the 15th is a Tuesday, then it will fire on Tuesday the 15th.
+	- However, if you specify `1W` as the value for day-of-month,
+	  and the 1st is a Saturday, the trigger will fire on Monday the 3rd,
+	  as it will not 'jump' over the boundary of a month's days.
+- last day of the month
+	- e.g. `* * L * *` - At every minute on a last day-of-month.
+- last weekday of the month
+	- e.g. `* * LW * *` - At every minute on a last weekday.
+
+Day of week extra features:
+
+- nth day
+	- e.g. `* * * * 7#4` - At every minute on 4th Sunday.
+	- 1-5
+	- Every day of week repeats 4-5 times a month. To target the last one, use "last day" feature instead.
+- last day
+	- e.g. `* * * * 7L` - At every minute on the last Sunday.
 
 Requirements
 ============