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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Ghostscript PostScript coding guidelines</title>
<!-- $Id$ -->
<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style">
</head>
<body>
<!-- [1.0 begin visible header] ============================================ -->
<!-- [1.1 begin headline] ================================================== -->
<h1>Ghostscript PostScript coding guidelines</h1>
<!-- [1.1 end headline] ==================================================== -->
<!-- [1.2 begin table of contents] ========================================= -->
<h2>Table of contents</h2>
<blockquote><ul>
<li><a href="#Summary">Summary of the coding guidelines</a>
<li><a href="#Introduction">Introduction</a>
<li><a href="#PS_features">Use of PostScript language features</a>
<ul>
<li><a href="#Restrictions">Restrictions</a>
<li><a href="#Protection">Protection</a>
<li><a href="#Standard_constructions">Standard constructions</a>
</ul>
<li><a href="#File_structuring">File structuring</a>
<li><a href="#Commenting">Commenting</a>
<li><a href="#Formatting">Formatting</a>
<ul>
<li><a href="#Indentation">Indentation</a>
<li><a href="#Spaces">Spaces</a>
</ul>
<li><a href="#Naming">Naming</a>
<li><a href="#Miscellany">Miscellany</a>
<ul>
<li><a href="#Non_standard_operators">Some useful non-standard operators</a>
<li><a href="#Useful_procedures">Some useful procedures</a>
<li><a href="#Other">Other</a>
</ul>
</ul></blockquote>
<!-- [1.2 end table of contents] =========================================== -->
<!-- [1.3 begin hint] ====================================================== -->
<p>
For other information, see the <a href="Readme.htm">Ghostscript
overview</a>.
<!-- [1.3 end hint] ======================================================== -->
<hr>
<!-- [1.0 end visible header] ============================================== -->
<!-- [2.0 begin contents] ================================================== -->
<h2><a name="Summary"></a>Summary of the coding guidelines</h2>
<ul>
<li>Don't store into literals.
<li>Use <code>loop</code> to create a block with multiple exits.
<li>Use a dictionary or an array for multi-way switches.
<li>Start every file with a copyright notice, the file name, and a one-line
summary.
<li>Comment every procedure with the arguments and result, and with the
function of the procedure unless it's obvious.
<li>Comment the stack contents ad lib, and particularly at the beginning of
every loop body.
<li>Indent every 2 spaces.
<li>Always put { at the end of a line, and } at the beginning of a line,
unless the contents are very short.
<li>Always put spaces between adjacent tokens.
<li>Use only lower-case letters and digits for names, or Vienna style names,
except for an initial "." for names only used within a single file.
<li>Don't allocate objects in heavily used code.
<li>Consider factoring out code into a procedure if it is used more than
once.
</ul>
<hr>
<h2><a name="Introduction"></a>Introduction</h2>
<p>
The many rules that Ghostscript's code follows almost everywhere are meant
to produce code that is easy to read. It's important to observe them as
much as possible in order to maintain a consistent style, but if you find a
rule getting in your way or producing ugly-looking results once in a while,
it's OK to break it.
<hr>
<h2><a name="PS_features"></a>Use of PostScript language features</h2>
<h3><a name="Restrictions"></a>Restrictions</h3>
<p>
If you need to store a value temporarily, don't write into a literal in the
code, as in this fragment to show a character given the character code:
<blockquote><pre>
( ) dup 0 4 -1 roll put show
</pre></blockquote>
<p>
Instead, allocate storage for it:
<blockquote><pre>
1 string dup 0 4 -1 roll put show
</pre></blockquote>
<h3><a name="Protection"></a>Protection</h3>
<p>
If an object is never supposed to change, use <code>readonly</code> to
make it read-only. This applies especially to permanently allocated objects
such as constant strings or dictionaries.
<p>
During initialization, and occasionally afterwards, it may be necessary to
store into a read-only dictionary, or to store a pointer to a dictionary in
local VM into a dictionary in global VM. The operators
<code>.forceput</code> and <b><tt>.forceundef</tt></b> are available for
this purpose. To make these operators inaccessible to ordinary programs,
they are removed from <code>systemdict</code> at the end of
initialization: system code that uses them should always use
<code>bind</code> and <b><tt>odef</tt></b> (or
<code>executeonly</code>) to make uses of them inaccessible as well.
<h3><a name="Standard_constructions"></a>Standard constructions</h3>
<h4>Multi-way conditionals</h4>
<p>
If you write a block of code with more than about 3 exit points, the usual
way to do it would be like this:
<blockquote><pre>
{
... {
...1
} {
... {
...2
} {
... {
...3
} {
...4
} ifelse
} ifelse
} ifelse
}
</pre></blockquote>
<p>
However, this causes the 4 logically somewhat parallel code blocks to be
indented differently, and as the indentation increases, it becomes harder to
see the structure visually. As an alternative, you can do it this way:
<blockquote><pre>
{ % The loop doesn't actually loop: it just provides a common exit.
... {
...1
exit
} if
... {
...2
exit
} if
... {
...3
exit
} if
...4
exit
} loop
</pre></blockquote>
<p>
Don't forget the final exit, to prevent the loop from actually looping.
<h4>Switches</h4>
<p>
Use a dictionary or an array of procedures to implement a 'switch', rather
than a series of conditionals, if there are more than about 3 cases. For
example, rather than:
<blockquote><pre>
dup /a eq {
pop ...a
} {
dup /b eq {
pop ...b
} {
dup /c eq {
pop ...c
} {
...x
} ifelse
} ifelse
} ifelse
</pre></blockquote>
<p>
(or using the loop/exit construct suggested above), consider:
<blockquote><pre>
/xyzdict mark
/a {...a} bind
/b {...b} bind
/c {...c} bind
.dicttomark readonly def
...
//xyzdict 1 index .knownget {
exch pop exec
} {
...x
} ifelse
</pre></blockquote>
<hr>
<h2><a name="File_structuring"></a>File structuring</h2>
<p>
Every code file should start with comments containing
<ol>
<li>a copyright notice;
<li>the name of the file in the form of an RCS Id:
<blockquote><pre>
% Id$: filename.ps $
</pre></blockquote>
<li>a very brief summary (preferably only one line) of what the file
contains.
</ol>
<p>
If you create a file by copying the beginning of another file, be sure to
update the copyright year and change the file name.
<hr>
<h2><a name="Commenting"></a>Commenting</h2>
<p>
If a file has well-defined functional sections, put a comment at the
beginning of each section to describe its purpose or function.
<p>
Put a comment before every procedure to describe what the procedure does,
unless it's obvious or the procedure's function is defined by the PLRM. In
case of doubt, don't assume it's obvious. If the procedure may execute a
deliberate 'stop' or 'exit' not enclosed in 'stopped' or a loop
respectively, that should be mentioned. However, information about the
arguments and results should go in the argument and result comment
(described just below) if possible, not the functional comment.
<p>
Put a comment on every procedure to describe the arguments and results:
<blockquote><pre>
/hypot { % <num1> <num2> hypot <real>
dup mul exch dup mul add sqrt
} def
</pre></blockquote>
<p>
There is another commenting style that some people prefer to the above:
<blockquote><pre>
/hypot { % num1 num2 --> realnum
dup mul exch dup mul add sqrt
} def
</pre></blockquote>
<p>
We have adopted the first style for consistency with Adobe's documentation,
but we recognize that there are technical arguments for and against both
styles, and might consider switching some time in the future. If you have
strong feelings either way, please make your opinion known to
<code>gs-devel@ghostscript.com</code>.
<p>
Put comments describing the stack contents wherever you think they will be
helpful; put such a comment at the beginning of every loop body unless you
have a good reason not to.
<p>
When you change a piece of code, do <em>not</em> include a comment with your
name or initials. Also, do <em>not</em> retain the old code in a comment,
unless you consider it essential to explain something about the new code; in
that case, retain as little as possible. (CVS logs do both of these things
better than manual editing.) However, if you make major changes in a
procedure or a file, you may put your initials, the date, and a brief
comment at the head of the procedure or file respectively.
<hr>
<h2><a name="Formatting"></a>Formatting</h2>
<h3><a name="Indentation"></a>Indentation</h3>
<p>
Indent 2 spaces per indentation level. You may use tabs at the left margin
for indentation, with 1 tab = 8 spaces, but you should not use tabs anywhere
else, except to place comments.
<p>
Indent { } constructs like this:
<blockquote><pre>
... {
...
} {
...
} ...
</pre></blockquote>
<p>
If the body of a conditional or loop is no more than about 20 characters,
you can put the entire construct on a single line if you want:
<blockquote><pre>
... { ... } if
</pre></blockquote>
rather than
<blockquote><pre>
... {
...
} if
</pre></blockquote>
<p>
There is another indentation style that many people prefer to the above:
<blockquote><pre>
...
{ ...
}
{ ...
} ...
</pre></blockquote>
<p>
We have adopted the first style for consistency with our C code, but we
recognize that there are technical arguments for and against both styles,
and might consider switching some time in the future. If you have strong
feelings either way, please make your opinion known to
<code>gs-devel@ghostscript.com</code>.
<h3><a name="Spaces"></a>Spaces</h3>
<p>
Always put spaces between two adjacent tokens, even if this isn't strictly
required. E.g.,
<blockquote><pre>
/Halftone /Category findresource
</pre></blockquote>
<p>
not
<blockquote><pre>
/Halftone/Category findresource
</pre></blockquote>
<hr>
<h2><a name="Naming"></a>Naming</h2>
<p>
All names should consist only of letters and digits, possibly with an
initial ".", except for names drawn from the PostScript or PDF reference
manual, which must be capitalized as in the manual. In general, an initial
"." should be used for those and only those names that are not defined in a
private dictionary but that are meant to be used only in the file where they
are defined.
<p>
For edits to existing code, names made up of multiple words should not use
any punctuation, or capitalization, to separate the words, again except for
names that must match a specification. For new code, you may use this
convention, or you may use the "Vienna" convention of capitalizing the first
letter of words, e.g., <code>readSubrs</code> rather than
<code>readsubrs</code>. If you use the Vienna convention, function names
should start with an upper case letter, variable names with a lower case
letter. Using the first letter of a variable name to indicate the
variable's type is optional, but if you do it, you should follow existing
codified usage (****** WE NEED A REFERENCE FOR THIS ******).
<hr>
<h2><a name="Miscellany"></a>Miscellany</h2>
<h3><a name="Non_standard_operators"></a>Some useful non-standard
operators</h3>
<dl>
<dt><code><obj1> <obj2> ... <objn> <n> .execn ...</code>
<dd>This executes <code>obj1</code> through <b><tt>objn</tt></b> in that
order, essentially equivalent to
<blockquote><pre>
<obj1> <obj2> ... <objn> <n> array astore {exec} forall
</pre></blockquote>
<p>
except that it doesn't actually create the array.
<dt><code><dict> <key> <b>.knownget</b> <value> true</code>
<dt><code><dict> <key> <b>.knownget</b> false</code>
<dd>This combines <code>known</code> and <b><tt>get</tt></b> in the
obvious way.
<dt><code><name> <proc> odef -</code>
<dd>This defines <code>name</code> as a "pseudo-operator". The value of
<code>name</code> will be executable, will have type
<code>operatortype</code>, and will be executed if it appears directly in
the body of a procedure (like an operator, unlike a procedure), but what
will actually be executed will be <code>proc</code>. In addition, if the
execution of <code>proc</code> is ended prematurely (by
<code>stop</code>, including the <b><tt>stop</tt></b> that is normally
executed when an error occurs, or <code>exit</code>) and the operand and
dictionary stacks are at least as deep as they were when the "operator" was
invoked, the stacks will be cut back to their original depths before the
error is processed. Thus, if pseudo-operator procedures are careful not to
remove any of their operands until they reach a point in execution beyond
which they cannot possibly cause an error, they will behave just like
operators in that the stacks will appear to be unchanged if an error occurs.
</dl>
<h3><a name="Useful_procedures"></a>Some useful procedures</h3>
<dl>
<dt><code><object> <errorname> signalerror -</code>
<dd>Signal an error with the given name and the given "current object".
This does exactly what the interpreter does when an error occurs.
</dl>
<h3><a name="Other"></a>Other</h3>
<p>
If you can avoid it, don't allocate objects (strings, arrays, dictionaries,
gstates, etc.) in commonly used operators or procedures: these will need to
be garbage collected later, slowing down execution. Instead, keep values on
the stack, if you can. The <code>.execn</code> operator discussed above
may be helpful in doing this.
<p>
If you find yourself writing the same stretch of code (more than about half
a dozen tokens) more than once, ask yourself whether it performs a function
that could be made into a procedure.
<!-- [2.0 end contents] ==================================================== -->
<!-- [3.0 begin visible trailer] =========================================== -->
<hr>
<p>
<small>Copyright © 2000-2006 Artifex Software, Inc. All rights reserved.</small>
<p>
This software is provided AS-IS with no warranty, either express or
implied.
This software is distributed under license and may not be copied, modified
or distributed except as expressly authorized under the terms of that
license. Refer to licensing information at http://www.artifex.com/
or contact Artifex Software, Inc., 7 Mt. Lassen Drive - Suite A-134,
San Rafael, CA 94903, U.S.A., +1(415)492-9861, for further information.
<p>
<small>Ghostscript version 9.01, 7 February 2011
<!-- [3.0 end visible trailer] ============================================= -->
</body>
</html>
|
