Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve Example output formatting #502

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

roberttoups
Copy link

@roberttoups roberttoups commented Jan 16, 2021

The current formatting does not tag the code block as PowerShell. The remarks attribute sometimes is the formatted output of the example which is not within the code block. If there is a new line between the command example and the output of the command in the ".EXAMPLE", the output is considered remarks and will be unformatted by the current implementation. This provides, subjectively, a more esthetic output.

Here are examples of the output:
https://github.com/roberttoups/IPv4Toolbox/blob/master/Docs/Invoke-IPv4ListSort.md
https://github.com/roberttoups/IPv4Toolbox/blob/master/Docs/Get-SubnetInformation.md

The current formatting does not tag the code block as PowerShell. The remarks attribute sometimes is the formatted output of the example which are not within the code block. If there is a new line between the command example and the output of the command in the ".EXAMPLE", the output is considered remarks and will be unformatted by the current implementation. This provides, subjectively, a more esthetic output.

Here is an example of the output: https://github.com/roberttoups/IPv4Toolbox/blob/master/IPv4Toolbox/0.1.0/Docs/Invoke-IPv4ListSort.md
@roberttoups
Copy link
Author

I forgot to add there is a side benefit to improving the output of the New-ExternalHelp XML for the code examples.

@adityapatwardhan
Copy link
Member

@roberttoups Can you add a screenshot for before / after the change?

@roberttoups
Copy link
Author

Get-SubnetInformation-After.pdf
Get-SubnetInformation-Before.pdf
@adityapatwardhan These are rendered to PDF by Typora. The "Before" PDF is the output for the latest platyPS from the Gallery. The "After" is my modification.

@MariusStorhaug
Copy link

MariusStorhaug commented Mar 25, 2024

Although the code doesn't indicate a change to this, the pdf's have a different title. Think the old title of the examples were better, would rather have it accept a title. Maybe this needs to be fixed on the "backend" too, so that the engine itself supports it having a title when writing the comment based docs:

<#
    .EXAMPLE Adding a title to the example
    ...

    .EXAMPLE Showing more examples with titles
    ...
#>
...
## Examples

### Example 1: Adding a title to the example
...

### Example 2: Showing more examples with titles
...

Opened a separate issue on it: #627

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants