From 782d2c17cac641c3c123cc284b219a01ef26e74f Mon Sep 17 00:00:00 2001
From: Rob Landley
The reason to pick "unsigned" is that way we're 8-bit clean by default.
Error messages are extremely terse not just to save bytes, but because we -don't use any sort of _("string") translation infrastructure.
+don't use any sort of _("string") translation infrastructure. (We're not +translating the command names themselves, so we must expect a minimum amount of +english knowledge from our users, but let's keep it to a minimum.)Thus "bad -A '%c'" is preferable to "Unrecognized address base '%c'", because a non-english speaker -can see that -A was the problem, and with a ~20 word english vocabulary is -more likely to know (or guess) "bad" than the longer message.
- -The help text might someday have translated versions, and strerror() -messages produced by perror_exit() and friends can be expected to be -localized by libc. Our error functions also prepend the command name, -which non-english speakers can presumably recognize already.
- -An enventual goal is UTF-8 support, although it isn't a priority for the -first pass of each command. (All commands should at least be 8-bit clean.)
- -Locale support isn't currently a goal; that's a presentation layer issue, -X11 or Dalvik's problem.
+can see that -A was the problem (giving back the command line argument they +supplied). A user with a ~20 word english vocabulary is +more likely to know (or guess) "bad" than the longer message, and you can +use "bad" in place of "invalid", "inappropriate", "unrecognized"... +Similarly when atolx_range() complains about range constraints with +"4 < 17" or "12 > 5", it's intentional: those don't need to be translated. + +The strerror() messages produced by perror_exit() and friends should be +localized by libc, and our error functions also prepend the command name +(which non-english speakers can presumably recognize already). Keep the +explanation in between to a minimum, and where possible feed back the values +they passed in to identify _what_ we couldn't process. +If you say perror_exit("setsockopt"), you've identified the action you +were trying to take, and the perror gives a translated error message (from libc) +explaining _why_ it couldn't do it, so you probably don't need to add english +words like "failed" or "couldn't assign".
+ +All commands should be 8-bit clean, with explicit +UTF-8 support where +necessary. Assume all input data might be utf8, and at least preserve +it and pass it through. (For this reason, our build is -funsigned-char on +all architectures; "char" is unsigned unless you stick "signed" in front +of it.)
+ +Locale support isn't currently a goal; that's a presentation layer issue +(I.E. a GUI problem).
I'm aware this indentation style creeps some people out, so here's +the sed invocation to convert groups of two leading spaces to tabs:
++ ++sed -i ':loop;s/^\( *\) /\1\t/;t loop' filename +
And here's the sed invocation to convert leading tabs to two spaces each:
+++sed -i ':loop;s/^\( *\)\t/\1 /;t loop' filename +
There's a space after C flow control statements that look like functions, so "if (blah)" instead of "if(blah)". (Note that sizeof is actually an operator, so we don't give it a space for the same reason ++ doesn't get @@ -336,8 +363,8 @@ to read.) We also put a space around assignment operators (on both sides), so "int x = 0;".
Blank lines (vertical whitespace) go between thoughts. "We were doing that, -now we're doing this. (Not a hard and fast rule about _where_ it goes, -but there should be some.)"
+now we're doing this." (Not a hard and fast rule about _where_ it goes, +but there should be some for the same reason writing has paragraph breaks.)Variable declarations go at the start of blocks, with a blank line between them and other code. Yes, c99 allows you to put them anywhere, but they're -- cgit v1.2.3