en-US/platyPS.psm1-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-PlatyPSExternalHelp</command:name> <command:verb>Get</command:verb> <command:noun>PlatyPSExternalHelp</command:noun> <maml:description><maml:para>Create External help file from platyPS markdown. </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 provided input doesn't follow schema described in platyPS.schema.md </maml:para> <maml:para>Store output of this command in the module directory in corresponding language folder, i.e en-US. </maml:para> </maml:description> <command:syntax><command:syntaxItem><maml:name>Get-PlatyPSExternalHelp</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>MarkdownFolder</maml:name> <maml:Description></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>skipPreambula</maml:name> <maml:Description></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>Get-PlatyPSExternalHelp</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>markdown</maml:name> <maml:Description></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>skipPreambula</maml:name> <maml:Description></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>MarkdownFolder</maml:name> <maml:Description><maml:para>Path to a folder with "*.md" files. Their content would be extracted and used. It may be convinient for big modules. Also breaking markdown to several files speed-up convertion process. </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>This parameter takes array of string, so you can simply pipe output of Get-Content . </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>skipPreambula</maml:name> <maml:Description><maml:para>Switch to avoid emmiting xml preambula and <helpitems> tag. </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:inputTypes> <command:returnValues><command:returnValue><dev:type><maml:name>System.String</maml:name> </dev:type> <maml:description><maml:para>Xml document that should be stored to the module folder in the corresponding language folder. </maml:para> <maml:para>I.e. en-US\platyPS.psm1-Help.xml </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 (platyPS) ------------------------------------</maml:title> <dev:code>$maml = Get-PlatyPSExternalHelp -markdown (cat -raw .\src\platyPS\platyPS.md) mkdir out\platyPS\en-US -ErrorAction SilentlyContinue > $null Set-Content -path out\platyPS\en-US\platyPS.psm1-Help.xml -Value $maml -Encoding UTF8</dev:code> <dev:remarks><maml:para> </maml:para> </dev:remarks> </command:example> <command:example><maml:title>----------------------------- Example 2 (skipPreambula) ------------------------------------</maml:title> <dev:code>$markdown = Get-PlatyPSMarkdown Get-PlatyPSMarkdown | Out-String Get-PlatyPSExternalHelp -markdown $markdown -skipPreambula | clip</dev:code> <dev:remarks><maml:para>Create $maml entry for one command and copy it to clip-board to copy-paste it into existing maml. </maml:para> </dev:remarks> </command:example> <command:example><maml:title>----------------------------- Example 3 (MarkdownFolder) ------------------------------------</maml:title> <dev:code>$maml = Get-PlatyPSExternalHelp -MarkdownFolder .\src\platyPS</dev:code> <dev:remarks><maml:para>You can break help for the big module into several markdown files and put them into a folder. In this case, you may find -MarkdownFolder parameter more convinient. </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> </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-PlatyPSMarkdown</command:name> <command:verb>Get</command:verb> <command:noun>PlatyPSMarkdown</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: Generate 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>Get-PlatyPSMarkdown</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"><maml:name>command</maml:name> <maml:Description></maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type><maml:name>Object</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>OneFilePerCommand</maml:name> <maml:Description></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>OutputFolder</maml:name> <maml:Description></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-PlatyPSMarkdown</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"><maml:name>maml</maml:name> <maml:Description></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>OneFilePerCommand</maml:name> <maml:Description></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>OutputFolder</maml:name> <maml:Description></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-PlatyPSMarkdown</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"><maml:name>module</maml:name> <maml:Description></maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type><maml:name>Object</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>OneFilePerCommand</maml:name> <maml:Description></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>OutputFolder</maml:name> <maml:Description></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>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">Object</command:parameterValue> <dev:type><maml:name>Object</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>maml</maml:name> <maml:Description><maml:para>Path or content of file with existing External Help (aka maml). </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="named" aliases="none"><maml:name>module</maml:name> <maml:Description><maml:para>Name of the module for bulk help generation. </maml:para> </maml:Description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type><maml:name>Object</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>OneFilePerCommand</maml:name> <maml:Description><maml:para>Use this switch to create a folder with one .md file per cmdlet. This parameter requires specifing -OutputFolder. </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>OutputFolder</maml:name> <maml:Description><maml:para>Path to a folder to output markdown files. This parameter requires -OneFilePerCommand. </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.Object</maml:name> </dev:type> <maml:description><maml:para> </maml:para> </maml:description> </command:inputType> <command:inputType><dev:type><maml:name>System.String</maml:name> </dev:type> <maml:description><maml:para> </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues><command:returnValue><dev:type><maml:name>System.String[]</maml:name> </dev:type> <maml:description><maml:para> </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>function foo {param([string]$bar)} Get-PlatyPSMarkdown -command foo</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>Import-Module platyPS Get-PlatyPSMarkdown -module platyPS</dev:code> <dev:remarks><maml:para>Module should be loaded in the PS Session. </maml:para> </dev:remarks> </command:example> <command:example><maml:title>----------------------------- Example 3 (from maml file path) ------------------------------------</maml:title> <dev:code>Get-PlatyPSMarkdown -maml 'C:\Program Files\WindowsPowerShell\Modules\PSReadline\1.1\en-US\Microsoft.PowerShell.PSReadline.dll-help.xml'</dev:code> <dev:remarks><maml:para>Create markdown help for inbox PSReadLine module. </maml:para> </dev:remarks> </command:example> <command:example><maml:title>----------------------------- Example 4 (from maml file content) ------------------------------------</maml:title> <dev:code>Get-PlatyPSMarkdown -maml (cat -raw 'C:\Program Files\WindowsPowerShell\Modules\PSReadline\1.1\en-US\Microsoft.PowerShell.PSReadline.dll-help.xml')</dev:code> <dev:remarks><maml:para>Create markdown help for inbox PSReadLine module. </maml:para> </dev:remarks> </command:example> <command:example><maml:title>----------------------------- Example 4 (maml, OneFilePerCommand) ------------------------------------</maml:title> <dev:code>Get-PlatyPSMarkdown -maml 'C:\Program Files\WindowsPowerShell\Modules\PSReadline\1.1\en-US\Microsoft.PowerShell.PSReadline.dll-help.xml' -OneFilePerCommand -OutputFolder PSReadLineHelp</dev:code> <dev:remarks><maml:para>Create markdown help for inbox PSReadLine module and output them into a PSReadLineHelp folder. Create one .md file per cmdlet. </maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks></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-PlatyPSModuleFromMaml</command:name> <command:verb>New</command:verb> <command:noun>PlatyPSModuleFromMaml</command:noun> <maml:description><maml:para>Takes a MAML file and generates a script module with corresponding help at the given location. </maml:para> </maml:description> </command:details> <maml:description><maml:para>Command generates dummy module with particular External Help file. You can use it to see, how generated help will look like. </maml:para> <maml:para>This cmdlet generates an object which contains the module name, module path and the list of cmdlets for the generated module. </maml:para> </maml:description> <command:syntax><command:syntaxItem><maml:name>New-PlatyPSModuleFromMaml</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="0" aliases="none"><maml:name>MamlFilePath</maml:name> <maml:Description></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>DestinationPath</maml:name> <maml:Description></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="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"><maml:name>DestinationPath</maml:name> <maml:Description><maml:para>Path to a folder, where module should be generated. </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="0" aliases="none"><maml:name>MamlFilePath</maml:name> <maml:Description><maml:para>Path to the 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:parameters> <command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name> </dev:type> <maml:description><maml:para> </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues><command:returnValue><dev:type><maml:name>System.Object</maml:name> </dev:type> <maml:description><maml:para> </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 (test the module) ------------------------------------</maml:title> <dev:code>$generatedModule = New-PlatyPSModuleFromMaml -MamlFilePath $outMamlFilePath $generatedModule.Cmdlets | % { Get-Help -Name "$($generatedModule.Name)\$_" -Full | Out-String }</dev:code> <dev:remarks><maml:para>Show generated help for the whole module as an output of Help engine system. </maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks></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-PlatyPSTextHelpFromMaml</command:name> <command:verb>Get</command:verb> <command:noun>PlatyPSTextHelpFromMaml</command:noun> <maml:description><maml:para>Get help text from an external help file xml as a plain text file. </maml:para> </maml:description> </command:details> <maml:description><maml:para>Command cretes a temp module with specified external help file and queries help engine to produce a text help for it. </maml:para> </maml:description> <command:syntax><command:syntaxItem><maml:name>Get-PlatyPSTextHelpFromMaml</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="0" aliases="none"><maml:name>MamlFilePath</maml:name> <maml:Description></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>TextOutputPath</maml:name> <maml:Description></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="0" aliases="none"><maml:name>MamlFilePath</maml:name> <maml:Description><maml:para>Path to the 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="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"><maml:name>TextOutputPath</maml:name> <maml:Description><maml:para>Path to output file with generated text help. </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> </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> </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 (platyPS) ------------------------------------</maml:title> <dev:code>Get-PlatyPSTextHelpFromMaml .\out\platyPS\en-US\platyPS.psm1-Help.xml -TextOutputPath platyPS.txt</dev:code> <dev:remarks><maml:para> </maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks></command:relatedLinks> </command:command> </helpItems> |