Tutorial Design

[jdhitsolutions]

In the initial module design, tutorials are written as stand-alone script files. The module provides a function to launch the tutorial. Each tutorial is a combination of text, often formatted with PSStyle, live output from the user's console, Clear-Host commands, and pauses. I thought I might move the static content to JSON files that could be imported. However, that makes adding formatting more difficult unless the text is exported to JSON with the styling. But then there's the challenge of orchestrating the content with live output and pauses.

I think editing or updating the content in JSON would be tedious. Otherwise we would need an authoring tool. I think the stand-alone script is easy to maintain. The user never sees the code and I can't think of any performance benefit to moving the data to external files.

[jdhitsolutions]

The tutorial feature captures the user's actual prompt.

$prompt = ((&prompt | Out-String) -replace "`n|`r", '').Trim()

In the tutorial, a prompt is presented that looks like the user.

$P5 = @"

Notice the Verb-Noun naming convention. The source is the name of the PowerShell {0}module{1} that
contains the command. A module is a package of related commands. Many modules are shipped with
PowerShell. Eventually, you will learn how to install additional modules from the PowerShell Gallery.

The {0}Version{1} number is the module version number.

Once you narrow down the command you want, use {2}Get-Command{1} to show you the syntax or how
to run the command.

$prompt {2}Get-Command{1} {3}Get-Process{1} {4}-syntax{1}
"@ -f $highLight,$reset,$cmdStyle,$defaultTokenStyle,$paramStyle

When run it looks the like user's prompt:

Followed by live output of the command

[jdhitsolutions]

If the user has a heavily modified prompt, or one laden with ANSI, the prompt may not be properly captured. It is assumed that beginners will be running this module and most likely won't have customized prompts.

[jdhitsolutions]

If the prompt can't be captured, then a default prompt will be used.

#validate a prompt is captured, otherwise use a default
$prompt = ((&prompt | Out-String) -replace "`n|`r", '').Trim()
if ($prompt.Length -eq 0) {
    if ($IsWindows) {
        $prompt = "PS C:\> "
    }
    else {
        $prompt = "PS /home/$([Environment]::UserName)>"
    }
}

[SamErde]

That's a really creative concept! I'd be happy to test with a custom prompt or two.

[jdhitsolutions]

If the custom prompt uses Write-Host, there's no way to capture that.

[SamErde]

I may not be clear on what you're shooting for, but using Get-Command seems to be a reliable way to get the full definition of a custom prompt (when not considering Oh My Posh). Here's an example with one of my old prompts:

[jdhitsolutions]

Tutorials also use a custom pause function.

function pause {
    [void](Read-Host "`e[3;37mEnter to continue$($PSStyle.Reset)")
    "`e[2A"
    "`e[K"
    "`e[3A"
    "`e[1G"
}

The tutorial presents information in bite-size chunks and pauses.

The pause function will wait until the user presses Enter, but then it uses ANSI magic to remove the Enter to continue message from the screen and move on to the next bit of information.

[jdhitsolutions]

As of v0.10.0, the prompt will accept q as a quit character.

    $r = (Read-Host "`e[3;37m$($strings.continue)$($PSStyle.Reset)")
    if ($r -eq 'q') {
        $msg = $strings.tutorialCommand -f $cmdStyle,$reset
        Write-Host "`n$msg"
        Break
    }