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