Releasing 0.10.0

Build.PSake.ps1

@@ -9,7 +9,7 @@ Properties {
     $buildDir = 'Release';
     $buildPath = (Join-Path -Path $basePath -ChildPath $buildDir);
     $releasePath = (Join-Path -Path $buildPath -ChildPath $moduleName);
-    $thumbprint = '177FC8E667D4C022C7CD9CFDFEB66991890F4090';
+    $thumbprint = '6F72C7A1BD6979DD8F08DC066ABC12FB80A453E9';
     $timeStampServer = 'http://timestamp.digicert.com';
     $exclude = @(
         '.git*',
@@ -177,9 +177,9 @@ Task Sign -Depends Deploy {
 
     if (-not (Get-ChildItem -Path Cert:\CurrentUser\My | Where-Object Thumbprint -eq $thumbprint)) {
         ## Decrypt and import code signing cert
-        .\appveyor-tools\secure-file.exe -decrypt .\VE_Certificate_2021.pfx.enc -secret $env:certificate_secret
+        .\appveyor-tools\secure-file.exe -decrypt .\VE_Certificate_2023.pfx.enc -secret "$env:certificate_secret" -salt "$env:certificate_salt"
         $certificatePassword = ConvertTo-SecureString -String $env:certificate_secret -AsPlainText -Force
-        Import-PfxCertificate -FilePath .\VE_Certificate_2021.pfx -CertStoreLocation 'Cert:\CurrentUser\My' -Password $certificatePassword
+        Import-PfxCertificate -FilePath .\VE_Certificate_2023.pfx -CertStoreLocation 'Cert:\CurrentUser\My' -Password $certificatePassword
     }
 
     Get-ChildItem -Path $releasePath -Exclude $signExclude | ForEach-Object {

ChangeLog.md

@@ -2,6 +2,16 @@
 
 ## Versions ##
 
+### 0.10.0 ###
+
+* __BREAKING CHANGE__ - XML output to be deprecated in a future release (#102)
+* Adds inline paragraph styling runs - see Example38.ps1 (#75, #97)
+  * __BREAKING CHANGE__ - XML paragraph output formatting changed
+* Adds `about_PScriboExamples` help file (#103)
+  * Run `Get-Help about_PScriboExamples` to return example documentation
+* Adds dynamic `-Format` parameter to `Export-Document`
+* Adds `about_TextPlugin`, `about_HtmlPlugin` and `about_WordPlugin` help topics
+
 ### 0.9.1 ###
 
 * Fixes Word table width bug with landscape orientation

Examples/Example01.ps1

@@ -12,8 +12,11 @@ Import-Module PScribo -Force -Verbose:$false
 
 <#
     We create a PScribo document with the 'Document' cmdlet. Inside the supplied script block, you can include any
-    standard Powershell code as well as addition PScribo content, such as paragraphs. The following code creates a
-    new blank document named 'PScribo Example 1', storing it in the $example1 variable
+    standard Powershell code as well as additional PScribo content, such as paragraphs. The following code creates a
+    new blank document named 'PScribo Example 1', storing it in the $example1 variable.
+
+    When documents are exported, they are exported using the name of the document appended with the extension of the
+    plugin. For example, exporting 'PScribo Example 1' to a Word document results in a 'PScribo Example 1.docx' file.
 #>
 
 $example1 = Document -Name 'PScribo Example 1' {

Examples/Example03.ps1

@@ -8,9 +8,10 @@ param (
 Import-Module PScribo -Force -Verbose:$false
 
 Document -Name 'PScribo Example 3' {
+
     <#
         By default, a PScribo document will default to an A4 page size. The default top and bottom
-        pages margins are configured at 25.4mm (or 1 inch). The default  left and right page margins
+        pages margins are configured at 25.4mm (or 1 inch). The default left and right page margins
         are set at 19.05mm (or 3/4 inch).
 
         You can override the defaults with the 'DocumentOption' cmdlet/keyword. The following sets the

Examples/Example04.ps1

@@ -8,15 +8,20 @@ param (
 Import-Module PScribo -Force -Verbose:$false
 
 $example4 = Document -Name 'PScribo Example 4' {
+
+    <#
+        NOTE: This example is the 'legacy' paragraph implementation. For
+              advanced paragraph styling options see Example38.ps1
+    #>
     Paragraph 'The default built-in style that is applied to paragraphs is named "Normal".'
-    Paragraph 'You can apply an alternative color to a particular paragraph by specifying a html color code to the -Color parameter.' -Color f00;
-    Paragraph 'You can also supply Word constant colors to a paragraph!' -Color SteelBlue;
+    Paragraph 'You can apply an alternative color to a particular paragraph by specifying a html color code to the -Color parameter.' -Color f00
+    Paragraph 'You can also supply Word constant colors to a paragraph!' -Color SteelBlue
     Paragraph 'You can apply bold styling to a particular paragraph by specifying the -Bold switch parameter.' -Bold
     Paragraph 'You can apply italic styling to a particular paragraph by specifying the -Italic switch parameter.' -Italic
     Paragraph 'You can apply underline styling to a particular paragraph by specifying the -Underline switch parameter.' -Underline
     Paragraph 'You can alter the default font size of a particular paragraph by specifying the font point size with the -Size parameter' -Size 16
     Paragraph 'You can alter the default font typeface of a particular paragraph by specifying -Font parameter. This parameter takes an array of font names. Typically, only the first font name is used in Word output, but all names are used in Html output.' -Font Arial
     Paragraph 'If you wish to indent a paragraph, specify the -Tabs parameter. This is an integer number that indents a paragraph at 12.7mm/0.5inch intervals.' -Tabs 1
-    Paragraph 'Of course you are free to combine multiple styling parameters to a single paragraph :).' -Color DarkOrchid -Size 14 -Bold
+    Paragraph 'Of course, you are free to combine multiple styling parameters to a single paragraph :).' -Color DarkOrchid -Size 14 -Bold
 }
 $example4 | Export-Document -Path $Path -Format $Format -PassThru:$PassThru

Examples/Example05.ps1

@@ -8,6 +8,7 @@ param (
 Import-Module PScribo -Force -Verbose:$false
 
 $example5 = Document -Name 'PScribo Example 5' {
+
     <#
         Rather than specifying styling options on individual paragraphs, PScribo supports defining (or
         overriding the default styles) with your own. Creating your own style is easy - just use the
@@ -23,7 +24,7 @@ $example5 = Document -Name 'PScribo Example 5' {
     Paragraph 'This paragraph is styled with the "Funky" style!' -Style Funky
 
     <#
-        If no style is specified, the default is used. You can override the default style (called "Normal")
+        If no style is specified, the default 'Normal' is used. You can override the default style
         by defining your own style with the same name:
     #>
     Style -Name 'Normal' -Font Tahoma -Size 12 -Color 000

Examples/Example06.ps1

@@ -8,6 +8,7 @@ param (
 Import-Module PScribo -Force -Verbose:$false
 
 $example6 = Document -Name 'PScribo Example 6' {
+
     <#
        You can create a document structure with the 'Section' cmdlet. This is the only PScribo
        cmdlet that supports nesting of script blocks.

Examples/Example07.ps1

@@ -8,6 +8,7 @@ param (
 Import-Module PScribo -Force -Verbose:$false
 
 $example7 = Document -Name 'PScribo Example 7' {
+
     <#
        Sections support automatic numbering, i.e. PScribo will automatically generate the section
        numbers/levels based on the nesting. To turn this on, use the 'DocumentOption' cmdlet.

Examples/Example08.ps1

@@ -20,6 +20,11 @@ $example8 = Document -Name 'PScribo Example 8' {
     #>
     TOC -Name 'Table of Contents'
 
+    <#
+        Microsoft Word creates the table of contents based on the name of the style applied. To
+        include a section in a Word TOC it must be styled with a "Heading*" style name. In this
+        instance, Microsoft Word will NOT include it as there no "Heading*" style applied.
+    #>
     Section -Name 'First Section' -ScriptBlock {
         Paragraph 'This section should be labeled as "1 First Section".'
     }
@@ -28,10 +33,8 @@ $example8 = Document -Name 'PScribo Example 8' {
         You can exclude sections from the TOC by specifying the -ExcludeFromTOC parameter
         on the 'Section' cmdlet.
 
-        NOTE: Microsoft Word creates the table of contents based on the style name. Therefore,
-        to include a section in a Word TOC it must be styled with a "Heading*" style name. In
-        addition, if the -ExcludeFromTOC is specified with a style name of "Heading*" then
-        Microsoft Word will include it - regardless.
+        NOTE: As this section is styled with the "Heading1" style, Microsoft Word will still
+              include it in the TOC, regardless of the -ExcludeFromTOC switch parameter.
     #>
     Section -Name 'Second "Styled" Section' -Style Heading1 -ExcludeFromTOC -ScriptBlock {
         Paragraph 'This section will be excluded from the table of contents.'

Examples/Example09.ps1

@@ -16,8 +16,8 @@ $example9 = Document -Name 'PScribo Example 9' {
        breaks and blank lines. This can be used to segregate content within a document.
 
        NOTE: not all breaks are rendered by PScribo plugins in the same manner. For example,
-       only Word output truly supports page breaks as there is no concept of pagination in
-       html, xml or text output.
+             only Word output truly supports page breaks as there is no concept of pagination
+             in html, xml or text output.
 
        The 'PageBreak' cmdlet is used to insert a page break. The following page break
        inserts a break between the table of content and the first section.

Examples/Example10.ps1

@@ -8,14 +8,18 @@ param (
 Import-Module PScribo -Force -Verbose:$false
 
 $example10 = Document -Name 'PScribo Example 10' {
+
     <#
-       PScribo supports insertion of tables into a document. In it's simplest form, a
-       collection of objects can be added to a document by using the 'Table' cmdlet.
+        PScribo supports insertion of tables into a document. In it's simplest form, a
+        collection of objects can be added to a document by using the 'Table' cmdlet. By
+        default, a table is created the full width (100%) of the document, with each
+        column width being equally distributed.
 
-       The following examples creates a table of all properties on all services.
+        The following examples creates a table of all properties on all services.
 
-       NOTE: Due to the number of properties, the table will not render in any
-       meaningful way!
+        NOTE: Due the the vast number of properties, the table will not render in any
+              meaningful way! Text output may also be truncated due to limitations/
+              implementation of the 'Format-Table' cmdlet.
     #>
     Table -InputObject (Get-Service | Select-Object -First 100)
 }

Examples/Example11.ps1

@@ -8,13 +8,17 @@ param (
 Import-Module PScribo -Force -Verbose:$false
 
 $example11 = Document -Name 'PScribo Example 11' {
+
     <#
         As the 'Table' keyword supports pipeline input, you can use the standard
-        Powershell Sort-Object, Group-Object, Select-Object and Where-Object cmdlets
-        etc. to filter, sort and/or group the input into the 'Table' cmdlet.
+        Powershell 'Sort-Object', 'Group-Object', 'Select-Object' and 'Where-Object'
+        cmdlets etc. to filter, sort and/or group the input into the 'Table' cmdlet.
 
         The following example creates a table of services, displaying the service
         names, display names and service statuses.
+
+        NOTE: Due the the length of the table cell content, text output may be
+              truncated due to limitations/implementation of the 'Format-Table' cmdlet.
     #>
     Get-Service | Select-Object Name,DisplayName,Status | Table
 }

Examples/Example12.ps1

@@ -11,16 +11,19 @@ $example12 = Document -Name 'PScribo Example 12' {
     <#
         The 'Table' cmdlet supports filtering of object properties by using the -Columns
         parameter. The -Columns parameter specifies the object properties you wish to
-        display in the table, in order required.
+        display in the table, in the order required.
 
         NOTE: The -Columns parameter is required if you wish to override the values
-        displayed in column headings.
+              displayed in column headings.
 
         The following example displays the Name, DisplayName and Status properties of
         all services sent down the pipeline, ignoring all other properties.
 
         NOTE: The columns are displayed in the exact order that they are listed in
-        the -Columns parameter.
+              the -Columns parameter.
+
+        NOTE: Due the the length of the table cell content, text output may be
+              truncated due to limitations/implementation of the 'Format-Table' cmdlet.
     #>
     Get-Service | Table -Columns Name,DisplayName,Status
 }

Examples/Example13.ps1

@@ -8,6 +8,7 @@ param (
 Import-Module PScribo -Force -Verbose:$false
 
 $example13 = Document -Name 'PScribo Example 13' {
+
     <#
         To override the column headers, the -Columns and -Headers parameters can be used
         together.
@@ -19,7 +20,10 @@ $example13 = Document -Name 'PScribo Example 13' {
         The following example overrides the column names with the values supplied in the
         -Headers parameter - a space is introduced in the 'DisplayName' property and the
         'Status' property is displayed as 'State' instead.
+
+        NOTE: Due the the length of the table cell content, text output may be
+              truncated due to limitations/implementation of the 'Format-Table' cmdlet.
     #>
     Get-Service | Table -Columns Name,DisplayName,Status -Headers Name,'Display Name',State
 }
-$example13 | Export-Document -Path $Path -Format $Format -PassThru:$PassThru
+$example13 | Export-Document -Path $Path -Format $Format -PassThru:$PassThru -Options @{ TextWidth = 160 }

Examples/Example14.ps1

@@ -8,11 +8,12 @@ param (
 Import-Module PScribo -Force -Verbose:$false
 
 $example14 = Document -Name 'PScribo Example 14' {
+
     <#
-        By default, tables are configured to 100% of available width and to autofit
-        the table's cell contents. You can override the table width, by specifying the
-        -Width parameter on the 'Table' cmdlet. The width is always set as a percentage
-        of available space.
+        By default, tables are configured to use 100% of available width. You can
+        override the table width, by specifying the -Width parameter on the 'Table'
+        cmdlet. The width is always set as a percentage of available space between
+        the left and right page margins (adjusting for indentation).
 
         The following example creates a table with its with set at 66% of the available
         space.

Examples/Example15.ps1

@@ -8,11 +8,13 @@ param (
 Import-Module PScribo -Force -Verbose:$false
 
 $example15 = Document -Name 'PScribo Example 15' {
+
     <#
-        You can optionally set the width of all columns by using the -ColumnWidths
+        You can optionally set the width of each column by using the -ColumnWidths
         parameter on the 'Table' cmdlet.
 
-        NOTE: You can only specify column widths if you also specify the -Columns.
+        NOTE: You can only specify column widths if you also specify the -Columns
+              parameter.
 
         Just like the Table -Width parameter, the column widths are specified in
         percentages (of overall table width).
@@ -23,6 +25,12 @@ $example15 = Document -Name 'PScribo Example 15' {
         DisplayName and Status properties. The column width for the Name property
         is set to 30%, the column width for the DisplayName property is set to 50%
         and the Status property column width set to 20%.
+
+        NOTE: It is recommended that you set column widths on all tables to ensure
+              consistent formatting between HTML and Word outputs.
+
+        NOTE: Column widths are not implemented for Text output rendering as they
+              are not supported/implemented in the 'Format-Table' cmdlet.
     #>
     Get-Service | Table -Columns Name,DisplayName,Status -ColumnWidths 30,50,20
 }

Examples/Example16.ps1

@@ -8,22 +8,23 @@ param (
 Import-Module PScribo -Force -Verbose:$false
 
 $example16 = Document -Name 'PScribo Example 16' {
+
     <#
         If you do not have a collection/array of objects that you wish to create
         a table from, PScribo supports creating a table from single ordered hashtable
         or an array of ordered hashtables.
 
         NOTE: You cannot pipe a single hashtable or an array of hashtables to the
-        'Table' cmdlet. You MUST pass the hashtable(s) via the -HashTable parameter. If
-        you pipe the hastable(s) the object properties are displayed and not the
-        hashtable key/value pairs!
+              'Table' cmdlet. You MUST pass the hashtable(s) via the -HashTable parameter.
+              If you pipe the hashtable(s), the hashtable object's properties are
+              displayed and not the hashtable key/value pairs!
 
         Creating a hashtable does permit the utilisation of spaces in the key names,
         requiring that the -Headers parameter does not necessarily need to be used.
 
         NOTE: This is not a standard hashtable, but a System.Collections.Specialized.OrderedDictionary
-        object. These can be created with the [Ordered] attribute on the hashtable
-        declaration, e.g. [Ordered] @{ Key1 = Value1; Key2 = Value2; }
+              object. These can be created with the [Ordered] attribute on the hashtable
+              declaration, e.g. [Ordered] @{ Key1 = Value1; Key2 = Value2; }
 
         The following example creates a table with a single row with the hashtable keys
         used as the header values and the corresponding values as the first table row.

Examples/Example17.ps1

@@ -8,12 +8,13 @@ param (
 Import-Module PScribo -Force -Verbose:$false
 
 $example17 = Document -Name 'PScribo Example 17' {
+
     <#
         To create a multi-row table from hashtables, simply create a collection/
         array of ordered hashtables.
 
         NOTE: You must ensure that the hashtable keys are the same on all hashtables
-        in the collection/array as only the first object is enumerated.
+              in the collection/array as only the first object is enumerated.
 
         The following example creates an table with a three rows from an array of
         ordered hashtables.

Examples/Example18.ps1

@@ -8,6 +8,7 @@ param (
 Import-Module PScribo -Force -Verbose:$false
 
 $example18 = Document -Name 'PScribo Example 18' {
+
     <#
         If you need to list an object's or hashtable's values in a list format, you
         can specify the -List parameter on the 'Table' cmdlet. Rather than creating
@@ -16,10 +17,11 @@ $example18 = Document -Name 'PScribo Example 18' {
 
         This is useful if not all properties will fit across as page (like Services).
         However, if multiple objects are encountered, PScribo will create a separate
-        two-column table for each object.
+        two-column table for each object (similar in functionality to the
+        'Format-List' cmdlet).
 
         The following example will create a list table, detailing every property,
-        for every service regiestered on the local machine.
+        for the first 10 services regiestered on the local machine.
     #>
     Get-Service | Select-Object -First 10 | Table -List
 }

Examples/Example19.ps1

@@ -8,6 +8,7 @@ param (
 Import-Module PScribo -Force -Verbose:$false
 
 $example19 = Document -Name 'PScribo Example 19' {
+
     <#
         Column widths can also be specified on -List tables. The total of the
         column widths must still total 100 (%), but only 2 widths are supported.

Examples/Example20.ps1

@@ -8,6 +8,7 @@ param (
 Import-Module PScribo -Force -Verbose:$false
 
 $example20 = Document -Name 'PScribo Example 20' {
+
     <#
         Hashtables can also be used in -List view along with the -Width
         and -ColumnWidths parameters.