This program stitches together PDF elements into a single page - elements such
as Ads, folios, rules and/or whole pages for Page Pairing.

It uses a parameter file in tables/form. This can be selected from the DF
FipHdr file and defaults to PDF_GLUE.FIP

Keywords for the parameter file are :
    ; comment line
    newname: (new name for the output file)         default: the same as input
    supercede: yes/no Overwrite the output if it exists default: do not
    outque: output queue for the new file.          default: spool/2go or -o switch
    doneque: done queue for the old file.           default: none or the -d switch
    dest:   Destination (as in sys/USERS)           default: none
    extra-fiphdr:   more fixed Fip Hdr fields to add to the file (before any new
matched additions)
                                default: none
    duplicate-output: make extra copies of the output   default: one single copy
        eg  duplicate-output:\PZ
        Here the FipHdr field PZ is checked and if the contents are 2 or more, the
output is duplicated that many times
        Otherwise a single output file only is created.
        FipHdr field S3 holds the copy number - so it can be used to make a unique
filename later on.
    script: script to run against the New file.     default: none
    log-line: extra logging information for the Fip log default: none
        Logging is done at the end of each page
            EN is filename
            EP is path
            S1 MAY be the size
            S2 is the pagenumber of pages generated from this input file
            S3 is the number of this particular copy when multiple
copies/duplicate-output are requested
        replacement string for each filename to include
        PM: display name
        PX: x pos
        PY: y pos
        PW: width
        PL: length
        PN: name
        possible, option ext for the file
        ie try both with and without

    force-pdf-version: (0-14)
        force thePDF version to be this
        0 -> 9 for pdf 1.0 to pdf 1.9
        10-14 for PDFx1 PDFx3 and PDFa

    default-media-area: (FipSeq to define 4 values of 0, 0, width, depth)
        Defaults for total area to be imaged - including white space around any
imagae/bleed area

    default-image-area: (FipSeq to define 4 values of offset bottom x, offset
bottom y, width, depth)
    default-bleed-area: (FipSeq to define 4 values of offset bottom x, offset
bottom y, width, depth)
        Defaults for total area that can be imaged - the first 2 are the offset (pos)
from the bottom left corner of the media area.
        These 2 are exactly the same thing.

    default-page-area: (FipSeq to define 4 values of offset bottom x, offset
bottom y, width, depth)
    default-ad-area:   (FipSeq to define 4 values of offset bottom x, offset
bottom y, width, depth)
    default-trim-area: (FipSeq to define 4 values of offset bottom x, offset
bottom y, width, depth)
        Defaults for normal area that can be imaged - the first 2 are the offset
(pos) from the bottom left corner of the media area.
        These 3 are exactly the same thing.

    show-missing-ads: (yes/no)
        Display the name of the missing ad in the box   default: yes
    missing-ad-comment: Replacement text/FipSeq for when the ad is missing
        default is just the name:   missing-ad-comment:\PM
        To use the comment field    missing-ad-comment:\PM - \PF
    missing-colour: (C, Y, M, K)
        define the colour of background for any missing ad
        the 4 values are in the range 0-255
        default is a tasty papayawhip : 0, 20, 100, 0
    font-path: (path)
        Copy your user fonts into a directory and add it then to the list of search
        Otherwise, only the 14 standard fonts can be used.
        This is ignored in the Windows version as all fonts MUST be put in the System
Fonts folder
    use-standard-fonts: y/n
        use the 14 standard fonts (TimesRoman, Helvetica, etc) - yes or no - default
is yes
        turn this off if you are ONLY using custom fonts.
    embed-fonts: y/n
        NO - turn this off if you do NOT want to embed the fonts in the file (for
some reason !)
        default is YES
    default-font: (name of default font)
    default-font-name: (name)
        This should match exactly the PSname of the font
        Default is the first system font
        Default of defaults is 'Helvetica'

    replace-folio-string:(FipSeq)   (Replacement string in FipSeq)
        There can be up to 10 replacements

    pick-tray: (yes/no)
        Pick tray by PDF size       default: output device default
    print-scaling: (yes/no)
        Scale the output to fit     default: output device default
    set-resolution: (number from 72 to 2048 dpi)
        set the output resolution   default: 150 dpi
    use-transparency: (yes/no)
    transparency-colour: (hex value)
    transparency-color: (hex value)
        Set/configure transparency
        default is (for PDF 1.4 on) transparency is ON and rgb_white (0xFFFFFF) is
