解释/记录复杂的机制

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 作为提醒，将手册页作为权威参考。

无论文本写得多么好，一些具体的例子总是有价值的。