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.
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.