none
Composing PowerShell "Get-Help" that is readable in my code RRS feed

  • Question

  • Hopefully I explain this so that you guys can get what I am trying to do. It is not so much a problem, but more of a personal preference. I would like to keep my code as easily readable as can be so that includes not having the code extend so far to the right that the reader has to scroll over to the right to read all of the text (without word-wrap). In my actual PS Code I can use the back-tick ("`") to allow me to add a line return in the code which can help keep the code narrow on the page, but it doesn't affect the code running as all one line of code itself.

    I am trying to do the same thing in my Comment Based Help I include with the Functions.  If I add a return/line break in the code it also does so in the Help text when printed.  This does not allow for people to have different sized PowerShell windows an have the help text scale accordingly to use their window size.  If I write in one giant line with no line breaks in the code it scales itself and wraps accordingly.

    Is there any such character or means of doing this in my help text that allows me to add line returns in my code, but have it appear as one long line that word wraps at the edges of the window size when running the Get-Help command?

    If I use the back-tick it just prints the back-tick and does not keep it one line.  I'll try and show below.

    <#
    .SYNOPSIS
    
    This works because it is one long line with no returns on the code itself. This function outputs the relevant information for documenting a users configuration for work orders.
    
    .DESCRIPTION
    
    This dos not work right as when I add returns to code it adds returns to the output also. 
    This function outputs the relevant information for documenting a users ` 
    configuration for work orders. It outputs Name, Employee ID, Login, Title, `
    Description, AD OU, Email, Home Directory, expiration date, and group
    memberships.
    


    Find this post helpful? Does this post answer your question? Be sure to mark it appropriately to help others find answers to their searches.

    Saturday, April 5, 2014 1:00 PM

