Load cups into easysw/current.
[thirdparty/cups.git] / doc / cmp.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
2 <HTML>
3 <HEAD>
4 <TITLE>CUPS Configuration Management Plan</TITLE>
5 <META NAME="author" CONTENT="Easy Software Products">
6 <META NAME="copyright" CONTENT="Copyright 1997-2005, All Rights Reserved">
7 <META NAME="docnumber" CONTENT="CUPS-CMP-1.1">
8 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-8859-1">
9 <STYLE TYPE="text/css"><!--
10 BODY { font-family: serif }
11 H1 { font-family: sans-serif }
12 H2 { font-family: sans-serif }
13 H3 { font-family: sans-serif }
14 H4 { font-family: sans-serif }
15 H5 { font-family: sans-serif }
16 H6 { font-family: sans-serif }
17 SUB { font-size: smaller }
18 SUP { font-size: smaller }
19 PRE { font-family: monospace }
20 --></STYLE>
21 </HEAD>
22 <BODY BGCOLOR="white">
23 <CENTER><A HREF="#CONTENTS"><IMG SRC="images/cups-large.gif" BORDER="0" WIDTH="431" HEIGHT="511" ALT="CUPS Configuration Management Plan"><BR>
24 <H1>CUPS Configuration Management Plan</H1></A><BR>
25 CUPS-CMP-1.1<BR>
26 Easy Software Products<BR>
27 Copyright 1997-2005, All Rights Reserved<BR>
28 </CENTER>
29 <HR NOSHADE>
30 <H1 ALIGN="CENTER"><A NAME="CONTENTS">Table of Contents</A></H1>
31 <BR>
32 <BR><B><A HREF="#1">1 Scope</A></B>
33 <UL>
34 <LI><A HREF="#1_1">1.1 Identification</A></LI>
35 <LI><A HREF="#1_2">1.2 System Overview</A></LI>
36 <LI><A HREF="#1_3">1.3 Document Overview</A></LI>
37 </UL>
38 <B><A HREF="#2">2 References</A></B>
39 <UL>
40 <LI><A HREF="#2_1">2.1 CUPS Documentation</A></LI>
41 <LI><A HREF="#2_2">2.2 Other Documents</A></LI>
42 </UL>
43 <B><A HREF="#3">3 File Management</A></B>
44 <UL>
45 <LI><A HREF="#3_1">3.1 Directory Structure</A></LI>
46 <LI><A HREF="#3_2">3.2 Source Files</A></LI>
47 <LI><A HREF="#3_3">3.3 Configuration Management</A></LI>
48 </UL>
49 <B><A HREF="#4">4 Trouble Report Processing</A></B>
50 <UL>
51 <LI><A HREF="#4_1">4.1 Classification</A></LI>
52 <LI><A HREF="#4_2">4.2 Identification</A></LI>
53 <LI><A HREF="#4_3">4.3 Correction</A></LI>
54 <LI><A HREF="#4_4">4.4 Notification</A></LI>
55 </UL>
56 <B><A HREF="#5">5 Software Releases</A></B>
57 <UL>
58 <LI><A HREF="#5_1">5.1 Version Numbering</A></LI>
59 <LI><A HREF="#5_2">5.2 Generation</A></LI>
60 <LI><A HREF="#5_3">5.3 Testing</A></LI>
61 <LI><A HREF="#5_4">5.4 Releases</A>
62 <UL>
63 <LI><A HREF="#5_4_1">5.4.1 Beta Releases</A></LI>
64 <LI><A HREF="#5_4_2">5.4.2 Release Candidates</A></LI>
65 <LI><A HREF="#5_4_3">5.4.3 Production Releases</A></LI>
66 </UL>
67 </LI>
68 </UL>
69 <B><A HREF="#6">A Glossary</A></B>
70 <UL>
71 <LI><A HREF="#6_1">A.1 Terms</A></LI>
72 <LI><A HREF="#6_2">A.2 Acronyms</A></LI>
73 </UL>
74 <B><A HREF="#7">B Coding Requirements</A></B>
75 <UL>
76 <LI><A HREF="#7_1">B.1 Source Files</A>
77 <UL>
78 <LI><A HREF="#7_1_1">B.1.1 Naming</A></LI>
79 <LI><A HREF="#7_1_2">B.1.2 Documentation</A></LI>
80 </UL>
81 </LI>
82 <LI><A HREF="#7_2">B.2 Functions</A>
83 <UL>
84 <LI><A HREF="#7_2_1">B.2.1 Naming</A></LI>
85 <LI><A HREF="#7_2_2">B.2.2 Documentation</A></LI>
86 </UL>
87 </LI>
88 <LI><A HREF="#7_3">B.3 Methods</A>
89 <UL>
90 <LI><A HREF="#7_3_1">B.3.1 Naming</A></LI>
91 <LI><A HREF="#7_3_2">B.3.2 Documentation</A></LI>
92 </UL>
93 </LI>
94 <LI><A HREF="#7_4">B.4 Variables</A>
95 <UL>
96 <LI><A HREF="#7_4_1">B.4.1 Naming</A></LI>
97 <LI><A HREF="#7_4_2">B.4.2 Documentation</A></LI>
98 </UL>
99 </LI>
100 <LI><A HREF="#7_5">B.5 Types</A>
101 <UL>
102 <LI><A HREF="#7_5_1">B.5.1 Naming</A></LI>
103 <LI><A HREF="#7_5_2">B.5.2 Documentation</A></LI>
104 </UL>
105 </LI>
106 <LI><A HREF="#7_6">B.6 Structures</A>
107 <UL>
108 <LI><A HREF="#7_6_1">B.6.1 Naming</A></LI>
109 <LI><A HREF="#7_6_2">B.6.2 Documentation</A></LI>
110 </UL>
111 </LI>
112 <LI><A HREF="#7_7">B.7 Classes</A>
113 <UL>
114 <LI><A HREF="#7_7_1">B.7.1 Naming</A></LI>
115 <LI><A HREF="#7_7_2">B.7.2 Documentation</A></LI>
116 </UL>
117 </LI>
118 <LI><A HREF="#7_8">B.8 Constants</A>
119 <UL>
120 <LI><A HREF="#7_8_1">B.8.1 Naming</A></LI>
121 <LI><A HREF="#7_8_2">B.8.2 Documentation</A></LI>
122 </UL>
123 </LI>
124 <LI><A HREF="#7_9">B.9 Code</A>
125 <UL>
126 <LI><A HREF="#7_9_1">B.9.1 Documentation</A></LI>
127 <LI><A HREF="#7_9_2">B.9.2 Style</A></LI>
128 </UL>
129 </LI>
130 </UL>
131 <B><A HREF="#8">C Software Trouble Report Form</A></B><HR NOSHADE>
132 <H1><A NAME="1">1 Scope</A></H1>
133 <H2><A NAME="1_1">1.1 Identification</A></H2>
134 <P>This configuration management plan document provides the guidelines
135  for development and maintenance of the Common UNIX Printing System
136  (&quot;CUPS&quot;) Version 1.1 software.</P>
137 <H2><A NAME="1_2">1.2 System Overview</A></H2>
138 <P>CUPS provides a portable printing layer for UNIX&reg;-based operating
139  systems. It has been developed by <A HREF="http://www.easysw.com">Easy
140  Software Products</A> to promote a standard printing solution for all
141  UNIX vendors and users. CUPS provides the System V and Berkeley
142  command-line interfaces.</P>
143 <P>CUPS uses the Internet Printing Protocol (&quot;IPP&quot;) as the basis for
144  managing print jobs and queues. The Line Printer Daemon (&quot;LPD&quot;) Server
145  Message Block (&quot;SMB&quot;), and AppSocket (a.k.a. JetDirect) protocols are
146  also supported with reduced functionality. CUPS adds network printer
147  browsing and PostScript Printer Description (&quot;PPD&quot;) based printing
148  options to support real-world printing under UNIX.</P>
149 <P>CUPS includes an image file RIP that supports printing of image files
150  to non-PostScript printers. A customized version of GNU Ghostscript
151  7.05 for CUPS called ESP Ghostscript is available separately to support
152  printing of PostScript files within the CUPS driver framework. Sample
153  drivers for Dymo, EPSON, HP, and OKIDATA printers are included that use
154  these filters.</P>
155 <P>Drivers for thousands of printers are provided with our ESP Print Pro
156  software, available at:</P>
157 <PRE>
158     <A HREF="http://www.easysw.com/printpro/">http://www.easysw.com/printpro/</A>
159 </PRE>
160 <P>CUPS is licensed under the GNU General Public License and GNU Library
161  General Public License. Please contact Easy Software Products for
162  commercial support and &quot;binary distribution&quot; rights.</P>
163 <H2><A NAME="1_3">1.3 Document Overview</A></H2>
164 <P>This configuration management document is organized into the
165  following sections:</P>
166 <UL>
167 <LI>1 - Scope</LI>
168 <LI>2 - References</LI>
169 <LI>3 - File Management</LI>
170 <LI>4 - Trouble Report Processing</LI>
171 <LI>5 - Software Releases</LI>
172 <LI>A - Glossary</LI>
173 <LI>B - Coding Requirements</LI>
174 </UL>
175 <H1><A NAME="2">2 References</A></H1>
176 <H2><A NAME="2_1">2.1 CUPS Documentation</A></H2>
177 <P>The following CUPS documentation is referenced by this document:</P>
178 <UL>
179 <LI>CUPS-CMP-1.1: CUPS Configuration Management Plan</LI>
180 <LI>CUPS-IDD-1.1: CUPS System Interface Design Description</LI>
181 <LI>CUPS-IPP-1.1: CUPS Implementation of IPP</LI>
182 <LI>CUPS-SAM-1.1.x: CUPS Software Administrators Manual</LI>
183 <LI>CUPS-SDD-1.1: CUPS Software Design Description</LI>
184 <LI>CUPS-SPM-1.1.x: CUPS Software Programming Manual</LI>
185 <LI>CUPS-SSR-1.1: CUPS Software Security Report</LI>
186 <LI>CUPS-STP-1.1: CUPS Software Test Plan</LI>
187 <LI>CUPS-SUM-1.1.x: CUPS Software Users Manual</LI>
188 <LI>CUPS-SVD-1.1: CUPS Software Version Description</LI>
189 </UL>
190 <H2><A NAME="2_2">2.2 Other Documents</A></H2>
191 <P>The following non-CUPS documents are referenced by this document:</P>
192 <UL>
193 <LI><A HREF="http://partners.adobe.com/asn/developer/PDFS/TN/5003.PPD_Spec_v4.3.pdf">
194 Adobe PostScript Printer Description File Format Specification, Version
195  4.3.</A></LI>
196 <LI><A HREF="http://partners.adobe.com/asn/developer/PDFS/TN/PLRM.pdf">
197 Adobe PostScript Language Reference, Third Edition.</A></LI>
198 <LI>IPP/1.1: Implementers Guide</LI>
199 <LI><A HREF="http://www.ietf.org/rfc/rfc1179.txt">RFC 1179, Line Printer
200  Daemon Protocol</A></LI>
201 <LI><A HREF="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396, Uniform
202  Resource Identifiers (URI): Generic Syntax</A></LI>
203 <LI><A HREF="http://www.ietf.org/rfc/rfc2567.txt">RFC 2567, Design Goals
204  for an Internet Printing Protocol</A></LI>
205 <LI><A HREF="http://www.ietf.org/rfc/rfc2568.txt">RFC 2568, Rationale
206  for the Structure of the Model and Protocol for the Internet Printing
207  Protocol</A></LI>
208 <LI><A HREF="http://www.ietf.org/rfc/rfc2569.txt">RFC 2569, Mapping
209  between LPD and IPP Protocols</A></LI>
210 <LI><A HREF="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616, Hypertext
211  Transfer Protocol -- HTTP/1.1</A></LI>
212 <LI><A HREF="http://www.ietf.org/rfc/rfc2617.txt">RFC 2617, HTTP
213  Authentication: Basic and Digest Access</A> Authentication</LI>
214 <LI><A HREF="http://www.ietf.org/rfc/rfc2910.txt">RFC 2910, IPP/1.1:
215  Encoding and Transport</A></LI>
216 <LI><A HREF="http://www.ietf.org/rfc/rfc2911.txt">RFC 2911, IPP/1.1:
217  Model and Semantics</A></LI>
218 <LI><A HREF="http://www.ietf.org/rfc/rfc3380.txt">RFC 3380, IPP: Job and
219  Printer Set Operations</A></LI>
220 </UL>
221 <H1><A NAME="3">3 File Management</A></H1>
222 <H2><A NAME="3_1">3.1 Directory Structure</A></H2>
223 <P>Each source file shall be placed a sub-directory corresponding to the
224  software sub-system it belongs to (&quot;scheduler&quot;, &quot;cups&quot;, etc.) To remain
225  compatible with older UNIX filesystems, directory names shall not
226  exceed 16 characters in length.</P>
227 <H2><A NAME="3_2">3.2 Source Files</A></H2>
228 <P>Source files shall be documented and formatted as described in
229  Appendix B, Coding Requirements. To remain compatible with older UNIX
230  filesystems, source file names shall not exceed 16 characters in
231  length.</P>
232 <H2><A NAME="3_3">3.3 Configuration Management</A></H2>
233 <P>Source files shall be placed under the control of the Concurrent
234  Versions System (&quot;CVS&quot;) software. Source files shall be &quot;checked in&quot;
235  with each change so that modifications can be tracked.</P>
236 <P>Documentation on the CVS software is included with the whitepaper,
237  &quot;CVS II: Parallelizing Software Development&quot;.</P>
238 <H1><A NAME="4">4 Trouble Report Processing</A></H1>
239 <P>A Software Trouble Report (&quot;STR&quot;) shall be submitted every time a
240  user or vendor experiences a problem with the CUPS software. Trouble
241  reports are maintained in a database with one of the following states:</P>
242 <OL>
243 <LI>STR is closed with complete resolution</LI>
244 <LI>STR is closed without resolution</LI>
245 <LI>STR is active</LI>
246 <LI>STR is pending (new STR or additional information available)</LI>
247 </OL>
248 <P>Trouble reports shall be processed using the following steps.</P>
249 <H2><A NAME="4_1">4.1 Classification</A></H2>
250 <P>When a trouble report is received it must be classified at one of the
251  following priority levels:</P>
252 <OL>
253 <LI>Request for enhancement, e.g. asking for a feature</LI>
254 <LI>Low, e.g. a documentation error or undocumented side-effect</LI>
255 <LI>Moderate, e.g. unable to print a file or unable to compile the
256  software</LI>
257 <LI>High, e.g. unable to print to a printer or key functionality not
258  working</LI>
259 <LI>Critical, e.g. unable to print at all</LI>
260 </OL>
261 <P>Level 4 and 5 trouble reports must be resolved in the next software
262  release. Level 1 to 3 trouble reports are scheduled for resolution in a
263  specific release at the discretion of the release coordinator.</P>
264 <P>The scope of the problem should also be determined as:</P>
265 <OL>
266 <LI>Specific to a machine or printer</LI>
267 <LI>Specific to an operating system</LI>
268 <LI>Applies to all machines, printers, and operating systems</LI>
269 </OL>
270 <H2><A NAME="4_2">4.2 Identification</A></H2>
271 <P>Once the level and scope of the trouble report is determined the
272  software sub-system(s) involved with the problem are determined. This
273  may involve additional communication with the user or vendor to isolate
274  the problem to a specific cause.</P>
275 <P>When the sub-system(s) involved have been identified, an engineer
276  will then determine the change(s) needed and estimate the time required
277  for the change(s).</P>
278 <H2><A NAME="4_3">4.3 Correction</A></H2>
279 <P>Corrections are scheduled based upon the severity and complexity of
280  the problem. Once all changes have been made, documented, and tested
281  successfully a new software release snapshot is generated. Additional
282  tests are added as necessary for proper testing of the changes.</P>
283 <H2><A NAME="4_4">4.4 Notification</A></H2>
284 <P>The user or vendor is notified when the fix is available or if the
285  problem was caused by user error.</P>
286 <H1><A NAME="5">5 Software Releases</A></H1>
287 <H2><A NAME="5_1">5.1 Version Numbering</A></H2>
288 <P>CUPS uses a three-part version number separated by periods to
289  represent the major, minor, and patch release numbers:</P>
290 <PRE>
291     MAJOR.MINOR.PATCH
292     1.1.0
293 </PRE>
294 <P>Beta-test releases are indentified by appending the letter B followed
295  by the build number:</P>
296 <PRE>
297     MAJOR.MINOR.PATCHbBUILD
298     1.1.0b1
299 </PRE>
300 <P>Release candidates are indentified by appending the letters RC
301  followed by the build number:</P>
302 <PRE>
303     MAJOR.MINOR.PATCHrcBUILD
304     1.1.0rc1
305 </PRE>
306 <P>A CVS snapshot is generated for every beta and final release and uses
307  the version number preceded by the letter &quot;v&quot; and with the decimal
308  points replaced by underscores:</P>
309 <PRE>
310     v1_1_0b1
311     v1_1_0rc1
312     v1_1_0
313 </PRE>
314 <P>Each change that corrects a fault in a software sub-system increments
315  the patch release number. If a change affects the overall software
316  design of CUPS then the minor release number will be incremented and
317  the patch release number reset to 0. If CUPS is completely redesigned
318  the major release number will be incremented and the minor and patch
319  release numbers reset to 0:</P>
320 <PRE>
321     1.1.0b1    First beta release
322     1.1.0b2    Second beta release
323     1.1.0rc1   First release candidate
324     1.1.0rc2   Second release candidate
325     1.1.0      First production release
326     1.1.1b1    First beta of 1.1.1
327     1.1.1rc1   First release candidate of 1.1.1
328     1.1.1      Production release of 1.1.1
329     1.1.2b1    First beta of 1.1.2
330     1.1.2rc1   First release candidate of 1.1.2
331     1.1.2      Production release of 1.1.2
332     2.0.0b1    First beta of 2.0.0
333     2.0.0rc1   First release candidate of 2.0.0
334     2.0.0      Production release of 2.0.0
335 </PRE>
336 <H2><A NAME="5_2">5.2 Generation</A></H2>
337 <P>Software releases shall be generated for each successfully completed
338  software trouble report. All object and executable files shall be
339  deleted prior to performing a full build to ensure that source files
340  are recompiled.</P>
341 <H2><A NAME="5_3">5.3 Testing</A></H2>
342 <P>Software testing shall be conducted according to the CUPS Software
343  Test Plan, CUPS-STP-1.1. Failed tests cause STRs to be generated to
344  correct the problems found.</P>
345 <H2><A NAME="5_4">5.4 Releases</A></H2>
346 <P>When testing has been completed successfully a new distribution image
347  is created from the current CVS code &quot;snapshot&quot;. No release shall
348  contain software that has not passed the appropriate software tests.
349  Three types of releases are used, beta, release candidate, and
350  production, and are released using the following basic schedule:
351 <CENTER>
352 <TABLE BORDER="1">
353 <TR><TH>Week</TH><TH>Version</TH><TH>Description</TH></TR>
354 <TR><TD>T-6 weeks</TD><TD>1.1.0b1</TD><TD>First beta</TD></TR>
355 <TR><TD>T-5 weeks</TD><TD>1.1.0b2</TD><TD>Second beta</TD></TR>
356 <TR><TD>T-4 weeks</TD><TD>1.1.0b3</TD><TD>Third beta</TD></TR>
357 <TR><TD>T-3 weeks</TD><TD>1.1.0rc1</TD><TD>First release candidate</TD></TR>
358 <TR><TD>T-2 weeks</TD><TD>1.1.0rc2</TD><TD>Second release candidate</TD></TR>
359 <TR><TD>T-0 weeks</TD><TD>1.1.0</TD><TD>Production</TD></TR>
360 </TABLE>
361 </CENTER>
362 </P>
363 <P>Beta releases are typically used prior to new major and minor version
364  releases. At least one release candidate is generated prior to each
365  production release.</P>
366 <H3><A NAME="5_4_1">5.4.1 Beta Releases</A></H3>
367 <P>Beta releases are generated when substantial changes have been made
368  that may affect the reliability of the software. Beta releases may
369  cause loss of data, functionality, or services and are provided for
370  testing by qualified individuals.</P>
371 <P>Beta releases are an OPTIONAL part of the release process and are
372  generated as deemed appropriate by the release coordinator. Functional
373  changes may be included in subsequent beta releases until the first
374  release candidate.</P>
375 <H3><A NAME="5_4_2">5.4.2 Release Candidates</A></H3>
376 <P>Release candidates are generated at least two weeks prior to a
377  production release. Release candidates are targeted for end-users that
378  wish to test new functionality or bug fixes prior to the production
379  release. While release candidates are intended to be substantially
380  bug-free, they may still contain defects and/or not compile on specific
381  platforms.</P>
382 <P>At least one release candidate is REQUIRED prior to any production
383  release. The distribution of a release candidate marks the end of any
384  functional improvements. Release candidates are generated at weekly
385  intervals until all level 4/5 trouble reports are resolved.</P>
386 <H3><A NAME="5_4_3">5.4.3 Production Releases</A></H3>
387 <P>Production releases are generated after a successful release
388  candidate and represent a stable release of the software suitable for
389  all users.</P>
390 <H1 TYPE="A" VALUE="1"><A NAME="6">A Glossary</A></H1>
391 <H2><A NAME="6_1">A.1 Terms</A></H2>
392 <DL>
393 <DT>C</DT>
394 <DD>A computer language.</DD>
395 <DT>parallel</DT>
396 <DD>Sending or receiving data more than 1 bit at a time.</DD>
397 <DT>pipe</DT>
398 <DD>A one-way communications channel between two programs.</DD>
399 <DT>serial</DT>
400 <DD>Sending or receiving data 1 bit at a time.</DD>
401 <DT>socket</DT>
402 <DD>A two-way network communications channel.</DD>
403 </DL>
404 <H2><A NAME="6_2">A.2 Acronyms</A></H2>
405 <DL>
406 <DT>ASCII</DT>
407 <DD>American Standard Code for Information Interchange</DD>
408 <DT>CUPS</DT>
409 <DD>Common UNIX Printing System</DD>
410 <DT>ESC/P</DT>
411 <DD>EPSON Standard Code for Printers</DD>
412 <DT>FTP</DT>
413 <DD>File Transfer Protocol</DD>
414 <DT>HP-GL</DT>
415 <DD>Hewlett-Packard Graphics Language</DD>
416 <DT>HP-PCL</DT>
417 <DD>Hewlett-Packard Page Control Language</DD>
418 <DT>HP-PJL</DT>
419 <DD>Hewlett-Packard Printer Job Language</DD>
420 <DT>IETF</DT>
421 <DD>Internet Engineering Task Force</DD>
422 <DT>IPP</DT>
423 <DD>Internet Printing Protocol</DD>
424 <DT>ISO</DT>
425 <DD>International Standards Organization</DD>
426 <DT>LPD</DT>
427 <DD>Line Printer Daemon</DD>
428 <DT>MIME</DT>
429 <DD>Multimedia Internet Mail Exchange</DD>
430 <DT>PPD</DT>
431 <DD>PostScript Printer Description</DD>
432 <DT>SMB</DT>
433 <DD>Server Message Block</DD>
434 <DT>TFTP</DT>
435 <DD>Trivial File Transfer Protocol</DD>
436 </DL>
437 <H1><A NAME="7">B Coding Requirements</A></H1>
438 <P>These coding requirements provide detailed information on source file
439  formatting and documentation content. These guidelines shall be applied
440  to all C and C++ source files provided with CUPS. Source code for other
441  languages should conform to these requirements as allowed by the
442  language.</P>
443 <H2><A NAME="7_1">B.1 Source Files</A></H2>
444 <H3><A NAME="7_1_1">B.1.1 Naming</A></H3>
445 <P>All source files names shall be 16 characters or less in length to
446  ensure compatibility with older UNIX filesystems. Source files
447  containing functions shall have an extension of &quot;.c&quot; for ANSI C and
448  &quot;.cxx&quot; for C++ source files. All other &quot;include&quot; files shall have an
449  extension of &quot;.h&quot;.</P>
450 <H3><A NAME="7_1_2">B.1.2 Documentation</A></H3>
451 <P>The top of each source file shall contain a header giving the name of
452  the file, the purpose or nature of the source file, the copyright and
453  licensing notice, and the functions contained in the file. The file
454  name and revision information is provided by the CVS &quot;$Id$&quot; tag:</P>
455 <PRE>
456     /*
457      * &quot;$Id$&quot;
458      *
459      *   Description of file contents.
460      *
461      *   Copyright 1997-2005 by Easy Software Products, all rights
462      *   reserved.
463      *
464      *   These coded instructions, statements, and computer programs are
465      *   the property of Easy Software Products and are protected by
466      *   Federal copyright law.  Distribution and use rights are outlined
467      *   in the file &quot;LICENSE.txt&quot; which should have been included with
468      *   this file.  If this file is missing or damaged please contact
469      *   Easy Software Products at:
470      *
471      *       Attn: CUPS Licensing Information
472      *       Easy Software Products
473      *       44141 Airport View Drive, Suite 204
474      *       Hollywood, Maryland 20636 USA
475      *
476      *       Voice: (301) 373-9600
477      *       EMail: cups-info@cups.org
478      *         WWW: http://www.cups.org
479      *
480      * Contents:
481      *
482      *   function1() - Description 1.
483      *   function2() - Description 2.
484      *   function3() - Description 3.
485      */
486 </PRE>
487
488 <!-- NEED 1in -->
489 <P>For source files that are subject to the Apple OS-Developed Software
490  exception, the following additional comment should appear after the
491  contact information:</P>
492 <PRE>
493      *   This file is subject to the Apple OS-Developed Software exception.
494 </PRE>
495 <P>The bottom of each source file shall contain a trailer giving the
496  name of the file using the CVS &quot;$Id$&quot; tag. The primary purpose of this
497  is to mark the end of a source file; if the trailer is missing it is
498  possible that code has been lost near the end of the file:</P>
499 <PRE>
500     /*
501      * End of &quot;$Id$&quot;.
502      */
503 </PRE>
504 <H2><A NAME="7_2">B.2 Functions</A></H2>
505 <H3><A NAME="7_2_1">B.2.1 Naming</A></H3>
506 <P>Functions with a global scope shall be capitalized (&quot;DoThis&quot;,
507  &quot;DoThat&quot;, &quot;DoSomethingElse&quot;, etc.) The only exception to this rule
508  shall be the CUPS interface library functions which may begin with a
509  prefix word in lowercase (&quot;cupsDoThis&quot;, &quot;cupsDoThat&quot;, etc.)</P>
510 <P>Functions with a local scope shall be declared &quot;static&quot; and be
511  lowercase with underscores between words (&quot;do_this&quot;, &quot;do_that&quot;,
512  &quot;do_something_else&quot;, etc.)</P>
513 <H3><A NAME="7_2_2">B.2.2 Documentation</A></H3>
514 <P>Each function shall begin with a comment header describing what the
515  function does, the possible input limits (if any), and the possible
516  output values (if any), and any special information needed:</P>
517 <PRE>
518     /*
519      * 'do_this()' - Compute y = this(x).
520      *
521      * Notes: none.
522      */
523
524     static float     /* O - Inverse power value, 0.0 &lt;= y &lt;= 1.1 */
525     do_this(float x) /* I - Power value (0.0 &lt;= x &lt;= 1.1) */
526     {
527       ...
528       return (y);
529     }
530 </PRE>
531 <P>Return/output values are indicated using an &quot;O&quot; prefix, input values
532  are indicated using the &quot;I&quot; prefix, and values that are both input and
533  output use the &quot;IO&quot; prefix for the corresponding in-line comment.</P>
534 <H2><A NAME="7_3">B.3 Methods</A></H2>
535 <H3><A NAME="7_3_1">B.3.1 Naming</A></H3>
536 <P>Methods shall be in lowercase with underscores between words
537  (&quot;do_this&quot;, &quot;do_that&quot;, &quot;do_something_else&quot;, etc.)</P>
538 <H3><A NAME="7_3_2">B.3.2 Documentation</A></H3>
539 <P>Each method shall begin with a comment header describing what the
540  method does, the possible input limits (if any), and the possible
541  output values (if any), and any special information needed:</P>
542 <PRE>
543     /*
544      * 'class::do_this()' - Compute y = this(x).
545      *
546      * Notes: none.
547      */
548
549     float                   /* O - Inverse power value, 0.0 &lt;= y &lt;= 1.0 */
550     class::do_this(float x) /* I - Power value (0.0 &lt;= x &lt;= 1.0) */
551     {
552       ...
553       return (y);
554     }
555 </PRE>
556 <P>Return/output values are indicated using an &quot;O&quot; prefix, input values
557  are indicated using the &quot;I&quot; prefix, and values that are both input and
558  output use the &quot;IO&quot; prefix for the corresponding in-line comment.</P>
559 <H2><A NAME="7_4">B.4 Variables</A></H2>
560 <H3><A NAME="7_4_1">B.4.1 Naming</A></H3>
561 <P>Variables with a global scope shall be capitalized (&quot;ThisVariable&quot;,
562  &quot;ThatVariable&quot;, &quot;ThisStateVariable&quot;, etc.) The only exception to this
563  rule shall be the CUPS interface library global variables which must
564  begin with the prefix &quot;cups&quot; (&quot;cupsThisVariable&quot;, &quot;cupsThatVariable&quot;,
565  etc.) Global variables shall be replaced by function arguments whenever
566  possible.</P>
567 <P>Variables with a local scope shall be lowercase with underscores
568  between words (&quot;this_variable&quot;, &quot;that_variable&quot;, etc.) Any local
569  variables shared by functions within a source file shall be declared
570  &quot;static&quot;.</P>
571 <H3><A NAME="7_4_2">B.4.2 Documentation</A></H3>
572 <P>Each variable shall be declared on a separate line and shall be
573  immediately followed by a comment block describing the variable:</P>
574 <PRE>
575     int this_variable;   /* The current state of this */
576     int that_variable;   /* The current state of that */
577 </PRE>
578 <H2><A NAME="7_5">B.5 Types</A></H2>
579 <H3><A NAME="7_5_1">B.5.1 Naming</A></H3>
580 <P>All type names shall be lowercase with underscores between words and
581  &quot;_t&quot; appended to the end of the name (&quot;this_type_t&quot;, &quot;that_type_t&quot;,
582  etc.)</P>
583 <H3><A NAME="7_5_2">B.5.2 Documentation</A></H3>
584 <P>Each type shall have a comment block immediately before the typedef:</P>
585 <PRE>
586     /*
587      * This type is for CUPS foobar options.
588      */
589     typedef int cups_this_type_t;
590 </PRE>
591 <H2><A NAME="7_6">B.6 Structures</A></H2>
592 <H3><A NAME="7_6_1">B.6.1 Naming</A></H3>
593 <P>All structure names shall be lowercase with underscores between words
594  and &quot;_str&quot; appended to the end of the name (&quot;this_struct_str&quot;,
595  &quot;that_struct_str&quot;, etc.)</P>
596 <H3><A NAME="7_6_2">B.6.2 Documentation</A></H3>
597 <P>Each structure shall have a comment block immediately before the
598  struct and each member shall be documented in accordance with the
599  variable naming policy above:</P>
600 <PRE>
601     /*
602      * This structure is for CUPS foobar options.
603      */
604     struct cups_this_struct_str
605     {
606       int this_member;   /* Current state for this */
607       int that_member;   /* Current state for that */
608     };
609 </PRE>
610 <H2><A NAME="7_7">B.7 Classes</A></H2>
611 <H3><A NAME="7_7_1">B.7.1 Naming</A></H3>
612 <P>All class names shall be lowercase with underscores between words
613  (&quot;this_class&quot;, &quot;that_class&quot;, etc.)</P>
614 <H3><A NAME="7_7_2">B.7.2 Documentation</A></H3>
615 <P>Each class shall have a comment block immediately before the class
616  and each member shall be documented in accordance with the variable
617  naming policy above:</P>
618 <PRE>
619     /*
620      * This class is for CUPS foobar options.
621      */
622     class cups_this_class
623     {
624       int this_member;   /* Current state for this */
625       int that_member;   /* Current state for that */
626     };
627 </PRE>
628 <H2><A NAME="7_8">B.8 Constants</A></H2>
629 <H3><A NAME="7_8_1">B.8.1 Naming</A></H3>
630 <P>All constant names shall be uppercase with underscored between words
631  (&quot;THIS_CONSTANT&quot;, &quot;THAT_CONSTANT&quot;, etc.) Constants defined for the CUPS
632  interface library must begin with an uppercase prefix
633  (&quot;CUPS_THIS_CONSTANT&quot;, &quot;CUPS_THAT_CONSTANT&quot;, etc.)</P>
634 <P>Typed enumerations shall be used whenever possible to allow for type
635  checking by the compiler.</P>
636 <H3><A NAME="7_8_2">B.8.2 Documentation</A></H3>
637 <P>Comment blocks shall immediately follow each constant:</P>
638 <PRE>
639     enum
640     {
641       CUPS_THIS_TRAY,   /* This tray */
642       CUPS_THAT_TRAY    /* That tray */
643     };
644 </PRE>
645 <H2><A NAME="7_9">B.9 Code</A></H2>
646 <H3><A NAME="7_9_1">B.9.1 Documentation</A></H3>
647 <P>All source code shall utilize block comments within functions to
648  describe the operations being performed by a group of statements:</P>
649 <PRE>
650     /*
651      * Clear the state array before we begin...
652      */
653
654     for (i = 0; i &lt; (sizeof(array) / sizeof(sizeof(array[0])); i ++)
655       array[i] = STATE_IDLE;
656
657     /*
658      * Wait for state changes...
659      */
660
661     do
662     {
663       for (i = 0; i &lt; (sizeof(array) / sizeof(sizeof(array[0])); i ++)
664         if (array[i] != STATE_IDLE)
665           break;
666
667       if (i == (sizeof(array) / sizeof(array[0])))
668         sleep(1);
669     } while (i == (sizeof(array) / sizeof(array[0])));
670 </PRE>
671 <H3><A NAME="7_9_2">B.9.2 Style</A></H3>
672 <H4 TYPE="a">B.9.2.a Indentation</H4>
673 <P>All code blocks enclosed by brackets shall begin with the opening
674  brace on a new line. The code then follows starting on a new line after
675  the brace and is indented 2 spaces. The closing brace is then placed on
676  a new line following the code at the original indentation:</P>
677 <PRE>
678     {
679       int i; /* Looping var */
680
681      /*
682       * Process foobar values from 0 to 999...
683       */
684
685       for (i = 0; i &lt; 1000; i ++)
686       {
687         do_this(i);
688         do_that(i);
689       }
690     }
691 </PRE>
692 <P>Single-line statements following &quot;do&quot;, &quot;else&quot;, &quot;for&quot;, &quot;if&quot;, and
693  &quot;while&quot; shall be indented 2 spaces as well. Blocks of code in a
694  &quot;switch&quot; block shall be indented 4 spaces after each &quot;case&quot; and
695  &quot;default&quot; case:</P>
696 <PRE>
697     switch (array[i])
698     {
699       case STATE_IDLE :
700           do_this(i);
701           do_that(i);
702           break;
703       default :
704           do_nothing(i);
705           break;
706     }
707 </PRE>
708 <H4>B.9.2.b Spacing</H4>
709 <P>A space shall follow each reserved word (&quot;if&quot;, &quot;while&quot;, etc.) Spaces
710  shall not be inserted between a function name and the arguments in
711  parenthesis.</P>
712 <H4>B.9.2.c Return Values</H4>
713 <P>Parenthesis shall surround values returned from a function using
714  &quot;return&quot;:</P>
715 <PRE>
716     return (STATE_IDLE);
717 </PRE>
718 <H4>B.9.2.d Loops</H4>
719 <P>Whenever convenient loops should count downward to zero to improve
720  program performance:</P>
721 <PRE>
722     for (i = sizeof(array) / sizeof(array[0]) - 1; i &gt;= 0; i --)
723       array[i] = STATE_IDLE;
724 </PRE>
725 <H1 ALIGN="RIGHT"><A NAME="8">C Software Trouble Report Form</A></H1>
726 <CENTER>
727 <TABLE WIDTH="80%">
728 <TR><TH ALIGN="RIGHT">Summary of Problem:</TH><TD COLSPAN="2">
729 _____________________________________________</TD></TR>
730 <TR><TD COLSPAN="3">&nbsp;</TD></TR>
731 <TR><TH ALIGN="RIGHT" ROWSPAN="5" VALIGN="TOP">Problem Severity:</TH><TD>
732 __1</TD><TD>Request for enhancement, e.g. asking for a feature</TD></TR>
733 <TR><TD>__2</TD><TD>Low, e.g. a documentation error or undocumented
734  side-effect</TD></TR>
735 <TR><TD>__3</TD><TD>Moderate, e.g. unable to print a file or unable to
736  compile the software</TD></TR>
737 <TR><TD>__4</TD><TD>High, e.g. unable to print to a printer or key
738  functionality not working</TD></TR>
739 <TR><TD>__5</TD><TD>Critical, e.g. unable to print at all</TD></TR>
740 <TR><TD COLSPAN="3">&nbsp;</TD></TR>
741 <TR><TH ALIGN="RIGHT" ROWSPAN="3" VALIGN="TOP">Problem Scope:</TH><TD>
742 __1</TD><TD>Machine or printer</TD></TR>
743 <TR><TD>__2</TD><TD>Operating System</TD></TR>
744 <TR><TD>__3</TD><TD>All machines, printers, or operating systems</TD></TR>
745 <TR><TD COLSPAN="3">&nbsp;</TD></TR>
746 <TR><TH ALIGN="RIGHT" VALIGN="TOP">Detailed Description of Problem:</TH><TD
747 COLSPAN="2">_____________________________________________
748 <BR> _____________________________________________
749 <BR> _____________________________________________
750 <BR> _____________________________________________
751 <BR> _____________________________________________</TD></TR>
752 </TABLE>
753 </CENTER>
754 </BODY>
755 </HTML>