News for hackers. Stuff that matters.
Re:Strftime's alpha-sorted man page vs. well-meaning people by kazinator on Sunday May 13, 2018 @10:12AM (#17058973)
> You didn't read and understand the whole documentation for this complex feature

Formatting a year's date into a string doesn't require a complex feature; the "complex feature" part is a warning itself. The date object (struct tm) has a year field that is a simple integer (almost: it's years since 1900). Sticking that into a string in the format "2018" is trivial. The word "weeks" doesn't enter into it and we don't need ISO to figure it out.

Also, you have to be super naive to believe that G was used for "year" instead of the letter Y, and then not even wonder out of curiosity that, if this is how you're supposed to obtain the year, why Y was not available and what the heck Y is being used for. The software field requires people who are curious like this and read documentation critically (as they do code).

Why would someone invent a date formatting printf thing in which %H is hour, but year is %G? Why would they forget to add the year feature, then use Y for something else, and add year support under G in some new standard? Of course, any nonsense lettering is due to historic extension when letters are running out. Why would the basic feature of generating year part of a date string be a historic extension?

> Standards usually sound like a good thing.

The first standard for a programming language or API is often good; then it is usually severely screwed in subsequent revisions. This is massively evident in C, C++, POSIX, Unicode, WWW, IP, USB, Ethernet, ...

Re:Strftime's alpha-sorted man page vs. well-meaning people by wffurr on Sunday May 13, 2018 @12:30PM (#17059715)
The whole point, which you are missing, is to make the API simple and obvious for a naive reader, which is most of us. Not everyone is as immersed in Unix and C culture as you clearly are.
Re:Strftime's alpha-sorted man page vs. well-meaning people by kazinator on Sunday May 13, 2018 @01:15PM (#17059902)
> make the API simple and obvious

Note that make the API is a very distinct activity from document the API, which is what is being criticized here.

A better API would use long identifiers for all weird stuff like %{iso-week-based-year} instead of %G.

> Unix and C culture

I'm confident I could properly understand an above-par engineering document written in plain English, such as what is being criticized here, from any branch of computing.

You can't pin this on Unix and C culture.

Those man pages are documenting this weird ISO "week-based year" about as well as can be. If you read documents in such a manner that you drop random adjectives (such that "week-based year" looks like "year" to your eyes) and ignore anything in parentheses as being optional such as "(see ...)" notices, that's a comprehension problem.

If the descriptions were not sorted alphabetically, that would also be criticized as unfriendly. Users would have to exhaustively scan that section when trying to decipher a format string that someone else wrote.