объяснение/документирование сложного механизма

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 является DateTime, 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 - как авторитетную ссылку.

И независимо от того, насколько хорошо написан текст, несколько конкретных примеров всегда ценны.