Dude, Where's My Manual?

Dude, Where's My Manual?

  • Comments 11

Windows PowerShell comes with a lot of help files and documents, but, somehow, my favorite and most-frequently-used help is the help that  I get by typing "Get-Help" in the console.

 

And I have always wondered why this help is not readily available as a  single document, ready to be viewed, searched, and printed. Well, now it is, with this simple Get-Manual script.

 

This script merges all of the about_* help content with cmdlet help, and puts it into one pretty formatted Microsoft Word document (.doc). Once you have this document, you can search it for specific content. Or, you can print it and have some enjoyable reading while sitting in your favorite armchair by the fireplace during the long winter evenings :)

 

Updated 09/30/2008: Now the script not only collects the about_*.txt files, but it also includes the content of cmdlet help. It is also more localization-friendly. (Thanks to Markus for his brilliant CDATA suggestion!)

 

---------------------------------------------------------------------

 

# Get-Manual.ps1

# This script merges the text from all about* files
# in the Windows PowerShell installation directory ($pshome)
# and help content from cmdlet help
# into one MS Word document file and opens the file that was created.

# Setting up helper functions.

function MakeHeading($text)
{
 return '<w:p><w:pPr><w:pStyle w:val="Heading1" /></w:pPr><w:r><w:t><![CDATA[' + $text + ']]></w:t></w:r></w:p>'
}

function MakeParagraph($text)
{
 return '<w:p><w:r><w:t><![CDATA[' + $text + ']]></w:t></w:r></w:p>'
}


# Set the file name for generated WordML document.
$doc = "PowerShell Get-Help Content.doc"

"Generating MS Word document..."

$sb=new-object system.text.stringbuilder

