K PDF Writer library

Every function takes a reference to a variable that represents the document
being built (`doc).


/ Initialization.

pdfw.init
   [`doc]
   Must be called exactly once at the start of a document.  The doc variable
   will be cleared.  No limit on number of simulaneous documents.


/ Document information.

pdfw.info.author
   [`doc;string]
   string:"Author (person) name"

pdfw.info.cdate
   [`doc;date]
   date:_t

pdfw.info.mdate
   [`doc;date]
   date:_t

pdfw.info.creator
   [`doc;string]
   string:"Creator name (original document title)"

pdfw.info.producer
   [`doc;string]
   string:"DFA K PDF Writer"

pdfw.info.title
   [`doc;string]
   string:"PDF document title"

pdfw.info.subject
   [`doc;string]

pdfw.info.keywords
   [`doc;string]


/ Page creation.

pdfw.page.init
   [`doc]
   Initializes the page tree structure.  Called automatically when pdfw.init
   is called.

pdfw.page.begin
   [`doc]
   Initializes a new page.  Must be called before any content is added.
   Nested start/end calls form page trees.

pdfw.page.end
   [`doc]
   Must be called at the end of the page or page tree definition, to perform
   cleanups.

pdfw.page.mediabox
   [`doc;rect]
   Defines the size of the media box for the current page (or all pages under
   the current tree node, if no page is active).  The media box is the size of
   the piece of paper.  This value must be set or inherited from the tree.

pdfw.page.cropbox
   [`doc;rect]
   Defines the size of the crop box for the current page or tree node.  The
   crop box is the size of the page should be cut down to after printing.

pdfw.page.rotate
   [`doc;degrees]
   Sets how the page will be rotated at display time, in clockwise degrees
   for the current page or tree node.

pdfw.page.lastmodified
   [`doc;_t]
   Sets modified date for the current page.

pdfw.page.artbox
   [`doc;rect]
   Sets the art box for the current page.  The art box is the box used to
   place PDF content into another application.

pdfw.page.trimbox
   [`doc;rect]
   Sets the trim box for the current page.  The trim box is the box in which
   the content of the page appears.

pdfw.page.bleedbox
   [`doc;rect]

pdfw.page.preferredzoom
   [`doc;scale]


/ Graphics state.

pdfw.gs.save
   [`doc]

pdfw.gs.restore
   [`doc]

pdfw.egs.gsdict
   [`doc;dict]
   Adds and activates a graphics state dictionary to the current page.


/ Global transformation matrix.
pdfw.ctm.matrix
   [`doc;a b c d x y]

pdfw.ctm.translate
   [`doc;x y]

pdfw.ctm.scale
   [`doc;x y]

pdfw.ctm.rotate
   [`doc;angle]
   Angle is in degrees.

pdfw.ctm.skew
   [`doc;a b]
   Angles are in degrees.

pdfw.ctm.rotate_rad
   [`doc;angle]
   Angle is in radians.

pdfw.ctm.skew_rad
   [`doc;a b]
   Angles are in radians.


/ Patterns.

pdfw.pattern.???


/ Color.

pdfw.color.fill_gray
   [`doc;gray]

pdfw.color.stroke_gray
   [`doc;gray]

pdfw.color.fill_rgb
   [`doc;r g b]

pdfw.color.stroke_rgb
   [`doc;r g b]

pdfw.color.fill_cmyk
   [`doc;c m y k]

pdfw.color.stroke_cmyk
   [`doc;c m y k]

pdfw.color.fill_color
   [`doc;color array]

pdfw.color.stroke_color
   [`doc;color array]

pdfw.color.fill_cs
   [`doc;colorspace]
   colorspace:`DeviceGray | `DeviceRGB | `DeviceCMYK | predefined pattern name

pdfw.color.stroke_cs
   [`doc;colorspace]
   colorspace:`DeviceGray | `DeviceRGB | `DeviceCMYK | predefined pattern name


/ Current point & shape drawing.

pdfw.path.moveto
   [`doc;x y]

pdfw.path.lineto
   [`doc;x y]

pdfw.path.curveto
   [`doc;x1 y1;x2 y2;x3 y3]

pdfw.path.rect
   [`doc;x y w h]

pdfw.path.closepath
   [`doc]

