doc/help/translation.html

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