P3ICLI Change Log

v3.0 released 12/27/2016
    - Support for Windows XP dropped due to lack of testing resources.
    - Source code distribution now includes P3ICLI build documentation.
    - Repaired several long-standing Developer Studio build issues.
    - The insert slide "hardening" algorithm described in the v2.8
      release notes (see below) has been implemented for versions of
      PPT that predate Office 2010.
    - Bug fix: suppose a P3ICLI script starts PPT, pastes at least one
      slide (via an "insert slide" command), and does not kill that PPT
      instance before it exits.  In this scenario, the PPT instance
      becomes an orphan process (only visible in task manager) when PPT
      is manually closed by the user.  This problem (now fixed) only
      observed on a Win10 host with PowerPoint 2016 installed.
    - Bug fix: when copying a source slide to effect an "insert slide"
      command via Windows copy/paste, do not display a window when
      briefly opening the source presentation.  This change removes
      instability when non-PPT application windows are opened during
      P3ICLI script execution.
    - When P3ICLI makes or kills a connection with PPT, the relevant
      kill/connection logic is executed in a limited retry loop with
      progressively longer delays inserted after each failed attempt.
      This change (hopefully) future-proofs P3ICLI with respect to
      ever-faster PC hosts.
    - Added a new, optional command line switch that configures two
      parameters relevant for program operation on fast PC hardware.
      Syntax:

          -W{a|x}:<msecs>

      Semantics of -Wa:<msecs>

          Wait <msecs> milliseconds after transmitting an Asynchronous
          PPT command.  If unspecified, the default is 220.

      Semantics of -Wx:<msecs>

          Wait <msecs> milliseconds at program eXit when the -T or -X
          options are in effect.  If unspecified, the default is 256.

      The "wait" parameters are also configurable via environment
      variables.  The new Async Wait parameter addresses P3ICLI
      instability issues when "copy src fmt on" is in effect and
      "insert slide" commands are executed in an Office 2010 or later
      environment.  The instability is most prominent on a fast host
      (i.e., SSD storage, 6th gen processor, lots of RAM) running
      PowerPoint 2016.
    - Added new "Fast PC Considerations" section to the reference
      manual, which discusses (among other things) the aforementioned
      environment vars and the rationale behind the new command line
      options.
    - P3ICLI (p3icli.exe) and its installation package are now signed
      with a code signing certificate.  The signing certificate format
      (SHA256 digest) is recognized on Windows 7 and later hosts.

      Note 1: The p3icli.exe signing certificate is flagged as
      invalid on Windows XP, but P3ICLI is still functional.

      Note 2: The signed 3.0 release was not tested on Vista, but
      various documentation indicates that SHA256 is also flagged as
      invalid on that host as well.

v2.9 released 8/31/2016
    - New command added:

          encoding {ansi | utf8}

      Specifies the character set that may be used within a title or
      caption <qstring>.  To maintain compability with existing P3ICLI
      scripts, the default for this command is "ansi".  Example usage:

          encoding utf8
          open template c:\temp\demo.pot
          cap1 "a caption with embedded, nifty unicode chars"
          title 'a title with embedded, dazzling unicode chars'

      Note that this feature should make P3ICLI much more functional
      when preparing non-English presentations.

      Refer to the reference manual's description of this command for
      example caption and title strings that demonstrate use of actual
      unicode characters.  Feature motivated by questions from Georgia
      Morgan and Dan Soltman.
    - Added new "UTF-8 (aka Unicode) Encoding Hints" section to the
      reference manual.
    - Bug fix: do not use stat() to test the validity/accessibility of
      filenames prefixed with these strings:

          http://     https://     file://

      Amusingly enough, PPT can process files specified with these
      prefixes so long as the user has READ access.  Problem noted
      when examining logfiles generated by Chad Hoffman.

