解釋/記錄錯綜複雜的機制

Question

我在兩個世界之間徘徊，我在命令行工具中使用了非常直觀（但錯綜複雜）的機制，我在想我應該在多大程度上解釋這一點。

我可以用簡單的方法，根本不解釋它，並相信我的用戶自己想出來，但是有些用戶可能永遠都不會發現這個特殊功能。

我可以去嚇人的方式，並將大量的數學符號放入幫助輸出和手冊頁，但用戶可能認爲這太複雜了，他們可能會對我的工具或此特定功能產生莫名其妙的恐懼。

我該如何解決實驗問題，比如保守用戶（那些在沒有正確解釋某些問題時不會多加努力的人）？

詳細說明：
該工具是關於日期和時間運算，在兩個日期和/或時間之間的特定計算的持續時間，並根據格式規範格式化的結果。

我的內部設計採用乘法表是這樣的：

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

其中x是未知的（不可分析）輸入，d是日期，t是一個時間和dt是日期時間，D是日期時間（分辨率爲1天），T是一個時間段（分辨率爲1秒），而S是一個時間戳記持續時間（分辨率爲1秒）。

現在的結果取決於持續時間類型和格式說明給出的，我真的很缺乏這說明一個簡潔的方式，所以我舉例做到這一點：

'%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) 
... 

我的意思是我大概可以按照給出的幾個例子來計算我的意思，但沒有正式的解釋或其中的任何內容。

爲清楚：
我試圖解決的問題是，你可以將任何標誌（秒，小時，天，月，等等），並計劃將「智能」給你結果。像%Y %d會給你一年和天數（範圍從0到365），而%Y %m %d會給你在0到30範圍內的日子（因爲其餘的是在本月「捕獲」）。

例子：%Y %d給1 year 90 days而%Y %w %d給1 year 12 weeks 6 days

Answer 1

如果你正在尋找創建工具本身的說明文字，幫忙看一下對Linux date命令。

或者，你可以做這樣的事情：

$ your_app --help 

usage: your_app [OPTIONS] [FORMAT] 

Returns the elapsed time between blah blah.... 

FORMAT: 

// list formats here 

OPTIONS: 

--help   Display this help text 
--help-detailed Display more extensive help text 
--help-examples Display example uses 

如果我是用戶，我想--help列出所有的選項作爲參考，我會想這個人的頁面包含儘可能多的細節。我傾向於使用--help作爲提醒，man手冊用作權威參考。

不管文本寫得多麼好，幾個具體的例子總是有價值的。