Formatting inconsistencies and style guide updates

[surfingoldelephant]

Prerequisites

• [x] Existing Issue: Search the existing issues for this repository. If there is an issue that fits your needs do not file a new one. Subscribe, react, or comment on that issue instead.
• [x] Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Typo in Get-Foo cmdlet" instead of "Typo."
• [x] Verify Version: If there is a mismatch between documentation and the behavior on your system, ensure that the version you are using is the same as the documentation. Check this box if they match or the issue you are reporting is not version specific.

Links

https://learn.microsoft.com/en-gb/powershell/scripting/community/contributing/powershell-style-guide#formatting-command-syntax-elements

Summary

The purpose of this issue is to:

• Discuss inconsistent formatting aspects of the PowerShell-Docs project.
• Determine a consistent approach going forward and update the PowerShell-Docs style guide.
• Add missing items to Formatting command syntax elements.

Discussion items:

• Header code
• Method name
• Module name
• Attribute
• PowerShell provider
• $env:
• PATH and other environment variables
• Namespace
• Scope name
• Value (parameter/property/enumeration)
• True/False/Null value
• Numeric literal suffix

This issue is primarily focused on formatting. I intend to submit a separate issue to discuss terminology inconsistencies (e.g., keyword/statement/loop/construct/flow control).

Let me know if there are discussion points I've missed and I will update the post.

---

Header code

• Should headers contain formatting such as bold and code spans?
• Should headers start with a lowercase syntax element (e.g., keywords)?
• Notes:
  • Formatting is not rendered in the generated table of contents. E.g., "hidden keyword" will appear as "hidden keyword".
  • Markdown best practices currently states, "avoid using bold or other markup in headers".
  • Command parameter documentation consistently does not format parameter names.
• For example:

1. ## Hidden keyword
2. ## hidden keyword
3. ## `Hidden` keyword
4. ## `hidden` keyword

1. ## Using the ArgumentList parameter
2. ## Using the **ArgumentList** parameter
3. ## Using the `-ArgumentList` parameter

1. ### -Include
2. ### `-Include`

Method name

• Should method names always be referred to with a trailing ()?
• Note: The style guide uses ToString() as an example.
• For example:

1. ## Where method
2. ## `Where()` method
3. ## **Where** method

1. You can use the **Stop** method [...]
2. You can use the `Stop()` method [...]
3. You can use the `Stop` method [...]

Module name

• How should modules be referred to?
• For example:

1. This function is extended by the **PSReadLine** module.
2. This function is extended by the `PSReadLine` module.
3. This function is extended by the PSReadLine module.

Attribute

• How should attributes be referred to generally?
• For example:

1. When you use the `CmdletBinding` attribute [...]
2. When you use the **CmdletBinding** attribute [...]
3. When you use **CmdletBindingAttribute** [...]
4. When you use `[CmdletBinding()]` [...]

1. You can use the optional `Parameter` attribute alone [...]
2. You can use the optional **Parameter** attribute alone [...]
3. You can use the optional **ParameterAttribute** alone [...]
4. You can use the optional `[Parameter()]` attribute alone [...]

PowerShell provider

• Should provider names be formatted?
• For example:

1. The Environment provider [...] 
2. The `Environment` provider [...]
3. The **Environment** provider [...]

$env:

• Should $env: be capitalized?
• Notes:

  • All built-in PowerShell drives begin with an uppercase letter and tab complete as such. E.g.,

    $<Ctrl+Space>
    [...]
    Alias
    Env
    Function
    [...]
    ``
    
    

  • Env: prefixed with the $ sigil is an exception, that (erroneously) completes as $env:.

• For example:

1. $env:PSModulePath
2. $Env:PSModulePath

PATH and other environment variables

• How should PATH and other environment variables be referred to generally?
• Notes:
  • PATH is OS-agnostic or non-Windows. Path is specific to Windows.
  • The latter should only be used when referring specifically to Windows.
• For example:

1. The `$env:PATH` environment variable contains [...]
2. The **PATH** environment variable contains [...]
3. The `PATH` environment variable contains [...]

1. 
- `PSModulePath`

  The `$env:PSModulePath` environment variable contains [...]

2.
- **PSModulePath**

  The `$env:PSModulePath` environment variable contains

Namespace

• How should namespaces be formatted?
• For example:

1. **System** namespace
2. `System` namespace

Scope name

• How should a scope name (not modifier) be capitalized and formatted?
• For example:

1. To create the same variable in the global scope, use the scope `Global:` modifier:
2. To create the same variable in the Global scope, use the scope `Global:` modifier:
3. To create the same variable in the **Global** scope, use the scope `Global:` modifier:
4. To create the same variable in the `Global` scope, use the scope `Global:` modifier:

Value (parameter/property/enumeration)

• Per the style guide, parameter/property values should be formatted with a code span. Does this apply to all contexts?
• Are there any notable contexts in which bold formatting should be used?
• Should the following examples all use code spans rather than bold formatting/no formatting?

The `$ErrorActionPreference` variable takes [...] values: **SilentlyContinue**, **Stop**, **Continue**, **Inquire**,
**Ignore**, or **Suspend**.

This command sets the **MaxEnvelopeSizekb** value to 200 on the local computer.

This example shows the effect of the **Continue** value.

The acceptable values for this parameter are: **WSMan** and **DCOM**. The default value is **DCOM**.

A value of 0 indicates [...]

True/False/Null value

• How should a True/False/Null value be capitalized and formatted?
• Note: This does not refer to the automatic $true/$false/$null variables.

`true`/`false`/`null` value
`True`/`False`/`Null` value
`TRUE`/`FALSE`/`NULL` value

**true**/**false**/**null** value
**True**/**False**/**Null** value
**TRUE**/**FALSE**/**NULL** value

Numeric literal suffix

• Should numeric literal suffixes be lowercase, uppercase or a mixture?
• For example:

1. 1mb
2. 1Mb
3. 1MB

• When multiple suffixes are used, should the case be mixed?
• For example:

1. 1.30dmb
2. 1.30Dmb
3. 1.30dMB

---

Missing Style Guide Items

I propose adding the items below to the Formatting command syntax elements section of the style guide. These items feature prominently throughout the project, but are not explicitly mentioned in the style guide.

Code span

• PowerShell drive
  • Include :
  • Always capitalize the drive name, excluding $env:
  • E.g., Alias: drive, Cert: drive, C: drive
• Scope modifier
  • Include :
  • E.g., Global: scope modifier, Using: scope modifier
• Comment-based help keyword
  • Include .
  • E.g., .DESCRIPTION keyword
• File/process name/extension
  • E.g., powershell.exe file, powershell process, .ps1 extension
• #Requires statement
  • Include #

<kbd>

• Single keys and chords
  • E.g., Ctrl, Ctrl+Space

General

• Do not prefix member names with .. For example:
  • FullName property, not .FullName property
  • Where() method, not .Where() method

[surfingoldelephant]

Here are my thoughts. I've included the example I feel best represents each item.

Header code

Providing there are no technical reasons not to, I think header code should be formatted.

4. ## `hidden` keyword
2. ## Using the **ArgumentList** parameter
2. ### `-Include`

Method name

() helps distinguish methods from other member types, so should be used consistently.

2. ## `Where()` method
2. You can use the `Stop()` method [...]

Module name

Module names are closely linked to command names, which use code span formatting.

2. This function is extended by the `PSReadLine` module.

Attribute

General reference: CmdletBinding attribute Explicit code reference: [CmdletBinding()]

2. When you use the **CmdletBinding** attribute [...]
2. You can use the optional **Parameter** attribute alone [...]

PowerShell provider

There's an argument for all three styles. I'm leaning towards bold formatting; referring to a provider by name in code is far less common than speaking generally about a provider.

3. The **Environment** provider [...]

$env:

The fact $env: tab completes as lowercase is a longstanding bug, in my opinion. I like $Env: for consistency, but tab completion behavior should probably take precedence.

1. $env:PSModulePath

PATH and other environment variables

1. The `$env:PATH` environment variable contains [...]
1. 
- `PSModulePath`

  The `$env:PSModulePath` environment variable contains [...]

Namespace

Closely linked to type names, which use bold formatting.

1. **System** namespace

Scope name

Scope names are accepted as the value of many command parameters (e.g., Set-Variable -Scope Global), so code span formatting makes the most sense here, I think.

3. To create the same variable in the `Global` scope, use the scope `Global:` modifier:

Value (parameter/property/enumeration)

Based on the style guide, all of the values in the example (including the unformatted numbers) should be formatted with a code span.

True/False/Null value

`True`/`False`/`Null` value

Numeric literal suffix

I prefer lowercase suffixes, unless changing the case adds visual clarity/distinction.

1. 1mb
2. 1.30Dmb

[sdwheeler]

@surfingoldelephant Thanks! I love this discussion. I need to meet with my team to discuss.