v2.8 released 3/31/2016
    - Bug fix: restructured "insert slide" implementation when "copy src
      fmt" is "on" such that PPT does not throw random exceptions. This
      longstanding bug affects Office 2010 and later (only).  Problem
      reported by Stephen Quadro.
    - Bug fix: following an "insert slide" command, reload slide state
      before selecting the last slide in the active presentation.  Problem
      appears to be specific to Office 2013 in a stress test environment.
    - Bug fix: while processing script errors, make internal state
      recognize there is "NO_TMPLT" when the current presentation is devoid
      of slides.
    - Hardened the "insert slide" implementation such that slide paste
      operations are repeated up to 4 times (w/o reporting an error)
      whenever PPT throws an exception in response to a paste request.
      With this change, P3ICLI gracefully recovers if some other app places
      non-slide data on the clipboard at the same time that PPT executes a
      paste command.

v2.7 (not released on SourceForge due to breakage of task scheduler
      functionality).

v2.6 released 1/24/2016
    - Bug fix: if filename suffix of "save as" command is .pptx, save in
      that format.  N/A for Office 2003.  Reported by Georgia Morgan.

    - New command added:

          third party fix {on | off}

      If "on", add special semantics for third party software that monitors
      and interferes with some PowerPoint operations.  Currently, the "on"
      state ensures that all insert slide operations are carried out via a
      clipboard copy and paste.  Default for this command is "off".

v2.5 released 12/29/2015
    - Bug fix: ignore UTF-8 (Unicode) Byte Order Mark (BOM) at beginning of
      file input.  Reported by Georgia Morgan.
    - Bug fix: don't exit if the 8-bit input stream includes a character with
      the high order bit set (i.e., non-ASCII input).  Discovered while fixing
      BOM bug.
    - Emit warning (only once) if the 8-bit input stream contains a character
      with the high order bit set.  Note that a warning is not issued when a
      BOM is encountered.

    - New commands added:

          custom property <qstring> = <qstring>
          custom property <qstring> = <int>
          custom property <qstring> = {yes | no}

      The above add a Text, Number or Yes/No custom property to the currently
      open presentation.  Additionally, if this notation is used, a Date
      custom property is added:

          custom property <qstring> = "date: <valid_date>"

      If this notation is used, the named property is deleted:

          custom property <qstring> = ""

      Examples of the latter two use cases:

          custom property "Tax Day" = "date: 2016/04/15"
          custom property "Tax Day" = ""        # delete Tax Day

v2.4 released 6/10/2015
    - Bug fix: when "copy src fmt" is on and "insert slide" is used to
      insert a template slide into an instance of PPT that includes only a
      single, default initialization slide (usually an "empty" slide),
      don't emit a runtime PPT error.  Reported by Mari Rossman while
      invoking p3icli with the -T command line switch.  Bug triggering
      conditions isolated by Georgia Morgan.  Note that due to the next
      change, the conditions under which this scenario might occur are
      now significantly reduced.
    - Kill the blank initial slide added to a presentation via the -T
      switch (requested by Georgia Morgan).
    - Added a new "Script Optimization Insights" section to the
      documentation, which describes computationally expensive
      features/idioms.

v2.3 released 5/29/2015
    - Added a -X option that forces P3ICLI to execute a "kill ppt discard"
      command after all script(s) are processed.  Useful if P3ICLI is run
      on a server.
    - The "Task Scheduler Caveats" section of the documentation was renamed
      to "Task Scheduler Hints/Caveats" and its content significantly
      expanded.
    - Hardened P3ICLI cleanup procedures associated with the -T and -X
      options. 
    - Tracing messages emitted by the -T switch are suppressed in the
      absence of a log file.
    - Bug fix:  don't prematurely exit during program cleanup while
      reporting a warning or information message.

