jed-extra 2.5.7-2 / usr / share / jed / jed-extra / extra / apsmode.hlp

This is the help file for the apsmode (Version 2.2)
===================================================

TOC:
- General
- Directories, Files
- Installation
- Menu Description
- QuickPrint
- QuickPrint Menu Description
- apsconf.sl
- Create a new printer setup with the help of QuickPrint
- a2ps Style Sheets
- Variable Definition for Printer Settings
- Printer Definition Example
- apsconf: Changes from V1.5 --> 2.2


General
-------
apsmode has been created to support printing directly from jed. 
The mode should fullfill the following requirements:
- syntax-highlighting (as in jed)
- printing directly from jed
- menu support
- available under UNIX, Windows
- selection of printers
- selection of print options


In fact apsmode serves as a frontend to a2ps/ghostview.

In this context "printer" means here rather a printer setup or setting than
a real (physical) printer. Real (physical) printer names are part of a 
printer setup.
See "Printer Definition Example" or apsconf.template for details.


Directory, Files
----------------
The following files have to be included in your jed library path:
- apsmode.sl
- apsmode.hlp
- SLang.ssh
- <other_mode>.ssh

apsmode.hlp and *.ssh files could be stored in a separate subdirectory
(e.g. /apsmode) as long as this subdirectory is also in the jed library path.
(Use set_jed_library_path, see site.sl)

- apsconf.template is a printer setup template. This can be modified by the
  single user and loaded via jed.rc.
  apsconf.sl has always to be loaded by the user itself. apsmode will not
  load it.


Installation
------------
- Copy apsmode.sl, apsmode.hlp, *.ssh to your jed-lib-directory
- maybe modify some custom_variables in apsmode.sl (for system wide usage)
  Change only variable values in section
     %%%%%%%%%%%%%% custom_variables begin %%%%%%%%%%%%%
     ...
     %%%%%%%%%%%%%% custom_variables variables end %%%%%%%%%%%%%
- jed.rc:
  Add the following line to enable text menus in WINGUI
     () = evalfile("menus");
  Load the apsmode
     () = evalfile("apsmode");
- apsconf.sl: 
  edit the file apsconf.template for your personal a2ps/printer settings
  (see there for details)
  Maybe you have to copy the file to your personal
  jed files first, in Unix this could be "~/.jed/lib/"
  in this case, make sure it is in the jed-library-path (see
  set_jed_library_path())
  add to jed.rc
     () = evalfile("apsconf.sl");
- For conversion of existing apsconf.sl files 
  see "apsconf: Changes from V1.5 --> 2.0" below.


Menu Description
----------------
Note: Already selected values will be marked by "*" in the menues.

- Print Buffer
  print the whole buffer at once

- Print Region
  print the marked region at once

- Print Buffer Preview
  preview, what will be sent to the printer (whole buffer)

- Print Region Preview
  preview, what will be sent to the printer (marked region)

- Default Printer
  shows, which printer setting is the default one
  click on the shown printer to list its settings in a separate buffer

- Set Default Printer
  select a new default printer from the list of all defined printers 

- QuickPrint
  see below

- Show Printer Settings
  select a printer to list its settings in a separate buffer

- Show Print Log File
  shows a separate buffer containing log information generated by a2ps
  and print/preview commands
  should be helpful in case of errors
  Note: If an error occurs during printing this buffer will be shown
  automatically (not under Windows). Windows users should check this log file
  manually, because error handling in Windows seems not to work properly.

- Current Settings in apsconf format
  list settings of the current printer in a separate buffer
  The data format of the settings is the same as to be used in apsconf.sl
  
- Create Style Sheet
  see below

- Show apsmode Settings
  shows current apsmode settings, e.g. global variables
  
- Help apsmode
  this help
  
- About apsmode
  shows apsmode version


QuickPrint
----------
Sometimes it is necessary to change some printer settings "on the fly" in jed.
This can be done by using QuickPrint as printer setup. QuickPrint settings can
be copied from a defined printer setting (see apsconf.sl), but will not
be saved after leaving jed.

Example:
Suppose your printer settings creates double-sided output, but you need
a single-sided one.
- Menu: QuickPrint --> Set QP as Copy of setup --> select a printer setup (this copies
  the printer settings to QuickPrint)
- Menu: QuickPrint --> Set QP as default printer --> select QuickPrint as
  the default printer
- Menu: QuickPrint --> 2 Sides --> select 1
Now the printout will be single sided.


QuickPrint Menu Description
---------------------------
Since apsmode V2.2 QuickPrint menus are context sensitiv. That means, that
the current defined settings will be shown in the QuickPrint menu.

- Orientation
  defines the paper orientation
  portrait, landscape
  
