1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
------------------------------
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.
|