v2.2 released 4/17/2015 (the Office 2013 workaround release)
    - "save as" command augmented with this new choice:

        save as pdf <filename>

      The new alternative save file format was added because Office 2013
      simply does not support saving presentations in html format.
    - New command added:

        slide size {4:3 | default}

      Office 2013 defaults to a 16:9 slide size aspect ratio, rather than
      the 4:3 ratio utilized by PPT for many, many years.  The newer ratio
      particularly impacts templates created pre-Office 2013, causing them to
      expand to a 13.33in width when accessed via the P3ICLI "insert slide"
      command.  The "slide size" command allows a reversion to a 4:3 aspect
      ratio under certain circumstances.  Consult the "slide size" syntax
      documentation for complete details.
    - Show example Office 2013 ALT TEXT location in P3ICLI documentation.
    - Do not trap negative integer arguments associated with the
      "{pic|cap|title} move" commands.  Instead, pass them as is to PPT.  In
      the case of rotated shapes, negative position arguments actually make
      sense (e.g., a title shape rotated 270 degrees might exhibit a
      negative "left" coordinate).
    - Bug fix: if a user manages to manually select the last slide in a
      presentation while P3ICLI is running and issues either variant of the
      "kill ppt" command, ignore a PPT "slide index out of range" runtime
      error when an attempt is made to delete the presentation's template
      slide.  This fix supports interactive testing.
    - More documentation corrections and clarifications.

v2.1 released 2/24/2015
    - New script commands added:

        pic<uint> move <int>,<int>
        pic<uint> size <uint>,<uint>

      These 2 commands provide the capability of moving and resizing a
      slide's picture shapes.  Size and position parameters are scaled in
      points (not inches or centimeters). Feature requested by Georgia
      Morgan.
    - For completeness sake, these commands were added as well:

        cap<uint> move <int>,<int>
        cap<uint> size <uint>,<uint>
        title move <int>,<int>
        title size <uint>,<uint>

      Note that resizing a caption and/or title has its limitations.  Refer
      to the documentation for further details.
    - New script command added:

        list geometries [<qstring>]

      Lists the dimensions and positions (in points) of the caption,
      picture, or title shapes on the template and current slides.  Slide
      bounds (width and height) are listed in points as well. Data is
      displayed on the console screen (stdout) unless a log file is
      specified on the P3ICLI command line.  In the latter case, the data
      is dumped into the log file.
    - Minor documentation clarifications and corrections.
    - Fixed longstanding bug:
          Start P3ICLI with no PPT instances running.  
          Issue a command that causes PPT to throw an exception (say, 
              opening a nonexistent template)
          P3ICLI correctly diagnoses the problem path (no such file or
              directory), and then exits.

v2.0 released 3/4/2014
    - Corrected build env so that p3icli runs on Windows XP.
    - Add examples to p3icli's -h output.
    - Add an example task scheduler command line to p3icli's formal 
      documentation.

v1.9 released 2/27/2014 (not released on SourceForge due to WinXP breakage)
    - Maximum number of captions allowed per slide bumped from 10 to 20.
    - Maximum number of pics allowed per slide bumped from 10 to 20 (change
      requested by Georgia Morgan).
    - Added a '-T' command line switch. Syntax:

                  -T waitmsecs 
                  
      Semantics:  assumes P3ICLI is running under the Windows Task Scheduler,
      which implies that before any script file(s) are processed:

      1) a single instance of PowerPoint is started, and
      2) that (new) PPT instance is allowed <waitmsecs> of time to cleanly
         initialize

      Note that after all script(s) are executed, P3ICLI implicitly
      executes a "kill ppt discard" command to avoid stranding "orphan"
      PowerPoint processes on the host computer.  Therefore, all script(s)
      run under the Task Scheduler must save all created presentations via
      the "save as" command or they will be lost.

      Example (waiting 15 seconds before a script is executed):

            p3icli -l c:\temp\log.txt -T 15000 c:\temp\script.txt

      Tested with the Win XP, Win7, and Win8 Task Schedulers.  This feature
      is not guaranteed to work on all hosts, since running an Office
      product under the Task Scheduler is not supported by Microsoft
      (google "microsoft article 257757" for details).  Note that when
      the -T switch is specified, program initialization is periodically
      annotated in the log (with a timestamp) up to the point at which
      script processing begins.  After all scripts are processed,
      annotations resume during P3ICLI's cleanup and shutdown phase.  These
      annotations serve as a debugging aid for further (future) P3ICLI mods
      that might make Task Scheduler execution more robust.  Task Scheduler
      compatibility was requested by Joel Fenner.
    - Bugfix: "remove comments" only removed a single slide comment when
      used in conjunction with Office 2010.
    - Application build env moved to Visual Studio 2012.
    - P3ICLI verified to work on Windows 8 (tested with Office 2010 only).

