3 ms·

No. What you put in “see notes” notes is the boring technical detail such as how week numbers are calculated and which document or paragraph this particular imp

No. What you put in “see notes” notes is the boring technical detail such as how week numbers are calculated and which document or paragraph this particular implementation holds authoritative over conflicting alternatives. What you put in the man page is the clear statement that for example YYYY “week year” should not be used where yyyy “calendar year” would usually be more appropriate: point out the confusing alternatives and which one the unaware reader is most likely to need.

naniwaduni 8y ago
... overlooking the fact that you aren't sure what it means for a year to be week-based in the first place, since years aren't a part of a week and weeks don't fit evenly into years. Literally the next sentence suggests that %Y is broadly similar, and that %G has exceptional cases: > The ISO 8601 week-based year (see NOTES) with century as a decimal number. The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead. (TZ) (Calculated from tm_year, tm_yday, and tm_wday.) The %Y text, by the way, is much shorter: > The year as a decimal number including the century. (Calculated from tm_year) I find it hard to fault the manual here; the only improvement I can see making is specifying that %Y is the calendar year, and perhaps noting that it is more appropriate when months are used. Of course, speople (e.g. GGP) feel that in this situation some condescension is deserved, and it may be true that what few users would be misled when they really do want to use a week-based year are more than outweighed by those who correctly choose to use %Y instead. The objection to this isn't technical, because the perceived slight isn't technical. But there is a sentiment, more popular in some circles than others, that the user should be respected as a responsible adult who knows what they're doing, that the programmer using the interface is a peer, and that if they aren't, or are operating while impaired, it behooves them to realize this and either sober up or pass the buck. This isn't necessarily true. Sometimes, e.g. if the interface is exposed to end-users in a field for preferred date format on an invoice or something, it's totally inappropriate. But it is a somewhat traditional assumption, especially for ~system-level interfaces like strftime.
- manicdee 8y ago
  There’s also the issue of week-of-year calendars being useful for a very small niche, so it’s basically technical jargon of one speciality imposed on the rest of the world, the same way lawyers debate commas and treat and & or completely differently to sane people. Familiarity with strftime is part of gaining experience in the field, and will usually involve using YYYY until it breaks and then finding articles like this one written over the last two decades explaining that you have tripped over a loose paver that everyone else in the industry already knows about (but at least now you understand why there are so many broken wrists). There’s a similar problem in orbital mechanics where people try doing a calculation using Kepler’s equations, but because they’re using degrees they get the wrong result. Of course the equation is entirely in radians, which they quickly learn about but not before suggesting that the languages or APIs they are using need new features to help other people avoid falling into that trap.

naniwaduni 8y ago

... overlooking the fact that you aren't sure what it means for a year to be week-based in the first place, since years aren't a part of a week and weeks don't fit evenly into years. Literally the next sentence suggests that %Y is broadly similar, and that %G has exceptional cases: > The ISO 8601 week-based year (see NOTES) with century as a decimal number. The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead. (TZ) (Calculated from tm_year, tm_yday, and tm_wday.) The %Y text, by the way, is much shorter: > The year as a decimal number including the century. (Calculated from tm_year) I find it hard to fault the manual here; the only improvement I can see making is specifying that %Y is the calendar year, and perhaps noting that it is more appropriate when months are used. Of course, speople (e.g. GGP) feel that in this situation some condescension is deserved, and it may be true that what few users would be misled when they really do want to use a week-based year are more than outweighed by those who correctly choose to use %Y instead. The objection to this isn't technical, because the perceived slight isn't technical. But there is a sentiment, more popular in some circles than others, that the user should be respected as a responsible adult who knows what they're doing, that the programmer using the interface is a peer, and that if they aren't, or are operating while impaired, it behooves them to realize this and either sober up or pass the buck. This isn't necessarily true. Sometimes, e.g. if the interface is exposed to end-users in a field for preferred date format on an invoice or something, it's totally inappropriate. But it is a somewhat traditional assumption, especially for ~system-level interfaces like strftime.

manicdee 8y ago
There’s also the issue of week-of-year calendars being useful for a very small niche, so it’s basically technical jargon of one speciality imposed on the rest of the world, the same way lawyers debate commas and treat and & or completely differently to sane people. Familiarity with strftime is part of gaining experience in the field, and will usually involve using YYYY until it breaks and then finding articles like this one written over the last two decades explaining that you have tripped over a loose paver that everyone else in the industry already knows about (but at least now you understand why there are so many broken wrists). There’s a similar problem in orbital mechanics where people try doing a calculation using Kepler’s equations, but because they’re using degrees they get the wrong result. Of course the equation is entirely in radians, which they quickly learn about but not before suggesting that the languages or APIs they are using need new features to help other people avoid falling into that trap.