- Paper Format
  defines the paper format
  A4, A3, Letter
  
- No Columns
  defines number of page columns paper side
  could be 1,2,3,4
  
- No Rows
  defines number of page rows per paper side
  could be 1,2,3,4
  
- 2 Sides
  defines single-sided/double-sided printing
  1 - single-sided, 2 - double-sided
  
- Copies
  defines number of copies to be printed
  1-10
  
- Fontsize
  defines the fontsize in points
  6, 7, 8, 9, 10, 11, 12
  14, 16, 18, 20, 22, 24, 26, 28,
  36, 48, 72

- Max Characters
  defines min:max number of characters per line
  0:80
  0:100
  0:132
  80:100
  80:132

- Truncate Lines
  defines, whether long lines should be truncated or not
  (check esp. with your MS Windows a2ps, what the correct value is)
  on, off
  
- Linenumbers
  print linenumbers every nth line
  0-10
  
- Borders
  defines, whether borders should be used per page
  on, off
  
- Margin
  define the margin in points
  0...12
  
- Print Direction
  defines print direction for multi-pages on one paper sheet
  columns, rows
  
- Color
  defines, whether to print in black/white or color
  bw, color
  
- Pretty Printing
  defines, whetehr a2ps should use pretty-printing
  on, off

- Header
  defines the header printed by a2ps

- Title Left
  defines the left title to be printed

- Title Center
  defines the center title to be printed

- Title Right
  defines the right title to be printed

- Footer Left
  defines the left footer to be printed

- Footer Center
  defines the center footer to be printed

- Footer Right
  defines the right footer to be printed

- Print Command
  defines the print command directly (e.g. can be used to access another 
  printer in the network)
  commands depends on operating system (will be derived from printer setups)

- View Command
  defines the view command directly
  commands depends on operating system (will be derived from printer setups)

- Set QP as Copy of setup
  copy printer settings to QuickPrint
  (will be derived from printer setups)

- Set QP as default printer
  sets QuickPrint as the default printer

apsconf.sl
--------------
This is a separate sl file, containing printer settings as array entries.
The entries itself will be described in apsconf.sl or in "Printer Definition
Example". (see there for more information).
In general these settings define a2ps parameters. So see also a2ps
documentation for more details (e.g. title definitions).

Create a new printer setup with the help of QuickPrint
------------------------------------------------------
An easy way to create a new printer setup would be the usage of QuickPrint
settings:
- Set QuickPrint as the default printer via menu
  "Set Default Printer --> QuickPrint"
- Modify QuickPrint Settings via menu
  "QuickPrint --> Orientation, Number of..."
- get the current settings in apsconf format via menu
  "Current Settings in apsconf format"
- Copy the contents of this buffer in your local apsconf.sl file
  (and do further adaptions there if necessary).


a2ps Style Sheets
-----------------
a2ps uses style sheets for syntax-highligthing of the printout. Not for every
jed language mode a corresponding a2ps style sheet exists by default. 
If syntax-highlighting of a jed language mode is required an a2ps style sheet
has to be created. 
apsmode supports this by extracting keywords and comment definition from 
the language mode definition. (It scans the sl mode file for syntax 
definitions. DFA syntax highlighting will not be taken into account!)
After extracting the keywords and/or comment definition an a2ps style sheet
will be created, named <mode-name>.ssh. The directory can be selected by the
user.
This is a very basic (rudimentary) a2ps style sheet, which can be enhanced
manually by adding a2ps instructions (see a2ps documentation for details).
To be able to use this style sheet apsconf.sl has to be modified.

Add a new entry to the following array (near the beginning of apsconf.sl) 

Apsmode_style_sheet["<my_mode>"] = 1;

where <my_mode> is the mode name of the mode for which jed-generated style 
sheet should be used.
<my_mode> has to be exactly the mode name (take care of upper/lower case).


- included style sheets
  apsmode includes a SLang.ssh style sheet. This is a very basic one.
  Paul Boekholt provided a much better one with his a2ps-mode (see below).