v1.8, released 7/14/2012
    - Support for Office XP dropped due to lack of testing resources.
      Even though P3ICLI may still work with Office XP, no support is
      offered for any problems that may be noted.
    - bugfix: In an Office 2010 environment, P3ICLI aborted when no instance
      of PPT was running and a script contained this sequence of commands:

          copy source format on
          insert slide <uint> from template <filename> 

      Put another way, P3ICLI aborted when copy source formatting was enabled
      and template slides were selected via the "insert" command. The
      "open template" command was not impacted.
      
                                 P3I Users Note
                                 ==============
      Due to this bug, P3I failed to create a new presentation when the 
      "Copy Source Formatting" feature was enabled and no running instance
      of PPT 2010 existed.
    - bugfix: In an Office 2010 environment, the "Copy Source Formatting"
      feature didn't copy very many attributes from source template slides.
      Missing attributes included (but were not limited to):  gradient fills,
      textured fills, pattern fills, and picture fills.  This bug also 
      affected all P3I users who enabled the Copy Source Formatting feature.
      Georgia Morgan discovered the (nifty) solution to this problem.
    - Updated documentation to show how to add Alternative Text to an
      Office 2010 slide shape (i.e., rectangle shape, caption, title).
    - Corrected formatting errors produced in the -S output listing.
    - Installation package released with latest version of Inno Setup,
      which allows p3icli to install cleanly on Windows 7 (compatiblity
      manager dialog box does not pop up).

v1.7, released 9/25/2009
    - added a -S commandline switch, which dumps accepted syntax on stdout
      and then forces a program exit.
    - bugfix:  when "copy src fmt on" is in effect, attempting to insert a
      an out-of-range numeric slide template would cause P3ICLI to "leak"
      an extra instance of PPT.
    - P3ICLI slide "comment" functionality (which essentially died with the
      release of Office XP) is now once again functional for Office XP,
      Office 2003, and Office 2007.  Commands that once again function
      correctly are:

        remove comments
        insert slide <qstring> from template <filename>

    - documentation updated to demonstrate how later versions of PPT
      create slide comments.
    - documentation updated to show PPT 2007 users how to access a shape's
      Alternative Text (location changed in this PPT rls).
    - P3ICLI is a mature product, now entering maintenance stage.  Send
      enhancement requests and/or bug reports to Clark Morgan, here: 

               spammers.are.scum@gmail.com 

v1.6, released 9/10/2009
    - Support for Office 2000 dropped (P3ICLI v1.6 is incompatible).
    - new script command added:

        copy src fmt {on | off}

      or equivalently:

        copy source format {on | off}

      Specifies whether P3ICLI copies background slide formatting
      information (e.g., design, color scheme, gradients, etc.) from the
      "source" slide during the execution of an insert slide command. 
      Default is off.

      Note 1:  the state of this P3ICLI parameter is both order dependent
      and persistent.  Place this command before a targeted insert slide
      command.

      Note 2:  user-defined textures cannot be copied for any version of
      PPT released prior to Office 2007, since no PPT programmatic support
      exists for this slide formatting feature.

v1.5, released 8/30/2009
    - P3ICLI released using software license GPLv3.
    - source files updated to work with latest release of cygwin (in
      particular, lex.l compiles cleanly).
    - bugfix:  when inserting template slides into an open presentation
      that has had slides deleted at some point in the past, PowerPoint 
      2003 reports slide index out of range errors.

v1.4, released 12/7/2005
    - added "-V vrsnfile" command-line switch, which is useful for 
      programmatically obtaining p3icli's version number via CreateProcess()
      (i.e., in the absence of shell redirection support).
    - fixed a PPT OLE runtime error that occurred when back-to-back
      "kill ppt discard" commands were executed on an underpowered PC.
    - fixed an obscure parsing problem that occurred when "halt" was the
      last line of a script and that line was not terminated with newline.
    - when connecting to a running instance of PPT, P3ICLI forces 
      "normal view" and then activates the slide pane.  These two 
      preconditions prevent numerous PPT runtime errors when various 
      scripting commands (e.g., title, pic<uint>, etc.) are executed.
    - when connecting to a running instance of PPT, P3ICLI kills all running
      slide shows (prevents lots of scripting commands from blowing sky high).
    - new script command added:
    
        remove comments

      which removes all comments from the currently active slide.
        
