Support paragraph wrapping in comment-based help
Votes from Connect: 7
Original Date Submitted: 8/16/2014 9:03:30 PM
Description:
Contact Information
Handle: Kirk Munro
Site Name: PowerShell
Feedback ID: 947737
Frequency: Always Happens
Regression: Yes, this happens in all previous versions
Problem Description:
Today if you wrap the text you enter for synopsis, description, parameters, etc. inside your comment-based help, PowerShell will output the help text for those fields exactly as it is displayed in the file. The trouble with this is that you really want two things:
- To wrap the text based on the size of the window where it is displayed, when someone opens the help.
- To wrap the text in your script file using a shorter length (such as 80 characters) so that it is easier to read and maintain in the file.
You can only achieve one of those two things today, because based on the current implementation, choosing one means choosing not to do the other.
I would like to see support added to comment-based help that allows for some text to be treated like markdown, so that you can achieve both of these goals: having text that is readable without scrolling horizontally in your ps1 files while having text that wraps properly when it is shown in help documentation.
Product Studio item created by Connect Synchronizer due to creation of feedback ID 947737 (http://connect.microsoft.com/PowerShell/feedback/ViewFeedback.aspx?FeedbackID=947737).
Repro Steps:
<#
.SYNOPSIS
This is the synopsis.
.DESCRIPTION
This is the description. If it is a long description, and if I want the text entered as a single paragraph that wraps properly when it is displayed, then I need to make sure that the paragraph doesn't contain any line breaks in my comment based help. Otherwise I end up with
lines broken just as I enter them in my description. If I prefer using a
width of something like 80 characters, then I can read the descriptive
text more easily in my file, but when the help is displayed in response to
a Get-Help request, PowerShell ends up having very short output lines that
do not respect the width of the display window. If for some reason the width I choose to use is longer than the width of the window where help is displayed
I may end up with some very unusual wrapping, which is unfortunate. Please consider providing a mechanism to control this more easily for both display of
help in the file (for maintenance purposes) and display of help in the help window.
And don't forget, being able to enter line breaks is important, so not all text should wrap, there should be a blank line above this line. :)
.INPUTS
None
.OUTPUTS
None
.EXAMPLE
PS C:\> Get-Help Test-Help
This command shows the help text with formatting issues based on how it is entered.
>
function Test-Help {}
Get-Help Test-Help
Expected Results:
I should be able to format my help in the script file so that it is readable without sacrificing how the help is output when help is requested.
Internal BugId: 8945
AdminJoey Aiello [MSFT]
(Program Manager, Windows Server)
shared this idea
1 comment
-
Marin Bernard
commented
I support this too! This would be a great feature.