Answers

  • Another note - if the concern is that the long lines are difficult to edit in your text editor, perhaps use an editor that provides wrapping of long lines on the screen ("virtual" wrap). EmEditor has this feature and it's quite handy.


    -- Bill Stewart [Bill_Stewart]

    • Marked as answer by Chase Roth Sunday, April 6, 2014 12:42 PM
    Saturday, April 5, 2014 2:22 PM
    Moderator
  • Oops, you're right - I use both PowerShell v2 and v3 on different systems and I didn't notice the wrapping in v3 help. (Didn't bother me in v2.)

    If the question is about editing the help information in the code being difficult, then I recommend a better text editor.


    -- Bill Stewart [Bill_Stewart]

    • Marked as answer by Chase Roth Sunday, April 6, 2014 12:43 PM
    Saturday, April 5, 2014 3:23 PM
    Moderator
  • If the question is about editing the help information in the code being difficult, then I recommend a better text editor.


    -- Bill Stewart [Bill_Stewart]


    Yes, this is basically what I was asking. Some of the other responses got a bit off topic (while I appreciate the participation). I didn't know if there was a way to enter the help text similar to using back-tics in the actual code where when it is output it still thinks it is a single line so the default wrapping occurs, no matter the width of the window. When I manually put those returns as shown in the example, it is not flexible to window size.

    So if I am not mistaken, the long and short of this question is really, "no you can't change that you need to put it as one long line". Using a different editor may just help me read it while coding.

    I currently just use the PowerShell ISE. I hadn't even checked if it could word wrap or not. Other suggestions for editors that will assist and highlight the PowerShell commands, formats, key types, etc.? Does EmEditor you mention do something like that?


    Find this post helpful? Does this post answer your question? Be sure to mark it appropriately to help others find answers to their searches.

    • Edited by Chase Roth Saturday, April 5, 2014 5:20 PM
    • Marked as answer by Chase Roth Sunday, April 6, 2014 12:43 PM
    Saturday, April 5, 2014 5:15 PM

All replies

  • A very interest question.  I think many of us have asked that and similar questions.

    The specification for help is a broad standard and not just limited to PowerShell.  Using external help files is the most  flexible but the formatting is still limited to line breaks and spaces.  There is no true flow.

    If you want a more flexible display then you can do this:

    help help -ShowWindow

    V3 or later.

    The online version is easiest to read and should be most up-to-date.

    help help -online

    The online version allows us to display the sections with HTML flow.

    Using default properties you can set you help to always display in either the window or online.

    I would prefer that the inline help be specified with XML tags s owe would not get such an ugly display.


    ¯\_(ツ)_/¯

    Saturday, April 5, 2014 1:16 PM
  • Here is some background on the help structure: http://en.wikipedia.org/wiki/Microsoft_Assistance_Markup_Language


    ¯\_(ツ)_/¯

    Saturday, April 5, 2014 1:20 PM
  • The examples you provided take me external to the PowerShell window itself.  The -ShowWindow one is nice for the user to expand what they can see, so thanks for that info.  When the function is something I wrote I can't use the online (without making a page maybe...). 

    I want to try to further illustrate what I am asking, not sure if I did a good job explaining my issue the first time around.  My code snippet below.  And then a screenshot marked up with example of the output. 

    Under "Description" the first paragraph has line breaks in code.  The second paragraph does not it is just one long line in my code.  The second paragraph expands nicely in a larger powershell window OR when using your example of "Get-Help Get-ADUserInfo -ShowWindow".  The first paragraph does not.

    Function Get-ADUserInfo {
    # ----------------------------------------------------------------------------------------------
    #    Author:    Chase Roth
    #    Modified:  4/4/2014
    #    Version:   2.1.01
    # ----------------------------------------------------------------------------------------------
    
    <#
    .SYNOPSIS
    
    This function outputs the relevant information for documenting a users 
    configuration for work orders.
    
    .DESCRIPTION
    
    This function outputs the relevant information for documenting a users 
    configuration for work orders. It outputs Name, Employee ID, Login, Title,
    Description, AD OU, Email, Home Directory, expiration date, and group
    memberships.
    
    It can be used by itself to output data or used inline with other scripts. The parameters allow the removal of extra lines and spaces to fit nicer with the flow of the script. The headline or 'Title' can also be changed.
    
    .PARAMETER Identity
    
    Any valid input to 'Get-ADUser' is valid for this parameter.
    
    .PARAMETER Server
    
    Specify the Active Directory server to search. This is necessary when
    running this function immediately after changes have been made to the
    user to ensure you are getting the new information and not stale data
    that hasn't been updated by replication.
    
    .PARAMETER Title
    
    Text to be displayed above the outputted user data. Especially useful in
    other scripts to customize the title like, "Change of status for user",
    instead of the default.
    
    <...>


    Find this post helpful? Does this post answer your question? Be sure to mark it appropriately to help others find answers to their searches.

    Saturday, April 5, 2014 1:52 PM
  • you cannot control that.

    Also be very careful of using baqtics.  THey can create issues when copying and pasting,  they are hard to see, they are almost never needed.

    I suspect the designers of PowerShell threw them in for completeness.

    Example:

    Send-MailMessage -From $me -to $you -subject $subject -Body $body -BodyAsHtml -SmtpServer $smtpserver -Attachments $file1,$files -Credential $creds

    Pretty ugly right? Now with ba1tics:

    Send-MailMessage `
                    -From $me `
                    -to $you `
                    -subject $subject `
                    -Body $body `
                    -BodyAsHtml `
                    -SmtpServer $smtpserver `
                    -Attachments $file1,$files `
                    -Credential $creds
    

    Better but harder to edit and very easy to break.  Now look at modern PowerShell V2 and later.

    $smtpprops=@{
        From=$me
        to=$you
        subject=$subject
        Body=$body
        BodyAsHtml=$true
        SmtpServer=$smtpserver
        Attachments=$file1,$files
        Credential=$creds
    }
    
    Send-MailMessage @smtpprops
    

    Now that is clean, flexible, robust and easy to edit.  It can even be saved and auto-populated.


    ¯\_(ツ)_/¯

    Saturday, April 5, 2014 2:06 PM
  • Note that by using the external XML you can have better control over wrapping but the inline display or ShowWindow will limit this because of console or Window width setting.

    We can replace the window with an HTML system or even supply a style sheet for the XML and display a local help in a browser that can be very nicely formatted.  There are many of these available on the Internet for free.

    The simple answer is NO.  You cannot control the display by changing the text.


    ¯\_(ツ)_/¯

    Saturday, April 5, 2014 2:11 PM
  • AFAIK, you can't control word wrap at the edge of the window. But why do you need to?


    -- Bill Stewart [Bill_Stewart]

    Saturday, April 5, 2014 2:11 PM
    Moderator
  • I should also point out that the wrap width is based on your console setting.  Leaving the section as a long string allows PowerShell to size it to the console without choppy lines.

    XML forces us to use <para> tags to format the output.


    ¯\_(ツ)_/¯

    Saturday, April 5, 2014 2:16 PM
  • Yes, the lines will wrap automatically at the window edge, albeit without word wrap (the wrapping can occur in the middle of "words"). The formatter currently doesn't do word wrap. Maybe it's on the to-do list, but I doubt it's a high priority.

    [Edit: The above is correct for PowerShell v2. Looks like PowerShell v3 word-wraps help at the window edge (I hadn't noticed it).]


    -- Bill Stewart [Bill_Stewart]



    Saturday, April 5, 2014 2:19 PM
    Moderator
  • Another note - if the concern is that the long lines are difficult to edit in your text editor, perhaps use an editor that provides wrapping of long lines on the screen ("virtual" wrap). EmEditor has this feature and it's quite handy.


    -- Bill Stewart [Bill_Stewart]

    • Marked as answer by Chase Roth Sunday, April 6, 2014 12:42 PM
    Saturday, April 5, 2014 2:22 PM
    Moderator
  • In V3 and later the wrapping appears to have been fixed.  It always wraps on a word boundary.

    The problem we have is that the line breaks are stripped once we have a long line.  It appears they are stripped after the first long line.

    Run this and look at how it works in V4 (maybe V3).

    Function Get-ADUserInfo {
    <#
    .SYNOPSIS
    
    This function outputs the relevant information for documenting a users configuration for work orders.
    
    .DESCRIPTION
    
    This function outputs the relevant information for documenting a users configuration for work orders. It outputs Name, Employee ID, Login, Title, Description, AD OU, Email, Home Directory, expiration date, and group memberships.
    
    
    It can be used by itself to output data or used inline with other scripts. The parameters allow the removal of extra lines and spaces to fit nicer with the flow of the script. The headline or 'Title' can also be changed.
    
    .PARAMETER Identity
    
    Any valid input to 'Get-ADUser' is valid for this parameter.
    
    .PARAMETER Server
    
    Specify the Active Directory server to search. This is necessary when running this function immediately after changes have been made to the user to ensure you are getting the new information and not stale data that hasn't been updated by replication.
    
    .PARAMETER Title
    
    Text to be displayed above the outputted user data. Especially useful in other scripts to customize the title like, "Change of status for user", instead of the default.
    #>
    }
    
    Get-ADUserInfo -?


    ¯\_(ツ)_/¯

    Saturday, April 5, 2014 2:39 PM
  • If you are building a module you should use external help and not try to embed it into the script.


    ¯\_(ツ)_/¯

    Saturday, April 5, 2014 2:40 PM
  • Oops, you're right - I use both PowerShell v2 and v3 on different systems and I didn't notice the wrapping in v3 help. (Didn't bother me in v2.)

    If the question is about editing the help information in the code being difficult, then I recommend a better text editor.


    -- Bill Stewart [Bill_Stewart]

    • Marked as answer by Chase Roth Sunday, April 6, 2014 12:43 PM
    Saturday, April 5, 2014 3:23 PM
    Moderator
  • If the question is about editing the help information in the code being difficult, then I recommend a better text editor.


    -- Bill Stewart [Bill_Stewart]


    Yes, this is basically what I was asking. Some of the other responses got a bit off topic (while I appreciate the participation). I didn't know if there was a way to enter the help text similar to using back-tics in the actual code where when it is output it still thinks it is a single line so the default wrapping occurs, no matter the width of the window. When I manually put those returns as shown in the example, it is not flexible to window size.

    So if I am not mistaken, the long and short of this question is really, "no you can't change that you need to put it as one long line". Using a different editor may just help me read it while coding.

    I currently just use the PowerShell ISE. I hadn't even checked if it could word wrap or not. Other suggestions for editors that will assist and highlight the PowerShell commands, formats, key types, etc.? Does EmEditor you mention do something like that?


    Find this post helpful? Does this post answer your question? Be sure to mark it appropriately to help others find answers to their searches.

    • Edited by Chase Roth Saturday, April 5, 2014 5:20 PM
    • Marked as answer by Chase Roth Sunday, April 6, 2014 12:43 PM
    Saturday, April 5, 2014 5:15 PM
  • Her is one of many help editors: http://pscmdlethelpeditor.codeplex.com/


    ¯\_(ツ)_/¯

    Saturday, April 5, 2014 5:23 PM
  • Thanks, jrv. Do they also work for coding or just the help file?

    FYI, not at computer right now to check them.


    Find this post helpful? Does this post answer your question? Be sure to mark it appropriately to help others find answers to their searches.



    • Edited by Chase Roth Saturday, April 5, 2014 5:27 PM
    Saturday, April 5, 2014 5:25 PM
  • AFAIK the Sapien tools don't have any kind of word wrapping. I have used PrimalScript in the past and am very underwhelmed by the anemic text editor they offer (no regular expression replacements, keyboard is barely configurable, many other limitations that are surprising for a product at its price point).

    EmEditor has keyword completion but not inspection of PowerShell objects the way the ISE does. However the text editor is very full-featured and offers far more capability than the ISE or the Sapien text editors.

    You're right, I think this discussion has really gotten off-topic and is really not a scripting question.


    -- Bill Stewart [Bill_Stewart]

    Sunday, April 6, 2014 12:28 AM
    Moderator
  • Bill. You apparently haven't used PrimalScript for a number of years because those things are not completely correct.  I have use PrimalScript for years.  It has Regex search and replace but it is a basic version.  PowerShell Studio 2014 has an awesome PowerShell editor.  It also has an excellent debugger and script packager along with dozens of useful feature.  It is also capable of forms design, project oriented script development and tweam collaboration with versioning.

    The question of Help editors is that Sapien supports Help in the Advanced function with snippets and keyword replacement.  It is about as good a help editor as an except the ones designed specifically to edit PowerShell help like the link I posted to the codeplex editor project.

    Visual Studio has always been able to edit MAML files due to it's excellent XML editing capabilities.  Any advanced XML editor should be able to correctly edit MAML files.

    As far as I know EmEditor and other editors have NO support for help publishing either in the advanced function or in MAML.

    If you are just looking for an advanced capability PowerShell IDE then PowerShell Studio 2014 is the most advanced editor currently available.  If you just want a basic but good editor for free than the re are many available. I recommend trying all of them until you find one that fits your needs.


    ¯\_(ツ)_/¯

    Sunday, April 6, 2014 1:18 AM
  • Here is an example of how an XML editor is able to edit MAML files.

    Since MAML is  a defined XML schema and has a publicly available schema any decent XML editor will have smart editing.

    Here is a picture of a MAML file in PrimalScript XML editor:

    Notice that the xmlns is stll the old MSH.  The schemas are all basic MAML/2004 which is when Microsoft published the help spec.  On the right you see the elements. If I right click on any location in the tree an select insert element I get a list of legitimate elements for that level of the schema.  In XML this is automatic in almost all good editors.

    You can also use XML Notepad and Visual Studio Express to edit XML/MAML with Intellisense and auto complete.  Both PrimalScript and Visual Studio lack a find for XML.  Only them most advanced and expensive XML products include a complete find and query system such as the Altova products.


    ¯\_(ツ)_/¯

    Sunday, April 6, 2014 2:12 AM
  • I have used PrimalScript and I'm very underwhelmed by the text editor portion of the product (peculiar, since that's it's main reason for existing). It does not support regular expression replacing--it can find regex, but it can't replace using backreferences, which for me is a common operation. It has other limitations that, to me, are rather surprising for a product that's as expensive as it is--for example, the keyboard configurability is extremely limited, it has no macros, no virtual line wrapping (the subject of this post), and very weak column editing.

    It does support inspection of .NET objects and late-bound scripting objects, but object inspection is of less value to me than a very robust text editor. It's nearly unusable for me for day-to-day editing because the editor is far too anemic. My opinion, of course. As you said, there are many editors available and most (including PrimalScript) offer trial versions if they're not free.


    -- Bill Stewart [Bill_Stewart]

    Sunday, April 6, 2014 3:14 AM
    Moderator
  • Un the end an editor is very specific to each persons needs.  I used to use P-Edit for year.  It had all of that and edited every current language.  The Regex was awesome.  I have more than one hundred macros.  The company went out of business.

    I have not found an editor that has great RegEx and every thing else I need.  PowerShell Studio is the best PowerShell editor I have found.   So far I find I am lacking for nothing.  All editors that are inexpensive an have RegEx do not do most other things well.  If you have an editor that works the way you like then you are very lucky and should stick with it.

    The plus with PrimalScript is that it edits almost every scripting language and debugs any that have a debugger available. I canaslo write and build C# and VB.Net  exes when needed.  It is lighter weight than VS and easy to use for simple utilities and console programs.  I even use it to generate code in C# for use in  PowerShell.

    For me PrimalScript is almost perfect.  I'll suffer through the missing RegEx bits.

    I m pretty sure that PrimalScript 2014 has the updated RegEx module.  I will download a copy and check it out.  If it does - Sapien promised me that they were going to upgrade RegEx - I will be even happier.


    ¯\_(ツ)_/¯

    Sunday, April 6, 2014 3:25 AM
  • I can say this.  PowerShell Studio has the new RegEx provider and it does allow for replace with back reference.  I will test the PrimalScript 2014 tomorrow.


    ¯\_(ツ)_/¯

    Sunday, April 6, 2014 3:30 AM
  • Ok, so as I mentioned this has gotten off topic from my original post.  Long and short is, "no".  I need to just write the help text as one long line per paragraph so everything fits nicely when displayed in the PowerShell window.  If I want it pretty in my functions or script files while coding I just need to use an editor that has Line Wrap/Word Wrap. 

    Find this post helpful? Does this post answer your question? Be sure to mark it appropriately to help others find answers to their searches.

    Sunday, April 6, 2014 12:39 PM
  • Ok, so as I mentioned this has gotten off topic from my original post.  Long and short is, "no".  I need to just write the help text as one long line per paragraph so everything fits nicely when displayed in the PowerShell window.  If I want it pretty in my functions or script files while coding I just need to use an editor that has Line Wrap/Word Wrap. 

    Find this post helpful? Does this post answer your question? Be sure to mark it appropriately to help others find answers to their searches.

    As I originally posted.  The answer is NO you cannot format the output by any normal means.  If you use external help you can.  I believe it was you who kept asking if there was some way to work around this.   The answer is NO.


    ¯\_(ツ)_/¯

    Sunday, April 6, 2014 1:15 PM
  • As I originally posted.  The answer is NO you cannot format the output by any normal means.  If you use external help you can.  I believe it was you who kept asking if there was some way to work around this.   The answer is NO.


    ¯\_(ツ)_/¯

    I'm sorry. I must not be able to understand what you meant then. At no time did you say, "NO."  The closest thing you said was, "there is no true flow", which I didn't know what was meant by that.  You said:

    A very interest question.  I think many of us have asked that and similar questions.

    The specification for help is a broad standard and not just limited to PowerShell.  Using external help files is the most  flexible but the formatting is still limited to line breaks and spaces.  There is no true flow.

    If you want a more flexible display then you can do this:

    help help -ShowWindow

    V3 or later.

    The online version is easiest to read and should be most up-to-date.

    help help -online

    The online version allows us to display the sections with HTML flow.

    Using default properties you can set you help to always display in either the window or online.

    I would prefer that the inline help be specified with XML tags s owe would not get such an ugly display.

    When I saw all the references to other ways to read the help for the user, I felt you were looking in the wrong place as I just wanted my code in the background readable, but to display to the user as if I typed one long line, which I why I provided the visual screenshot. 

    You and I just don't seem to speak the same language.  Thanks for all your input and information.  I have marked several of your posts as helpful.


    Find this post helpful? Does this post answer your question? Be sure to mark it appropriately to help others find answers to their searches.

    Sunday, April 6, 2014 1:31 PM
  • You'll find that jrv really likes to have the last word. For sure he will post another reply to this thread even though you've already marked an answer. He won't move on unless he's posted the last message to the thread. [jrv knows I'm giving him a hard time and it's all in fun]


    -- Bill Stewart [Bill_Stewart]

    Sunday, April 6, 2014 1:37 PM
    Moderator
  • As I originally posted.  The answer is NO you cannot format the output by any normal means.  If you use external help you can.  I believe it was you who kept asking if there was some way to work around this.   The answer is NO.


    ¯\_(ツ)_/¯

    I'm sorry. I must not be able to understand what you meant then. At no time did you say, "NO."  The closest thing you said was, "there is no true flow", which I didn't know what was meant by that.  You said:

    A very interest question.  I think many of us have asked that and similar questions.

    The specification for help is a broad standard and not just limited to PowerShell.  Using external help files is the most  flexible but the formatting is still limited to line breaks and spaces.  There is no true flow.

    If you want a more flexible display then you can do this:

    help help -ShowWindow

    V3 or later.

    The online version is easiest to read and should be most up-to-date.

    help help -online

    The online version allows us to display the sections with HTML flow.

    Using default properties you can set you help to always display in either the window or online.

    I would prefer that the inline help be specified with XML tags s owe would not get such an ugly display.

    When I saw all the references to other ways to read the help for the user, I felt you were looking in the wrong place as I just wanted my code in the background readable, but to display to the user as if I typed one long line, which I why I provided the visual screenshot. 

    You and I just don't seem to speak the same language.  Thanks for all your input and information.  I have marked several of your posts as helpful.


    Find this post helpful? Does this post answer your question? Be sure to mark it appropriately to help others find answers to their searches.

    I thought you understood the question you were asking which was how to get text to flow correctly.  In word processing this is also referred to as " "justify" but it is not really the same thing.  In Windows "flow" is how text is adjusted to the space allocated for it.  In HTML this is controlled by "style".  In Windows it is a function of the control displaying the text.

    A console program has no Window or one Window depending on how you wan to argue it.  The window wraps long lines.  It has no other capabilities other tan line breaks and tabs.

    No flow no formatting.

    What I posted clearly implied "NO" and offered other methods to overcome this shortcoming.  I guess you just missed the implications of the language I used.  I will try to be less subtle in the future which I should do since so many here do not speak English as a first language at least not American English.


    ¯\_(ツ)_/¯

    Sunday, April 6, 2014 2:18 PM
  • I knew jrv wouldn't be able to resist posting another message to this thread. [grin]


    -- Bill Stewart [Bill_Stewart]

    Monday, April 7, 2014 3:08 PM
    Moderator
  • I knew jrv wouldn't be able to resist posting another message to this thread. [grin]


    -- Bill Stewart [Bill_Stewart]


    You were right I guess!

    Find this post helpful? Does this post answer your question? Be sure to mark it appropriately to help others find answers to their searches.

    Monday, April 7, 2014 10:54 PM
  • Bill, Chase - I knew you guys were incontinent.  I just love making you pee in your pants with excitement.  Go ahead.  Do it again. We love it.


    ¯\_(ツ)_/¯

    Monday, April 7, 2014 11:02 PM