Case in point: I want to use “find” to find files I’ve recently created.
-ctime n[smhdw] If no units are specified, this primary evaluates to true if the difference between the time of last modification time and the time find was started, rounded up to the next full 24-hour period, is n 24-hour periods.
If units are specified, this primary evaluates to true if the difference between the time of last modification time and the time find was started is exactly n units. Please refer to the -atime primary description for information on supported time units.
Humane documentation FAIL! The precision here is all well and good to include somewhere, but unnecessary for most usages. Please, just tell me what I need to know and Don’t Make Me Think!.
What I wanted to see:
-mtime t
Include only files modified t days ago. You will typically want to specify a +/- sign. e.g. “-ctime +3” for files created 3 or more days ago. To measure in another unit of time, you can append one of the following to t: s for seconds, m for minutes, h for hours, d for days, w for weeks, but note that “-ctime” unfortunately only works if the time is at least one day. For example, “find . -ctime 1d6h” will return files created in the past 30 seconds.
Technical detail: (the legalese stuff goes here. 99% of users will never need it and never read it.)
The improved version focuses on what the typical user needs to know, uses active voice, avoids the cross-reference (it’s documentation, not code, so embrace redundancy!), and most importantly, includes an example. (The man page does include examples at the bottom, but (a) they should be included against each component too; and (b) they still shy away from concrete values: “-newer ttt”!!!)
A lot of these man pages have been around for two decades or more, with minimal changes to my knowledge; I’d love to see someone like Ubuntu sponsor an effort to bring them up to date. Plain English without dumbing down.
