From 782d2c17cac641c3c123cc284b219a01ef26e74f Mon Sep 17 00:00:00 2001 From: Rob Landley Date: Wed, 17 Feb 2016 12:30:31 -0600 Subject: Add the sed invocations to convert tabs/spaces and back, plus some tweaks. --- www/design.html | 59 +++++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 43 insertions(+), 16 deletions(-) (limited to 'www') diff --git a/www/design.html b/www/design.html index 4a42753c..050c953f 100755 --- a/www/design.html +++ b/www/design.html @@ -294,24 +294,40 @@ feeding the compiler -funsigned-char.

The reason to pick "unsigned" is that way we're 8-bit clean by default.

Error messages and internationalization:

+

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

Coding style

@@ -327,6 +343,17 @@ columns. (Indentation of continuation lines is awkward no matter what you do, sometimes two spaces looks better, sometimes indenting to the contents of a parentheses looks better.)

+

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