Improve / fix the description of the -NoNewline parameter supported by Write-Host / Set-Content / Add-Content / Out-File / Out-String

[mklement0]

The actual behavior of the -NoNewline parameter is as follows:

• It directly concatenates the string representations of the input objects to form the output - it neither places newlines between them nor places a trailing newline after the last one.
  • Add a -NoLastNewline switch parameter to Write-Host, Set-Content, Add-Content, Out-File, Out-String PowerShell/PowerShell#5108 proposes adding a -NoLastNewline parameter that only suppresses a newline after the last input object.
• Additionally, with Out-File and (soon) Out-String, which implicitly use PowerShell's formatting system to generate the output strings, any normally multi-line representations generated for types that have PS formatting data have embedded newlines stripped as well.
  • Therefore, the -NoNewline behavior with Out-File / Out-String is not really useful with types that have formatting representations, but Out-File -NoNewline has worked this way since it was introduced in PSv5.
    Given that using formatter output is the primary reason for using Out-File / Out-String, I can't help but wonder whether -NoNewline should ever have been added to Out-File (and now Out-String) to begin with - see The -NoNewLine switch parameter of Out-File and Out-String should not strip embedded newlines from formatter-generated output  PowerShell/PowerShell#5107 (comment)

The current descriptions do not explain these behaviors adequately:

• Out-File's description of -NoNewline reads:

Specifies that the content displayed in the console [sic] does not end with a newline character.

• Set-Content (my personal favorite):

Indicates that this cmdlet uses the no newline setting.

• Add-Content:

Indicates that this cmdlet does not add a new line/carriage return to the content.

(As an aside: No need to reference specific chars. here - "newline" / "line break" works as a platform-neutral term; for the same reason, "newline character" should be avoided.)

• Write-Host:

Specifies that the content displayed in the console does not end with a newline character.

Version(s) of document impacted

• Impacts 6 document
• Impacts 5.1 document
• Impacts 5.0 document
• Impacts 4.0 document
• Impacts 3.0 document