Both comments bury the lede. The bit that alludes to but does not actually state "this does not do what you want" is at the end of the description, not the beginning where it might actually warn someone off.
"You didn't read and understand the whole documentation for this complex feature" is not making it easy to do the right thing. It's just fodder for people "in the know" to make fun of normies.
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, ...
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.
The "Linux Programmer's Manual" man page from the Linux documentation project has it as:
This clearly says "%G is some ISO nonsense you don't want to be using".But the "week-based year" alone should alert you that something is wrong. Because, like, the year that you know is not week-based! There aren't exactly 52 weeks in a year: 365 isn't divisible by 7, and if it were, then 366 wouldn't be.
A (see NOTES) is also alarming. Why do you have to see some notes about planting the year part of the date into a simple date string?
The glibc manual has it here:https://www.gnu.org/software/libc/manual/html_node/Formattin... It also makes it perfectly clear that this is something weird:
"This has the same format and value as %y, except that if the ISO week number (see %V) belongs to the previous or next year, that year is used instead. This format was first standardized by ISO C99 and by POSIX.1-2001."
Three warning labels here: ISO, C99 and POSIX 2001!
C99 itself gives it like this.
%G is replaced by the week-based year (see below) as a decimal number (e.g., 1997). [tm_year, tm_wday, tm_yday]
If you don't "see below", that is your problem, just like ignoring "(see NOTES)". The "see below" paragraph has this:
%g, %G, and %V give values according to the ISO 8601 week-based year. In this system, weeks begin on a Monday and week 1 of the year is the week that includes January 4th, which is also the week that includes the first Thursday of the year, and is also the first week that contains at least four days in the year. [... more explanation]