Skip to content

Commit d5cfec3

Browse files
(GH-116) Clarify New-ExternalHelpCab is Windows-only (#117)
Prior to this change, the documentation didn't state that the PlatyPS cmdlet `New-ExternalHelpCab` only works on Windows, despite requiring the `MakeCab.exe` native command, which is only available on Windows. This change adds a notice to the cmdlet documentation to clarify this limitation. - Resolves #116 - Fixes AB#41454
1 parent 389a9b1 commit d5cfec3

File tree

1 file changed

+21
-11
lines changed

1 file changed

+21
-11
lines changed

reference/ps-modules/PlatyPS/New-ExternalHelpCab.md

Lines changed: 21 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -9,40 +9,50 @@ schema: 2.0.0
99
# New-ExternalHelpCab
1010

1111
## SYNOPSIS
12-
Generates a .cab file.
12+
Generates a `.cab` file.
1313

1414
## SYNTAX
1515

1616
```
17-
New-ExternalHelpCab -CabFilesFolder <String> -LandingPagePath <String> -OutputFolder <String>
17+
New-ExternalHelpCab -CabFilesFolder <String> -LandingPagePath <String>
18+
-OutputFolder <String>
1819
[-IncrementHelpVersion] [<CommonParameters>]
1920
```
2021

2122
## DESCRIPTION
2223

23-
The `New-ExternalHelpCab` cmdlet generates a .cab file that contains all the non-recursive content
24+
The `New-ExternalHelpCab` cmdlet generates a `.cab` file that contains all the non-recursive content
2425
in a folder. This cmdlet compresses the provided files.
2526

27+
> [!NOTE]
28+
> This cmdlet depends on the `MakeCab.exe` native command, which is only available on Windows. This
29+
> cmdlet raises an error if used on non-Windows machines.
30+
2631
We recommend that you provide as content only about_ topics and the output from the
2732
[New-ExternalHelp](New-ExternalHelp.md) cmdlet to this cmdlet.
2833

29-
This cmdlet uses metadata stored in the module markdown file to name your .cab file. This naming
30-
matches the pattern that the Windows PowerShell help system requires for use as updatable help. This
34+
This cmdlet uses metadata stored in the module markdown file to name your `.cab` file. This naming
35+
matches the pattern that the PowerShell help system requires for use as updatable help. This
3136
metadata is part of the module file created using the [New-MarkdownHelp](New-MarkdownHelp.md)
3237
cmdlet with the **WithModulePage** parameter.
3338

3439
This cmdlet also generates or updates an existing `helpinfo.xml` file. That file provides versioning
35-
and locale details to the Windows PowerShell help system.
40+
and locale details to the PowerShell help system.
3641

3742
## EXAMPLES
3843

3944
### Example 1: Create a CAB file
4045

4146
```powershell
42-
New-ExternalHelpCab -CabFilesFolder 'C:\Module\ExternalHelpContent' -LandingPagePath 'C:\Module\ModuleName.md' -OutputPath 'C:\Module\Cab\'
47+
$params = @{
48+
CabFilesFolder = 'C:\Module\ExternalHelpContent'
49+
LandingPagePath = 'C:\Module\ModuleName.md'
50+
OutputPath = 'C:\Module\Cab\'
51+
}
52+
New-ExternalHelpCab @params
4353
```
4454

45-
This commmand creates a `.cab` file that contains the content folder files. The `.cab` file is named
55+
The cmdlet creates a `.cab` file that contains the content folder files. The `.cab` file is named
4656
for updatable help based on metadata. The command places the `.cab` file in the output folder.
4757

4858
## PARAMETERS
@@ -65,8 +75,8 @@ Accept wildcard characters: False
6575
6676
### -LandingPagePath
6777
68-
Specifies the full path of the Module Markdown file that contains all the metadata required to name
69-
the .cab file. For the required metadata, run `New-MarkdownHelp` with the **WithLandingPage**
78+
Specifies the full path of the module Markdown file that contains all the metadata required to name
79+
the `.cab` file. For the required metadata, run `New-MarkdownHelp` with the **WithLandingPage**
7080
parameter.
7181

7282
```yaml
@@ -99,7 +109,7 @@ Accept wildcard characters: False
99109

100110
### -IncrementHelpVersion
101111

102-
Automatically increment the help version in the module markdown file.
112+
Automatically increment the help version in the module Markdown file.
103113

104114
```yaml
105115
Type: SwitchParameter

0 commit comments

Comments
 (0)