Futilities/human/ui standards

User Interface standards and conventions as used in The Futilities

Guidelines

• Commands will always identify themselves when run (name, version, date of last major revision).
• In general, the app should always guide the user towards constructing a useful command string.
• When a command is run without proper input (including no input), it should at least:
  • describe itself (name, version, revision date)
  • show the format it expects for input arguments
  • list any available options
  • link to a documentation page.
  • describe what is missing
• Error messages will be human-readable.

If a machine-interface is desired (e.g. communicating with the app via JSON or XML), there will be an --API flag; when that flag is used, these guidelines do not apply. I have not had need to implement this yet, however.

Progress Indication

If an operation might take a long time, there will be visual feedback regarding progress.

• This feedback does not have to be quantitative or make any estimates about completion, but if possible it should provide enough information for the user to compare with other runs on similar data and make their own reasonable guess.
• The application should not, by default, take extra time to gather information necessary for estimating percent-completion or time-to-complete. It may offer this service as an option, however.

I was asked why this is useful, so here's my answer to that:

• It lets me know that something is actually happening, rather than something being hung up.
• It gives me some sense of whether what I thought I was asking for is actually what is happening.
• It gives me some idea of how long the process is likely to take, based on what I know of how large the fileset is.
• It lets me know which parts of the process are taking longer than others.
• It gives me spot-check reminders of what's in the fileset, which may prompt me to take additional actions towards whatever it is I'm trying to do with it.

Notes

Command Links

Handy command for making a commandlike link to a php executable:

ln -r --symbolic ./<X>.php <X>

...where <X> is the name of the executable php file (first line must be «#!/usr/bin/php». and the file must have «+x» permission).

Advanced Path Syntax

Keep in mind the counterintuitive reality that bash does helpful processing on the ~ (tilde) character, converting it into the path to your home folder, while it also does unhelpful processing on the * (asterisk) character, expanding it into a list of matching files which may totally confuse the app, if it is not inside quotes.

You can in fact get the preferred behavior for both of these by putting the asterisks in quotes but leaving the tilde outside -- like:

~/path/"*.ext"

Unescaped quote characters will protect their contents from preprocessing, but will also be removed before the preprocessed result is passed to the app. For me, the above would then be passed as:

/home/woozle/path/*.ext