$null = $sb.Append(@'
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<?mso-application progid="Word.Document"?>
<w:wordDocument
  xmlns:w="http://schemas.microsoft.com/office/word/2003/wordml"
  xmlns:wx="http://schemas.microsoft.com/office/word/2003/auxHint"
 w:macrosPresent="no" w:embeddedObjPresent="no" w:ocxPresent="no" xml:space="preserve">
 <w:styles>
  <w:versionOfBuiltInStylenames w:val="4" />
  <w:style w:type="paragraph" w:default="on" w:styleId="Normal">
   <w:name w:val="Normal" />
   <w:rPr>
    <w:rFonts w:ascii="Lucida Console" w:h-ansi="Lucida Console" w:cs="Lucida Console" />
    <w:sz w:val="24" />
    <w:sz-cs w:val="24" />
    <w:lang w:val="EN-US" w:fareast="ZH-CN" w:bidi="AR-SA" />
   </w:rPr>
  </w:style>
  <w:style w:type="paragraph" w:styleId="Heading1">
   <w:name w:val="heading 1" />
   <wx:uiName wx:val="Heading 1" />
   <w:basedOn w:val="Normal" />
   <w:next w:val="Normal" />
   <w:pPr>
    <w:pStyle w:val="Heading1" />
    <w:keepNext />
    <w:spacing w:before="240" w:after="120" />
    <w:outlineLvl w:val="0" />
   </w:pPr>
   <w:rPr>
    <w:b />
    <w:b-cs />
    <w:kern w:val="32" />
    <w:sz w:val="32" />
    <w:sz-cs w:val="32" />
   </w:rPr>
  </w:style>
 </w:styles>
 <w:docPr>
  <w:view w:val="web"/>
  <w:zoom w:val="full-page" w:percent="100"/>
 </w:docPr>
 <w:body>
'@)

# Get all content from about* help files.
$filter = "about*.txt"
dir $pshome -filter $filter -recurse | %{
 $null = $sb.Append((MakeHeading($_)))
 
 get-content $_.FullName | %{
  $null = $sb.Append((MakeParagraph($_)))
 }
}

# Get all content from cmdlet help.
get-command | %{
 $null = $sb.Append((MakeHeading($_.Name + ' Cmdlet')))

 $helpText = $_ | get-help -full | Out-String

 if ($helpText -eq "") { $helpText= '<no help found>' }

 $helpText -split "`n" | %{
  $null = $sb.Append((MakeParagraph($_)))
 }
}


$null = $sb.Append("</w:body></w:wordDocument>")

# Write generated string to document file.
$sb.ToString() | out-file $doc -encoding UTF8

# Open the resulting file in MS-Word.
$null = [System.Diagnostics.Process]::Start("$pwd\$doc")

"Done"
 

------------------------------------------------------------------------------

 

Vladimir Averkin

Windows PowerShell Test

Leave a Comment
  • Please add 3 and 7 and type the answer here:
  • Post
  • PingBack from http://blog.a-foton.ru/2008/07/dude-wheres-my-manual/

  • Ok, we need someone who's a wizard with PowerShell and Word to tweak this script to apply additional Styles to the sub-sections of the the about files.

    For example, this script already applies "heading 1" to the title of each document.

    You should be able to apply the same type of styles to other sections.  Such as:

    "sub-headings" = word: heading 2

    "paragraph text" = word: normal

    "code samples" = word: emphasis

    Should be pretty easy to do, since all the sections seem to be uniformly indented.   However, my wife will kill me if I spend the next several hours figuring out the in's-and-out's of Word formatting code.

    Someone who's a regular-expression wizard might even be able to do some fancy formatting with the "fixed width tables" (ie, where the document describes the available operators).  Though that would take some real work since it would involve back-tracking to prior lines once you "discover" a table.

  • PingBack from http://www.andreatedeschi.com/2008/07/generating-powershell-help-in-ms-word.html

  • I actually greatly prefer the HTML or compiled help versions floating around on the 'net.  A "flat" word doc is useless to me because this is reference material, not a book meant to be read straight through.

    Try these out:

    new-htmlhelp: http://tinyurl.com/5c326o

    PS Graphical Help (v1) http://tinyurl.com/63fn4v

    PS Graphical Help (v2) http://tinyurl.com/5a2x3u

    Also, most if not all of the good IDEs out there that have Powershell support also have integrated context-sensitive help.  PrimalScript, Powershell Analyzer, Admin Script Editor are some.  (Visual Studio 2008--not on the list.  :< )

  • The Windows PowerShell teams posts a script that will merge all of the PowerShell text files together

  • The PowerShell Graphical Help File has the same information, with more rich formatting.

    http://www.microsoft.com/downloadS/details.aspx?FamilyID=3b3f7ce4-43ea-4a21-90cc-966a7fc6c6e8&displaylang=en

  • From Text to Help with PowerShell

  • The version above doesn't work very well on international systems (ie German with Umlauts) so I made some simple modifications to make it work:

    * ensure Get-Content is called with -encoding UTF8

    * wrap the heading and text within CDATA sections; thus we also get rid of the .replace() statements automatically as a positive side-effect

    Here you are:

    # Get-Manual.ps1

    # This script merges the text from all about* help files in the Windows

    # PowerShell installation directory ($pshome) into one Microsoft Word

    # document (.doc) file and opens the file that was created.

    # Set the file name for generated WordML document.

    $doc = "AboutHelp.doc"

    "Generating MS Word document ..."

    $sb = New-Object System.Text.StringBuilder

    $null = $sb.Append(@'

    <?xml version="1.0" encoding="UTF-8" standalone="yes" ?>

    <?mso-application progid="Word.Document"?>

    <w:wordDocument

     xmlns:w="http://schemas.microsoft.com/office/word/2003/wordml"

     xmlns:wx="http://schemas.microsoft.com/office/word/2003/auxHint"

          w:macrosPresent="no" w:embeddedObjPresent="no" w:ocxPresent="no" xml:space="preserve">

          <w:styles>

                 <w:versionOfBuiltInStylenames w:val="4" />

                 <w:style w:type="paragraph" w:default="on" w:styleId="Normal">

                        <w:name w:val="Normal" />

                        <w:rPr>

                              <w:rFonts w:ascii="Lucida Console" w:h-ansi="Lucida Console" w:cs="Lucida Console" />

                              <w:sz w:val="24" />

                              <w:sz-cs w:val="24" />

                              <w:lang w:val="EN-US" w:fareast="ZH-CN" w:bidi="AR-SA" />

                        </w:rPr>

                 </w:style>

                 <w:style w:type="paragraph" w:styleId="Heading1">

                        <w:name w:val="heading 1" />

                        <wx:uiName wx:val="Heading 1" />

                        <w:basedOn w:val="Normal" />

                        <w:next w:val="Normal" />

                        <w:pPr>

                              <w:pStyle w:val="Heading1" />

                              <w:keepNext />

                              <w:spacing w:before="240" w:after="120" />

                              <w:outlineLvl w:val="0" />

                        </w:pPr>

                        <w:rPr>

                              <w:b />

                              <w:b-cs />

                              <w:kern w:val="32" />

                              <w:sz w:val="32" />

                              <w:sz-cs w:val="32" />

                        </w:rPr>

                 </w:style>

          </w:styles>

          <w:body>

    '@)

    # Get all text lines in about* help files.

    $filter = "about*.txt"

    dir $PsHome -filter $filter -recurse | %{

          $null = $sb.Append("<w:p><w:pPr><w:pStyle w:val=`"Heading1`" /></w:pPr><w:r><w:t><![CDATA[")

          $null = $sb.Append($_)

          $null = $sb.Append("]]></w:t></w:r></w:p>")

          Get-Content $_.FullName -encoding UTF8 | %{

                 $null = $sb.Append("<w:p><w:r><w:t><![CDATA[")

    $null = $sb.Append($_)

                 $null = $sb.Append("]]></w:t></w:r></w:p>")

          }

    }

    $null = $sb.Append("</w:body></w:wordDocument>")

    # Write generated string to document file.

    $sb.ToString() | Out-File $doc -encoding UTF8

    # Open the resulting file in MS-Word.

    $null = [System.Diagnostics.Process]::Start("$pwd\$doc")

    "Done"

  • I am getting an odd error when i try and run this.  When i run the script, i get the following:  

    A Text/XML declaration may occur at the very beginning of input.  

    Location: Line 2, Column:56

    This looks like it could be very helpful.  Any assistance would be great.

    app

  • I get this error as well. Can't open the Word doc.

  • About the following error:

    A Text/XML declaration may occur at the very beginning of input.  

    Location: Line 2, Column:56

    This error can happen if there is a whitespace character at the biginning of the file. It can be SPACE or TAB or LF or CR or any of them in combination. Most probably it is caused by  inadvertent insertion of tab or space character into the script while copy-pasting it.

    To fix it please make sure that in the following lines

    $null = $sb.Append(@'

    <?xml version="1.0" encoding="UTF-8" standalone="yes" ?>

    there are no extra whitespace characters between @' and <?xml

Page 1 of 1 (11 items)