the colour
    add-pdf-comment: (CommentKey) = (FipSeq) [optsep (|) opt (2ndKey) = (FipSeq) ]
        Add Comment to PDF page
        The structure is Key = Value.  Multiple key=value may be added using a '|' as
a separator.
        add-pdf-comment:Author=\SA|Producer=Fip at pubo|Agfa-SpreadType=JUMP
        Note that user-defined keys should be defined as 7 bit ASCII string and the
use of special characters like /, \, #, or character codes higher than 127
should be avoided. The value of document info entry should not contain binary
    compression-level: (0,1,2,3)
        Set the Compression level (see dynapdf book !)  default: 1
        (0-none, 1-default, 2-fastest, 3-max)

Where sections of FipHdr fields are required or changes to the output style,
use keywords : fixed, partial, combie, optional, repeat, newdate and/or style.
(see The SysAdmin manual for more information).

    They are normally specified :
        fixed:QZ    1234543
        partial:QT  ST,3,2,U,<,>
        combie:QY   ep|na,(0000000)a
        option:QE   ep,11,7,s
        repeat:QK   XK,-,3
    or  repeat:QP   PK,,4,#X
        style:QS    XN,%.03d

The FipHdr of the incoming file can also be used to change the
        Add/Dont add the FipHdr to the output file  default: add
        Output folder to override the -o Input switch   default: /fip/spool/2go
            which overrides the "output:..." parameter
        Done folder to override the -d Input switch default: none
            which overrides the "doneque:..." parameter

Input Parameters are (all optional) :
    -1 : path/filename for single shot      default: spooled
        The input file is NOT deleted
        If this does NOT start with a '/', it is assumed relative to the current
    -i : input queue                    default: spool/2pdfglue
        If this does NOT start with a '/', it is assumed under spool.
    -B : show all valid BBoxes/Areas            default: do not
        Use this for debugging troublesome Bounding Boxes !
        Generally it is ONLY used with the -1 single file option as it is NEVER
required for live working !
        NOTE that Media and any other area set to the same are normally invisible as
it is outside the main printed area by definition
        Fixed colours are used :
            - Media - black
            - Crop  - purple
            - Bleed - cobalt blue
            - Trim  - kermit green
            - Art/Ad/Edit - orange
    -d : done folder for the input file in FipSeq       default: none
        If this does NOT start with a '/', it is assumed under spool.
    -f : display Fip markup and results default: spooled
        The display is to the screen (ie NOT the log file), so just run manually in a
CMD or terminal on its own
    -F : display Font names, calls and success in matching  default: spooled
        The display is to the screen (ie NOT the log file), so just run manually in a
CMD or terminal on its own
    -L : do NOT log files in                default: log
    -N : Name of output file            default: input filename with some extra dedup
        This option overwrites the parameter 'newname'
    -o : output queue                   default: spool/2go
        If this does NOT start with a '/', it is assumed under spool.
    -w : file wait for files arriving across a network. default: no wait
    -z : default parameter file in tables/setup     default: tables/form/PDF_GLUE.FIP
    -v : print version number and exit


Windows install

- add dynapdf DLLs to some folder in your PATH environment - but not /fip/bin !
Normally this will be /fip/3rdparty or (in extremis) c:\WINDOWS\

DataFile syntax

The data file is a series of single lines witha TYPE in the first field.
    All fields are TAB separated.
    All Lines MUST have an end of line added : '\n' or '\r\n'

PAGE    - start page and add FipHdr (usually FipHdr info about the page)
    syntax  PAGE (tab) (FipHdr in FipSeq)
    eg  PAGE (\t)

FIPHDR  - extra FipHdr info
    syntax  FIPHDR (tab) (FipHdr in FipSeq)
    eg  FIPHDR\t#PJ:\PJ#ZN:\ZN#ZW:\ZW#JN:\JN#JC:\JC#JR:\JR#\n

