dataplat/docs

Command output

Closed this issue · 7 comments

niphlod commented

it's just multiline ........ see "multiline" as in "how do I separate the part that lives in the PS console and its explanation"

wsmelton commented

I don't follow...a multiline command in PS is not the same thing as output.

niphlod commented

yeah, but the real thing "the page wants" is just "separation" between "code/console" and "humanized description".
You can use the same "techniques" to keep the "code/console" part "open" for multiline commands, singleline commands with multiline outputs, etc .

I guess I'll update those so they can be used as an example, and then close this

niphlod commented

sorry, maybe I grasped.
This is what it can be right now

image

I get that the PS output "object" in a console is not >> prefixed but at that point neither PS nor "the docs page" can tell when the piece of the example regarding code is closed or not. We can insert another identifier for "lines in console which do not need to be rendered with >>" (was thinking about ...) but I'm asking if it's something we really want or if we wanna go for the rendering from above.

niphlod commented

the more "complicated version" would be to rewrite CBH as

    .LINK
        https://dbatools.io/Test-DbaConnection

    .EXAMPLE
        PS C:\> Test-DbaConnection -SqlInstance SQL2016
        ...
        ... ComputerName         : SQL2016
        ... InstanceName         : MSSQLSERVER
        ... SqlInstance          : sql2016
        ... SqlVersion           : 13.0.4001
        ... ConnectingAsUser     : BASE\ctrlb
        ... ConnectSuccess       : True
        ... AuthType             : Windows Authentication
        ... AuthScheme           : KERBEROS
        ... TcpPort              : 1433
        ... IPAddress            : 10.2.1.5
        ... NetBiosName          : sql2016.base.local
        ... IsPingable           : True
        ... PSRemotingAccessible : True
        ... DomainName           : base.local
        ... LocalWindows         : 10.0.15063.0
        ... LocalPowerShell      : 5.1.15063.502
        ... LocalCLR             : 4.0.30319.42000
        ... LocalSMOVersion      : 13.0.0.0
        ... LocalDomainUser      : True
        ... LocalRunAsAdmin      : False


        Test connection to SQL2016 and outputs information collected

to get this

image

This way, >> still denotes multiline, while ... denotes the output (which is hidden in the "rendering").

niphlod commented

or, maybe, this is better (also because the "copy" will effectively copy just the command and not the output).

    .LINK
        https://dbatools.io/Test-DbaConnection

    .EXAMPLE
        PS C:\> Test-DbaConnection -SqlInstance SQL2016
        ```
        ComputerName         : SQL2016
        InstanceName         : MSSQLSERVER
        SqlInstance          : sql2016
        SqlVersion           : 13.0.4001
        ConnectingAsUser     : BASE\ctrlb
        ConnectSuccess       : True
        AuthType             : Windows Authentication
        AuthScheme           : KERBEROS
        TcpPort              : 1433
        IPAddress            : 10.2.1.5
        NetBiosName          : sql2016.base.local
        IsPingable           : True
        PSRemotingAccessible : True
        DomainName           : base.local
        LocalWindows         : 10.0.15063.0
        LocalPowerShell      : 5.1.15063.502
        LocalCLR             : 4.0.30319.42000
        LocalSMOVersion      : 13.0.0.0
        LocalDomainUser      : True
        LocalRunAsAdmin      : False
        ```

        Test connection to SQL2016 and outputs information collected

will be rendered as
image

/cc @potatoqualitee , @wsmelton

  • 👍1
niphlod commented

okay, we'll go for the latest