v1.3, released 2/6/2005
    - template slides may now be referenced by name (rather than solely by
      their ordinal index).  A "name" is attached to a slide by adding a
      PowerPoint comment shape to the slide and including within that shape
      text that appropriately identifies the template.  Example name: 
      "4 pics, 1 title" .  New syntax that supports this feature is:

        insert slide <qstring> from template <filename>

      Note 1:  p3icli removes the referenced comment shape (and only that
      comment shape) after successfully inserting a slide by name.

      Note 2:  the <qstring> and comment shape text are both trimmed of
      leading and trailing white space prior to testing for string
      equality.  The string equality test is case _insensitive_ .

      Example:
        insert slide '4 pics, 1 title' from template c:\temp\xyz.pot

    - p3icli now supports template caption shapes, which can be used to add
      arbitrary text to a slide.  Pedantically, any PowerPoint shape that
      includes a "text frame" may be used as a caption shape.  Informally,
      any shape capable of displaying text is acceptable.  Note that a
      caption shape need not be physically located within the proximity of
      a picture shape--P3ICLI assumes no shared association between these
      shape types.  Thus, it's possible for a template slide to consist of
      nothing but captions.  New syntax to support captions is as follows:

        cap<uint> <qstring>
        cap<uint> '<'cleaned'>'

      Examples:
        cap1 "March Sales Summary"
        cap2 'Household Net Value'

    - the "clean" command syntax supports captions.  New syntax:

        clean { slide | pics | caps }

      The command "clean slide" implies that all unused shapes known to
      p3icli (titles, captions, and pictures) will be removed.
    - Documentation's "Script Hints" section updated to reflect an annoying
      issue associated with duplicate shape labels.  Suffice it to say, dup
      shape labels leads to script behavior that's no fun to debug.

v1.2, released 2/2/2005
    - fixed parser/scanner so that a syntax error is _not_ reported if the
      last line of a syntactically valid script does not include a
      terminating newline (reported by Georgia Morgan).
    - fixed various cases where a syntax error was reported with an
      off-by-one line number.  Example:

            $ cat | p3icli
            title # forgot the qstring
            ^Z
            p3icli: line 2: error: syntax error     <-- incorrect line#
    - minor documentation formatting errors corrected.

v1.1, released 9/20/2004
    - setup installer now permits a non-administrator install on
      WIN XP/2K.
    - example used in documentation and on web site reworked   
      so that 6x4 snapshots are placed in proportionally similar 
      rectangular shapes ('cuz I was told that PowerPoint's   
      automatic scaling is not so good).
    - new syntax provides script control over PPT's application
      window:

          start ppt [minimized]

v1.0, released 9/17/2004
    - p3icli now accepts multiple script files as input.  Ex:

          p3icli script1.txt script2.txt script3.txt

    - OLE errors decoded before reporting
    - documented that "sleep" is actually useful on a Windows ME
      host
    - help is now html-based
    - p3icli now hosted on SourceForge

v0.9, released 9/2/2004
    - p3icli now includes an icon (useful for setup and desktop shortcut).
    - p3icli now distributed with a self-extracting setup program.
    - a couple of documentation errors fixed.

v0.8, released 8/30/2004
    - new script commands:

          insert slide <uint> from template <filename>
          kill ppt {save | discard}
          pic<uint> '<'cleaned'>'
          save as {html | presentation} <filename>

    - if a template rectangle shape includes a text rotation angle != 0.00 
      degrees, that rotation is applied to subsequently inserted 
      pictures/graphics files (feature not supported by Office 2000).
    - p3icli now tests existence of user-specified template when processing
      "open template" command.
    - internal deletion of unused dup template no longer generates error
      message if user has externally closed PPT.
    - lexical analysis simplified.

v0.7, released 8/23/2004
    - Rudimentary functionality completed.