v4.2

MartinPacker · Dec 27, 2023 · b2eb418 · b2eb418
1 parent ed8682d
commit b2eb418
Show file tree

Hide file tree

Showing 4 changed files with 74 additions and 4 deletions.
diff --git a/docs/user-guide.html b/docs/user-guide.html
@@ -1214,6 +1214,7 @@ <h3 id="table-of-contents">Table Of Contents<a class="headerlink" href="#table-o
 <li><a href="#specifying-how-many-spaces-represent-an-indentation-level-with-indentspaces">Specifying How Many Spaces Represent An Indentation Level With <code>IndentSpaces</code></a></li>
 <li><a href="#specifying-where-temporary-files-are-stored-with-tempdir">Specifying Where Temporary Files Are Stored With <code>tempDir</code></a></li>
 <li><a href="#deleting-the-first-(processing-summary)-slide-with-deletefirstslide">Deleting The First (Processing Summary) Slide - with <code>DeleteFirstSlide</code></a></li>
+<li><a href="#specifying-slide-background-images-with-backgroundimage">Specifying Slide Background Images With <code>backgroundImage</code></a></li>
 <li><a href="#table-metadata">Table Metadata</a><ul>
 <li><a href="#shrinking-tables-with-compacttables">Shrinking Tables With <code>compactTables</code></a></li>
 <li><a href="#adjusting-table-heading-font-size-with-tableheadingsize">Adjusting Table Heading Font Size With <code>tableHeadingSize</code></a></li>
@@ -1348,6 +1349,7 @@ <h3 id="table-of-contents">Table Of Contents<a class="headerlink" href="#table-o
 <li><a href="#numbersheight"><code>NumbersHeight</code></a></li>
 <li><a href="#tablemargin"><code>TableMargin</code></a></li>
 <li><a href="#transition"><code>Transition</code></a></li>
+<li><a href="#backgroundimage"><code>BackgroundImage</code></a></li>
 </ul>
 </li>
 </ul>
@@ -1475,6 +1477,11 @@ <h2 id="change-log">Change Log<a class="headerlink" href="#change-log" title="Pe
 </thead>
 <tbody>
 <tr>
+<td align="left">4.2</td>
+<td align="right">27&nbsp;December&nbsp;2023</td>
+<td align="left">Added background image support using <a href="#specifying-slide-background-images-with-backgroundimage"><code>backgroundImage</code></a>.</td>
+</tr>
+<tr>
 <td align="left">4.1.2</td>
 <td align="right">11&nbsp;July&nbsp;2023</td>
 <td align="left">Fixed two bugs: Using <code>&lt;sub&gt;</code> &amp; <code>&lt;sup&gt;</code> causes a crash. Also <a href="#card-slides">Card Slides</a> cause a crash.</td>
@@ -3289,6 +3296,14 @@ <h4 id="deleting-the-first-processing-summary-slide-with-deletefirstslide">Delet
 </code></pre>
 <p>The default is <code>no</code>.</p>
 <p><strong>Note:</strong> If you don&rsquo;t have a Processing Summary slide - perhaps because the slide master you used doesn&rsquo;t have a slide - the first slide would still be removed if you specified <code>removeFirstSlide: yes</code>. This is probably not what you want to have happen.</p>
