P3ICLI (PowerPoint Picture Insert Command Line Interface)
Reference Manual

Version 3.0

Table Of Contents

Figures and Tables


Overview

P3ICLI is a semi-acronym denoting "PowerPoint Picture Insert Command Line Interface", which is a command line tool that programmatically adds pictures, captions, and slide titles to Microsoft PowerPoint® presentations. If the choice of this acronym seems odd, try rolling the logical alternative (pppicli) across your tongue.

How Does It Work?

P3ICLI requires three input elements:
  1. One or more specially constructed template slides containing graphical objects that specify the exact placement of title text, caption text, and graphics objects.
  2. Picture/graphic files ('natch).
  3. A simple text file script that specifies:
    1. Template file path,
    2. Slide title and caption text,
    3. Picture/graphic file placement on the template,
    4. The sequence point at which an unmodified copy of the template is duplicated so that steps "b", "c", and "d" may be repeated as necessary to create the desired PowerPoint presentation.

Creating A Template

A template is a PowerPoint slide comprised of at least three elements:
  1. An optional title placeholder shape,
  2. Up to 20 optional caption shapes, and
  3. Up to 20 rectangle shapes that denote the coordinates where picture/graphic files are to be placed. The rectangles may also specify a nonzero text rotation angle, which is subsequently applied to inserted pictures/graphic files. This latter feature is only supported by versions of PowerPoint newer than Office 2000 (e.g., Office 2003, Office 2007, etc.).

Template Shape Notes

The P3ICLI release distribution includes an example template called sampleTemplate.pot, which is shown in the following screen shot:

Figure 1 -- sampleTemplate.pot
screen shot of sampleTemplate.pot

The text placed within the frames of each of these nine shapes (i.e., "title", "Rect 1", etc.) is irrelevant to P3ICLI, but does serve as a useful visual cue when formally labeling template shapes (see next topic).

Note
At the user's discretion, other shape types and effects may be placed on the template, but they are ignored by P3ICLI.

Labeling Template Shapes (Office 2003)

Since a variety of shapes/effects might be placed on a template, some mechanism is required to uniquely identify P3ICLI's title, caption, and rectangle shapes. That mechanism is the shape's Web Alternative Text string, which is accessed by:
  1. Selecting and right-clicking the shape,
  2. Clicking the Format Placeholder or Autoshape menu item,
  3. Clicking the "Web" dialog tab.

See Figure 2A for a screen shot of an actual Office 2003 Web Alternative Text dialog box taken from sampleTemplate.pot:

Figure 2A -- Example Web Alternative Text (Office 2003)
screen shot of Alternative Text (Office XP and Office 2003)

Labeling Template Shapes (Office 2007)

Accessing a shape's Web Alternative Text in Office 2007 requires these steps:
  1. Select and right-click the shape,
  2. Click the "Size and Position" menu item,
  3. Click the "Alt Text" dialog tab.

See Figure 2B for a screen shot of an example of the Office 2007 Alt Text dialog box.

Figure 2B -- Example Web Alternative Text (Office 2007)
screen shot of Alternative Text (Office 2007)

Labeling Template Shapes (Office 2010)

Office 2010 uses a slightly different interface than Office 2007. Accessing a shape's Web Alternative Text in Office 2010 requires these steps:
  1. Select and right-click the shape,
  2. Click either the "Size and Position" or "Format Shape" menu items,
  3. Click the "Alt Text" button in the dialog box that pops up.

Figure 2C displays an example Office 2010 Alt Text screen shot.

Figure 2C -- Example Web Alternative Text (Office 2010)
screen shot of Alternative Text (Office 2010)

Labeling Template Shapes (Office 2013 and 2016)

Office 2013 and 2016 present a much different interface than Office 2010. Editorial comment suppressed here. Accessing a shape's Web Alternative Text in Office 2013/2016 requires these steps:
  1. Select and right-click the shape.
  2. Click the "Size and Position" menu item, which opens a pinned dialog box in PPT's right hand window pane.
  3. Collapse (minimize) the displayed "SIZE" data by clicking the "SIZE" menu.
  4. Click the "ALT TEXT" menu in the right hand window pane.

Figure 2D displays an example Office 2013/2016 Alt Text screen shot.

Figure 2D -- Example Web Alternative Text (Office 2013 and 2016)
screen shot of Alternative Text (Office 2013 and 2016)

Required Web Alternative Text Strings

The following table specifies required P3ICLI Web Alt Text strings:


Table 1 -- Shapes Versus Alternative Text Strings
P3ICLI Template
Shape Type
Alternative
Text String
Identifies
Title title optional title placeholder shape
Rectangle #1 pic1 picture shape #1
Rectangle #2 pic2 picture shape #2
... ... ...
Rectangle #20 pic20 picture shape #20
Caption #1 cap1 text caption shape #1
Caption #2 cap2 text caption shape #2
... ... ...
Caption #20 cap20 text caption shape #20

It should be emphasized that text case matters. Use the exact case shown in Table 1 above. (e.g., "title", not "TITLE" or "Title").

Naming Template Slides

The simplest P3ICLI template "package", for lack of a better term, is comprised of a single PowerPoint slide populated with one or more template shapes. But it's difficult to create a complex presentation based on a single slide. Fortunately, P3ICLI provides an insert slide command that provides runtime access to an unlimited number of template slides.

The insert slide command references template slides by either their ordinal position within a PowerPoint file (i.e., slide #1, slide #2, etc.) or by a user-defined name. The latter approach facilitates mnemonic recall and self-documenting scripts. Ordinal naming, on the other hand, is brittle and subject to failure when template slides are reordered or deleted.

A template slide is named by adding a PowerPoint comment to the slide and including comment text that appropriately identifies the template. See Figure 3 for an example of a named slide.

Figure 3 -- Example Named Slide
screen shot of named slide

 
Slide Insertion Example Syntax

The single slide template shown in Figure 3 could be accessed by P3ICLI using either of these two equivalent commands:

insert slide 1 from template c:\path\to\template.ppt
insert slide "2up, no caps" from template c:\path\to\template.ppt
 

Template Slide Naming Notes

The remainder of this manual describes script syntax and program invocation.

Syntax/Semantics Notation

Table 2 -- Syntax Notation
Notation Explanation
{a | b} Choose "a" or "b".
<value> User-specified value. The semantics of value are described in the discussion of the affected script command.
[element] Syntax element is optional.
... Preceding syntax element may be repeated zero or more times.
'element' Syntax requires use of literal element. Used when the command syntax requires a symbol included in this notation. Example syntax:
insert '['xyzzy']'
which says that "insert [xyzzy]" is a valid command (the single quotes remove any special syntactical meaning associated with the bracket characters).

 
Table 3 -- Semantics Notation
Notation Explanation
PPT Abbreviation for PowerPoint.
(R) Script command requires Running, OLE-connected PPT instance.
(T) Script command requires active Template slide (i.e., must be preceded by open template or insert slide command).

Script File Format

A script file is comprised of command elements and optional comments, one command per logical scriptfile line. Command elements include:
Table 4 -- Script File Format
Element Description
defined keywords Examples: open, slide, sleep
<int> Integer, optionally preceded with a minus sign (-) .
<uint> Unsigned integer.
<filename> Unquoted character string specifying a file path.
# comment Annotate script with comments—blank script lines are also accepted. Inline comments are supported (see 2nd example). Examples:

 # next, create slide number 3
 title "Not Sure Yet"  # FIXME later

<qstring> Quoted string, which may be delimited with double or single quotes. Supported escape sequences include:
 
 \r   insert carriage return, useful for forcing a title break
 \n  insert newline
 \t  insert tab
 \'  insert literal single quote
 \"  insert literal double quote
 \\  insert \
 
Examples:

 "string #1"
 'string #2'
 'strval is \'xyz\''

Scripting Syntax

Table 5 -- P3ICLI Script Syntax
Script Command Description
cap<uint> <qstring> Set the text of the specified caption shape (R) (T). Once set, the shape is marked "modified", which has implications for the clean command. The valid range of <uint> is 1-20. Example:
cap1 'Summary Statistics'

Data embedded within <qstring> may be encoded in either the UTF-8 or ANSI character sets, as specified by the encoding command.

cap<uint> '<'cleaned'>' Mark the specified template shape as "modified", thereby protecting it from the clean command. (R) (T). The valid range of <uint> is 1-20. Example:
cap2 <cleaned>

which ensures that cap2 is not removed by a subsequent clean command. This idiom is useful when circumstances require manually adding caption text at a later time.

cap<uint> move <int>','<int> Move the specified caption shape to a new location on the current slide (original template slide remains unchanged) (R) (T). This command's two numerical arguments reflect the affected shape's new left and top coordinates (scaled in points, 72 points per inch). Example:

   cap3 move 198, 126

Which moves cap3 to a location 2.75 inches from the left edge of the current slide and 1.75 inches below the slide's top edge.

Refer to the topic Dynamically Modifying Text Shapes for further details.

cap<uint> size <uint>','<uint> Resize the specified caption shape while maintaining its current location on the current slide (original template slide remains unchanged) (R) (T). This command's two numerical arguments reflect the affected shape's new width and height (scaled in points, 72 points per inch). Example:

   cap1 size 72, 144

Which resizes cap1 as a 1in wide by 2in tall rectangle. Cap1 does not move.

Refer to the topic Dynamically Modifying Text Shapes for further details.

clean {slide | pics | caps} With respect to PPT's currently active slide, remove unmodified shapes known to P3ICLI. (R) (T). Refer to the topic Labeling Template Shapes (Office 2013 and 2016) for a description of how P3ICLI identifies template shapes in newer versions of PPT. Note that slightly different labeling mechanisms are used in Office 2003, Office 2007, and Office 2010. See also the descriptions of these commands:
  • cap<uint> <qstring>
  • pic<uint> <filename>
  • title <qstring>
for an explanation of how template shapes transition to the "modified" state. The command:
clean slide

removes all unmodified picture, caption, title shapes. The command:

clean pics

only affects unmodified picture shapes (title and caption shapes ignored). The command:

clean caps

only affects unmodified caption shapes (title and picture shapes ignored).

copy src fmt {on | off}

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. Example:
copy src fmt on

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.

custom property <qstring>'='<qstring>

custom property <qstring>'='<int>

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

Add a Text, Number, or Yes/No custom property to the presentation that P3ICLI is creating (R) (T). 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:

   custom property "Local Owner"  = "Kilroy"
   custom property "Kilroy ID"    = 1234
   custom property "Kilroy Lives" = yes
   custom property "Kilroy Bday"  = "date: 2016/04/15"
   custom property "Kilroy BDay"  = "" # delete prop

Note that deleting a nonexistent property generates a cryptic PPT error. Adding a custom property that already exists also elicits a PPT error.

{dup | duplicate} template Duplicate an unmodified copy of the template slide and make that duplicate PPT's active slide. (R) (T). This command adds a new, unmodified template slide to the current presentation.
encoding {ansi | utf8} Specifies whether P3ICLI transmits ANSI or UTF-8 character codes via these commands:
  • cap<uint> <qstring>
  • title <qstring>

Example:

encoding utf8
open template c:\temp\mytmplt.ppt
cap1 "Production 3-σ limits"
title "¿Se recomienda precaución?"

Note 1: UTF-8 provides access to a vast collection of symbols not supported by ANSI.

Note 2: for the sake of backwards compatibility with existing P3ICLI scripts, the default encoding is ansi.

Note 3: the state of this P3ICLI parameter is both order dependent and persistent. Place this command before any cap<uint> or title command that includes caption/title string data not compatible with the current encoding.

Note 4: if garbage is displayed instead of Unicode characters, consult these Encoding Hints.

halt P3ICLI exits immediately. Useful script debugging aid.
insert slide <uint> from template <filename>

insert slide <qstring> from template <filename>

The <uint> version of this command inserts template slides by ordinal number from <filename> into a new or existing PPT instance. The <qstring> version of this command inserts template slides by name.

Unlike the open command, insert only creates a new presentation when PPT is not currently running. The insert command:

  • Permits the creation of a presentation based upon an essentially unlimited number of template slides.
  • Establishes an OLE-connected instance of PPT, as well as establishing the current active template slide.
  • Is affected by the copy src fmt command.
  • Is affected by the slide size command.

Examples:

  insert slide 3 from template c:\ppt\tmplt.pot
  insert slide 7 from template c:\ppt\tmplt.pot
  insert slide "2up" from template \ppt\slds.pot

Users transitioning to Office 2013/2016 from an earlier version should study the slide size command.

kill ppt {save | discard} Close all running PPT instances. The save/discard arguments specify whether unsaved changes in currently open presentations are saved or discarded. It's not an error to issue this command when no PPT instances exist.

It's worth noting that kill ppt save exhibits quirks with respect to modified presentations that have never before been saved. To wit:

  • Office 2000 saves the presentations on the desktop (i.e., in the folder \windows\desktop) using the first slide's title as the presentation filename (I kid you not).
  • Office XP (service pack 3) saves the presentations in the \windows\system32 folder using the first slide's title as the presentation filename (wow!).

Consequently, it's fairly important to precede kill ppt save with a save as command.

list geometries [<qstring>] For each caption, picture, and title shape resident on the original template slide, list its dimensions and position scaled in points (72 points to the inch) (R) (T). Additionally, list the template slide's dimensions (width and height), scaled in points. The listing is repeated for the current slide (the contents of which might have been modified by various {size|move} commands), thus allowing a quick comparision of the geometries associated with the current slide versus the unmodifid template slide.

The optional <qstring> argument adds a user-defined annotation that precedes this command's listing.

Listing format sans <qstring> annotation:

   Tmplt Slide: bounds (width,height)
   Tmplt Slide: title (width,height) @ (left,top)
   Tmplt Slide: pic1 (width,height) @ (left,top)
   Tmplt Slide: pic2 (width,height) @ (left,top)
        etc.
   Tmplt Slide: cap1 (width,height) @ (left,top)
   Tmplt Slide: cap2 (width,height) @ (left,top)
        etc.
 
   Curr Slide: bounds (width,height)
   Curr Slide: title (width,height) @ (left,top)
   Curr Slide: pic1 (width,height) @ (left,top)
   Curr Slide: pic2 (width,height) @ (left,top)
        etc.
   Curr Slide: cap1 (width,height) @ (left,top)
   Curr Slide: cap2 (width,height) @ (left,top)
        etc.

Example command usage that includes a <qstring> annotation:

   list geometries "1 title, 1 pic tmplt"
  
   1 title, 1 pic tmplt
   Tmplt Slide: bounds (720, 540)
   Tmplt Slide: title (612,72) @ (66,30)
   Tmplt Slide: pic1 (264,168) @ (54,126)
  
   1 title, 1 pic tmplt
   Curr Slide: bounds (720, 540)
   Curr Slide: title (612,72) @ (66,30)
   Curr Slide: pic1 (264,168) @ (54,126)

Refer to the topics Dynamically Modifying Picture Shapes and Dynamically Modifying Text Shapes for further details.

open template <filename> Open <filename> in a new or existing PPT instance. This command:
  • Establishes an OLE-connected instance of PPT, as well as establishing the current active template slide.
  • Creates a new, unnamed PPT presentation based on <filename>'s single template slide. Contrast open template with insert slide, which utilizes one to N slides.
It bears repeating one more time that this command is designed for use with a template file containing a single slide.
pic<uint> <filename> Replace the template shape labeled pic<uint> with the graphic/picture stored in <filename>. (R) (T). The valid range of <uint> is 1-20. A replaced template shape is marked "modified", which has implications for the clean command. Example usage:

  pic1 c:\temp\wrapup.png
  pic4 c:\stats\analysis3\ttest.jpeg

pic<uint> '<'cleaned'>' Mark the specified template shape as "modified", thereby protecting it from the clean command. (R) (T). The valid range of <uint> is 1-20. Example:

  pic2 <cleaned>

which ensures that pic2 is not removed by a subsequent clean command. This idiom is useful when circumstances require manually adding graphics at a later time.

pic<uint> move <int>','<int> Move the specified picture shape to a new location on the current slide (original template slide remains unchanged) (R) (T). This command's two numerical arguments reflect the affected shape's new left and top coordinates (scaled in points, 72 points per inch). Example:

   pic3 move 216, 288

Which moves pic3 to a location 3 inches from the left edge of the current slide and 4 inches below the slide's top edge.

Refer to the topic Dynamically Modifying Picture Shapes for further details.

pic<uint> size <uint>','<uint> Resize the specified picture shape while maintaining its current location on the current slide (original template slide remains unchanged) (R) (T). This command's two numerical arguments reflect the affected shape's new width and height (scaled in points, 72 points per inch). Example:

   pic1 size 180, 144

Which resizes pic1 as a rectangle 2.5 inches wide by 2 inches tall. Pic1 does not move.

Refer to the topic Dynamically Modifying Picture Shapes for further details.

remove comments Arbitrarily remove all comments from the currently active slide. (R) (T). In the case where no comments exist, no error is reported.
save as {html | pdf | presentation} <filename> Save PPT's current, active window contents to the specified <filename> in either html, pdf, or presentation format. (R). If <filename> exists, it is silently overwritten. When the save as operation completes, PPT's active window is closed.

Note that the pdf format is not supported in Office 2003. On the other hand, the html format is not supported in Office 2013 (and presumably, later versions as well) and will elicit a PPT runtime error. Support for the html format in Office 2010 is shaky at best, as many web browsers cannot access anything but the first slide in a multi-slide presentation. PDF seems to be the most reliable alternative file format for Office 2010 and beyond. Example usage:

  save as presentation c:\temp\pres1.ppt
  save as pdf c:\temp\pres1.pdf
  save as html c:\temp\pres1.html

sleep <uint> Pause script <uint> milliseconds. Crude debugging aid. Can also be used as a synchronizing device on very slow hosts (see the second example script below). Valid range is 0-30000 (30 seconds). Example:
sleep 5000   # sleep for 5 seconds
slide size {4:3 | default} Office 2013 (and later) changed the default slide size dimensions from 720 by 540 to 960 by 540, scaled in points. This translates to a change from 10in wide by 7.5in tall to 13.33in by 7.5in (the former values constitute a 4:3 aspect ratio and the latter 16:9). P3ICLI templates created pre-Office 2013 retain their existing slide geometries when opened with the open template command. But if those same pre-Office 2013 templates are opened via an insert slide {<uint>|<qstring>} command, they are automatically expanded to a 13.33in width. If this behavior is objectionable, place a slide size command somewhere before the first insert slide command included in a script. Correct example usage:
slide size 4:3       # force 720 by 540
insert slide 1 from template c:\temp\tmplt.pot
# remainder of script ...
Incorrect:
insert slide 1 from template c:\temp\tmplt.pot
slide size 4:3       # wrong order
# remainder of script ...
To disable the 4:3 setting, use this command:
slide size default   # PPT chooses slide size
By default, P3ICLI makes no effort to manage slide size. In other words, the default for this command is default :-) . It's worth emphasizing that the open template command ignores the current slide size setting.
start ppt [minimized] Launch PowerPoint, if not already running—establishes an OLE-connected instance of PPT. The optional minimized argument specifies that PPT starts as a minimized window, which prevents the application from flashing open as the topmost, foreground window.

This command is not strictly necessary, since the open template and insert slide commands launch PowerPoint as necessary.

third party fix {on | off} Apply internal workaround(s) for a third party security application that monitors and disrupts P3ICLI activities. Currently, the on state ensures that all insert slide operations are carried out via a clipboard copy and paste (as opposed to a direct file copy).

Default is off. Example:

third party fix on
title <qstring> Set the text of a template's title shape. (R) (T). Once set, the shape is marked "modified", which has implications for the clean command. Example:
title "Voter Turnout By County"

Data embedded within <qstring> may be encoded in either the UTF-8 or ANSI character sets, as specified by the encoding command.

title move <int>','<int> Move the title shape to a new location on the current slide (original template slide remains unchanged) (R) (T). This command's two numerical arguments reflect the affected shape's new left and top coordinates (scaled in points, 72 points per inch). Example:

   title move 288, 36

Which moves the title to a location 4.5 inches from the left edge of the current slide and 0.5 inches below the slide's top edge.

Refer to the topic Dynamically Modifying Text Shapes for further details.

title size <uint>','<uint> Resize the title shape while maintaining its current location on the current slide (original template slide remains unchanged) (R) (T). This command's two numerical arguments reflect the affected shape's new width and height (scaled in points, 72 points per inch). Example:

   title size 144, 72

Which resizes the title as a 2in wide by 1in tall rectangle. The title does not move.

Refer to the topic Dynamically Modifying Text Shapes for further details.

P3ICLI Command Line Invocation

p3icli [-hvDSX] [-T <msec>] [-W{a|x}:<msec>] [-V <versionfile>] [-l <logfile>] [<scriptfile>...]

where:

-h display command line syntax (help) and exit.
-v display program version and exit.
-D[n] enable internal debug messages at optional level "n" (an unsigned integer). Higher levels enable more detailed debugging. Default is level "0".
-S dump accepted syntax on stdout and exit.
-X forces P3ICLI to execute a kill ppt discard command after all script(s) are processed. Useful in a server environment (prevents errant scripts from stranding orphan instances of PowerPoint).
-T <msec> assumes P3ICLI is running under the Windows Task Scheduler, which implies that before any <scriptfiles> are processed:
  1. a single instance of PowerPoint is started, and
  2. that (new) PowerPoint instance is allowed <msec> (milliseconds) of time to cleanly initialize.
Carefully read Task Scheduler Hints/Caveats for further information.
-V <versionfile> write program version to <versionfile> and exit.
-Wa:<msec> wait <msec> milliseconds after transmitting an Asynchronous PPT command. If unspecified, the default is 220 milliseconds. This parameter may also be configured via an environment variable. Refer to the Fast PC Considerations topic for further details.
-Wx:<msec> wait <msec> milliseconds at program eXit when the -T or -X command line options are in effect. If unspecified, the default is 256 milliseconds. This parameter may also be configured via an environment variable. Refer to the Fast PC Considerations topic for further details.
-l <logfile> record error count and error messages in <logfile> instead of stderr.
<scriptfile> specifies the path to one or more files containing P3ICLI scripting commands. If not specified, commands are read from stdin.

Example Command Line Invocation

Process one script, errors (if any) listed on stderr:
        p3icli my_script.txt
    
Process two scripts, error(s) listed in user-specified log file:
        p3icli -l c:\temp\p3icli_log.txt script1.txt script2.txt
    

P3ICLI Exit Code

The program's exit code is set to the total number of syntax or runtime errors encountered during the course of command execution.

Currently, P3ICLI aborts when 8 total errors are detected.

Log File Format

Table 6 -- Log File Format
Logical File
Line Number
Data
1 P3ICLI exit code (i.e., total error count)
2 Runtime error/warning/informational message #1 (if any)
3 Runtime error/warning/informational message #2 (if any)
... ...
N + 1 Runtime error/warning/informational message #N (if any)

Example Script Using Open Template

Using the template file sampleTemplate.pot (included with the P3ICLI distribution), the following script creates two slides from six hypothetical graphic/picture files stored in c:\temp .
# begin script
open template \path\to\sampleTemplate.pot
# populate slide #1 => 3 pics
title "What a cute baby!"
pic1 c:\temp\baby_smiling1.jpeg
cap1 "Say Cheese!"
pic2 c:\temp\baby_smiling2.jpeg
cap2 "Feb, 2005"
pic3 c:\temp\baby_pose.jpeg
cap3 "Blue skies"
clean slide                  # remove pic4 snd cap4 shapes
#
# all slide 1 template picture shapes populated
#
duplicate template           # create and move to next slide
# populate slide #2 => 3 pics
title "Happy Baby"
pic1 c:\temp\baby_pout.jpeg
cap1 "Are we done, yet?"
pic3 c:\temp\baby_drool1.jpeg
cap3 "Can we talk?"
pic4 c:\temp\baby_on_stomach.jpeg
cap4 "Just for fun"
clean slide                  # remove pic2 and cap2 shapes
save as presentation c:\temp\example.ppt

Example Script Using Insert Slide

The template file portfolio.pot (included with the P3ICLI distribution) is comprised of three slides, each of which includes a title shape and, in sequential order, one, two, and three rectangular shapes. The following script creates a presentation comprised of four slides fully populated with graphic/picture files:
# begin script
kill ppt discard
# On a very slow host, killing PPT and immediately attempting to restart it
# occasionally causes the PPT automation server to _not_ start.
# So wait a bit.
sleep 200
#
insert slide 1 from template \path\to\portfolio.pot
title "National Sales Figures"
pic1 c:\temp\national_sales_figures.jpeg
clean slide      # not really necessary
#
dup template     # create another slide with just one rectangle shape
title "Oregon Sales Figures"
pic1 c:\temp\oregon_sales_figures.jpeg
#
insert slide 2 from template \path\to\portfolio.pot
title "Largest Two National Customers"
pic1 c:\temp\mega_corp1_sales.gif
pic2 c:\temp\mega_corp2_sales.gif
#
insert slide 3 from template \path\to\portfolio.pot
title "Largest Three Oregon Customers"
pic1 c:\temp\pdx_cust1.png
pic2 c:\temp\pdx_cust2.png
pic3 c:\temp\salem_cust1.png
#
save as presentation c:\temp\sales_summary.ppt

Example Using General Purpose Scripting Language

Of course, no one wants to sit at a keyboard and type P3ICLI commands into a console window and/or text editor. P3ICLI is primarily targeted for use within a programming framework that dynamically creates both graphic images and P3ICLI commands that manipulate same.

The JMP Scripting Language serves this purpose well, as described here.

Script Hints

UTF-8 (aka Unicode) Encoding Hints

Suppose you wish to add nifty Unicode characters to P3ICLI caption and/or title shapes. You've located said characters by browsing online documentation and pasted their Unicode values into the <qstring> argument associated with either a cap<uint> or title command. The commands will look similar to this fragment:
encoding utf8
# open a template or insert a template slide
cap4 'The Empty Set symbol looks like this: ∅'
title "This is a pair of scissors: ✂"
When this snippet is processed by P3ICLI, a pretty ∅ symbol may be displayed in caption number 4, along with a pair of scissors in the title. Or, garbage may appear instead. If garbage is displayed, what's the problem? Could be one of these issues:
  1. The PowerPoint font associated with the affected title/caption shapes may not support the desired Unicode character.
    NB: If PowerPoint displays garbage when a desired Unicode character is manually pasted into the targeted caption/title shape, P3ICLI cannot copy it correctly from a script.
    In this situation, find a PowerPoint font that supports the desired characters and adjust the affected title/caption shape's font to match.
     
  2. A PowerPoint bug. For example, the author's copy of PowerPoint 2013 cannot display Unicode characters with a value greater than 0xFFFF (U+FFFF). On the other hand, Word 2013 and Excel 2013 are not similarly affected.
     
  3. As a last resort, this could be a P3ICLI bug. Contact the author.

Script Optimization Insights

In general, optimizing a script for maximum speed doesn't buy much, given the fact that thick slide decks overwhelm most audiences. Put another way, optimizing P3ICLI to shave a few seconds off the creation time of a short presentation is a fool's errand.

But if there's a need to run the same script over and over, or if a script generates many PPT slides, efficiency might matter. What follows are two optimizing tips that may apply to your environment.

Dynamically Modifying Picture Shapes

Caution!
This is an advanced topic--explore only after mastering the basics of populating captions, titles, and pictures/graphics on PowerPoint slides.

Note: This topic focuses on picture shape manipulation, since rectifying skewed/distored graphic images is of greater concern than moving and resizing shapes that store simple text strings. Caption and title shapes are covered in the topic Dynamically Modifying Text Shapes.

This discussion should be prefaced by noting that when P3ICLI inserts an image within a PowerPoint template shape, the shape is not allowed to change its size or location. This behavior is considered a useful feature, as it prevents PowerPoint from haphazardly scattering images across a slide. But there's an obvious drawback to this "feature". When P3ICLI is used in an automation environment where graphic images are created on the fly (e.g., invoking P3ICLI from a JMP JSL script), the aspect ratio of one or more programmatically generated images may not adequately match the fixed geometry of a template picture shape included on a template slide. Left uncorrected, the affected images appear distorted (stretched too much in either the x or y axis) and require manual resizing when P3ICLI exits. For a large presentation, this constitutes annoying scut work.

Assuming that the automation environment in question provides access to the geometry of programmatically generated images, P3ICLI provides a set of commands that move and/or resize picture shapes on the current presentation slide. (Note that shapes on the original template slide remain untouched).

First Step -- What's My Canvas Look Like?

  1. invoke P3ICLI
  2. insert and/or open a template slide
  3. enter this command:       list geometries
Here's actual example text displayed by P3ICLI:
$ p3icli
> insert slide 1 from template c:\cm\git\p3icli\test\tmplts\demo.pot
> list geometries
Tmplt Slide: bounds (720,540)
Tmplt Slide: title (612,54) @ (66,30)
Tmplt Slide: pic1 (630,228) @ (54,126)
Tmplt Slide: cap1 (630,54) @ (54,384)

Curr Slide: bounds (720,540)
Curr Slide: title (612,54) @ (66,30)
Curr Slide: pic1 (630,228) @ (54,126)
Curr Slide: cap1 (630,54) @ (54,384)

This template contains one title, one picture, and one caption shape and visually looks like so (all shapes are selected on the slide to highlight their borders):  
 
screen shot of demo slide before shape manipulation occurs

Both the template and current slide are listed as 720 (width) by 540 (height) units.

Question: Geometry Data Associated with the "list" Command is Scaled How?

Answer: The numbers displayed by the "list" command are integers scaled in points, 72 points per inch. So, from the previous example, we see that the slide is 10 inches wide and 7.5 inches tall.

Second Step -- Determine Shape Geometries

Before deciding if a picture shape requires a size adjustment after, say, inserting a newly generated graphic image, you must know the current aspect ratio of the targeted shape. Looking at the listing above, it can be seen that pic1 is 630 points wide and 228 points tall on both the current and template slide. Or, 8.75 inches by 3.17 inches (i.e., 630/72 by 228/72).

Note also that pic1 is located at coordinate location (54,126). Given that coordinate (0,0) denotes a slides top left corner, it can be determined that pic1 is positioned 0.75 inches from the left edge of the slide and 1.75 inches from the top slide edge (i.e., @ 54/72,126/72).

Put more succintly, this symbolic notation summarizes the last five sentences:

pic1 (width,height) @ (left,top)
The current aspect ratio of pic1 is 2.76 (630/228), but suppose 2.00 is desired instead. This P3ICLI command achieves that effect:
> pic1 size 630,315
Since pic1's height was just increased by 87 points (1.21 in), it would be nice to vertically recenter the shape based on its previous location. That requires moving the shape "up" 43 points (87/2). This P3ICLI command gets the job done:
> pic1 move 54,83     # (126 - 43 => 83)
Without exiting P3ICLI, it's instructive to once again display template and current slide geometry data:
> list geometries
Tmplt Slide: bounds (720,540)
Tmplt Slide: title (612,54) @ (66,30)
Tmplt Slide: pic1 (630,228) @ (54,126)
Tmplt Slide: cap1 (630,54) @ (54,384)

Curr Slide: bounds (720,540)
Curr Slide: title (612,54) @ (66,30)
Curr Slide: pic1 (630,315) @ (54,83)
Curr Slide: cap1 (630,54) @ (54,384)

Pic1 on the current slide indicates the expected geometry, but it remains unchanged on the template slide. This dichotomy is by design. The next duplicate template command will create a new slide in the presentation that is populated with pristine copies of the original template slide shapes. In other words, each duplicate template throws away all changes made to the current slide shape(s) via the aforementioned "size" and/or "move" commands.

Taking a closer look at the updated geometry data shows a couple of problems. The title's shapes bottom edge (30 + 54) overlaps pic1's top edge (83). Likewise, pic1's bottom edge (83 + 315) overlaps cap1's top edge (384). Here's the visual result (not very appealing):

screen shot of demo slide after pic shape manipulation occurs

So, pic1 has the desired aspect ratio and slide position, but the title and cap1 shapes are now "in the way". The topic Dynamically Modifying Text Shapes proposes a solution for this problem.

Question: Should I Resize/Move a Pic Shape Before or After Adding a Graphics Image to Same?

Answer: Use whichever order produces the best image scaling by your version of PowerPoint. Just make sure that image(s) are added before the next duplicate template command.

Question: Is it Possible to Grab Geometry Data Programmatically?

Answer: By default, P3ICLI dumps geometry data generated by the "list" command onto the console screen (stdout). But if the program is invoked with a log file command line argument, the output goes there instead. So, if the following actions can be mimicked from your automation environment, you're good to go:
  1. Create a short P3ICLI script (call it generate_geom_script.txt) that looks something like this:
    kill ppt discard   # start with guaranteed clean slate
    insert slide 1 from template c:\path\to\my\template\file
    list geometries
    kill ppt discard   # tidy up before exiting
            
  2. Now invoke P3ICLI from your automation environment with these command line arguments:
    p3icli -l c:\path\to\geom_data_log_file.txt c:\path\to\generate_geom_script.txt
            
  3. After P3ICLI exits, use your scripting/programming language to open "geom_data_log_file.txt" and parse its contents.

Dynamically Modifying Text Shapes

Caution!
This is an advanced topic--explore only after mastering the basics of populating captions, titles, and pictures/graphics on PowerPoint slides.
Although P3ICLI provides commands that support moving and resizing title and caption shapes, a la the pic<uint> {move|size} commands, it's important to note that resizing caption/title shapes does not imply the same semantics as resizing a picture shape.

Caption and title shapes are treated differently than picture shapes when text is added via the title <qstring> and cap<uint> <qstring> commands. When text is added, P3ICLI makes no effort to maintain a shape's location or size. As it turns out, template title and caption shapes almost never change slide location during text insertion, but PowerPoint will, as the need arises, expand the size of these shapes to accommodate text that might otherwise overflow affected shape frames. This behavior is considered useful, since title and caption shapes transparently accommodate arbitrarily large strings of textual data, irrespective of the original shape's size.

So, in the larger scheme of things, a caption/title can be moved before or after text insertion; but the effects of shape resizing are only guaranteed to "stick" after text is inserted.
Returning to the slide manipulated in the topic
Dynamically Modifying Picture Shapes, the title and cap1 shape must be moved "off" the previously resized (and moved) pic1 shape. Let's move the the title shape up 0.25 inches and move cap1 down 0.5 inches. These commands accomplish that task:
> title move 66,12     # (30 - 72 * 0.25 => 12)
> cap1 move 54,420     # (384 + 72 * 0.5 => 420)
These two commands make adjustments such that there are now no overlapping slide shapes, as demonstrated here:  
 
screen shot of demo slide after title and caption moved

Office 2013 (and later) Considerations

Task Scheduler Hints/Caveats

 

Fast PC Considerations

The advent of fast PC hosts configured with SSD storage, muscular CPUs, and lots of RAM unmasked P3ICLI stability issues with respect to Office 2010 and its successors.

First Area of Concern

P3ICLI eXits when either the -T or -X command line switches are in effect.

In this situation, P3ICLI must delay for "awhile" after killing all running instances of PowerPoint, before exiting itself. The length of this delay is, by default, configured for 256 milliseconds, but can be changed to a value in the range of 0-16000 milliseconds via this command line switch:

-Wx:<milliseconds>

Example:     p3icli -X -Wx:400 myscript.txt
This example directs P3ICLI to linger for 400 milliseconds after killing all PPT instances. In general, the delay at exit only becomes important when running scripts back-to-back in an automated scripting environment (e.g., a .bat file) on a fast host. For example, the delay is important for a .bat file structured like so:
rem begin scripts on thumping fast PC
p3icli -X -l c:\temp\log1.txt script1.txt
p3icli -X -l c:\temp\log2.txt script2.txt
Without the default eXit delay of 256 milliseconds inserted at the end of script1.txt, script2.txt may generate random PowerPoint errors.

Second Area of Concern

The insert slide command adds slide(s) to a new presentation when copy src fmt is on.
In this scenario, the slide is actually copy-and-pasted into the new presentation via the Windows clipboard. The copy/paste mechanism utilized by P3ICLI is Asynchronous in nature and so, when the paste is complete, P3ICLI must delay for "awhile" until PowerPoint has finished formatting the background of the newly inserted slide. The length of the delay is, by default, configured for 220 milliseconds, but can be changed to a value in the range of 0-16000 milliseconds via this command line switch:
-Wa:<milliseconds>

Example:     p3icli -Wa:384 myscript.txt
This example directs P3ICLI to pause for 384 milliseconds after pasting a slide into PowerPoint with copy src fmt on.

Environment Variables
The values associated with the -W command line switch are also configurable via two environment variables:
P3ICLI_ASYNC_WAIT
P3ICLI_EXIT_WAIT
Initialize either environment variable with an unsigned integer in the range 0-16000 to specify the desired delay, in milliseconds.

If both an environment variable and command line switch setting are in effect for the same -W parameter, the command line overrides.

Finally, if the debug switch (-D) is added to the command line, P3ICLI lists the aforementioned wait values in effect at program invocation.