< Back
New-ExternalHelp
Post
NAME New-ExternalHelp
SYNOPSIS
Creates external help file based on markdown supported by PlatyPS.
SYNTAX
New-ExternalHelp -OutputPath <String> [-Encoding <Encoding>] [-Force] -Path <String[]> [-ApplicableTag <String[]>]
[-MaxAboutWidth <Int32>] [-ErrorLogFile <String>] [-ShowProgress] [<CommonParameters>]
DESCRIPTION
The New-ExternalHelp cmdlet creates an external help file based on markdown help files supported by PlatyPS. You
can ship this with a module to provide help by using the Get-Help cmdlet.
If the markdown files that you specify do not follow the PlatyPS Schema
(https://github.com/PowerShell/platyPS/b ... .schema.md), this cmdlet returns error messages.
PARAMETERS
-OutputPath <String>
Specifies the path of a folder where this cmdlet saves your external help file. The folder name should end
with a locale folder, as in the following example: `.\\out\\PlatyPS\\en-US`.
Required? true
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Encoding <Encoding>
Specifies the character encoding for your external help file. Specify a System.Text.Encoding object. For more
information, see Character Encoding in the .NET Framework
(https://msdn.microsoft.com/en-us/library/ms404377.aspx)in the Microsoft Developer Network. For example, you
can control Byte Order Mark (BOM) preferences. For more information, see Using PowerShell to write a file in
UTF-8 without the BOM
(http://stackoverflow.com/questions/5596 ... ut-the-bom)at the
Stack Overflow community.
Required? false
Position? named
Default value UTF8 without BOM
Accept pipeline input? False
Accept wildcard characters? false
-Force [<SwitchParameter>]
Indicates that this cmdlet overwrites an existing file that has the same name.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-Path <String[]>
Specifies an array of paths of markdown files or folders. This cmdlet creates external help based on these
files and folders.
Required? true
Position? named
Default value None
Accept pipeline input? True (ByPropertyName, ByValue)
Accept wildcard characters? true
-ApplicableTag <String[]>
Specify array of tags to use as a filter. If cmdlet has `applicable` in the yaml metadata and none of the
passed tags is mentioned there, cmdlet would be ignored in the generated help. Same applies to the Parameter
level `applicable` yaml metadata. If `applicable` is ommited, cmdlet or parameter would be always present. See
design issue (https://github.com/PowerShell/platyPS/issues/273)for more details.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-MaxAboutWidth <Int32>
Specifies the maximimum line length when generating "about" help text files. (See New-MarkdownAboutHelp.)
Other help file types are not affected by this parameter.
Lines inside code blocks are not wrapped at all and are not affected by the MaxAboutWidth parameter.
Required? false
Position? named
Default value 80
Accept pipeline input? False
Accept wildcard characters? false
-ErrorLogFile <String>
The path where this cmdlet will save formatted results log file.
The path must include the location and name of the folder and file name with the json extension. The JSON
object contains three properties, Message, FilePath, and Severity (Warning or Error).
If this path is not provided, no log will be generated.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-ShowProgress [<SwitchParameter>]
Display progress bars under parsing existing markdown files.
If this is used generating of help is much slower.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
String[]
You can pipe an array of paths to this cmdlet.
OUTPUTS
System.IO.FileInfo[]
This cmdlet returns a FileInfo[] object for created files.
NOTES
Example 1: Create external help based on the contents of a folder
PS C:\\> New-ExternalHelp -Path ".\\docs" -OutputPath "out\\platyPS\\en-US"
Directory: D:\\Working\\PlatyPS\\out\\platyPS\\en-US
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 5/19/2016 12:32 PM 46776 platyPS-help.xml
This command creates an external help file in the specified location. This command uses the best practice that the
folder name includes the locale.
------- Example 2: Create help that uses custom encoding -------
PS C:\\> New-ExternalHelp -Path ".\\docs" -OutputPath "out\\PlatyPS\\en-US" -Force -Encoding
([System.Text.Encoding]::Unicode)
Directory: D:\\Working\\PlatyPS\\out\\PlatyPS\\en-US
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 5/22/2016 6:34 PM 132942 platyPS-help.xml
This command creates an external help file in the specified location. This command specifies the Force parameter,
therefore, it overwrites an existing file. The command specifies Unicode encoding for the created file.
--------- Example 3: Write warnings and errors to file ---------
PS C:\\> New-ExternalHelp -Path ".\\docs" -OutputPath "out\\platyPS\\en-US" -ErrorLogFile ".\\WarningsAndErrors.json"
Directory: D:\\Working\\PlatyPS\\out\\platyPS\\en-US
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 5/19/2016 12:32 PM 46776 platyPS-help.xml
This command creates an external help file in the specified location. This command uses the best practice that the
folder name includes the locale. This command writes the warnings and errors to the WarningsAndErrors.json file.
RELATED LINKS
Online Version: https://github.com/PowerShell/platyPS/b ... nalHelp.md
PowerShell V2 External MAML Help
https://blogs.msdn.microsoft.com/powers ... maml-help/
Schema https://github.com/PowerShell/platyPS/b ... .schema.md
SYNOPSIS
Creates external help file based on markdown supported by PlatyPS.
SYNTAX
New-ExternalHelp -OutputPath <String> [-Encoding <Encoding>] [-Force] -Path <String[]> [-ApplicableTag <String[]>]
[-MaxAboutWidth <Int32>] [-ErrorLogFile <String>] [-ShowProgress] [<CommonParameters>]
DESCRIPTION
The New-ExternalHelp cmdlet creates an external help file based on markdown help files supported by PlatyPS. You
can ship this with a module to provide help by using the Get-Help cmdlet.
If the markdown files that you specify do not follow the PlatyPS Schema
(https://github.com/PowerShell/platyPS/b ... .schema.md), this cmdlet returns error messages.
PARAMETERS
-OutputPath <String>
Specifies the path of a folder where this cmdlet saves your external help file. The folder name should end
with a locale folder, as in the following example: `.\\out\\PlatyPS\\en-US`.
Required? true
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Encoding <Encoding>
Specifies the character encoding for your external help file. Specify a System.Text.Encoding object. For more
information, see Character Encoding in the .NET Framework
(https://msdn.microsoft.com/en-us/library/ms404377.aspx)in the Microsoft Developer Network. For example, you
can control Byte Order Mark (BOM) preferences. For more information, see Using PowerShell to write a file in
UTF-8 without the BOM
(http://stackoverflow.com/questions/5596 ... ut-the-bom)at the
Stack Overflow community.
Required? false
Position? named
Default value UTF8 without BOM
Accept pipeline input? False
Accept wildcard characters? false
-Force [<SwitchParameter>]
Indicates that this cmdlet overwrites an existing file that has the same name.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-Path <String[]>
Specifies an array of paths of markdown files or folders. This cmdlet creates external help based on these
files and folders.
Required? true
Position? named
Default value None
Accept pipeline input? True (ByPropertyName, ByValue)
Accept wildcard characters? true
-ApplicableTag <String[]>
Specify array of tags to use as a filter. If cmdlet has `applicable` in the yaml metadata and none of the
passed tags is mentioned there, cmdlet would be ignored in the generated help. Same applies to the Parameter
level `applicable` yaml metadata. If `applicable` is ommited, cmdlet or parameter would be always present. See
design issue (https://github.com/PowerShell/platyPS/issues/273)for more details.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-MaxAboutWidth <Int32>
Specifies the maximimum line length when generating "about" help text files. (See New-MarkdownAboutHelp.)
Other help file types are not affected by this parameter.
Lines inside code blocks are not wrapped at all and are not affected by the MaxAboutWidth parameter.
Required? false
Position? named
Default value 80
Accept pipeline input? False
Accept wildcard characters? false
-ErrorLogFile <String>
The path where this cmdlet will save formatted results log file.
The path must include the location and name of the folder and file name with the json extension. The JSON
object contains three properties, Message, FilePath, and Severity (Warning or Error).
If this path is not provided, no log will be generated.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-ShowProgress [<SwitchParameter>]
Display progress bars under parsing existing markdown files.
If this is used generating of help is much slower.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
String[]
You can pipe an array of paths to this cmdlet.
OUTPUTS
System.IO.FileInfo[]
This cmdlet returns a FileInfo[] object for created files.
NOTES
Example 1: Create external help based on the contents of a folder
PS C:\\> New-ExternalHelp -Path ".\\docs" -OutputPath "out\\platyPS\\en-US"
Directory: D:\\Working\\PlatyPS\\out\\platyPS\\en-US
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 5/19/2016 12:32 PM 46776 platyPS-help.xml
This command creates an external help file in the specified location. This command uses the best practice that the
folder name includes the locale.
------- Example 2: Create help that uses custom encoding -------
PS C:\\> New-ExternalHelp -Path ".\\docs" -OutputPath "out\\PlatyPS\\en-US" -Force -Encoding
([System.Text.Encoding]::Unicode)
Directory: D:\\Working\\PlatyPS\\out\\PlatyPS\\en-US
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 5/22/2016 6:34 PM 132942 platyPS-help.xml
This command creates an external help file in the specified location. This command specifies the Force parameter,
therefore, it overwrites an existing file. The command specifies Unicode encoding for the created file.
--------- Example 3: Write warnings and errors to file ---------
PS C:\\> New-ExternalHelp -Path ".\\docs" -OutputPath "out\\platyPS\\en-US" -ErrorLogFile ".\\WarningsAndErrors.json"
Directory: D:\\Working\\PlatyPS\\out\\platyPS\\en-US
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 5/19/2016 12:32 PM 46776 platyPS-help.xml
This command creates an external help file in the specified location. This command uses the best practice that the
folder name includes the locale. This command writes the warnings and errors to the WarningsAndErrors.json file.
RELATED LINKS
Online Version: https://github.com/PowerShell/platyPS/b ... nalHelp.md
PowerShell V2 External MAML Help
https://blogs.msdn.microsoft.com/powers ... maml-help/
Schema https://github.com/PowerShell/platyPS/b ... .schema.md