+<h4 id="specifying-slide-background-images-with-backgroundimage">Specifying Slide Background Images With <code>backgroundImage</code><a class="headerlink" href="#specifying-slide-background-images-with-backgroundimage" title="Permanent link"></a></h4>
+<p><a id="specifying-slide-background-images-with-backgroundimage"></a></p>
+<p>You can specify a background image for slides with <code>backgroundImage</code>. For example:</p>
+<pre><code>backgroundImage: myFavouriteBackground.png
+</code></pre>
+<p>The default is no background image (other than from the slide master), represented by an empty string.</p>
+<p>You can override this value with <a href="#backgroundimage-dynamic">Dynamic Metadata</a>.</p>
+<p><strong>Note:</strong> python-pptx doesn&rsquo;t know how to truly manipulate a slide background <em>image</em>. Accordingly, md2pptx places the graphic you specify behind all the other objects it creates on the slide (but in front of any real background). It covers the slide area entirely, scaling the graphic to fit. It&rsquo;s a good idea to make your background image be the same size, or have the same aspect ratio, as the slide.</p>
 <h4 id="table-metadata">Table Metadata<a class="headerlink" href="#table-metadata" title="Permanent link"></a></h4>
 <h5 id="shrinking-tables-with-compacttables">Shrinking Tables With <code>compactTables</code><a class="headerlink" href="#shrinking-tables-with-compacttables" title="Permanent link"></a></h5>
 <p><a id="shrinking-tables-with-compacttables"></a></p>
@@ -4180,6 +4195,11 @@ <h4 id="transition"><code>Transition</code><a class="headerlink" href="#transiti
 <pre><code>&lt;!-- md2pptx: transition: reveal --&gt;
 </code></pre>
 <p>It&rsquo;s important to note that doing this will affect the transition <strong>into</strong> this slide. Likewise all subsequent slides - until overridden again or reverted.</p>
+<p><a id="backgroundimage-dynamic"></a></p>
+<h4 id="backgroundimage"><code>BackgroundImage</code><a class="headerlink" href="#backgroundimage" title="Permanent link"></a></h4>
+<p>You can override the presentation <a href="#specifying-slide-background-images-with-backgroundimage">BackgroundImage</a> specification on a slide-by-slide basis:</p>
+<pre><code>&lt;!-- md2pptx: backgroundImage: myNewBackground.png --&gt;
+</code></pre>
 <h2 id="modifying-the-slide-template">Modifying The Slide Template<a class="headerlink" href="#modifying-the-slide-template" title="Permanent link"></a></h2>
 <p><a id="modifying-the-slide-template"></a></p>
 <p>The included template presentation - Martin Template.pptx - is what the author tested with and gives good results. However, you probably want to develop your own template from it.</p>

diff --git a/docs/user-guide.log b/docs/user-guide.log
@@ -5,8 +5,8 @@ mdpre Markdown Preprocessor v0.6.7 (17 December, 2023)
 Def mdpre_date = 17 December, 2023
 Def mdpre_level = 0.6.7
 Def userid = martinpacker
-Def time = 10&colon;32
-Def date = 23 December&comma; 2023
+Def time = 16&colon;20
+Def date = 27 December&comma; 2023
 Def TOC = Table Of Contents
 Def md = Markdown
 Def pp = Powerpoint
@@ -113,6 +113,7 @@ CSV Stop
 ..... ..... .....  Specifying How Many Spaces Represent An Indentation Level With `IndentSpaces`
 ..... ..... .....   Specifying Where Temporary Files Are Stored With `tempDir`
 ..... ..... .....  Deleting The First (Processing Summary) Slide - with `DeleteFirstSlide`
+..... ..... .....  Specifying Slide Background Images With `backgroundImage`
 ..... ..... .....  Table Metadata
 ..... ..... ..... .....  Shrinking Tables With `compactTables`
 ..... ..... ..... .....  Adjusting Table Heading Font Size With `tableHeadingSize`
@@ -225,6 +226,7 @@ CSV Stop
 ..... ..... .....   `NumbersHeight`
 ..... ..... .....  `TableMargin`
 ..... ..... .....  `Transition`
+..... ..... .....  `BackgroundImage`
 .....  Modifying The Slide Template
 ..... .....  Basics
 ..... .....  Slide Template Sequence

diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -101,6 +101,7 @@ As you can see in the [change log](#change-log), md2pptx is frequently updated -
 		* [Specifying How Many Spaces Represent An Indentation Level With `IndentSpaces`](#specifying-how-many-spaces-represent-an-indentation-level-with-indentspaces)
 		* [Specifying Where Temporary Files Are Stored With `tempDir`](#specifying-where-temporary-files-are-stored-with-tempdir)
 		* [Deleting The First (Processing Summary) Slide - with `DeleteFirstSlide`](#deleting-the-first-(processing-summary)-slide-with-deletefirstslide)
+		* [Specifying Slide Background Images With `backgroundImage`](#specifying-slide-background-images-with-backgroundimage)
 		* [Table Metadata](#table-metadata)
 			* [Shrinking Tables With `compactTables`](#shrinking-tables-with-compacttables)
 			* [Adjusting Table Heading Font Size With `tableHeadingSize`](#adjusting-table-heading-font-size-with-tableheadingsize)
@@ -207,6 +208,7 @@ As you can see in the [change log](#change-log), md2pptx is frequently updated -
 		* [`NumbersHeight`](#numbersheight)
 		* [`TableMargin`](#tablemargin)
 		* [`Transition`](#transition)
+		* [`BackgroundImage`](#backgroundimage)
 * [Modifying The Slide Template](#modifying-the-slide-template)
 	* [Basics](#basics)
 	* [Slide Template Sequence](#slide-template-sequence)
@@ -341,6 +343,7 @@ To quote from the python-pptx license statement:
 
 |Level|Date|What|
 |:-|-:|:-|
+|4.2|27&nbsp;December&nbsp;2023|Added background image support using [`backgroundImage`](#specifying-slide-background-images-with-backgroundimage).|
 |4.1.2|11&nbsp;July&nbsp;2023|Fixed two bugs: Using `<sub>` &amp; `<sup>` causes a crash. Also [Card Slides](#card-slides) cause a crash.|
 |4.1.1|10&nbsp;July&nbsp;2023|Added [`numbersFontSize`](#specifying-slide-number-font-size-with-numbersfontsize) and [`footerFontSize`](#specifying-footer-font-size-with-footerfontsize).|
 |4.1|28&nbsp;April&nbsp;2023|Added [`funnelLabelsPosition`](#funnel-labels-position-funnellabelsposition) and [`funnelWidest`](#funnel-orientation-funnelwidest). Added [`cardTitleBackground`](#card-title-background-colours-cardtitlebackground). Added quotation mark related [HTML entity references](#html-entity-references).|
@@ -2029,6 +2032,20 @@ The default is `no`.
 
 **Note:** If you don't have a Processing Summary slide - perhaps because the slide master you used doesn't have a slide - the first slide would still be removed if you specified `removeFirstSlide: yes`. This is probably not what you want to have happen.
 
+
+#### Specifying Slide Background Images With `backgroundImage`
+<a id="specifying-slide-background-images-with-backgroundimage"></a>
+
+You can specify a background image for slides with `backgroundImage`. For example:
+
+    backgroundImage: myFavouriteBackground.png
+
+The default is no background image (other than from the slide master), represented by an empty string.
+
+You can override this value with [Dynamic Metadata](#backgroundimage-dynamic).
+
+**Note:** python-pptx doesn't know how to truly manipulate a slide background *image*. Accordingly, md2pptx places the graphic you specify behind all the other objects it creates on the slide (but in front of any real background). It covers the slide area entirely, scaling the graphic to fit. It's a good idea to make your background image be the same size, or have the same aspect ratio, as the slide.
+
 #### Table Metadata
 
 ##### Shrinking Tables With `compactTables`
@@ -2045,7 +2062,6 @@ For example, to remove the margins and reduce the font size to 16pt code
 
 You can override this value with [Dynamic Metadata](#compacttables-dynamic).
 
-
 <a id="adjusting-table-heading-font-size-with-tableheadingsize"></a>
 ##### Adjusting Table Heading Font Size With `tableHeadingSize`
 
@@ -3264,6 +3280,13 @@ You can override the presentation [Transition](#slide-transitions-transition) sp
 
 It's important to note that doing this will affect the transition **into** this slide. Likewise all subsequent slides - until overridden again or reverted.
 
+<a id="backgroundimage-dynamic"></a>
+#### `BackgroundImage`
+
+You can override the presentation [BackgroundImage](#specifying-slide-background-images-with-backgroundimage) specification on a slide-by-slide basis:
+
+    <!-- md2pptx: backgroundImage: myNewBackground.png -->
+
 
 ## Modifying The Slide Template
 <a id="modifying-the-slide-template"></a>

diff --git a/docs/user-guide.mdp b/docs/user-guide.mdp
@@ -154,6 +154,7 @@ To quote from the python-pptx license statement:
 =colalign l r l
 =csv
 Level,Date,What
+4.2,27&nbsp;December&nbsp;2023,Added background image support using [`backgroundImage`](#specifying-slide-background-images-with-backgroundimage).
 4.1.2,11&nbsp;July&nbsp;2023,Fixed two bugs: Using `<sub>` &amp; `<sup>` causes a crash. Also [Card Slides](#card-slides) cause a crash.
 4.1.1,10&nbsp;July&nbsp;2023,Added [`numbersFontSize`](#specifying-slide-number-font-size-with-numbersfontsize) and [`footerFontSize`](#specifying-footer-font-size-with-footerfontsize).
 4.1,28&nbsp;April&nbsp;2023,Added [`funnelLabelsPosition`](#funnel-labels-position-funnellabelsposition) and [`funnelWidest`](#funnel-orientation-funnelwidest). Added [`cardTitleBackground`](#card-title-background-colours-cardtitlebackground). Added quotation mark related [HTML entity references](#html-entity-references).
@@ -2040,6 +2041,24 @@ The default is `no`.
 If you don't have a Processing Summary slide - perhaps because the slide master you used doesn't have a slide - the first slide would still be removed if you specified `removeFirstSlide: yes`. \
 This is probably not what you want to have happen.
 
+
+#### Specifying Slide Background Images With `backgroundImage`
+<a id="specifying-slide-background-images-with-backgroundimage"></a>
+
+You can specify a background image for slides with `backgroundImage`. For example:
+
+    backgroundImage: myFavouriteBackground.png
+
+The default is no background image (other than from the slide master), represented by an empty string.
+
+You can override this value with [Dynamic Metadata](#backgroundimage-dynamic).
+
+**Note:** \
+python-pptx doesn't know how to truly manipulate a slide background *image*. \
+Accordingly, md2pptx places the graphic you specify behind all the other objects it creates on the slide (but in front of any real background). \
+It covers the slide area entirely, scaling the graphic to fit. \
+It's a good idea to make your background image be the same size, or have the same aspect ratio, as the slide.
+
 #### Table Metadata
 
 ##### Shrinking Tables With `compactTables`
@@ -2056,7 +2075,6 @@ For example, to remove the margins and reduce the font size to 16pt code
 
 You can override this value with [Dynamic Metadata](#compacttables-dynamic).
 
-
 <a id="adjusting-table-heading-font-size-with-tableheadingsize"></a>
 ##### Adjusting Table Heading Font Size With `tableHeadingSize`
 
@@ -3377,6 +3395,13 @@ You can override the presentation [Transition](#slide-transitions-transition) sp
 
 It's important to note that doing this will affect the transition **into** this slide. Likewise all subsequent slides - until overridden again or reverted.
 
+<a id="backgroundimage-dynamic"></a>
+#### `BackgroundImage`
+
+You can override the presentation [BackgroundImage](#specifying-slide-background-images-with-backgroundimage) specification on a slide-by-slide basis:
+
+    <!-- md2pptx: backgroundImage: myNewBackground.png -->
+
 
 ## Modifying The Slide Template
 <a id="modifying-the-slide-template"></a>