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