|
| 1 | +# Formatting code blocks |
| 2 | + |
| 3 | +We want to adopt a consistent style for PowerShell code blocks and output in our documentation. |
| 4 | +The existing documentation has uses multiple styles and the formatting rules have changed multiple times. |
| 5 | +The current Open Publishing System (OPS) we use has a syntax highlighting feature that support many languages. |
| 6 | +OPS also adds a **Copy** button that copies the contents of the code block to the clipboard. |
| 7 | +This allows you to quickly paste the code into a script for testing the code example. |
| 8 | +However, not all examples in our documentation are intended to be run. |
| 9 | +Some code blocks are simple illustrations of a PowerShell concept. |
| 10 | + |
| 11 | +We are defining two scenarios for code blocks: |
| 12 | + |
| 13 | +1. Illustrative examples |
| 14 | +2. Executable examples |
| 15 | + |
| 16 | +## Formatting illustrative examples |
| 17 | + |
| 18 | +Illustrative examples are used to explain a PowerShell concept. |
| 19 | +They are not meant to be copied to the clipboard for execution. |
| 20 | +These are most commonly used for simple examples that are easy to type. |
| 21 | +They are also used for syntax examples where you are illustrating the syntax of a command. |
| 22 | + |
| 23 | +Illustrative examples use a "naked" code fence to mark the beginning and end of the code block. |
| 24 | +The code block may contain example output from the command being illustrated. |
| 25 | + |
| 26 | +### Syntax block |
| 27 | + |
| 28 | +Here is an example of a syntax block: |
| 29 | + |
| 30 | + ``` |
| 31 | + Get-Command [-Verb <String[]>] [-Noun <String[]>] [-Module <String[]>] |
| 32 | + [-FullyQualifiedModule <ModuleSpecification[]>] [-TotalCount <Int32>] [-Syntax] [-ShowCommandInfo] |
| 33 | + [[-ArgumentList] <Object[]>] [-All] [-ListImported] [-ParameterName <String[]>] |
| 34 | + [-ParameterType <PSTypeName[]>] [<CommonParameters>] |
| 35 | + ``` |
| 36 | + |
| 37 | +This is example is illustrating all of the possible parameters of the `Get-Command` cmdlet. |
| 38 | + |
| 39 | +Here is another syntax example that is describing the `for` statement in general terms: |
| 40 | + |
| 41 | + ``` |
| 42 | + for (>init>; <condition>; <repeat>) |
| 43 | + {<statement list>} |
| 44 | + ``` |
| 45 | + |
| 46 | +### Simple illustration example |
| 47 | + |
| 48 | +Here is an example illustrating PowerShell comparison operators: |
| 49 | + |
| 50 | + ``` |
| 51 | + PS> 2 -eq 2 |
| 52 | + True |
| 53 | + |
| 54 | + PS> 2 -eq 3 |
| 55 | + False |
| 56 | + |
| 57 | + PS> 1,2,3 -eq 2 |
| 58 | + 2 |
| 59 | + |
| 60 | + PS> "abc" -eq "abc" |
| 61 | + True |
| 62 | + |
| 63 | + PS> "abc" -eq "abc", "def" |
| 64 | + False |
| 65 | + |
| 66 | + PS> "abc", "def" -eq "abc" |
| 67 | + abc |
| 68 | + ``` |
| 69 | + |
| 70 | +Note that this example has the simplified PowerShell prompt and shows the resulting output. |
| 71 | +In this case, we don't intend the reader to copy this example and try to run the copied code. |
| 72 | + |
| 73 | +## Formatting executable examples |
| 74 | + |
| 75 | +More complex examples or examples that would be useful to copy and execute should use <code>\`\`\`powershell</code> … <code>\`\`\`</code> code fence markers. |
| 76 | +Output emitted by PowerShell commands should be enclosed in a **Output** code block to prevent syntax highlighting. |
| 77 | + |
| 78 | + For example: |
| 79 | + |
| 80 | + ```powershell |
| 81 | + Get-Command -Module Microsoft.PowerShell.Security |
| 82 | + ``` |
| 83 | + |
| 84 | + ```Output |
| 85 | + CommandType Name Version Source |
| 86 | + ----------- ---- ------- ------ |
| 87 | + Cmdlet ConvertFrom-SecureString 3.0.0.0 Microsoft.PowerShell.Security |
| 88 | + Cmdlet ConvertTo-SecureString 3.0.0.0 Microsoft.PowerShell.Security |
| 89 | + Cmdlet Get-Acl 3.0.0.0 Microsoft.PowerShell.Security |
| 90 | + Cmdlet Get-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security |
| 91 | + Cmdlet Get-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security |
| 92 | + Cmdlet Get-Credential 3.0.0.0 Microsoft.PowerShell.Security |
| 93 | + Cmdlet Get-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security |
| 94 | + Cmdlet Get-PfxCertificate 3.0.0.0 Microsoft.PowerShell.Security |
| 95 | + Cmdlet New-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security |
| 96 | + Cmdlet Protect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security |
| 97 | + Cmdlet Set-Acl 3.0.0.0 Microsoft.PowerShell.Security |
| 98 | + Cmdlet Set-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security |
| 99 | + Cmdlet Set-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security |
| 100 | + Cmdlet Test-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security |
| 101 | + Cmdlet Unprotect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security |
| 102 | + ``` |
| 103 | + |
| 104 | +The **Output** code label is not an official "language" supported by the syntax highlighting system. |
| 105 | +However, this label is useful because OPS adds the "Output" label to the code box on the web page. |
| 106 | +And this "Output" code box has no syntax highlighting. |
| 107 | + |
| 108 | +## Understanding the COPY button |
| 109 | + |
| 110 | +OPS also adds a **Copy** button that copies the contents of the code block to the clipboard. |
| 111 | +This allows you to quickly paste the code into a script for testing the code example. |
| 112 | +The **Copy** button also removes PowerShell prompts from the text before copying it to the clipboard. |
| 113 | +The **Copy** button uses the following javascript code to remove the prompts. |
| 114 | + |
| 115 | +```javascript |
| 116 | +if (language === 'powershell') { |
| 117 | + text = text.replace(/\bPS [a-z]:\\>\s?/gi, ''); |
| 118 | +} |
| 119 | +``` |
| 120 | + |
| 121 | +Note that the regex used only matches simple prompts like "`PS C:\>`". |
| 122 | +Prompts that include subdirectories or paths from other PSDrive providers will not be removed. |
| 123 | +See the general guidelines, in the next section, for the appropriate use of prompts in examples. |
| 124 | + |
| 125 | +## General guidelines |
| 126 | + |
| 127 | +- Code fences |
| 128 | + |
| 129 | + Markdown allows for indentation to signal code block, however, all code blocks should be contained in a code fence. |
| 130 | + A code fence is a block of code surrounded by <code>\`\`\`</code> strings. |
| 131 | + The code fence markers must be on their own line before and after the code sample. |
| 132 | + The marker at the start of the code block may have an optional language label. |
| 133 | + See the previous discussion about illustrative and executable examples for the proper use of language labels. |
| 134 | + |
| 135 | +- Line continuation in code samples |
| 136 | + |
| 137 | + Avoid using line continuation characters (\`) in PowerShell code examples. |
| 138 | + These are a hard to see and can cause problems if there are extra spaces on the end of the line. |
| 139 | + Use PowerShell splatting to reduce line length for cmdlets that have a lot of parameters. |
| 140 | + Take advantage of PowerShell's natural line break opportunities, like after pipe (\|) characters and opening braces, parentheses, and brackets. |
| 141 | + |
| 142 | +- PowerShell prompts in examples |
| 143 | + |
| 144 | + PowerShell prompts should only be used in illustrative examples (as defined previously). |
| 145 | + For most of these examples, the prompt string should be "`PS>`". |
| 146 | + This prompt is independent of OS-specific indicators. |
| 147 | + Use of the prompt string is discouraged and should be limited to scenarios that are meant to illustrate command line usage. |
| 148 | + More complex prompt strings are required for examples that illustrate commands that alter the prompt |
| 149 | + or when the path displayed is significant to the scenario being illustrated. |
| 150 | + The following example illustrate how the prompt changes when using the Registry provider. |
| 151 | + |
| 152 | + ``` |
| 153 | + PS C:\> cd HKCU:\System\ |
| 154 | + PS HKEY_CURRENT_USER\System\> dir |
| 155 | + |
| 156 | + |
| 157 | + Hive: HKEY_CURRENT_USER\System |
| 158 | + |
| 159 | + |
| 160 | + Name Property |
| 161 | + ---- -------- |
| 162 | + CurrentControlSet |
| 163 | + GameConfigStore GameDVR_Enabled : 1 |
| 164 | + GameDVR_FSEBehaviorMode : 2 |
| 165 | + Win32_AutoGameModeDefaultProfile : {2, 0, 1, 0...} |
| 166 | + Win32_GameModeRelatedProcesses : {1, 0, 1, 0...} |
| 167 | + GameDVR_HonorUserFSEBehaviorMode : 0 |
| 168 | + GameDVR_DXGIHonorFSEWindowsCompatible : 0 |
| 169 | + ``` |
0 commit comments