Question

我在两个世界之间徘徊，我在命令行工具中有这个非常直观（但错综复杂）的机制，我想知道我应该在多大程度上解释这个。

我可以采用简单的方式，而不是完全解释它并相信我的用户自己弄明白，但是有些用户可能永远不会发现这个特定的功能。

我可以采用可怕的方式并在帮助输出和手册页中加入大量的数学符号，但是用户可能会认为这太复杂了，他们可能会对我的工具或这个特殊功能产生莫名的恐惧。 / p>

我如何解决实验性问题，比如保守用户（那些在没有正确解释问题时不会加倍努力的用户）？

详细信息：
该工具是关于日期和时间的算术，特别是计算两个日期和/或时间之间的持续时间，并根据格式规范格式化结果。

我的内部设计使用这样的乘法表：

-  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 page作为权威参考。

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

解释/记录错综复杂的机制

1 个答案: