doc/help/translation.html

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