doc/help/translation.html

   1 <HTML>
   2 <!-- SECTION: Getting Started -->
   3 <HEAD>
   4         <TITLE>Translating and Customizing CUPS</TITLE>
   5         <LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
   6 </HEAD>
   7 <BODY>
   8
   9 <H1 CLASS="title">Translating and Customizing CUPS</H1>
  10
  11 <P>Thanks to its extensive use of templates, images, and message catalogs, CUPS can be easily translated (or customized!) to suit your needs. This help file will guide you through the CUPS localization files so you can get the most out of it.</P>
  12
  13
  14 <H2 CLASS="title" ID="INTRO">Getting Started</H2>
  15
  16 <P>Start by downloading the CUPS source code from <A HREF="https://www.cups.org/" TARGET="_blank">www.cups.org</A>. After you extract the files from the source archive (or clone the Git repository), you will want to copy the following files and directories:</P>
  17
  18 <UL>
  19
  20         <LI><VAR>desktop/cups.desktop</VAR> - the GNOME/KDE desktop file pointing to the CUPS web interface</LI>
  21
  22         <LI><VAR>doc/index.html.in</VAR> - the web interface home page</LI>
  23
  24         <LI><VAR>locale/cups.pot</VAR> - the message catalog</LI>
  25
  26         <LI><VAR>templates/*.tmpl</VAR> and <VAR>templates/header.tmpl.in</VAR> - the web interface     template files</LI>
  27
  28 </UL>
  29
  30 <P>With the exception of the message catalogs and desktop file, localization files are placed in subdirectories under the <VAR>doc</VAR> and <VAR>templates</VAR> using the locale name. Locale names are either <VAR>ll</VAR> or <VAR>ll_CC</VAR>, where "ll" is the 2-letter language code and "CC" is the 2-letter country code. <em>CUPS does not currently use or support the newer <VAR>ll-region</VAR> syntax for locale names.</em></P>
  31
  32 <P>All non-image files must be encoded using the UTF-8 character set.</P>
  33
  34
  35 <H2 CLASS="title" ID="SUBMIT">Submitting a Translation for CUPS</H2>
  36
  37 <P>To submit a translation for inclusion in CUPS, translate the desktop file, all of the template files, the <VAR>index.html.in</VAR> file, and the message catalog. Place these files in the correct subdirectories in the CUPS source code archive and run the following command to create an archive with your files:</P>
  38
  39 <PRE CLASS="command">
  40 tar cvf <I>ll_CC</I>.tar.gz desktop/cups.desktop doc/<I>ll_CC</I> locale/cups_<I>ll_CC</I>.po templates/<I>ll_CC</I>
  41 </PRE>
  42
  43 <P>Replace "ll_CC" with the locale name for your translation. Once you have created the archive, go to the <A HREF="https://github.com/apple/cups" TARGET="_blank">CUPS project page</A> and submit a bug report, attaching the translation to the report.</P>
  44
  45 <P>Alternately, you can clone the CUPS project on Github, make your changes, and submit a pull request from the same link.</P>
  46
  47
  48 <H2 CLASS="title" ID="DESKTOP">The Desktop File</H2>
  49
  50 <P>The <VAR>desktop/cups.desktop</VAR> file provides a link to the CUPS web interface from desktop environments such as GNOME and KDE. To translate this file, add two lines to the bottom with the <tt>Name</tt> and <tt>Comment</tt> keys:</P>
  51
  52 <PRE CLASS="command">
  53 Name[<I>ll_CC</I>]=<I>Translation of "Manage Printing"</I>
  54 Comment[<I>ll_CC</I>]=<I>Translation of "CUPS Web Interface"</I>
  55 </PRE>
  56
  57
  58 <H2 CLASS="title" ID="HOMEPAGE">The Home Page</H2>
  59
  60 <P>The <VAR>index.html.in</VAR> file is a complete HTML file that is displayed when the user visits "http://localhost:631/". Edit the existing <VAR>doc/index.html.in</VAR> and save it in the <VAR>doc/ll_CC</VAR> subdirectory so that the configure script can generate it. After configuring, run "make install" in the <VAR>doc</VAR> subdirectory to test the new home page.</P>
  61
  62
  63 <H2 CLASS="title" ID="CATALOGS">Message Catalogs</H2>
  64
  65 <P>CUPS message catalogs are GNU gettext ".po" text files that provide a list of localized message strings for the CUPS software. Message catalogs are named <VAR>cups_ll.po</VAR> or <VAR>cups_ll_CC.po</VAR>, where "ll" is the standard 2-letter abbreviation for the language and "CC" is the standard 2-letter abbreviation for the country.</P>
  66
  67 <P>When translating a new message catalog, copy the <VAR>cups.pot</VAR> message catalog file in the <VAR>locale</VAR> subdirectory of the CUPS source code. For example, to start translating the message catalog to Canadian French, you would type the following commands:</P>
  68
  69 <PRE CLASS="command">
  70 cd locale
  71 cp cups.pot cups_fr_CA.po
  72 </PRE>
  73
  74 <P>Alternatively, you can copy the existing <VAR>cups_fr.po</VAR> message catalog and then make any necessary changes.</P>
  75
  76 <P>Once you have make your copy of the file, edit it using your favorite text editor or translation program to translate the text to the desired language.</P>
  77
  78 <P>Then validate your translation using the <VAR>locale/checkpo</VAR> utility:</P>
  79
  80 <PRE CLASS="command">
  81 cd locale
  82 ./checkpo cups_ll_CC.po
  83 </PRE>
  84
  85 <P>After fixing any errors in your translation, add your locale to the <CODE>LANGUAGES</CODE> variable in the <VAR>Makedefs</VAR> file and run the "make install" command in the <VAR>locale</VAR> subdirectory to test the translation. <em>This variable is automatically updated when you run the configure script.</em></P>
  86
  87
  88 <H2 CLASS="title" ID="TEMPLATES">Template Files</H2>
  89
  90 <P>The CUPS scheduler provides a web interface that can be used to do many common printing and administration tasks. The built-in web server supports localization of web pages through the use of subdirectories for each locale, e.g. "fr" for French, "de" for German, "fr_ca" for French in Canada, and so forth.</P>
  91
  92 <P>Template files are HTML files with special formatting characters in them that allow substitution of variables and arrays. The CUPS CGI programs (<CODE>admin.cgi</CODE>, <CODE>classes.cgi</CODE>, <CODE>help.cgi</CODE>, <CODE>jobs.cgi</CODE>, and <CODE>printers.cgi</CODE>) use these template file to provide dynamic content for the web interface. Template files are installed in the <VAR>/usr/share/cups/templates</VAR> directory by default. <A HREF="table1">Table 1</a> lists the various template files and their purpose.</P>
  93
  94 <P>Translated versions of the template files should be saved in
  95 the <VAR>templates/ll_CC</VAR> subdirectory. For example,
  96 Canadian French template files should be saved in the
  97 <VAR>templates/fr_CA</VAR> subdirectory. After you have
  98 translated all of the templates, add the locale to the
  99 <CODE>LANGUAGES</CODE> variable in the
 100 <VAR>Makedefs</VAR> file and run "make install" in the
 101 <VAR>templates</VAR> subdirectory to test the translation.</P>
 102
 103 <DIV CLASS="table"><TABLE ID="table1" SUMMARY="Web Interface Template Files">
 104 <CAPTION>Table 1: Web Interface Template Files</CAPTION>
 105 <THEAD>
 106 <TR>
 107         <TH>Filename</TH>
 108         <TH>Purpose</TH>
 109 </TR>
 110 </THEAD>
 111 <TBODY>
 112 <TR>
 113         <TD>add-class.tmpl</TD>
 114         <TD>This is the initial form that is shown to add a new printer class.</TD>
 115 </TR>
 116 <TR>
 117         <TD>add-printer.tmpl</TD>
 118         <TD>This is the initial form that is shown to add a new printer.</TD>
 119 </TR>
 120 <TR>
 121         <TD>admin.tmpl</TD>
 122         <TD>This is the main administration page.</TD>
 123 </TR>
 124 <TR>
 125         <TD>choose-device.tmpl</TD>
 126         <TD>This is the form that shows the list of available devices.</TD>
 127 </TR>
 128 <TR>
 129         <TD>choose-make.tmpl</TD>
 130         <TD>This is the form that shows the list of available manufacturers.</TD>
 131 </TR>
 132 <TR>
 133         <TD>choose-model.tmpl</TD>
 134         <TD>This is the form that shows the list of available printer models/drivers.</TD>
 135 </TR>
 136 <TR>
 137         <TD>choose-serial.tmpl</TD>
 138         <TD>This is the form that allows the user to choose a serial port and any options.</TD>
 139 </TR>
 140 <TR>
 141         <TD>choose-uri.tmpl</TD>
 142         <TD>This is the form that allows the user to enter a device URI for network printers.</TD>
 143 </TR>
 144 <TR>
 145         <TD>class.tmpl</TD>
 146         <TD>This template shows information about a single class.</TD>
 147 </TR>
 148 <TR>
 149         <TD>class-added.tmpl</TD>
 150         <TD>This template shows the "class added" message.</TD>
 151 </TR>
 152 <TR>
 153         <TD>class-confirm.tmpl</TD>
 154         <TD>This is the template used to confirm the deletion of a class.</TD>
 155 </TR>
 156 <TR>
 157         <TD>class-deleted.tmpl</TD>
 158         <TD>This template shows the "class deleted" message.</TD>
 159 </TR>
 160 <TR>
 161         <TD>class-jobs-header.tmpl</TD>
 162         <TD>This template shows the "jobs" header for jobs in a class.</TD>
 163 </TR>
 164 <TR>
 165         <TD>class-modified.tmpl</TD>
 166         <TD>This template shows the "class modified" message.</TD>
 167 </TR>
 168 <TR>
 169         <TD>classes.tmpl</TD>
 170         <TD>This template shows one or more printer classes.</TD>
 171 </TR>
 172 <TR>
 173         <TD>classes-header.tmpl</TD>
 174         <TD>This template shows the "showing N of M classes" header in the class list.</TD>
 175 </TR>
 176 <TR>
 177         <TD>command.tmpl</TD>
 178         <TD>This template shows the status of a command job.</TD>
 179 </TR>
 180 <TR>
 181         <TD>edit-config.tmpl</TD>
 182         <TD>This is the cupsd.conf editor page.</TD>
 183 </TR>
 184 <TR>
 185         <TD>error.tmpl</TD>
 186         <TD>This template displays a generic error message.</TD>
 187 </TR>
 188 <TR>
 189         <TD>error-op.tmpl</TD>
 190         <TD>This is the "unknown operation" error page.</TD>
 191 </TR>
 192 <TR>
 193         <TD>header.tmpl(.in)</TD>
 194         <TD>This template is used as the standard header on all dynamic content. Edit the <VAR>header.tmpl.in</VAR> file and let the configure script generate the <VAR>header.tmpl</VAR> file.</TD>
 195 </TR>
 196 <TR>
 197         <TD>help-header.tmpl</TD>
 198         <TD>This is the top part of the help page.</TD>
 199 </TR>
 200 <TR>
 201         <TD>help-printable.tmpl</TD>
 202         <TD>This is the standard page header for the printable version of help files.</TD>
 203 </TR>
 204 <TR>
 205         <TD>help-trailer.tmpl</TD>
 206         <TD>This is the bottom part of the help page.</TD>
 207 </TR>
 208 <TR>
 209         <TD>job-cancel.tmpl</TD>
 210         <TD>This template shows "job canceled".</TD>
 211 </TR>
 212 <TR>
 213         <TD>job-hold.tmpl</TD>
 214         <TD>This template shows "job held".</TD>
 215 </TR>
 216 <TR>
 217         <TD>job-move.tmpl</TD>
 218         <TD>This template shows the move-job form.</TD>
 219 </TR>
 220 <TR>
 221         <TD>job-moved.tmpl</TD>
 222         <TD>This template shows "job moved".</TD>
 223 </TR>
 224 <TR>
 225         <TD>job-release.tmpl</TD>
 226         <TD>This template shows "job released".</TD>
 227 </TR>
 228 <TR>
 229         <TD>job-restart.tmpl</TD>
 230         <TD>This template shows "job reprinted".</TD>
 231 </TR>
 232 <TR>
 233         <TD>jobs.tmpl</TD>
 234         <TD>This template is used to list the print jobs on a server, class, or printer.</TD>
 235 </TR>
 236 <TR>
 237         <TD>jobs-header.tmpl</TD>
 238         <TD>This template shows the "showing N or M jobs" header in the jobs list.</TD>
 239 </TR>
 240 <TR>
 241         <TD>list-available-printers.tmpl</TD>
 242         <TD>This template shows a list of new printers that have been found.</TD>
 243 </TR>
 244 <TR>
 245         <TD>modify-class.tmpl</TD>
 246         <TD>This template is used as the first form when modifying a class.</TD>
 247 </TR>
 248 <TR>
 249         <TD>modify-printer.tmpl</TD>
 250         <TD>This template is used as the first form when modifying a printer.</TD>
 251 </TR>
 252 <TR>
 253         <TD>norestart.tmpl</TD>
 254         <TD>This template shows "server not restarted because no changes were made to the configuration".</TD>
 255 </TR>
 256 <TR>
 257         <TD>option-boolean.tmpl</TD>
 258         <TD>This template is used to select a boolean PPD option.</TD>
 259 </TR>
 260 <TR>
 261         <TD>option-conflict.tmpl</TD>
 262         <TD>This template shows the conflicting options.</TD>
 263 </TR>
 264 <TR>
 265         <TD>option-header.tmpl</TD>
 266         <TD>This template is used to start a PPD option group.</TD>
 267 </TR>
 268 <TR>
 269         <TD>option-pickmany.tmpl</TD>
 270         <TD>This template is used to select a multi-valued PPD option.</TD>
 271 </TR>
 272 <TR>
 273         <TD>option-pickone.tmpl</TD>
 274         <TD>This template is used to select a single-valued PPD option.</TD>
 275 </TR>
 276 <TR>
 277         <TD>option-trailer.tmpl</TD>
 278         <TD>This template is used to end a PPD option group.</TD>
 279 </TR>
 280 <TR>
 281         <TD>pager.tmpl</TD>
 282         <TD>This template shows the previous/next pager bar.</TD>
 283 </TR>
 284 <TR>
 285         <TD>printer.tmpl</TD>
 286         <TD>This template shows information about a single printer.</TD>
 287 </TR>
 288 <TR>
 289         <TD>printer-accept.tmpl</TD>
 290         <TD>This template shows "printer now accepting jobs".</TD>
 291 </TR>
 292 <TR>
 293         <TD>printer-added.tmpl</TD>
 294         <TD>This template shows "printer added".</TD>
 295 </TR>
 296 <TR>
 297         <TD>printer-cancel-jobs.tmpl</TD>
 298         <TD>This template shows "All jobs on printer have been canceled."</TD>
 299 </TR>
 300 <TR>
 301         <TD>printer-configured.tmpl</TD>
 302         <TD>This template shows "printer configured".</TD>
 303 </TR>
 304 <TR>
 305         <TD>printer-confirm.tmpl</TD>
 306         <TD>This template asks the user to confirm the deletion of a printer.</TD>
 307 </TR>
 308 <TR>
 309         <TD>printer-default.tmpl</TD>
 310         <TD>This template shows "default printer set".</TD>
 311 </TR>
 312 <TR>
 313         <TD>printer-deleted.tmpl</TD>
 314         <TD>This template shows "printer deleted".</TD>
 315 </TR>
 316 <TR>
 317         <TD>printer-jobs-header.tmpl</TD>
 318         <TD>This templates shows the "jobs" header for jobs on a printer.</TD>
 319 </TR>
 320 <TR>
 321         <TD>printer-modified.tmpl</TD>
 322         <TD>This template shows "printer modified".</TD>
 323 </TR>
 324 <TR>
 325         <TD>printer-reject.tmpl</TD>
 326         <TD>This template shows "printer now rejecting jobs".</TD>
 327 </TR>
 328 <TR>
 329         <TD>printer-start.tmpl</TD>
 330         <TD>This template shows "printer started".</TD>
 331 </TR>
 332 <TR>
 333         <TD>printer-stop.tmpl</TD>
 334         <TD>This template shows "printer stopped".</TD>
 335 </TR>
 336 <TR>
 337         <TD>printers.tmpl</TD>
 338         <TD>This template is used to list information on one or more printers.</TD>
 339 </TR>
 340 <TR>
 341         <TD>printers-header.tmpl</TD>
 342         <TD>This template shows the "showing printer N of M" header in the printers list.</TD>
 343 </TR>
 344 <TR>
 345         <TD>restart.tmpl</TD>
 346         <TD>This template shows "server restarting".</TD>
 347 </TR>
 348 <TR>
 349         <TD>search.tmpl</TD>
 350         <TD>This template shows the search form.</TD>
 351 </TR>
 352 <TR>
 353         <TD>set-printer-options-header.tmpl</TD>
 354         <TD>This template shows the first part of the set printer options form.</TD>
 355 </TR>
 356 <TR>
 357         <TD>set-printer-options-trailer.tmpl</TD>
 358         <TD>This template shows the last part of the set printer options form.</TD>
 359 </TR>
 360 <TR>
 361         <TD>test-page.tmpl</TD>
 362         <TD>This template shows "test page printed".</TD>
 363 </TR>
 364 <TR>
 365         <TD>trailer.tmpl</TD>
 366         <TD>This template is used as the standard trailer on all dynamic content.</TD>
 367 </TR>
 368 <TR>
 369         <TD>users.tmpl</TD>
 370         <TD>This template shows the set allowed users form.</TD>
 371 </TR>
 372 </TBODY>
 373 </TABLE></DIV>
 374
 375 <H4 ID="VARIABLE">Inserting Attributes and Values</H4>
 376
 377 <P>Template files consist of HTML with variable substitutions for named inside curly braces "{name}". Variable names are generally the IPP attribute names with the hyphen ("-") replaced by the underscore ("_") character. For example, the <TT>job-printer-uri</TT> attribute is renamed to <TT>job_printer_uri</TT>.</P>
 378
 379 <P>Curley braces ("{" and "}") to indicate substitutions, and the backslash ("\") character for quoting. To insert any of these special characters as-is you need to use the HTML <CODE>&amp;name;</CODE> mechanism or prefix each special character with the backslash ("\".)</P>
 380
 381 <P>You substitute the value of a variable using <CODE>{NAME}</CODE> in your template file. If the variable is undefined then the <CODE>{NAME}</CODE> string is output as-is.</P>
 382
 383 <P>To substitute an empty string if the variable is undefined, use <CODE>{?NAME}</CODE> instead.</P>
 384
 385 <H4>Array Substitutions</H4>
 386
 387 <P>The number of array elements can be inserted using <CODE>{#NAME}</CODE>. If the array is undefined then 0 is output. The current array element (starting at 1) is inserted with <CODE>{#}</CODE>.</P>
 388
 389 <P>Arrays are handled using <CODE>{[NAME]</CODE> at the beginning of a section and <CODE>}</CODE> at the end. The information between the closing bracket ("]") and closing brace ("}") is repeated for as many elements as are in the named array. For example, the following template will display a list of each job in the <CODE>job_id</CODE> array:</P>
 390
 391 <PRE CLASS="command">
 392 &lt;TABLE&gt;
 393 &lt;TR&gt;
 394         &lt;TH&gt;Job ID&lt;/TH&gt;
 395         &lt;TH&gt;Destination&lt;/TH&gt;
 396         &lt;TH&gt;Title&lt;/TH&gt;
 397 &lt;/TR&gt;
 398
 399 {[job_id]
 400 &lt;TR&gt;
 401         &lt;TD&gt;{?job_id}&lt;/TD&gt;
 402         &lt;TD&gt;{?job_printer_name}&lt;/TD&gt;
 403         &lt;TD&gt;{?job_name}&lt;/TD&gt;
 404 &lt;/TR&gt;
 405 }
 406 &lt;/TABLE&gt;
 407 </PRE>
 408
 409 <P>Arrays can be nested, however all elements within the curly braces ("{" and "}") are indexed using the innermost array.</P>
 410
 411 <H4>Conditional Tests</H4>
 412
 413 <P>Templates can also test variables against specific values and conditionally include text in the template. The format is:</P>
 414
 415 <PRE CLASS="command">
 416 {<I>variable</I>?<I>true</I>:<I>false</I>}
 417 {<I>variable</I>=<I>value</I>?<I>true</I>:<I>false</I>}
 418 {<I>variable</I>!<I>value</I>?<I>true</I>:<I>false</I>}
 419 {<I>variable</I>&lt;<I>value</I>?<I>true</I>:<I>false</I>}
 420 {<I>variable</I>><I>value</I>?<I>true</I>:<I>false</I>}
 421 </PRE>
 422
 423 <P>where <VAR>true</VAR> is the text that is included if the condition is true and <VAR>false</VAR> is the text that is included if the condition is false. A value of <CODE>#</CODE> is replaced with the current element number (starting at 1.) The character after the variable name specifies the condition to test. <A HREF="#table2">Table 2</A> shows the available test conditions.</P>
 424
 425 <DIV CLASS="table"><TABLE ID="table2" SUMMARY="Template Substitution Conditions">
 426 <CAPTION>Table 2: Template Substitution Conditions</CAPTION>
 427 <TR>
 428         <TH>Char</TH>
 429         <TH>Condition</TH>
 430 </TR>
 431 <TR>
 432         <TD>?</TD>
 433         <TD>True if <VAR>variable</VAR> exists.</TD>
 434 </TR>
 435 <TR>
 436         <TD>=</TD>
 437         <TD>True if <VAR>variable</VAR> is equal to <VAR>value</VAR>.</TD>
 438 </TR>
 439 <TR>
 440         <TD>!</TD>
 441         <TD>True if <VAR>variable</VAR> is not equal to <VAR>value</VAR>.</TD>
 442 </TR>
 443 <TR>
 444         <TD>&lt;</TD>
 445         <TD>True if <VAR>variable</VAR> is less than <VAR>value</VAR>.</TD>
 446 </TR>
 447 <TR>
 448         <TD>></TD>
 449         <TD>True if <VAR>variable</VAR> is greater than <VAR>value</VAR>.</TD>
 450 </TR>
 451 </TABLE></DIV>
 452
 453 <H4 ID="LOCTMPL">What to Localize in a Template File</H4>
 454
 455 <P>Because HTML contains both markup (that generally is not localized) and text (which <em>is</em> localized), you should carefully avoid changing the markup unless it contains human-readable text. The following HTML examples show how to correctly localize template files:</P>
 456
 457 <P CLASS="command">
 458 &lt;!-- English table heading --&gt;<br>
 459 &lt;table class="list" summary="Printer List"><br>
 460 <br>
 461 &lt;!-- Correctly localized to French; the class attribute is unchanged but summary is localized --><br>
 462 &lt;table class="list" summary="Liste des imprimantes"><br>
 463 <br>
 464 <br>
 465 &lt;!-- English hyperlink --><br>
 466 &lt;li>&lt;a {SECTION=help?class="active" :}href="/help/">Help&lt;/a>&lt;/li><br>
 467 <br>
 468 &lt;!-- Correctly localized to Danish; the href attribute is unchanged while the link text is localized --><br>
 469 &lt;li>&lt;a {SECTION=help?class="active" :}href="/help/">Hjælp&lt;/a>&lt;/li><br>
 470 </P>
 471
 472
 473 <H3 ID="CGI">CGI Programs</H3>
 474
 475 <P>CUPS uses five CGI programs to manage the dynamic web interfaces:</P>
 476
 477 <UL>
 478
 479         <LI><CODE>admin.cgi</CODE></LI>
 480         <LI><CODE>classes.cgi</CODE></LI>
 481         <LI><CODE>help.cgi</CODE></LI>
 482         <LI><CODE>jobs.cgi</CODE></LI>
 483         <LI><CODE>printers.cgi</CODE></LI>
 484
 485 </UL>
 486
 487 <P>Each CGI program accepts standard form variables such as <CODE>OP</CODE> for the operation to perform, <CODE>PRINTER_NAME</CODE> for the printer or class name to operate on, <CODE>QUERY</CODE> for any search words,<CODE>FIRST</CODE> for the first class, job, or printer to display, and <CODE>ORDER</CODE> to control the order that classes, jobs, or printers are displayed.</P>
 488
 489 <P>In addition, the <CODE>classes.cgi</CODE>, <CODE>jobs.cgi</CODE>, and <CODE>printers.cgi</CODE> programs support a <CODE>WHICH_JOBS</CODE> variable to control which jobs are displayed. <A HREF="#table3">Table 3</A> lists the supported values.</P>
 490
 491 <DIV CLASS="table"><TABLE ID="table3" SUMMARY="WHICH_JOBS Values">
 492 <CAPTION>Table 3: WHICH_JOBS Values</CAPTION>
 493 <THEAD>
 494 <TR>
 495         <TH>WHICH_JOBS Value</TH>
 496         <TH>Description</TH>
 497 </TR>
 498 </THEAD>
 499 <TR>
 500         <TD>all</TD>
 501         <TD>Show all jobs</TD>
 502 </TR>
 503 <TR>
 504         <TD>completed</TD>
 505         <TD>Show completed jobs</TD>
 506 </TR>
 507 <TR>
 508         <TD>not-completed</TD>
 509         <TD>Show active jobs</TD>
 510 </TR>
 511 </TABLE></DIV>
 512
 513 <H4 ID="admin.cgi">admin.cgi</H4>
 514
 515 <P>The <CODE>admin.cgi</CODE> program handles all of the printer and class administration functions and is run for all direct accesses to the <VAR>/admin</VAR> resource. For most operations it uses the <CODE>PRINTER_NAME</CODE> and <CODE>OP</CODE> form variables to specify the action requested. <A HREF="#table4">Table 4</A> shows the supported <CODE>OP</CODE> values.</P>
 516
 517 <DIV CLASS="table"><TABLE ID="table4" SUMMARY="admin.cgi OP Values">
 518 <CAPTION>Table 4: admin.cgi OP Values</CAPTION>
 519 <THEAD>
 520 <TR>
 521         <TH>OP Value</TH>
 522         <TH>Description</TH>
 523 </TR>
 524 </THEAD>
 525 <TBODY>
 526 <TR>
 527         <TD>add-class</TD>
 528         <TD>Adds a new printer class.</TD>
 529 </TR>
 530 <TR>
 531         <TD>add-printer</TD>
 532         <TD>Adds a new printer.</TD>
 533 </TR>
 534 <TR>
 535         <TD>config-server</TD>
 536         <TD>Configures the server.</TD>
 537 </TR>
 538 <TR>
 539         <TD>delete-class</TD>
 540         <TD>Deletes a printer class. The form variable <CODE>CONFIRM</CODE>
 541         may be set to any value to bypass the confirmation page.</TD>
 542 </TR>
 543 <TR>
 544         <TD>delete-printer</TD>
 545         <TD>Deletes a printer. The form variable <CODE>CONFIRM</CODE>
 546         may be set to any value to bypass the confirmation page.</TD>
 547 </TR>
 548 <TR>
 549         <TD>find-new-printers</TD>
 550         <TD>Find new printers that have not yet been added.</TD>
 551 </TR>
 552 <TR>
 553         <TD>modify-class</TD>
 554         <TD>Modifies a printer class.</TD>
 555 </TR>
 556 <TR>
 557         <TD>modify-printer</TD>
 558         <TD>Modifies a printer.</TD>
 559 </TR>
 560 <TR>
 561         <TD>redirect</TD>
 562         <TD>Redirects the web browser to the location referenced by
 563         the URL form variable.</TD>
 564 </TR>
 565 <TR>
 566         <TD>set-allowed-users</TD>
 567         <TD>Sets the allowed users for a destination.</TD>
 568 </TR>
 569 <TR>
 570         <TD>set-as-default</TD>
 571         <TD>Sets the default destination.</TD>
 572 </TR>
 573 <TR>
 574         <TD>set-printer-options</TD>
 575         <TD>Sets the default options for a printer.</TD>
 576 </TR>
 577 <TR>
 578         <TD>set-sharing</TD>
 579         <TD>Sets the printer-is-shared attribute for a destination.</TD>
 580 </TR>
 581 </TBODY>
 582 </TABLE></DIV>
 583
 584 <H4 ID="classes.cgi">classes.cgi</H4>
 585
 586 <P>The <CODE>classes.cgi</CODE> program is responsible for listing class information, including jobs destined for that class. It is for all direct accesses to the <VAR>/classes</VAR> resource and supports the optional form variables <CODE>OP</CODE> and <CODE>WHICH_JOBS</CODE>. If no form variables are supplied then the CGI lists all or a specific class and the active jobs on each class. <A HREF="#table5">Table 5</A> shows the supported <CODE>OP</CODE> values.</P>
 587
 588 <DIV CLASS="table"><TABLE ID="table5" SUMMARY="classes.cgi OP Values">
 589 <CAPTION>Table 5: classes.cgi OP Values</CAPTION>
 590 <THEAD>
 591 <TR>
 592         <TH>OP Value</TH>
 593         <TH>Description</TH>
 594 </TR>
 595 </THEAD>
 596 <TBODY>
 597 <TR>
 598         <TD>accept-jobs</TD>
 599         <TD>Start accepting jobs for a class.</TD>
 600 </TR>
 601 <TR>
 602         <TD>cancel-jobs</TD>
 603         <TD>Cancel all jobs for a class.</TD>
 604 </TR>
 605 <TR>
 606         <TD>move-jobs</TD>
 607         <TD>Move all jobs to a different destination.</TD>
 608 </TR>
 609 <TR>
 610         <TD>print-test-page</TD>
 611         <TD>Print a PostScript test page.</TD>
 612 </TR>
 613 <TR>
 614         <TD>reject-jobs</TD>
 615         <TD>Stop accepting jobs for a class.</TD>
 616 </TR>
 617 <TR>
 618         <TD>start-class</TD>
 619         <TD>Start processing jobs for a class.</TD>
 620 </TR>
 621 <TR>
 622         <TD>stop-class</TD>
 623         <TD>Stop processing jobs for a class.</TD>
 624 </TR>
 625 </TBODY>
 626 </TABLE></DIV>
 627
 628
 629 <H4 ID="help.cgi">help.cgi</H4>
 630
 631 <P>The <CODE>help.cgi</CODE> program handles all of the on-line help functions and is run for all direct accesses to the <VAR>/help</VAR> resource.</P>
 632
 633
 634 <H4 ID="jobs.cgi">jobs.cgi</H4>
 635
 636 <P>The <CODE>jobs.cgi</CODE> program handles all of the job functions and is run for all direct accesses to the <VAR>/jobs</VAR> resource. For most operations it uses the <CODE>JOB_ID</CODE>, <CODE>OP</CODE>, and <CODE>WHICH_JOBS</CODE> form variables to specify the action requested. <A HREF="#table6">Table 6</A> shows the supported <CODE>OP</CODE> values.</P>
 637
 638 <DIV CLASS="table"><TABLE ID="table6" SUMMARY="jobs.cgi OP Values">
 639 <CAPTION>Table 6: jobs.cgi OP Values</CAPTION>
 640 <THEAD>
 641 <TR>
 642         <TH>OP Value</TH>
 643         <TH>Description</TH>
 644 </TR>
 645 </THEAD>
 646 <TBODY>
 647 <TR>
 648         <TD>cancel-job</TD>
 649         <TD>Cancels a job.</TD>
 650 </TR>
 651 <TR>
 652         <TD>hold-job</TD>
 653         <TD>Holds a job indefinitely.</TD>
 654 </TR>
 655 <TR>
 656         <TD>move-job</TD>
 657         <TD>Moves a job to another destination.</TD>
 658 </TR>
 659 <TR>
 660         <TD>release-job</TD>
 661         <TD>Releases a job for printing.</TD>
 662 </TR>
 663 <TR>
 664         <TD>restart-job</TD>
 665         <TD>Restarts/reprints a stopped, canceled, completed, or aborted
 666         print job.</TD>
 667 </TR>
 668 </TBODY>
 669 </TABLE></DIV>
 670
 671
 672 <H4 ID="printers.cgi">printers.cgi</H4>
 673
 674 <P>The <CODE>printers.cgi</CODE> program is responsible for listing printer information, including jobs destined for that printer. It is for all direct accesses to the <VAR>/printers</VAR> resource and supports the optional form variables <CODE>OP</CODE> and <CODE>WHICH_JOBS</CODE>. If no form variables are supplied then the CGI lists all printers or a specific printer and the active jobs on that printer. <A HREF="#table7">Table 7</A> shows the supported <CODE>OP</CODE> values.</P>
 675
 676 <DIV CLASS="table"><TABLE ID="table7" SUMMARY="printers.cgi OP Values">
 677 <CAPTION>Table 7: printers.cgi OP Values</CAPTION>
 678 <THEAD>
 679 <TR>
 680         <TH>OP Value</TH>
 681         <TH>Description</TH>
 682 </TR>
 683 </THEAD>
 684 <TBODY>
 685 <TR>
 686         <TD>accept-jobs</TD>
 687         <TD>Start accepting jobs for a printer.</TD>
 688 </TR>
 689 <TR>
 690         <TD>cancel-jobs</TD>
 691         <TD>Cancel all jobs for a printer.</TD>
 692 </TR>
 693 <TR>
 694         <TD>clean-print-heads</TD>
 695         <TD>Clean the print heads.</TD>
 696 </TR>
 697 <TR>
 698         <TD>move-jobs</TD>
 699         <TD>Move all jobs to a different destination.</TD>
 700 </TR>
 701 <TR>
 702         <TD>print-self-test-page</TD>
 703         <TD>Print a printer self-test page.</TD>
 704 </TR>
 705 <TR>
 706         <TD>print-test-page</TD>
 707         <TD>Print a PostScript test page.</TD>
 708 </TR>
 709 <TR>
 710         <TD>reject-jobs</TD>
 711         <TD>Stop accepting jobs for a printer.</TD>
 712 </TR>
 713 <TR>
 714         <TD>start-printer</TD>
 715         <TD>Start processing jobs for a printer.</TD>
 716 </TR>
 717 <TR>
 718         <TD>stop-printer</TD>
 719         <TD>Stop processing jobs for a printer.</TD>
 720 </TR>
 721 </TBODY>
 722 </TABLE></DIV>
 723
 724 </BODY>
 725 </HTML>