Standardize statement block/script block terminology

[surfingoldelephant]

Prerequisites

• 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.
• 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."
• 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-us/powershell/module/microsoft.powershell.core/about/about_throw
• https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_foreach
• https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_do
• https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_switch
• https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_psitem
• https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_script_blocks
• https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing

Summary

Statement block/script block terminology is inconsistent throughout the docs.

Details

Script block vs statement block

There are various instances throughout the documentation in which a statement block is incorrectly referred to as a script block. For example (non-exhaustive):

• PowerShell-Docs/reference/7.4/Microsoft.PowerShell.Core/About/about_Throw.md

  Lines 20 to 22 in 4a6a36f

  	For example, you can use the `throw` keyword in the script block of an `if`
  	statement to respond to a condition or in the `catch` block of a
  	`try`-`catch`-`finally` statement.

• PowerShell-Docs/reference/7.4/Microsoft.PowerShell.Core/About/about_Foreach.md

  Lines 140 to 142 in 4a6a36f

  	the location of functions contained within. The example demonstrates how to use
  	the `MoveNext` method and the `Current` property of the `$foreach` variable
  	inside of a `foreach` script block.

• PowerShell-Docs/reference/7.4/Microsoft.PowerShell.Core/About/about_Do.md

  Lines 18 to 20 in 4a6a36f

  	The `do` keyword works with the `while` keyword or the `until` keyword to run
  	the statements in a script block, subject to a condition. Unlike the related
  	`while` loop, the script block in a `do` loop always runs at least once.

• PowerShell-Docs/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md

  Lines 71 to 75 in 4a6a36f

  	switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] (<test-expression>) {
  	string | number | variable | { <value-scriptblock> }
  	{ <action-scriptblock> }
  	default { <action-scriptblock> } # optional
  	}

  
  (in the context of switch, value-scriptblock is correct for the conditional value, but action-scriptblock is not)

• PowerShell-Docs/reference/7.4/Microsoft.PowerShell.Core/About/about_PSItem.md

  Line 37 in 4a6a36f

  - In the scriptblock of a `catch` statement

Semantically, statement blocks are very different to script blocks and using the terms interchangeably is bound to cause confusion. I've seen cases where users were under impression that variable assignments don't persist outside the context of an if, switch, etc statement because some docs use the term "script block" in relation to these constructs.

Script block vs scriptblock

Referring to a script block in a general sense (i.e., not specifically as a type) is inconsistent. The docs are currently split on "script block" and "scriptblock". It should, in my opinion, be:

• "script block" when referring to it in a general sense (matches about_Script_Blocks)
• ScriptBlock/System.Management.Automation.ScriptBlock when referring to the type name/fullname itself
• [scriptblock] when referring to the type accelerator

Suggested Fix

• Correct all instances in which a statement block is referred to as a script block.
• Standardize the term "script block" throughout the docs.
• In about_Script_Blocks:
  • Note the differences between a script block and a statement block, such as scope creation and automatic variable management.
• In about_Parsing:
  • Note that in expression mode, {...} is parsed as a statement block when a language keyword is encountered. In argument mode or with variable assignment, it's parsed as a script block (literal).
  • Add a new section on whitespace differences between expression mode and argument mode.
    • A statement block's opening { can be placed on a new line due to whitespace insignificance in expression mode.
    • Like all arguments, a script block in argument mode must be on the same line as the parameter.
  • Correct the typo here ("begin a new script blocks" -> "begin a new script block").

I have a couple of write-ups here and here on the subject.

[surfingoldelephant]

I'm happy to work on this one. I just need confirmation that "script block" rather than "scriptblock" is the standardized term going forward.

I have a list of other terminology inconsistencies which I'll create a separate issue for.

• null/Null/NULL
• false/False/FALSE
• true/True/TRUE
• hash table/hashtable/Hashtable/HashTable
• keyword/statement/loop/construct/flow control
• dot source/dot-source/dotsource
• subexpression/sub-expression/sub expression
• member-access/member access
• declare/initialize (in context of a variable)
• Native/external command (see here)
• file system/filesystem
• file name/filename
• Localhost/localhost/LocalHost
• CIM session/CIMSession/CimSession/CIM Session
• wsman/WSMan/WSMAN
• PSSnapin/PSSnapIn/PsSnapin
• SDDL/Sddl/sddl
• winrm/WINRM/Winrm
• `try`-`catch`/`try/catch`/`Try/Catch`/Try Catch
• **Do-Until**/ `Do Until`
• **Script/Global/Local** scope / **script/global/local** scope / script/global/local scope