From 41e7186b012e864c6252e5c5a415fb4379503bfd Mon Sep 17 00:00:00 2001 From: Rob Landley Date: Tue, 30 Apr 2024 14:18:57 -0500 Subject: [PATCH] Add a little bit on the what and why of help text. --- www/design.html | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/www/design.html b/www/design.html index 7d59f661..f5ca6787 100644 --- a/www/design.html +++ b/www/design.html @@ -436,7 +436,7 @@ you can't fix a bug in the old system if you can't build in the old environment.

Partly because toybox's maintainer has his own corollary to Moore's law: -50% of what you know about programming the hardware is obsolete every 18 +50% of what you know about programming is obsolete every 18 months, but the advantage of C & Unix it's usually the same 50% cycling out over and over.

@@ -563,7 +563,7 @@ feeding the compiler -funsigned-char.

The reason to pick "unsigned" is that way char strings are 8-bit clean by default, which makes UTF-8 support easier.

-

Error messages and internationalization:

+

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. (We're not @@ -602,6 +602,18 @@ of it.)

Someday we should probably have translated --help text, but that's a post-1.0 issue.

+

Help text

+ +

Each command's help text tries to briefly answer the questions "what does +this command do" and "how do I use it". There's a usage: line, basic +description, list of command line options (mostly in alphabetical order), +and sometimes additional explanation at the end. Default values and --longopts +are usually in parentheses on the end of an option's explanation line.

+ +

Toybox silently accepts a lot of compatibility flags like patch -u +that aren't in the help text to work with existing scripts, but may not +mention options that don't help write new scripts (mostly synonyms and NOPs).

+

Shared Libraries

Toybox's policy on shared libraries is that they should never be