explaining/documenting an intricate mechanism

Question

I'm torn between two worlds, I have this very intuitive (but intricate) mechanism in a command line tool, and I'm wondering as to what extent I should explain this.

I can go the simple way, not explaining it at all and trust my users to figure it out themselves, but then some users might never discover this particular feature.

I can go the scary way and put a lot of mathematical notation into the help output and the man pages, but then users might think this is too complicated and they might develop an inexplicable fear towards my tool or this particular feature.

How can I address both experimental and, let's say, conservative users (the ones that don't go the extra mile when something isn't explained properly)?

Details:
The tool is about date and time arithmetic, in particular calculating durations between two dates and/or times, and formatting the results according to format specs.

My internal design uses a multiplication table like this:

-  x  d  t  dt
x  x  x  x  x
d  x  D  x  D
t  x  x  T  x
dt x  D  x  S

where x is unknown (unparsable) input, d is a date, t is a time and dt is a datetime, D is a date duration (resolution is 1 day), T is a time duration (resolution is 1 second), and S is a time-stamp duration (resolution 1 second).

Now the result depends on the duration type and the format specifiers given, and I'm really lacking a succinct way of explaining this, so I do it by example:

'%d' will return the duration in days (like 12 days)
'%w' will return the duration in weeks (like 1 week)
'%w %d' will return the duration in weeks and days (like 1 week and 5 days)
...
'%S' will return the duration in seconds (e.g. 86464 seconds)
'%M' will return the duration in minutes (e.g. 1441 minutes)
'%H' will return the duration in hours (e.g. 24 hours)
'%H %M %S' will return the duration in hours, minutes and seconds (24h 1m 4s)
'%H %S' will return the duration in hours and seconds (24h 64s)
...

I mean I could probably work out what I mean with just these few examples given, but there's no formal explanation or anything in there.

Edit for clarity:
The issue I'm trying to point out is that you can combine any of the flags (for seconds, hours, days, months, etc.) and the program will "intelligently" give you a result. Like %Y %d would give you a year and the number of days (in the range 0 to 365) whereas %Y %m %d would give you the days in the range 0 to 30 (because the rest is "captured" in the month)

Answer 1

I think the best way to approach this is to do the following

1. Give examples of how to call your command line tool
2. List the parameter inputs
3. Explain what the parameters mean

DateCalculator.exe [time1] [time2] [format|opt]

time1 - The first date you want to compare
time2 - The second date you want to compare
format - List all of the different formats
'%d' will return the duration in days (like 12 days)
'%w %d' will return the duration in weeks and days (like 1 week and 5 days)

[opt] means that the formatting is optional. By default the date format is "%d"

Then show examples of how to use the tool and expected results. I don't think users really need to know how the parameters will be multiplied together in your code. Just give them a list of inputs and expected outputs. They will should treat your code as a black box.

Some good real life examples of this is how Microsoft does this for their date time format list and how Wolfram Alpha shows their date calculation.

Essentially show enough examples to show me what is possible out of the tool and tell me that it will accept different combinations. Otherwise you will have to write out every permutation and the users will end up reading 10 of the permutations and think the tool is too complex or they will spend more time looking for the right combo rather than just typing in what date fields they want returned.