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