- additional style sheets created by Paul Boekholt
  Paul provided an a2ps jedmode for editing a2ps style sheets, which requires 
  a2ps v4.13. (http://jedmodes.sourceforge.net/mode/a2ps). It includes
  already style sheets for slang and tm.
  * SLang.ssh
    You can use his style sheet by copying it into jed_library_path. Be sure
    to name it SLang.ssh.
  * tm.ssh
    slangtm.ssh is another style from Paul for printing tm documentation.
    For usage copy it into jed_library_path and rename it to tm.ssh.
    Add a new entry in apsconf.sl
       Apsmode_style_sheet["tm"] = 1;
       


Variable Definition for Printer Settings
----------------------------------------

%%%%%%%%%%%%%%%%%% Define printers %%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 
% This structure contains the printer settings for apsmode.sl
% Most of the settings are directly copied from a2ps options
% See a2ps documentation for further details.
% These settings have been tested with:
% - UNIX      : a2ps v4.12
% - MSWINDOWS : a2ps v4.13b
% 
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% JED<XYZ> variables used as placeholder for print options
% 
% name       : JEDFILENAME
% description: use this variable in footer/header definitions to print
%              the path/name of the buffer to be printed
%              do not use "$f" option of a2ps, because this will print
%              the name of the temporary print file instead of the name of 
%              the buffer
% 
% name       : JEDDATETIME
% description: use this variable in footer/header definitions to print
%              the current date, time of the buffer print formatted
%              as YYYY-MMM-DD, HH:MM:SS
%              this is a replacement for the "%e %*" option of a2ps
%              which seems to not work correctly under MSWINDOWS
%              Correction: with apsmode V1.4 options for Windows are 
%              correctly send to a2ps, so "%e %*" should work
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 
% name       : setup
% description: printer id
%              this will be used as program internal identifier for 
%              the print setup
% value(s)   : integer, incremented by 1
% 
% name       : setupname
% description: that's the name of the printer setup, which will be used as 
%              identifier
%              should not be too long, because it will be used within 
%              the menus
% value(s)   : text
% example    : "code 2x1x1, A4"
% 
% name       : name
% description: physical printer name as known by the OS
% value(s)   : text
% example    : "114_f004"
% 
% name       : description
% description: Your information about the printer setup
% value(s)   : text
% example    : "This is an example description"
% 
% name       : columns
% description: specify the number of columns of virtual pages per physical page
% value(s)   : integer (1...n)
% example    : "2"
% 
% name       : rows
% description: specify the number of rows of virtual pages per physical page
% value(s)   : integer (1...n)
% example    : "2"
% 
% name       : fontsize
% description: defines fontsize in points
%              if other formats than points needs to be supported 
%              by QuickPrint then function <set_qp_fontsize_callback> has to be 
%              modified accordingly
% value(s)   : 8,...,72 points, anything your printer and a2ps supports
% example    : "8points"
% 
% name       : chars
% description: number of characters to be printed on one line
%              format = min:max
%              min - minimum of characters to be printed
%              max - maximum of characters to be printed
% value(s)   : Integer:Integer
% example    : "80:100"
% 
% name       : borders
% description: switches border printing around each page on/off
% value(s)   : on,off
% example    : "on"
% 
% name       : orientation
% description: defines sheet orientation
% value(s)   : portrait,landscape
% example    : "portrait"
% 
% name       : medium
% description: defines print medium (sheet size)
%              if other formats than a3, a4, letter needs to be supported 
%              by QuickPrint then function <set_qp_medium_callback> has to be 
%              modified accordingly
% value(s)   : a4, a3, letter, ..., anything your printer and a2ps supports
% example    : "a4"
% 
% name       : sides
% description: printing on one/both sides of a sheet
% value(s)   : 1,2
% example    : "2"
% 
% name       : truncate
% description: truncate lines, if they are longer than maximum number of 
%              printing characters
%              !!! ATTENTION !!!
%              try on/off values with your a2ps installation
%              there seems to be a bug in different a2ps version 
%              and/or OS version
%              UNIX     , a2ps v4.12  : truncate=on does not truncate
%              MSWINDOWS, a2ps v4.13b : truncate=off does not truncate
% value(s)   : on,off
% example    : "on"
% 
% name       : linenumbers
% description: add linenumbers every x line to your printout
%              helpful for program code
%              switch off with value 0
% value(s)   : 0...n
% example    : "5"
% 
% name       : copies
% description: number of copies to be printed
% value(s)   : 1...n
% example    : "1"
% 
% name       : major
% description: specify whether the virtual pages should be first filled in 
%              rows (direction = rows) or in columns (direction = columns).
% value(s)   : rows,columns
% example    : "columns"
% 
% name       : margin
% description: Specify the size of the margin (num PostScript points, 
%              or 12 points without arguments) to leave in the inside 
%              (i.e. left for the front side page, and right for the back 
%              side).  This is intended to ease the binding.
% value(s)   : 0...n
% example    : "5"
% 
% name       : header
% description: sets the page header
% value(s)   : text
% example    : "Your Page header"
% 
% name       : title_left
% description: Set virtual page left title to text
%              see a2ps documentation for more detailed options
% value(s)   : text and/or a2ps options
% example    : "%e %*"
% 
% name       : title_center
% description: Set virtual page center title to text
%              see a2ps documentation for more detailed options
% value(s)   : text and/or a2ps options
% example    : "$f", "JEDFILENAME"
% 
% name       : title_right
% description: Set virtual page right title to text
%              see a2ps documentation for more detailed options
% value(s)   : text and/or a2ps options
% example    : "%s./%s#"
% 
% name       : footer_left
% description: Set virtual page left footer to text
%              see a2ps documentation for more detailed options
% value(s)   : text and/or a2ps options
% example    : "%e %*"
% 
% name       : footer_center
% description: Set virtual page center footer to text
%              see a2ps documentation for more detailed options
% value(s)   : text and/or a2ps options
% example    : "$f"
% 
% name       : footer_right
% description: Set virtual page right footer to text
%              see a2ps documentation for more detailed options
% value(s)   : text and/or a2ps options
% example    : "%s./%s#"
% 
% name       : color
% description: switches color printing on/off
%              bw - Style is plain: pure black and white, with standard fonts
%              color - Colors are used to highlight the keywords
% value(s)   : bw,color
% example    : "color"
% 
% name       : pretty
% description: switches pretty printing feature of a2ps on/off
% value(s)   : on,off
% example    : "on"
% 
% name       : print_cmd
% description: string containing the OS specific command to send the created
%              postscript file to the physical printer
%              could also be a ghostview command if direct printing 
%              is somehow not supported
% value(s)   : text
% example    : strcat("lpr -P ", Apsmode_Printers[setup].name, " ", Apsmode_tmp_file)
% 
% name       : view_cmd
% description: string containing the OS specific command to view the created
%              postscript file (ghostview preferred)
% value(s)   : text
% example    : strcat("gv ", Apsmode_tmp_file)
%              strcat("gsview32.exe ", Apsmode_tmp_file);
% 
% name       : copy_of
% description: internal variable, which is needed for QuickPrint settings
%              has to be 0, don't change it
% value(s)   : 0
% example    : "0"
% 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


Printer Definition Example
--------------------------
create your own apsconf.sl file from apsconf.template similar to the 
example below and load it via
() = evalfile("apsconf.sl"); % full path or
                             % relative to jed-library-path


% Don't forget to define a private variable 'setup' in your local apsconf file;
% private variable aps_id = 0;

setup++;
Apsmode_Printers[setup].setupname = "code, A4, 6pt, 2x1, duplex, CCB_3_F008";
Apsmode_Printers[setup].name = "CCB_3_F008";
Apsmode_Printers[setup].description = "Printer 1";
Apsmode_Printers[setup].columns = "2";
Apsmode_Printers[setup].rows = "1";
Apsmode_Printers[setup].fontsize = "6points";
Apsmode_Printers[setup].chars = "80:100";
Apsmode_Printers[setup].borders = "on";
Apsmode_Printers[setup].orientation = "landscape";
Apsmode_Printers[setup].medium = "A4";
Apsmode_Printers[setup].sides = "2";
Apsmode_Printers[setup].truncate = "on";
Apsmode_Printers[setup].linenumbers = "5";
Apsmode_Printers[setup].copies = "1";
Apsmode_Printers[setup].major = "columns";
Apsmode_Printers[setup].margin = "5";
Apsmode_Printers[setup].header = "";
Apsmode_Printers[setup].title_left = "";
Apsmode_Printers[setup].title_center = "";
Apsmode_Printers[setup].title_right = "";
Apsmode_Printers[setup].footer_left = "JEDDATETIME";
Apsmode_Printers[setup].footer_center = "JEDFILENAME";
Apsmode_Printers[setup].footer_right = "%s./%s#";
Apsmode_Printers[setup].color = "bw";
Apsmode_Printers[setup].pretty = "on";
Apsmode_Printers[setup].print_cmd = strcat("lpr -P ", Apsmode_Printers[setup].name, " ", Apsmode_tmp_file);
Apsmode_Printers[setup].view_cmd = strcat("gv ", Apsmode_tmp_file);
Apsmode_Printers[setup].copy_of = 0;


apsconf: Changes from V1.5 --> 2.2
----------------------------------
In apsmode V2.2 a lot of variable names have been changed.
Global variables are now named "Apsmode_<xyz>".
For existing apsconf.sl files the following variable name changes
have to be applied:
a2ps_cmd                 --> Apsmode_a2ps_cmd
aps_del_ps_file          --> Apsmode_del_ps_file
aps_menu                 --> Apsmode_menu
aps_tmp_dir              --> Apsmode_tmp_dir
aps_tmp_file             --> Apsmode_tmp_file
default_printer          --> Apsmode_default_printer
printer                  --> Apsmode_Printers
use_jed_a2ps_style_sheet --> Apsmode_style_sheet
printer[].setup          --> Apsmode_Printers[].setupname
aps_pid                  --> setup

setup has to be a private variable in apsconf.sl (see apsconf.template)