pdfw.path.clip
   [`doc;rule]
   rule:`nz or `eo

pdfw.path.paint
   [`doc;params]
   params:`newpath, or `stroke and/or `fill
          if `stroke, add optional `nz (default) or `eo,
                      add optional `closepath and/or `fill


/ Line drawing parameters.

pdfw.line.flatness
   [`doc;pixels]

pdfw.line.cap
   [`doc;style]
   style:`butt | `round | `square

pdfw.line.dash
   [`doc;array;phase]
   array is on/off pattern (vector)
   phase is distance into array to begin

pdfw.line.join
   [`doc;style]
   style:`miter | `round | `bevel

pdfw.line.width
   [`doc;width]

pdfw.line.miter_limit
   [`doc;limit]


/ Font controls.

pdfw.font.add_type1
   [`doc;base;encoding]
   base:Must be one of the 'standard 14':
        Courier, Courier-Bold, Courier-BoldOblique, Courier-Oblique,
        Helvetica, Helvetica-Bold, Helvetica-BoldOblique, Helvetica-Oblique,
        Times-Roman, Times-Bold, Times-BoldItalic, Times-Italic,
        Symbol, ZapfDingbats
   encoding:one of: MacRomanEncoding,MacExpertEncoding,WinAnsiEncoding, or _n


/ Text wrappers.

pdfw.text.begin
   [`doc]

pdfw.text.end
   [`doc]


/ Text parameters.

pdfw.text.char_spacing
   [`doc;units]
   units:intracharacter text-space units

pdfw.text.word_spacing
   [`doc;units]
   units:text-space units to add to space character width

pdfw.text.horiz_scale
   [`doc;scale]
   scale:percent to horizontally scale text

pdfw.text.leading
   [`doc;units]
   units:line height

pdfw.text.font
   [`doc;name;size]
   name:`Courier | `Helvetica | ...
   size:point size

pdfw.text.render_mode
   [`doc;mode]
   mode:zero or mode of `fill`stroke`clip

pdfw.text.rise
   [`doc;units]
   units:text-space units to move text baseline


/ Text matrix. (Tm)

pdfw.text.matrix
   [`doc;a b c d x y]

pdfw.text.translate
   [`doc;x y]

pdfw.text.scale
   [`doc;x y]

pdfw.text.rotate
   [`doc;angle]
   Angle is in degrees.

pdfw.text.skew
   [`doc;a b]
   Angles are in degrees.

pdfw.text.rotate_rad
   [`doc;angle]
   Angle is in radians.

pdfw.text.skew_rad
   [`doc;a b]
   Angles are in radians.


/ Text current point/matrix.

pdfw.text.move (Td)
   [`doc;x y]
   effectively same as pdfw.text.translate

pdfw.text.nl (T*)
   [`doc]
   requires that leading have been set
   effectively same as pdfw.text.move[`doc;0 leading]

pdfw.text.leading_nl (TD)
   [`doc;x y]
   same as pdfw.text.leading[`doc;y];pdfw.text.move[`doc;x y]


/ Text rendering.

pdfw.text.show (Tj)
   [`doc;string]

pdfw.text.nl_show (')
   [`doc;string]
   newline occurs *before* show, not after

pdfw.text.nl_show_wc (")
   [`doc;word;char;string]
   set word and char spacing then newline and show string

pdfw.text.show_dyn (TJ)
   [`doc;spacing/string list]
   list:alternating strings/character spacing
        e.g., (120;"T";90;"his is ";95;" a test")


/ External objects.

pdfw.xobj.placeimage (Do)
   [`doc;w;h;cs;bpc;filter;pixmap]
   w:width of pixmap
   h:height of pixmap
   cs:colorspace bitmap is drawn in
   bpc:bits per component
   filter:filter used to compress pixmap or _n
   pixmap:vector of binary image data
   
   Image is drawn at current point, in a 1x1 point box.  User should probably
   gs.save, ctm.translate, ctm.scale, xobj.placeimage, gs.restore


/ Render page.

pdfw.render
  [`doc]
  Generate PDF and return it as a character vector.

pdfw.print
  [`doc;panel]
  panel:boolean to pop up a print preferences panel
  
  Generate PDF, save to TMP file, and request Acrobat to print it.  panel
  option may not work under non-Acrobat readers.

pdfw.view
  [`doc]
  Generate PDF, save to TMP file, and spawn Acrobat (or other PDF viewer).