BANNER  - some FipSeq for a Banner at the top of the page (usually above/below
the Trim area_
    syntax  BANNER (tab) (Markup)
    eg  BANNER\t<q:z><m:8><q:z><j:8><q:z><n: Region code.JR-\JR-
\\PN Publication \\PP Section \\PS Edition \\ZD-\\ZT-\\ZZ at \\$d-\\$m-\\$e\\$y

MEDIAAREA   - Complete printable/visable area : see also below for more on Areas
CROPAREA    - Crop area
IMAGEAREA   - Bleed or Image areas (these are equivalent)
BLEEDAREA   - Bleed or Image areas (these are equivalent)
PAGEAREA    - Page or Trim areas (these are equivalent) - usually page is to be
cropped to this
TRIMAREA    - Page or Trim areas (these are equivalent) - usually page is to be
cropped to this
ADAREA      - Ad or Editorial area
    syntax  (xx)AREA (tab) - (tab) (x pos) (tab) (y pos) (tab) (width) (tab)
    eg  MEDIAAREA\t-\t\C5\t\C6\t\C7\t\C8\n
        MEDIAAREA - -75 -60 450 600\n
    If different, always specify MEDIA first, then BLEED then TRIM

    ** NOTE the only mandatory one for PDF is the MEDIA area; so if you do NOT
specify any areas, ippdfglue will generate one for you.

FILE        - Insert the contents of a PDF at this point
MISS        - Blank the area and put a missing element message in the bottom left
    syntax  FILE (tab) (filepathname) (tab) x (tab) y (tab) width (tab) height
    eg  MISS    PDF_ADS/CLASSIFIED/03/2447727-470708063 478.35  234.99  281.34  198.43

MARKUP      - Markup to generally add to a page eg with an
FIPSGML     - all 3 are exactly the same
    syntax  MARKUP (tab) (Markup in FipSmgl/FipSeq)
    eg  MARKUP <n: Region code.JR-\JR-

RULE        - Draw a rule
    syntax  RULE (tab) - (tab) x (tab) y (tab) width (tab) height
    eg  RULE    -   475.27  0.28    0.50    447.59

FOLIO   - Place a folio file
NOFOLIO - do NOT place a folio file - but trigger a startofpage
    syntax  FOLIO   (tab) - (tab) x (tab) y (tab) width (tab) height
    eg  NOFOLIO -   0.00    0.00    759.69  1020.47 0.00

COMMENT comment message to be added to the Fip ALL log
    syntax  COMMENT (tab)   (log message in FipSeq)
    As the comment can be in FipSeq, use this to log current FipHdr settings
    eg  COMMENT\tbx.\BX r8.\R8 r9.\R9 pw.LorR.\PW d6.\D6 d7.\D7 d8.\D8 d9.\D9
rx.\RX ry.\RY w6.\W6 w7.\W7 p3.\P3 p

Example :
MEDIAAREA   -   -34 -42.5   827.69  1094.17
TRIMAREA    -   -34 -42.5   827.69  1094.17
ADAREA  -   0   0   759.69  1020.47
BANNER  <q:z><m:8><q:z><j:8><q:z><n: Region code.JR-N- c/d.JW-->
FOLIO   -   0.00    0.00    759.69  1020.47 0.00    /fip/customer/folios_rm/MC-DEF-DEF-R.fip
FILE    PDF_Headings2PDF/4/025-6x6  2.13    1003.46 564.09  17.01
FILE    PDF_ADS/CLASSIFIED/03/2447696-470718516 1.77    0.00    277.80  481.89
FILE    PDF_ADS/CLASSIFIED/03/2447739-470723954 288.78  315.21  277.80  181.42
FILE    PDF_ADS/CLASSIFIED/03/2448075-470870481 287.01  99.50   281.34  184.25
MISS    PDF_Headings2PDF/4/600-3x6  288.78  293.10  277.80  17.01
MISS    PDF_Headings2PDF/4/426-3x6  0.1


There are 4. Which are in order of size (decending) :
- MEDIAAREA - complete printable area with gutters - this will be the actual
dimensions of the whole PDF.
- CROPAREA  - Crop (optional)
- BLEEDAREA - Bleed (optional)
- TRIMAREA  - Ad/Ed text area plus Folios (can also be called the PAGEAREA)
- ADAREA    - basic Ad and/or editorial page - this is mainly for informational
purposes only and is not really used. (optional)
Lower levels MUST be wholly contained by those above
All take 4 variable x, y, wid ht - where x,y are the lower left corner

It is an excellent idea to have the x,y of the TRIMAREA as 0,0 so that all ads,
text elements, headings, fillers etc - all included files can be placed without
any maths to calculate the offset !! In this case, if gutters are required, use
a neg value for x,y in the MEDIAAREA (and possibly BLEEDAREA)
MEDIAAREA   -   -34 -42.5   827.69  1094.17
BLEEDAREA   -   -34 -42.5   827.69  1094.17
PAGEAREA    -   0   0   759.69  1020.47
ADAREA      -   0   0   759.69  1020.47

Note that the width and height of the MediaArea is the whole surface area - any
miscalculations will expand/contract the overall PDF size.

Note that on a Linux, you can use 'pdfinfo' to check the actual Areas/Boxes :
    pdfinfo -box Classfied_Apr20_p30.pdf

- There are a few builtins for folios for <z: (passthru)>

    gsave       - maps to a PDF save (ie same effect as EPS)
    grestore    - maps to a PDF restore (ie same effect as EPS)
        - The maximum allowed nesting level of save/restore graphics state operators
in PDF is 28.
    setcmykcolor    - maps EPS setcmykcolour 0.00 to 1.00 to the same PDF colour for
CMYK : 0 to 255
    setgray     - maps EPS setgray to a PDF tint (0->1 is stretched to a tint of
    fip_pdf_circle  - one parameter = radius in points
              use <x: xlead> and <w: ws> to position exactly the bullseye beforehand
              use setcmykcolor to set the colour beforehand
    fip_pdf_chord   - p1 and p2 - width and height of containing box, p3 and p4 -
starting and ending angle
              use <x: xlead> and <w: ws> to position exactly the start point beforehand
              use setcmykcolor to set the colour beforehand
    rotate      - Note that EPS is counter-clockwise but PDF is clockwise : so the neg
has the opposite effect !
              use <x: xlead> and <w: ws> to position exactly the rotate point (esp for
QR and QC/QM)

Version Control
; 2u5   28sep13 ;a added embed-fonts: y/n and default-font-name ;c 7apr14 bugette
with zero chrs
        ;d 12apr14 rotate added
        ;e 14apr14 added MARKUP properly
        ;f-h 29apr14 added -N for default newname
        ;i-k 2may14 added -B to draw all the (valid) bounding boxes
        ;l 5aug14 default in BOX means zero NOT the last
        ;m 2sep15 added compress-level
        ;n-p 3nov15 added default black for Rules
        ;q 26jan16 reverted rules to 02m
        ;rs 15feb17 dyna v4
        ;tu 12mar19 added COMMENT to log ;u4-5 4jan24 fonts-use Unicode 1st/bugette
with MissingAds and added conversions
;01z    19apr11 folios/text version ;d-e added missingAd ;f 02jun11 rotated ad bug
;g letterspc ;h logging font errors
        ;i-k added -F, note/include pdf
        ;l for Folio, use name first and aliasName second
        ;m added default-font and bugette with WS - always need a new element
        ;n-o duplicate-output added
        ;p DrawCircle and DrawChord added
        ;q-t added replacement of pass thru ;u bug with fonts not resetting at start
of line
        ;v-w redid styles and passthrus and blocks and eles
        ;x 2apr13 added transparency
        ;yz 5aug13 added Comments and allow-std-fonts:y/n
;000q   10feb10 original version
    ;h rules better ;i added alias-name ;j-l added FipHdr, pdfVersion, pdfTitle
;m-p added text/folio etc

(copyright) 2024 and previous years FingerPost Ltd.