0

私は2つの世界の間で引き裂かれ、コマンドラインツールにこの非常に直感的な（しかし複雑な）メカニズムがあり、これをどの程度説明すべきか疑問に思っています。

私はそれをまったく説明せずに簡単な方法で進むことができ、ユーザーがそれを自分で理解することを信頼しますが、そうすると一部のユーザーはこの特定の機能を決して発見しないかもしれません。

私は恐ろしい方法でヘルプ出力とマニュアルページに多くの数学表記を入れることができますが、ユーザーはこれが複雑すぎると思うかもしれず、私のツールやこの特定の機能に対して不可解な恐れを抱くかもしれません。

実験的なユーザーと、たとえば保守的なユーザー（何かが適切に説明されていないときに余分な努力をしないユーザー）の両方にどのように対処できますか？

詳細：
このツールは、日付と時刻の計算、特に2つの日付や時刻の間の期間の計算、およびフォーマット仕様に従って結果のフォーマットに関するものです。

私の内部設計では、次のような掛け算の九九を使用しています。

-  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で、unknown（解析不能）入力、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、1年と日数（0から365の範囲）が表示%Y %m %dされますが、0から30の範囲の日数が表示されます（残りは月に「キャプチャ」されるため）。

例：%Y %d与える1 year 90 days一方%Y %w %d与える1 year 12 weeks 6 days

4

1 に答える 1

1

ツール自体にヘルプテキストを作成する場合は、linuxdateコマンドのヘルプを参照してください。

または、次のようにすることもできます。

$ 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ページを信頼できるリファレンスとして使用する傾向があります。

そして、テキストがどれほどうまく書かれていても、いくつかの具体的な例は常に価値があります。

于 2012-04-05T14:25:04.380 に答える