  Hpmodeset Users Guide
  Glenn Maughan, gglleennnnmm@@iinnsseecctt..ssdd..mmoonnaasshh..eedduu..aauu
  v2.1, 22 January 1996

  Many of the newer model Hewlett-Packard printers do not have a control
  panel to change printer settings.  In a Windows/DOS environment you
  are typically given drivers that allow you to change the printer set-
  tings.  However, in a Unix environment such as Linux you usually do
  not get such nice drivers!  I purchased a new LaserJet printer and
  found I could not control it completely under Linux.  To reduce my
  frustrations I developed this utility.  HHppmmooddeesseett provides a simple
  interface for changing printer control settings on most printers.
  Hpmodeset will encapsulate any number of print files, such as
  PostScript or PCL, within printer control codes.

  11..  IInnttrroodduuccttiioonn


  HHppmmooddeesseett provides a configurable utility for controlling printer
  settings in a Unix environment.  Most newer model printers have a
  control language that can be used to change the way documents will be
  printed.  For example, all Hewlett-Packard printers support the
  language PJL (Printer Job Language) for changing printer settings.

  The settings you can change on a printer usually include features such
  as, toner saving modes, extra margins, orientation, duplex printing
  and so on.  Hpmodeset can be configured to set the features that your
  printer supports.


  22..  SSwwiittcchheess


  The current configuration of hhppmmooddeesseett on your system can be listed by
  executing with the --hheellpp switch:



       $ hpmodeset -help




  This will output the current configuration of hpmodeset on your
  system.  It will look similar to the following:





















  ______________________________________________________________________
  Synopsis:
      hpmodeset [-help | -config | -license]
      hpmodeset [<config switches>] [<printer switches>] file ...
  General switches:
      -help               display this help message and current printer switches
      -config             display the printer configuration information
      -license            display the licensing information (GNU General Public License)
  Configuration switches:
      -configfile=<file>  use <file> as the configuration file and store
                          in <file>.store
      -notext             do not allow unknown printer languages to be passed through as
                          straight text
      -pjlonly            output PJL commands only.  Do not process file list.
  Example printer switches: (default values shown in braces)
      -formlines=[5-128 {60}]
      -economode=[ON | {OFF} | on | off]
      -pageprotect=[ON | {AUTO} | on | auto]
      -resolution=[300 | {600}]
      -orientation=[{PORTRAIT} | LANDSCAPE | portrait | landscape]
      -mptray=[{CASSETTE} | MANUAL | FIRST | cassette | manual | first]
      -copies=[1-999 {1}]
      -manualfeed=[ON | {OFF} | on | off]
      -personality=[{AUTO} | PCL | POSTSCRIPT | auto | pcl | postscript]
      -ret=[OFF | LIGHT | {MEDIUM} | DARK | off | light |
          medium | dark]
      -paper=[LETTER | LEGAL | {A4} | EXECUTIVE | COM10 | MONACH |
          C5 | CL | B5 | CUSTOM | letter | legal |
          a4 | executive | com10 | monach | c5 | cl |
          b5 | custom]
      -timeout=[5-300 {15}]
  ______________________________________________________________________




  22..11..  GGeenneerraall SSwwiittcchheess


  The following switches are available at all times.  If used, all other
  switches on the command line are ignored.  Only one of the switches
  can be used at a time.


     --hheellpp
        Display a short description of the command line syntax.  This
        also lists all printer control switches currently available and
        their valid options.


     --sshhoowwccoonnffiigg
        List the current configuration in the form of each command line
        switch, the printer control command, valid options and the
        default option.


     --lliicceennssee
        Show the copyright and licensing information.


  22..22..  CCoonnffiigguurraattiioonn SSwwiittcchheess


  The following switches are used to select a specific configuration
  file to be read and to adjust the way hhppmmooddeesseett operates.  The order
  in which these switches appears on the command line is unimportant.
  However, for readability, they should be listed first before any
  printer control switches or the file list.


     --ccoonnffiiggffiillee==<<ffiillee>>
        Use <file> as the configuration file.  hhppmmooddeesseett will read and
        parse the configuration settings in <file> and store the
        resulting configuration in a file named <file>..ssttoorree. Running
        hhppmmooddeesseett again with the same configuration file will result in
        the store file being read.  The config file will only be read
        again if it has been modified or the store file has been
        removed.


     --nnootteexxtt
        Do not allow unknown print file languages to be output.  By
        default, any print file containing an unknown printer language
        is output as straight text (without an EENNTTEERR LLAANNGGUUAAGGEE command).
        This option turns off this feature.


     --ppjjlloonnllyy
        Only output the PJL commands.  Ignore any file list.  This is
        useful for sending SSEETT DDEEFFAAUULLTT commands to printers to make
        persistent changes to the printer settings.


  22..33..  PPrriinntteerr SSwwiittcchheess


  The general form of a printer control command line switch is as
  follows:


       switch=value


  Where sswwiittcchh is one of the recognised printer switches and vvaalluuee is a
  valid textual value for that switch.  For example, hhppmmooddeesseett may be
  configured to understand a switch to turn draft mode on or off.  The
  user may then add the following switch to hhppmmooddeesseett's command line:


       -draft=on


  This would encapsulate the printer files in the printer control
  command to turn draft mode on.  The vvaalluuee is optional.  If the user
  does not add a vvaalluuee after the equals sign then the default option is
  used:


       -draft=


  would encapsulate the printer files in the default draft mode printer
  control command.

  Any number of printer control switches can be added to the command
  line.  The list of file names to encapsulate will be read following
  the last valid printer control switch.  Note that the equals sign is
  required whether a vvaalluuee has been given or not.




  22..44..  FFiillee LLiisstt



     ffiilleelliisstt
        The files containing printer language commands (as
        understandable by your printer).  Each file will be encapsulated
        within the printer control commands that represent the options
        selected by the user.  The resulting file will then be sent to
        stdout.  If the file name -- is used then stdin will be read at
        that position in the file list.




  33..  UUssaaggee


  hhppmmooddeesseett generates encapsulated printer files to its standard output.
  To determine the switches available in your local configuration run
  hhppmmooddeesseett with the --hheellpp switch.  This will list all available command
  line switches along with the valid values for each switch.

  The user can redirect the output of hhppmmooddeesseett to a file, pipe it
  directly to a print command (like llpprr), or to another filter for
  further processing.


       hpmodeset file1 < file2



       hpmodeset -draft=on file1 | lpr


  The first example above encapsulates ffiillee11 within printer control
  commands (in this case none) and redirects the output to ffiillee22.  The
  second example pipes the output (encapsulated in a draft command) to
  the llpprr command.

  To read standard input use the file marker --, as in the following
  example:


       cat file1 | hpmodeset -draft=on - | lpr



  44..  CCoonnffiigguurraattiioonn


  hhppmmooddeesseett is configured through a text file that defines the available
  printer control switches, their command syntax and valid options. The
  configuration file is composed of a number of sections.  Each section
  has the following form:


       Section SectionName SectionEntry EndSection


  The valid SSeeccttiioonnNNaammees are gglloobbaallss, llaanngguuaaggeess, and vvaarriiaabblleess.  Each
  SSeeccttiioonnEEnnttrryy has a different format depending on the section it is
  contained within.



  44..11..  GGlloobbaallss SSeeccttiioonn


  The gglloobbaallss section is mandatory.  It contains a number of global
  settings for hhppmmooddeesseett to function correctly.  The syntax for
  SSeeccttiioonnEEnnttrryy in the gglloobbaallss section is as follows:


       GlobalVariableName VariableValue


  The GGlloobbaallVVaarriiaabblleeNNaammee may be one of jjoobb__hheeaaddeerr, jjoobb__ttrraaiilleerr,
  rreesseett__ccoommmmaanndd, eenndd__ooff__ccoommmmaanndd or wwhhiittee__ssppaaccee.

  The VVaarriiaabblleeVVaalluuee for each of these settings must be a string of
  characters surrounded by double quotes.  Entries for every
  GGlloobbaallVVaarriiaabblleeNNaammee must appear in the config file.

  The globals section typically looks like:


  ______________________________________________________________________
  Section globals
      job_header        "%/27/%%-12345X@PJL COMMENT (C) 1995/1996 Glenn Maughan"
      job_trailer       "%/27/%%-12345X@PJL COMMENT end of job"
      reset_command     "@PJL RESET%N%/27/%%-12345X"
      end_of_command    "%N"
      white_space       " "
  EndSection
  ______________________________________________________________________




  55..  LLaanngguuaaggeess SSeeccttiioonn


  The llaanngguuaaggeess section defines the languages supported by the printer
  and the magic numbers to search for to determine the language used in
  a print file.  This section should define the languages that your
  printer supports.  The syntax for a SSeeccttiioonnEEnnttrryy in the llaanngguuaaggeess
  section is as follows:


       Language EnterCommand LeaveCommand Offset MagicString


  The LLaanngguuaaggee is an arbitrary name used for the language.  For example
  ppoossttssccrriipptt and ppccll are valid language names.

  The EEnntteerrCCoommmmaanndd is the printer control command to enter the language
  in question.  This command should be complete.  ie., the printer
  should expect a stream of code in the language specified immediately
  after the EEnntteerrCCoommmmaanndd.

  The LLeeaavveeCCoommmmaanndd specifies a command to use when leaving the language.
  For example, PostScript expects a Control-D character after every
  PostScript file.  This can be specified in the LLeeaavveeCCoommmmaanndd.

  The OOffffsseett specifies the byte to start searching for the MMaaggiiccSSttrriinngg.
  One (1) is the first byte in the file, not zero (0).  The MMaaggiiccSSttrriinngg
  is an arbitrary string of characters that will uniquely determine the
  type of code in the print file.  For example, PostScript code can be
  recognised by the magic string "%!%dquot; starting at byte one (1) of
  a print file.

  A typical languages section that supports both PostScript and PCL for
  the PJL language would look like the following:


  ______________________________________________________________________
  Section languages
      postscript  "@PJL ENTER LANGUAGE = POSTSCRIPT"    "%/3/"    1    "%%!"
      pcl         "@PJL ENTER LANGUAGE = PCL"           ""        1    "%/27/E%/27/"
  EndSection
  ______________________________________________________________________




  55..11..  VVaarriiaabblleess SSeeccttiioonn


  The final, and most important section in the config file is the
  vvaarriiaabblleess section.  This section defines the available command line
  switches, their valid options, the default option and the printer
  command to set the variable.  The syntax for SSeeccttiioonnEEnnttrryy in the
  vvaarriiaabblleess section is as follows:


       Switch Variable Options Default


  The SSwwiittcchh defines the command line syntax for each switch.  This must
  be a word preceeded by a hyphen (-) character.  The VVaarriiaabbllee is the
  printer command used to set the variable.  This must be a string of
  characters surrounded by double quotes (").  The OOppttiioonnss is a comma
  separated list of valid options in the form of either a word, a number
  (optionally signed) or a numeric interval (in the form "lower-upper").
  The DDeeffaauulltt option is the option that will be used if the user
  specifies the switch with no value.

  Any number of variables may be specified.  The SSwwiittcchh should not
  include the equals sign (=).  This is added automatically by the
  hhppmmooddeesseett utility when parsing the command line.

  The following listing is a sample of a vvaarriiaabblleess section:


  ______________________________________________________________________
  Section variables
      -autocont           "@PJL SET AUTOCONT ="           ON,OFF,on,off           OFF
      -autoselect         "@PJL SET AUTOSELECT ="         ON,OFF,on,off           ON
      -binding            "@PJL SET BINDING ="            LONGEDGE,SHORTEDGE,
                                                          longedge,shortedge      LONGEDGE
      -clearablewarnings  "@PJL SET CLEARABLEWARNINGS ="  JOB,ON,job,on           ON
      -contextswitch      "@PJL SET CONTEXTSWITCH ="      ON,OFF,on,off           ON
      -copies             "@PJL SET COPIES ="             1-999                   1
      -cplock             "@PJL SET CPLOCK ="             OFF,ON,off,on           OFF
      -density            "@PJL SET DENSITY ="            1-5                     3
  EndSection
  ______________________________________________________________________




  55..22..  CCoonnffiigg SSyynnttaaxx


  The syntax for a configuration file is described in the following
  _c_o_n_c_r_e_t_e _s_y_n_t_a_x.  There are four basic terminal types: number, word,
  string and switch and interval.  Each is defined as follows:
     nnuummbbeerr
        An optionally signed integer or real number.  For example, 11,
        11..00, --11 and --11..00 are valid numbers.


     wwoorrdd
        A word is a single token of characters starting with an letter
        (a-z or A-Z).


     sswwiittcchh
        a word with a leading hyphen character (-).


     iinntteerrvvaall
        two numbers separated by a hyphen character (-).


     ssttrriinngg
        A string is an arbitrary number of characters surrounded by
        double quotes (").  Control characters and unprintable
        characters can be embeded within a string using the Eiffel
        syntax for special characters.

        A special character is included by using one of the following
        codes:


        %%BB backspace

        %%FF formfeed

        %%NN newline

        %%RR carriage return

        %%TT horizontal tab

        %%UU null

        %%%% percent

        ssppeecciiaall
           any character with its decimal ASCII code surrounded by
           slashes and with a leading percent sign. eg, '%/34/' is the
           double quote character.  This is the only way to embed a
           double quote within a string. (This made the lexical analyser
           a little simpler!)


















  ______________________________________________________________________
  Hp_Config               ::=     Section_list;
  Section_list            ::=     {Section [";"] ...};
  Section                 ::=     "Section" Section_body "EndSection";
  Section_body            ::=     Variables | Globals | Languages;

  Variables               ::=     "variables" Variable_list;
  Variable_list           ::=     {Printer_variable [";"] ...};
  Printer_variable        ::=     Switch_type Variable_syntax Options Default;
  Variable_syntax         ::=     String_type;
  Options                 ::=     {Setting "," ...};
  Setting                 ::=     Alpha_type | Numeric_type | String_type | Interval_type;
  Default                 ::=     Setting;

  Globals                 ::=     "globals" Globals_list;
  Globals_list            ::=     {Global [";"] ...};
  Global                  ::=     Alpha_type String_type;

  Languages               ::=     Language_list;
  Language_list           ::=     {Language [";"] ...};
  Language                ::=     Alpha_type Language_command Numeric_type
                                  Language_magic_string;
  Language_command        ::=     String_type;
  Language_magic_string   ::=     String_type;

  Switch_type             ::=     "'-' ('a'..'z') *(~('a'..'z') | '_' | ('0'..'9'))";
  Alpha_type              ::=     "~('a'..'z') *(~('a'..'z') | '_' | ('0'..'9'))";
  Numeric_type            ::=     "$Z";
  Interval_type           ::=     "$N '-' $N";
  String_type             ::=     "'%"' *($. - '%"') '%"'";
  ______________________________________________________________________




  55..33..  EEnnccaappssuullaattiioonn OOrrddeerr


  hhppmmooddeesseett encapsulates files in the following order:

  The job_header is output first: jjoobb__hheeaaddeerr eenndd__ooff__ccoommmmaanndd

  Followed by each option specified on the command line: VVaarriiaabbllee
  wwhhiittee__ssppaaccee OOppttiioonn eenndd__ooff__ccoommmmaanndd.

  Followed by the relevant language enter command determined by
  examining each print file: EEnntteerrCCoommmmaanndd eenndd__ooff__ccoommmmaanndd

  Followed by the raw print file stream.

  This is repeated for each print file.

  The complete job is then ended with: jjoobb__ttrraaiilleerr eenndd__ooff__ccoommmmaanndd
  rreesseett__ccoommmmaanndd


  66..  CCoonnttrriibbuuttoorrss


  The Linux Community:  The first version released to the public was
  version 1.2.  It was released to the Linux community in binary form
  only.  It was downloaded approximatelly 400 times in the first 3 days
  after release!  Many new ideas and encouragement for a new release was
  received in the following weeks.  This release is the result.


  Eiffel: The Eiffel language made writing this utility easy.


  77..  WWhheerree ttoo ffiinndd iitt??


  HHppmmooddeesseett was written by Glenn Maughan glennm@insect.sd.monash.edu.au.
  All bugs and suggestions should be sent to Glenn.

  The latest version of hhppmmooddeesseett is available via ftp at
  ftp://hornet.sd.monash.edu.au/pub/hpmodeset.  Also the html version of
  this documentation can be browsed at
  http://www.sd.monash.edu.au/~glennm.





















































