diff options
-rw-r--r-- | Util/completion-style-guide | 44 | ||||
-rw-r--r-- | Util/zsh-development-guide | 138 |
2 files changed, 0 insertions, 182 deletions
diff --git a/Util/completion-style-guide b/Util/completion-style-guide deleted file mode 100644 index 307954760..000000000 --- a/Util/completion-style-guide +++ /dev/null @@ -1,44 +0,0 @@ -For now this is just a list of things one should or shouldn't do. - -1) Use the functions `_files' and `_path_files' instead of `compgen' - with the `-f', `-/', or `-g' options. -2) *Never* use `compgen' with the `-s' option. This can always be done - by a call to `compadd' which is faster. -3) Using `compgen' with the `-k' option should only be done if a) the - array is already existent or b) it is very large (several hundred - or thousend elements). In other cases using `compadd' is faster. -4) Supply match specifications to `compadd' and `compgen' if there are - sensible ones. -5) Use `_description' when adding matches with `compadd' or - `compgen'. Use `_message' in places where no matches can be - generated. If you want to add different types of matches, add them - with multiple calls to `compadd' or `compgen', supplying different - descriptions. -6) Use helper functions that do option completion for you (like - `_arguments' and `_long_options') -- it will make your life much - easier. -7) Use helper functions like `_users' and `_groups' instead of direct - calls to `compgen -u' or some ad hoc mechanisms to generate such - information. This ensures that user can change the way these things - will be completed everywhere by just using their own implementations - for these functions. -8) Make sure that the return value of your functions is correct: zero - if matches where added and non-zero if no matches were found. - In some cases you'll need to test the value of `$compstate[nmatches]' - for this. This should always be done by first saving the old value - (`local nm="$compstate[nmatches]"') and later comparing this with - the current value after all matches have been added (e.g. by - writing `[[ nmm -ne compstate[nmatches] ]]' at the end of your - function). This guarantees that your functions will be re-usable - because calling functions may rely on the correct return value. -9) In places where different behaviors may be useful, add a - configuration key to allow users to select the behavior they - prefer. Names for configuration keys should look like `prefix_name', - where `prefix' is the (probably abbreviated) name of your function - and `name' describes what can be configured. - When testing the values of configuration keys, the empty string - should result in the same behavior as if the key were unset. This - can be achieved by the test `[[ -n "$compconfig[prefix_name]" ]]'. -10) When writing helper functions that generate matches, the arguments - of these should be given unchanged to `compadd' or `compgen' (if - they are not used by the helper function itself). diff --git a/Util/zsh-development-guide b/Util/zsh-development-guide deleted file mode 100644 index d574d8af0..000000000 --- a/Util/zsh-development-guide +++ /dev/null @@ -1,138 +0,0 @@ ------------------------------- -GUIDELINES FOR ZSH DEVELOPMENT ------------------------------- - -Zsh is currently developed and maintained by the Zsh Development Group. -This development takes place by mailing list. Check the META-FAQ for the -various zsh mailing lists and how to subscribe to them. The development -is very open and anyone is welcomed and encouraged to join and contribute. -Because zsh is a very large package whose development can sometimes -be very rapid, I kindly ask that people observe a few guidelines when -contributing patches and feedback to the mailing list. These guidelines -are very simple and hopefully should make for a more orderly development -of zsh. - -Patches -------- - -* Send all patches to the mailing list rather than directly to me. - -* Send only context diffs "diff -c oldfile newfile". They are much - easier to read and understand while also allowing the patch program - to patch more intelligently. Please make sure the filenames in - the diff header are relative to the top-level directory of the zsh - distribution; for example, it should say "Src/init.c" rather than - "init.c" or "zsh/Src/init.c". - -* Please put only one bug fix or feature enhancement in a single patch and - only one patch per mail message. This helps me to multiplex the many - (possibly conflicting) patches that I receive for zsh. You shouldn't - needlessly split patches, but send them in the smallest LOGICAL unit. - -* If a patch depends on other patches, then please say so. Also please - mention what version of zsh this patch is for. - -* Please test your patch and make sure it applies cleanly. It takes - considerably more time to manually merge a patch into the baseline code. - -* There is now a zsh patch archive. To have your patches appear in the - archive, send them to the mailing list with a Subject: line starting - with "PATCH:". - -C coding style --------------- - -* The primary language is ANSI C as defined by the 1989 standard, but the - code should always be compatible with late K&R era compilers ("The C - Programming Language" 1st edition, plus "void" and "enum"). There are - many hacks to avoid the need to actually restrict the code to K&R C -- - check out the configure tests -- but always bear the compatibility - requirements in mind. In particular, preprocessing directives must - have the "#" unindented, and string pasting is not available. - -* Conversely, there are preprocessor macros to provide safe access to some - language features not present in pure ANSI C, such as variable-length - arrays. Always use the macros if you want to use these facilities. - -* Avoid writing code that generates warnings under gcc with the default - options set by the configure script. For example, write - "if ((foo = bar))" rather than "if (foo = bar)". - -* Please try not using lines longer than 79 characters. - -* The indent/brace style is Kernighan and Ritchie with 4 characters - indentations (with leading tab characters replacing sequences of - 8 spaces). This means that the opening brace is the last character - in the line of the if/while/for/do statement and the closing brace - has its own line: - - if (foo) { - do that - } - -* Put only one simple statement on a line. The body of an if/while/for/do - statement has its own line with 4 characters indentation even if there - are no braces. - -* Do not use space between the function name and the opening parenthesis. - Use space after if/for/while. Use space after type casts. - -* Do not use (unsigned char) casts since some compilers do not handle - them properly. Use the provided STOUC(X) macro instead. - -* If you use emacs 19.30 or newer you can put the following line to your - ~/.emacs file to make these formatting rules the default: - - (add-hook 'c-mode-common-hook (function (lambda () (c-set-style "BSD")))) - -* Function declarations must look like this: - - /**/ - int - foo(char *s, char **p) - { - function body - } - - There must be an empty line, a line with "/**/", a line with the - type of the function, and finally the name of the function with typed - arguments. These lines must not be indented. The script generating - function prototypes and the ansi2knr program depend on this format. - If the function is not used outside the file it is defined in, it - should be declared "static"; this keyword goes on the type line, - before the return type. - -* Global variable declarations must similarly be preceded by a - line containing only "/**/", for the prototype generation script. - The declaration itself should be all on one line (except for multi-line - initialisers). - -* Leave a blank line between the declarations and statements in a compound - statement, if both are present. Use blank lines elsewhere to separate - groups of statements in the interests of clarity. There should never - be two consecutive blank lines. - -Documentation -------------- - -* Edit only the .yo files. All other formats (man pages, TeXinfo, HTML, - etc.) are automatically generated from the yodl source. - -* Always use the correct markup. em() is used for emphasis, and bf() - for citations. tt() marks text that is literal input to or output - from the shell. var() marks metasyntactic variables. - -* In addition to appropriate markup, always use quotes (`') where - appropriate. Specifically, use quotes to mark text that is not a part - of the actual text of the documentation (i.e., that it is being quoted). - In principle, all combinations of quotes and markup are possible, - because the purposes of the two devices are completely orthogonal. - For example, - - Type `tt(xyzzy)' to let zsh know you have played tt(advent). - Saying `plugh' aloud doesn't have much effect, however. - - In this case, "zsh" is normal text (a name), "advent" is a command name - ocurring in the main text, "plugh" is a normal word that is being quoted - (it's the user that says `plugh', not the documentation), and "xyzzy" - is some text to be typed literally that is being quoted. |