en-US/platyPS-help.xml
|
<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details><command:name>Get-HelpPreview</command:name> <command:verb>Get</command:verb> <command:noun>HelpPreview</command:noun> <maml:description><maml:para>Preview the output Get-Help would return from an external help file(s). </maml:para> </maml:description> </command:details> <maml:description><maml:para>You can use PowerShell help engine to display the text help output for external help. This cmdlet verifies how markdown-generated help will look in Get-Help output. </maml:para> <maml:para>It simulates the output produced by Get-Help cmdlet. </maml:para> </maml:description> <command:syntax><command:syntaxItem><maml:name>Get-HelpPreview</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"><maml:name>Path</maml:name> <maml:Description><maml:para>Path to MAML help files. You can pass several of them. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters><command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"><maml:name>Path</maml:name> <maml:Description><maml:para>Path to MAML help files. You can pass several of them. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes><command:inputType><dev:type><maml:name>String[]</maml:name> </dev:type> <maml:description><maml:para>You can pipe a collection of paths to this cmdlet. </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues><command:returnValue><dev:type><maml:name>Help Object</maml:name> </dev:type> <maml:description><maml:para>Help object, which is the same as Get-Help provides. </maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet><maml:alert><maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples><command:example><maml:title>Example 1</maml:title> <dev:code>PS C:\> $help = Get-HelpPreview .\out\platyPS\en-US\platyPS-help.xml PS C:\> $help.Name Get-HelpPreview Get-MarkdownMetadata New-ExternalHelp New-ExternalHelpCab New-MarkdownHelp Update-MarkdownHelp Update-MarkdownHelpModule Update-MarkdownHelpSchema</dev:code> <dev:remarks><maml:para>Returns a help object get-help preview from maml xml and assign it to the $help variable. Gets the names of Cmdlet objects inside help. </maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks><maml:navigationLink><maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/PowerShell/platyPS/blob/master/docs/Get-HelpPreview.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details><command:name>Get-MarkdownMetadata</command:name> <command:verb>Get</command:verb> <command:noun>MarkdownMetadata</command:noun> <maml:description><maml:para>Gets the markdown header metadata in the form of a hashtable. </maml:para> </maml:description> </command:details> <maml:description><maml:para>PlatyPS stores metadata information in the header block of the markdown file. It's stored as key-value string pairs. </maml:para> <maml:para>By default, platyPS stores help file name and markdown schema version. </maml:para> <maml:para>The metadata section can contain user-provided key-value string pairs to be used by external tools. These pairs would be ignored by [New-ExternalHelp](New-ExternalHelp.md). </maml:para> <maml:para>[Get-MarkdownMetadata](Get-MarkdownMetadata.md) provides a consistent way to retrieve these key-value pairs. The cmdlet returns a key-value <Dictionary[String, String]> object. </maml:para> </maml:description> <command:syntax><command:syntaxItem><maml:name>Get-MarkdownMetadata</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"><maml:name>Path</maml:name> <maml:Description><maml:para>Path to markdown file or folder. Markdown files typically use extension .md </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem><maml:name>Get-MarkdownMetadata</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Markdown</maml:name> <maml:Description><maml:para>String object containing markdown. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters><command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"><maml:name>Path</maml:name> <maml:Description><maml:para>Path to markdown file or folder. Markdown files typically use extension .md </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Markdown</maml:name> <maml:Description><maml:para>String object containing markdown. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes><command:inputType><dev:type><maml:name>String[]</maml:name> </dev:type> <maml:description><maml:para>You can pipe a collection of paths to this cmdlet. </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues><command:returnValue><dev:type><maml:name>Dictionary[String, String]</maml:name> </dev:type> <maml:description><maml:para>The dictionary contains key-value pairs found in the markdown metadata block. </maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet><maml:alert><maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples><command:example><maml:title>Example 1 (Get metadata from a file)</maml:title> <dev:code>PS C:\> Get-MarkdownMetadata -Path .\docs\Get-MarkdownMetadata.md Key Value --- ----- external help file platyPS-help.xml schema 2.0.0</dev:code> <dev:remarks><maml:para>Retrives metadata from a markdown file at the path provided. </maml:para> </dev:remarks> </command:example> <command:example><maml:title>Example 2 (Get metadata from a markdown string)</maml:title> <dev:code>PS C:\> $markdown = cat -Raw .\docs\Get-MarkdownMetadata.md PS C:\> Get-MarkdownMetadata -Markdown $markdown Key Value --- ----- external help file platyPS-help.xml schema 2.0.0</dev:code> <dev:remarks><maml:para>Retrives metadata from a markdown string. </maml:para> </dev:remarks> </command:example> <command:example><maml:title>Example 1 (Get metadata from all files in a folder)</maml:title> <dev:code>PS C:\> Get-MarkdownMetadata .\docs Key Value --- ----- external help file platyPS-help.xml schema 2.0.0 external help file platyPS-help.xml schema 2.0.0 external help file platyPS-help.xml schema 2.0.0 external help file platyPS-help.xml schema 2.0.0 external help file platyPS-help.xml schema 2.0.0 external help file platyPS-help.xml schema 2.0.0 external help file platyPS-help.xml schema 2.0.0 external help file platyPS-help.xml schema 2.0.0</dev:code> <dev:remarks><maml:para>Retrives metadata from all markdown file at the directory path provided. </maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks><maml:navigationLink><maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/PowerShell/platyPS/blob/master/docs/Get-MarkdownMetadata.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details><command:name>New-ExternalHelp</command:name> <command:verb>New</command:verb> <command:noun>ExternalHelp</command:noun> <maml:description><maml:para>Create External help xml file from platyPS markdown. Ship it with your module to provide Get-Help (https://msdn.microsoft.com/en-us/library/dd878343.aspx)capability. </maml:para> </maml:description> </command:details> <maml:description><maml:para>Create External help file from platyPS markdown. </maml:para> <maml:para>You will get error messages if the markdown files do not follow the schema described in platyPS.schema.md (https://github.com/PowerShell/platyPS/blob/master/platyPS.schema.md). </maml:para> </maml:description> <command:syntax><command:syntaxItem><maml:name>New-ExternalHelp</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>OutputPath</maml:name> <maml:Description><maml:para>Path to a folder where you want to put your external help file(s). The name should end with a locale folder, i.e. ".\out\platyPS\en-US". </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Encoding</maml:name> <maml:Description><maml:para>Character encoding for your external help file. </maml:para> <maml:para>It should be of the type [System.Text.Encoding]. You can control precise details (https://msdn.microsoft.com/en-us/library/ms404377.aspx)about your encoding. For example (http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom), you can control BOM (Byte Order Mark) preferences with it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type><maml:name>Encoding</maml:name> <maml:uri /></dev:type> <dev:defaultValue>UTF8 without BOM</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Force</maml:name> <maml:Description><maml:para>Override existing files. </maml:para> </maml:Description> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"><maml:name>Path</maml:name> <maml:Description><maml:para>Path to markdown files or directories. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters><command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>OutputPath</maml:name> <maml:Description><maml:para>Path to a folder where you want to put your external help file(s). The name should end with a locale folder, i.e. ".\out\platyPS\en-US". </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Encoding</maml:name> <maml:Description><maml:para>Character encoding for your external help file. </maml:para> <maml:para>It should be of the type [System.Text.Encoding]. You can control precise details (https://msdn.microsoft.com/en-us/library/ms404377.aspx)about your encoding. For example (http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom), you can control BOM (Byte Order Mark) preferences with it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type><maml:name>Encoding</maml:name> <maml:uri /></dev:type> <dev:defaultValue>UTF8 without BOM</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Force</maml:name> <maml:Description><maml:para>Override existing files. </maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"><maml:name>Path</maml:name> <maml:Description><maml:para>Path to markdown files or directories. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes><command:inputType><dev:type><maml:name>String[]</maml:name> </dev:type> <maml:description><maml:para>You can pipe a collection of paths to this cmdlet. </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues><command:returnValue><dev:type><maml:name>System.IO.FileInfo[]</maml:name> </dev:type> <maml:description><maml:para>This cmdlet returns a FileInfo[] object for created files. </maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet><maml:alert><maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples><command:example><maml:title>Example 1 (Markdown folder)</maml:title> <dev:code>PS C:\> New-ExternalHelp -Path .\docs -OutputPath out\platyPS\en-US Directory: D:\dev\platyPS\out\platyPS\en-US Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 5/19/2016 12:32 PM 46776 platyPS-help.xml</dev:code> <dev:remarks><maml:para>Create external help file in output path directory. Note that directory should include language name. </maml:para> </dev:remarks> </command:example> <command:example><maml:title>Example 1 (With -Force and custom encoding)</maml:title> <dev:code>PS C:\> New-ExternalHelp .\docs -OutputPath out\platyPS\en-US -Force -Encoding ([System.Text.Encoding]::Unicode) Directory: D:\dev\platyPS\out\platyPS\en-US Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 5/22/2016 6:34 PM 132942 platyPS-help.xml</dev:code> <dev:remarks><maml:para>Create and overwrite existing external help file in output path directory. Use Unicode Encoding for output file. </maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks><maml:navigationLink><maml:linkText>PowerShell V2 External MAML Help</maml:linkText> <maml:uri>https://blogs.msdn.microsoft.com/powershell/2008/12/24/powershell-v2-external-maml-help/</maml:uri> </maml:navigationLink> <maml:navigationLink><maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/PowerShell/platyPS/blob/master/docs/New-ExternalHelp.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details><command:name>New-ExternalHelpCab</command:name> <command:verb>New</command:verb> <command:noun>ExternalHelpCab</command:noun> <maml:description><maml:para>Generates a cabinet file, compressing the provided files. </maml:para> </maml:description> </command:details> <maml:description><maml:para>The New-ExternalHelpCab cmdlet generates a cabinet file containing all of the non-recursive content in a provided folder. </maml:para> <maml:para>It is reccomended to use content only provided as AboutTopics.Txt and the output from [New-ExternalHelp](New-ExternalHelp.MD) </maml:para> <maml:para>Using Metadata provided in the Module MD file, the out put cab file is correctly named. This naming aligns it to the pattern required by the PowerShell help engine to use as updatable help. This metadeta is part of the module file created by [New-Markdown](New-MarkdownHelp.md) with the -WithModulePage switch. </maml:para> <maml:para>A helpinfo.xml is also generated, or updated if existing. This helpinfo.xml provides help verioning and locale details to the PowerShell help engine. </maml:para> </maml:description> <command:syntax><command:syntaxItem><maml:name>New-ExternalHelpCab</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>CabFilesFolder</maml:name> <maml:Description><maml:para>The folder containing all of the help content that should be placed into the cab file. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>LandingPagePath</maml:name> <maml:Description><maml:para>The path and name of the Module Markdown file containing all of the metadata required to name the cab. See the top of the [New-MarkdownHelp -WithLandingPage](New-MarkdownHelp.md) output for a list of all required metadata. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>OutputFolder</maml:name> <maml:Description><maml:para>This is the location of the cab file and helpinfo.xml created by New-ExternalHelpCab </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters><command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>CabFilesFolder</maml:name> <maml:Description><maml:para>The folder containing all of the help content that should be placed into the cab file. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>LandingPagePath</maml:name> <maml:Description><maml:para>The path and name of the Module Markdown file containing all of the metadata required to name the cab. See the top of the [New-MarkdownHelp -WithLandingPage](New-MarkdownHelp.md) output for a list of all required metadata. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>OutputFolder</maml:name> <maml:Description><maml:para>This is the location of the cab file and helpinfo.xml created by New-ExternalHelpCab </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name> </dev:type> <maml:description><maml:para>This cmdlet does not take in input over the pipeline. </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name> </dev:type> <maml:description><maml:para>This cmdlet does not output to the console. The only output is in the output folder specificed by the -OutputPath parameter. </maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet><maml:alert><maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples><command:example><maml:title>Example 1</maml:title> <dev:code>PS C:\> New-ExternalHelpCab -CmdletContentFolder 'C:\Module\ExternalHelpContent' -OutputPath 'C:\Module\Cab\' -ModuleMdPageFullPath 'C:\Module\SomeModuleName.md'</dev:code> <dev:remarks><maml:para>Generates the cab file, containing the content folder files and correctlty named for updatable help, and places in the output path directory. </maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks><maml:navigationLink><maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/PowerShell/platyPS/blob/master/docs/New-ExternalHelpCab.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details><command:name>New-MarkdownHelp</command:name> <command:verb>New</command:verb> <command:noun>MarkdownHelp</command:noun> <maml:description><maml:para>Convert your existing external help into markdown or generate it from Help object. </maml:para> </maml:description> </command:details> <maml:description><maml:para>An easy way to start with platyPS. This cmdlet generates help stub from: </maml:para> <maml:para>- Module. </maml:para> <maml:para>- Command. </maml:para> <maml:para>- External help xml (aka maml). </maml:para> </maml:description> <command:syntax><command:syntaxItem><maml:name>New-MarkdownHelp</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Command</maml:name> <maml:Description><maml:para>Name of a command from your PowerShell session. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Encoding</maml:name> <maml:Description><maml:para>Character encoding for your markdown help files. </maml:para> <maml:para>It should be of the type [System.Text.Encoding]. You can control precise details (https://msdn.microsoft.com/en-us/library/ms404377.aspx)about your encoding. For example (http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom), you can control BOM (Byte Order Mark) preferences with it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type><maml:name>Encoding</maml:name> <maml:uri /></dev:type> <dev:defaultValue>UTF8 without BOM</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Force</maml:name> <maml:Description><maml:para>Override existing files. </maml:para> </maml:Description> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Metadata</maml:name> <maml:Description><maml:para>String-to-string hashtable. It would be writed in a header of every markdown help file. It would be ignored by New-ExternalHelp, but can be used by external tools. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type><maml:name>Hashtable</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>NoMetadata</maml:name> <maml:Description><maml:para>Don't emit any metadata in generated markdown. </maml:para> </maml:Description> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>OnlineVersionUrl</maml:name> <maml:Description><maml:para>The URL where help can be downloaded using the updatable help function in PowerShell. Empty string would be used, if no value provided. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>OutputFolder</maml:name> <maml:Description><maml:para>Path to the directory to output markdown help files. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem><maml:name>New-MarkdownHelp</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Encoding</maml:name> <maml:Description><maml:para>Character encoding for your markdown help files. </maml:para> <maml:para>It should be of the type [System.Text.Encoding]. You can control precise details (https://msdn.microsoft.com/en-us/library/ms404377.aspx)about your encoding. For example (http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom), you can control BOM (Byte Order Mark) preferences with it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type><maml:name>Encoding</maml:name> <maml:uri /></dev:type> <dev:defaultValue>UTF8 without BOM</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Force</maml:name> <maml:Description><maml:para>Override existing files. </maml:para> </maml:Description> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>FwLink</maml:name> <maml:Description><maml:para>Metadata for module page, to enable cab creation. It would be used as markdown header metadata in the module page. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>HelpVersion</maml:name> <maml:Description><maml:para>Metadata for module page, to enable cab creation. It would be used as markdown header metadata in the module page. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Locale</maml:name> <maml:Description><maml:para>Metadata for module page, to enable cab creation. It would be used as markdown header metadata in the module page. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Metadata</maml:name> <maml:Description><maml:para>String-to-string hashtable. It would be writed in a header of every markdown help file. It would be ignored by New-ExternalHelp, but can be used by external tools. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type><maml:name>Hashtable</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"><maml:name>Module</maml:name> <maml:Description><maml:para>Name of the modules to be used in markdown help generation. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>NoMetadata</maml:name> <maml:Description><maml:para>Don't emit any metadata in generated markdown. </maml:para> </maml:Description> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>OutputFolder</maml:name> <maml:Description><maml:para>Path to the directory to output markdown help files. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>WithModulePage</maml:name> <maml:Description><maml:para>Generate module page in the output directory. </maml:para> </maml:Description> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem><maml:name>New-MarkdownHelp</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Encoding</maml:name> <maml:Description><maml:para>Character encoding for your markdown help files. </maml:para> <maml:para>It should be of the type [System.Text.Encoding]. You can control precise details (https://msdn.microsoft.com/en-us/library/ms404377.aspx)about your encoding. For example (http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom), you can control BOM (Byte Order Mark) preferences with it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type><maml:name>Encoding</maml:name> <maml:uri /></dev:type> <dev:defaultValue>UTF8 without BOM</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Force</maml:name> <maml:Description><maml:para>Override existing files. </maml:para> </maml:Description> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>FwLink</maml:name> <maml:Description><maml:para>Metadata for module page, to enable cab creation. It would be used as markdown header metadata in the module page. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>HelpVersion</maml:name> <maml:Description><maml:para>Metadata for module page, to enable cab creation. It would be used as markdown header metadata in the module page. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Locale</maml:name> <maml:Description><maml:para>Metadata for module page, to enable cab creation. It would be used as markdown header metadata in the module page. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>MamlFile</maml:name> <maml:Description><maml:para>Path to a MAML xml external help file. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Metadata</maml:name> <maml:Description><maml:para>String-to-string hashtable. It would be writed in a header of every markdown help file. It would be ignored by New-ExternalHelp, but can be used by external tools. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type><maml:name>Hashtable</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>ModuleGuid</maml:name> <maml:Description><maml:para>Metadata for module page, to enable cab creation. It would be used as markdown header metadata in the module page. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>ModuleName</maml:name> <maml:Description><maml:para>Metadata for module page, to enable cab creation. It would be used to name module page. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>NoMetadata</maml:name> <maml:Description><maml:para>Don't emit any metadata in generated markdown. </maml:para> </maml:Description> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>OutputFolder</maml:name> <maml:Description><maml:para>Path to the directory to output markdown help files. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>WithModulePage</maml:name> <maml:Description><maml:para>Generate module page in the output directory. </maml:para> </maml:Description> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters><command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Command</maml:name> <maml:Description><maml:para>Name of a command from your PowerShell session. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Encoding</maml:name> <maml:Description><maml:para>Character encoding for your markdown help files. </maml:para> <maml:para>It should be of the type [System.Text.Encoding]. You can control precise details (https://msdn.microsoft.com/en-us/library/ms404377.aspx)about your encoding. For example (http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom), you can control BOM (Byte Order Mark) preferences with it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type><maml:name>Encoding</maml:name> <maml:uri /></dev:type> <dev:defaultValue>UTF8 without BOM</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Force</maml:name> <maml:Description><maml:para>Override existing files. </maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>FwLink</maml:name> <maml:Description><maml:para>Metadata for module page, to enable cab creation. It would be used as markdown header metadata in the module page. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>HelpVersion</maml:name> <maml:Description><maml:para>Metadata for module page, to enable cab creation. It would be used as markdown header metadata in the module page. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Locale</maml:name> <maml:Description><maml:para>Metadata for module page, to enable cab creation. It would be used as markdown header metadata in the module page. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>MamlFile</maml:name> <maml:Description><maml:para>Path to a MAML xml external help file. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Metadata</maml:name> <maml:Description><maml:para>String-to-string hashtable. It would be writed in a header of every markdown help file. It would be ignored by New-ExternalHelp, but can be used by external tools. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type><maml:name>Hashtable</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"><maml:name>Module</maml:name> <maml:Description><maml:para>Name of the modules to be used in markdown help generation. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>ModuleGuid</maml:name> <maml:Description><maml:para>Metadata for module page, to enable cab creation. It would be used as markdown header metadata in the module page. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>ModuleName</maml:name> <maml:Description><maml:para>Metadata for module page, to enable cab creation. It would be used to name module page. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>NoMetadata</maml:name> <maml:Description><maml:para>Don't emit any metadata in generated markdown. </maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>OnlineVersionUrl</maml:name> <maml:Description><maml:para>The URL where help can be downloaded using the updatable help function in PowerShell. Empty string would be used, if no value provided. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>OutputFolder</maml:name> <maml:Description><maml:para>Path to the directory to output markdown help files. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>WithModulePage</maml:name> <maml:Description><maml:para>Generate module page in the output directory. </maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes><command:inputType><dev:type><maml:name>String[]</maml:name> </dev:type> <maml:description><maml:para>You can pipe module names to this cmdlet. </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues><command:returnValue><dev:type><maml:name>System.IO.FileInfo[]</maml:name> </dev:type> <maml:description><maml:para>This cmdlet returns a FileInfo[] object for created files. </maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet><maml:alert><maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples><command:example><maml:title>Example 1 (from command)</maml:title> <dev:code>PS C:\> function foo {param([string]$bar)} PS C:\> New-MarkdownHelp -command foo -OutputFolder .\docs Directory: D:\dev\platyPS\docs Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 5/22/2016 6:53 PM 664 foo.md</dev:code> <dev:remarks><maml:para>Create stub markdown on the fly from the function foo. </maml:para> </dev:remarks> </command:example> <command:example><maml:title>Example 2 (from module)</maml:title> <dev:code>PS C:\> Import-Module platyPS PS C:\> New-MarkdownHelp -module platyPS -OutputFolder .\docs-new -Force Directory: D:\dev\platyPS\docs-new Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 5/22/2016 6:54 PM 1496 Get-HelpPreview.md -a---- 5/22/2016 6:54 PM 3208 Get-MarkdownMetadata.md -a---- 5/22/2016 6:54 PM 3059 New-ExternalHelp.md -a---- 5/22/2016 6:54 PM 2702 New-ExternalHelpCab.md -a---- 5/22/2016 6:54 PM 6234 New-MarkdownHelp.md -a---- 5/22/2016 6:54 PM 2346 Update-MarkdownHelp.md -a---- 5/22/2016 6:54 PM 1633 Update-MarkdownHelpModule.md -a---- 5/22/2016 6:54 PM 1630 Update-MarkdownHelpSchema.md</dev:code> <dev:remarks><maml:para>The module should be loaded in the PS Session first. Markdown generated for all commands in the module. </maml:para> </dev:remarks> </command:example> <command:example><maml:title>Example 3 (from maml file path)</maml:title> <dev:code>PS C:\> $mamlPath = 'C:\Program Files\WindowsPowerShell\Modules\PSReadline\1.1\en-US\Microsoft.PowerShell.PSReadline.dll-help.xml' PS C:\> New-MarkdownHelp -OutputFolder .\psreadline-docs -MamlFile $mamlPath Directory: D:\dev\platyPS\psreadline-docs Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 5/22/2016 6:56 PM 7443 Get-PSReadlineKeyHandler.md -a---- 5/22/2016 6:56 PM 3586 Get-PSReadlineOption.md -a---- 5/22/2016 6:56 PM 1549 Remove-PSReadlineKeyHandler.md -a---- 5/22/2016 6:56 PM 5947 Set-PSReadlineKeyHandler.md -a---- 5/22/2016 6:56 PM 15320 Set-PSReadlineOption.md</dev:code> <dev:remarks><maml:para>Create markdown help for inbox PSReadLine module. You don't need to load the module itself to do it. Only the help file would be used. </maml:para> </dev:remarks> </command:example> <command:example><maml:title>Example 4 (from maml file with module page)</maml:title> <dev:code>PS C:\> $mamlPath = 'C:\Program Files\WindowsPowerShell\Modules\PSReadline\1.1\en-US\Microsoft.PowerShell.PSReadline.dll-help.xml' PS C:\> New-MarkdownHelp -OutputFolder .\psreadline-docs -MamlFile $mamlPath -WithModulePage -Force -ModuleName PSReadLine Directory: D:\dev\platyPS\psreadline-docs Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 5/22/2016 6:59 PM 7443 Get-PSReadlineKeyHandler.md -a---- 5/22/2016 6:59 PM 3586 Get-PSReadlineOption.md -a---- 5/22/2016 6:59 PM 1549 Remove-PSReadlineKeyHandler.md -a---- 5/22/2016 6:59 PM 5947 Set-PSReadlineKeyHandler.md -a---- 5/22/2016 6:59 PM 15320 Set-PSReadlineOption.md -a---- 5/22/2016 6:59 PM 942 PSReadLine.md</dev:code> <dev:remarks><maml:para>Create markdown help for inbox PSReadLine module. Create a "ModulePage" with name PSReadLine.md, links to other help files and metadata needed for creating cab files. </maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks><maml:navigationLink><maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/PowerShell/platyPS/blob/master/docs/New-MarkdownHelp.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details><command:name>Update-MarkdownHelp</command:name> <command:verb>Update</command:verb> <command:noun>MarkdownHelp</command:noun> <maml:description><maml:para>Update platyPS markdown help files in place. </maml:para> </maml:description> </command:details> <maml:description><maml:para>Update platyPS markdown help files in place. Files content would be alternated. </maml:para> <maml:para>Some parameters attributes changes over time, i.e. parameter sets, types, default value, required, etc. </maml:para> <maml:para>Automatically propogate these changes to your markdown help file: </maml:para> <maml:para>- Load new version of the module in your PowerShell session. </maml:para> <maml:para>- Call Update-MarkdownHelp. </maml:para> <maml:para>- Check new parameters metadata in the markdown files. </maml:para> <maml:para> </maml:para> <maml:para>It also will contain placeholders for new parameters to speed-up your help-authoring expirience. </maml:para> </maml:description> <command:syntax><command:syntaxItem><maml:name>Update-MarkdownHelp</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"><maml:name>Path</maml:name> <maml:Description><maml:para>Path to markdown files or folder. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"><maml:name>Encoding</maml:name> <maml:Description><maml:para>Character encoding for your updated markdown help files. </maml:para> <maml:para>It should be of the type [System.Text.Encoding]. You can control precise details (https://msdn.microsoft.com/en-us/library/ms404377.aspx)about your encoding. For example (http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom), you can control BOM (Byte Order Mark) preferences with it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type><maml:name>Encoding</maml:name> <maml:uri /></dev:type> <dev:defaultValue>UTF8 without BOM</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"><maml:name>LogPath</maml:name> <maml:Description><maml:para>Put log information into a provided file path. By default, VERBOSE stream is used for it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>LogAppend</maml:name> <maml:Description><maml:para>Don't overwrite log file, instead append to it. </maml:para> </maml:Description> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters><command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"><maml:name>Encoding</maml:name> <maml:Description><maml:para>Character encoding for your updated markdown help files. </maml:para> <maml:para>It should be of the type [System.Text.Encoding]. You can control precise details (https://msdn.microsoft.com/en-us/library/ms404377.aspx)about your encoding. For example (http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom), you can control BOM (Byte Order Mark) preferences with it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type><maml:name>Encoding</maml:name> <maml:uri /></dev:type> <dev:defaultValue>UTF8 without BOM</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>LogAppend</maml:name> <maml:Description><maml:para>Don't overwrite log file, instead append to it. </maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"><maml:name>LogPath</maml:name> <maml:Description><maml:para>Put log information into a provided file path. By default, VERBOSE stream is used for it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"><maml:name>Path</maml:name> <maml:Description><maml:para>Path to markdown files or folder. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes><command:inputType><dev:type><maml:name>String[]</maml:name> </dev:type> <maml:description><maml:para>You can pipe a collection of paths to this cmdlet. </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues><command:returnValue><dev:type><maml:name>System.IO.FileInfo[]</maml:name> </dev:type> <maml:description><maml:para>This cmdlet returns a FileInfo[] object for updated files. </maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet><maml:alert><maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples><command:example><maml:title>Example 1 (Update all files in a folder)</maml:title> <dev:code>PS C:\> Update-MarkdownHelp .\docs Directory: D:\dev\platyPS\docs Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 5/22/2016 6:54 PM 1496 Get-HelpPreview.md -a---- 5/22/2016 6:54 PM 3208 Get-MarkdownMetadata.md -a---- 5/22/2016 6:54 PM 3059 New-ExternalHelp.md -a---- 5/22/2016 6:54 PM 2702 New-ExternalHelpCab.md -a---- 5/22/2016 6:54 PM 6234 New-MarkdownHelp.md -a---- 5/22/2016 6:54 PM 2346 Update-MarkdownHelp.md -a---- 5/22/2016 6:54 PM 1633 Update-MarkdownHelpModule.md -a---- 5/22/2016 6:54 PM 1630 Update-MarkdownHelpSchema.md</dev:code> <dev:remarks><maml:para>Update all markdown files is a folder with information from the 'live' commands. </maml:para> </dev:remarks> </command:example> <command:example><maml:title>Example 2 (Update one file and capture log)</maml:title> <dev:code>PS C:\> Update-MarkdownHelp .\docs\Update-MarkdownHelp.md -LogPath .\my.log Directory: D:\dev\platyPS\docs Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 5/22/2016 8:20 PM 9993 New-MarkdownHelp.md</dev:code> <dev:remarks><maml:para>Update markdown help file and write log to "my.log" file. </maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks><maml:navigationLink><maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/PowerShell/platyPS/blob/master/docs/Update-MarkdownHelp.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details><command:name>Update-MarkdownHelpModule</command:name> <command:verb>Update</command:verb> <command:noun>MarkdownHelpModule</command:noun> <maml:description><maml:para>Update all files in a markdown help module folder. </maml:para> </maml:description> </command:details> <maml:description><maml:para>This cmdlet provides a way to update existing help and create new markdown for newly created commands. </maml:para> <maml:para>It combines Update-MarkdownHelp and New-MarkdownHelp and provides a convinient way to do a bulk update. </maml:para> </maml:description> <command:syntax><command:syntaxItem><maml:name>Update-MarkdownHelpModule</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"><maml:name>Path</maml:name> <maml:Description><maml:para>Path to markdown help module folder. Folder should contain module page to retrive module name. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"><maml:name>Encoding</maml:name> <maml:Description><maml:para>Character encoding for your updated markdown help files. </maml:para> <maml:para>It should be of the type [System.Text.Encoding]. You can control precise details (https://msdn.microsoft.com/en-us/library/ms404377.aspx)about your encoding. For example (http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom), you can control BOM (Byte Order Mark) preferences with it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type><maml:name>Encoding</maml:name> <maml:uri /></dev:type> <dev:defaultValue>UTF8 without BOM</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"><maml:name>LogPath</maml:name> <maml:Description><maml:para>Put log information into a provided file path. By default, VERBOSE stream is used for it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>LogAppend</maml:name> <maml:Description><maml:para>Don't overwrite log file, instead append to it. </maml:para> </maml:Description> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters><command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"><maml:name>Encoding</maml:name> <maml:Description><maml:para>Character encoding for your updated markdown help files. </maml:para> <maml:para>It should be of the type [System.Text.Encoding]. You can control precise details (https://msdn.microsoft.com/en-us/library/ms404377.aspx)about your encoding. For example (http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom), you can control BOM (Byte Order Mark) preferences with it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type><maml:name>Encoding</maml:name> <maml:uri /></dev:type> <dev:defaultValue>UTF8 without BOM</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>LogAppend</maml:name> <maml:Description><maml:para>Don't overwrite log file, instead append to it. </maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"><maml:name>LogPath</maml:name> <maml:Description><maml:para>Put log information into a provided file path. By default, VERBOSE stream is used for it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"><maml:name>Path</maml:name> <maml:Description><maml:para>Path to markdown help module folder. Folder should contain module page to retrive module name. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes><command:inputType><dev:type><maml:name>System.String[]</maml:name> </dev:type> <maml:description><maml:para>You can pipe a collection of paths to this cmdlet. </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues><command:returnValue><dev:type><maml:name>System.IO.FileInfo[]</maml:name> </dev:type> <maml:description><maml:para>This cmdlet returns a FileInfo[] object for updated and newly created files. </maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet><maml:alert><maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples><command:example><maml:title>Example 1</maml:title> <dev:code>PS C:\> Update-MarkdownHelpModule .\docs Directory: D:\dev\platyPS\docs Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 5/22/2016 6:54 PM 1496 Get-HelpPreview.md -a---- 5/22/2016 6:54 PM 3208 Get-MarkdownMetadata.md -a---- 5/22/2016 6:54 PM 3059 New-ExternalHelp.md -a---- 5/22/2016 6:54 PM 2702 New-ExternalHelpCab.md -a---- 5/22/2016 6:54 PM 6234 New-MarkdownHelp.md -a---- 5/22/2016 6:54 PM 2346 Update-MarkdownHelp.md -a---- 5/22/2016 6:54 PM 1633 Update-MarkdownHelpModule.md -a---- 5/22/2016 6:54 PM 1630 Update-MarkdownHelpSchema.md</dev:code> <dev:remarks><maml:para>Update all markdown files is a folder with information from the 'live' commands. Create help markdown for commands, that didn't have them before. </maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks><maml:navigationLink><maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/PowerShell/platyPS/blob/master/docs/Update-MarkdownHelpModule.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details><command:name>Update-MarkdownHelpSchema</command:name> <command:verb>Update</command:verb> <command:noun>MarkdownHelpSchema</command:noun> <maml:description><maml:para>Upgrade markdown help from version 1.0.0 to the latest one (2.0.0). </maml:para> </maml:description> </command:details> <maml:description><maml:para>Migrate to the latest markdown help schema. </maml:para> <maml:para>As a release 0.4.0, there are two schemas: 1.0.0 and 2.0.0 We highly encourage you to migrate to the latest schema. </maml:para> <maml:para>It's easlier and provides visually apealing expirience. </maml:para> </maml:description> <command:syntax><command:syntaxItem><maml:name>Update-MarkdownHelpSchema</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"><maml:name>Path</maml:name> <maml:Description><maml:para>Path to markdown files or directories. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"><maml:name>OutputFolder</maml:name> <maml:Description><maml:para>Path to the directory to output markdown help files. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"><maml:name>Encoding</maml:name> <maml:Description><maml:para>Character encoding for created markdown help files. </maml:para> <maml:para>It should be of the type [System.Text.Encoding]. You can control precise details (https://msdn.microsoft.com/en-us/library/ms404377.aspx)about your encoding. For example (http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom), you can control BOM (Byte Order Mark) preferences with it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type><maml:name>Encoding</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Force</maml:name> <maml:Description><maml:para>Override existing files. </maml:para> </maml:Description> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters><command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"><maml:name>Encoding</maml:name> <maml:Description><maml:para>Character encoding for created markdown help files. </maml:para> <maml:para>It should be of the type [System.Text.Encoding]. You can control precise details (https://msdn.microsoft.com/en-us/library/ms404377.aspx)about your encoding. For example (http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom), you can control BOM (Byte Order Mark) preferences with it. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type><maml:name>Encoding</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"><maml:name>Force</maml:name> <maml:Description><maml:para>Override existing files. </maml:para> </maml:Description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type><maml:name>SwitchParameter</maml:name> <maml:uri /></dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"><maml:name>OutputFolder</maml:name> <maml:Description><maml:para>Path to the directory to output markdown help files. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type><maml:name>String</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"><maml:name>Path</maml:name> <maml:Description><maml:para>Path to markdown files or directories. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type><maml:name>String[]</maml:name> <maml:uri /></dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes><command:inputType><dev:type><maml:name>String[]</maml:name> </dev:type> <maml:description><maml:para>You can pipe a collection of paths to this cmdlet. </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues><command:returnValue><dev:type><maml:name>System.IO.FileInfo[]</maml:name> </dev:type> <maml:description><maml:para>This cmdlet returns a FileInfo[] object for created files. </maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet><maml:alert><maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples><command:example><maml:title>Example 1</maml:title> <dev:code>PS C:\> Update-MarkdownHelpSchema .\Examples\PSReadLine.dll-help.md -OutputFolder .\PSReadLine Directory: D:\dev\platyPS\PSReadLine Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 5/22/2016 8:47 PM 1410 Get-PSReadlineKeyHandler.md -a---- 5/22/2016 8:47 PM 648 Get-PSReadlineOption.md -a---- 5/22/2016 8:47 PM 4091 Set-PSReadlineKeyHandler.md -a---- 5/22/2016 8:47 PM 10964 Set-PSReadlineOption.md</dev:code> <dev:remarks><maml:para>Upgrade PSReadLine platyPS markdown from version 1.0.0 to the latest one (2.0.0). </maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks><maml:navigationLink><maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/PowerShell/platyPS/blob/master/docs/Update-MarkdownHelpSchema.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |