Build/PScribo/en-US/about_Document.help.txt

TOPIC
Document
 
SYNOPSIS
PScribo is a documentation domain-specific language for Powershell. The Document keyword is used to instantiate a new PScribo document object.
 
DESCRIPTION
PScribo provides a set of functions that make it easy to create a document-like structure within Powershell, without having to handle multiple output formats. A document's layout and contents only need to defined once regardless of target output format(s).
     
After report creation, the document can be exported to one or more formats using the Export-Document cmdlet.
 
CREATING A DOCUMENT
After importing the PScribo module, you can start creating a PScribo document by using the 'Document' keyword together with a document name and a script-block. This can reside within a standard .ps1 file.
 
    Import-Module -Name PScribo
 
    Document 'Example Report' {
        Paragraph 'PScribo demonstration document'
        Section 'Heading' {
            Paragraph 'Local services'
            Get-Service | Table 'Services Table'
        }
    }
 
In the example above a table is created from the output of the Get-Service cmdlet. The 'Document' scriptblock can contain any standard Powershell code in addition to PScribo document-specific keywords such as:
 
    DocumentOption - sets global or plugin-specific options
    *Header - defines the document header displayed on all pages
    *Footer - defines the document footer displayed on all pages
    Style - defines a custom formatting style that can be applied to sections, paragraphs and within table styles.
    TableStyle - defines a custom formatting style for tables that is comprised of a heading, row and alternate row styles.
    Section - creates a new section or heading. Sections create a hierarchy within the document. Numbering can be applied to sections.
    Paragraph - creates a block of text.
    Table - creates a table from a collection of objects or an array of hashtables.
    PageBreak - inserts a page break.
    LineBreak - inserts a line break.
    BlankLine - inserts a blank line.
 
SETTING DOCUMENT OPTIONS
The GlobalOption cmdlet is used to set global document options, including page size and page margins. Supported parameters include:
     
    SpaceSeparator - the character used when spaces are encountered and need to be replaced.
    ForceUppercaseHeader - forces headings to uppercase.
    ForceUppercaseSection - forces section names to uppercase.
    EnableSectionNumbering - enables numbering on document sections. This numbering is automatic - you do not need to specify individual numbers.
    Margin - sets the all document margins to the points (pt) specified.
     MarginTopAndBottom - set the top and bottom page margins to the points (pt) specified (defaults to 72 pt or 1 inch).
     MarginLeftAndRight - set the left and right page margins to the points (pt) specified (defaults to 54 pt or 3/4 inch).
    PageSize - sets the page size. Available options include A4, Letter and Legal (defaults to A4).
 
EXPORTING A DOCUMENT
When the Document cmdlet is run, PScribo will return a PSCustomObject containing the nested document hierarchy and associated document options. Ths custom object can be stored in a variable for later use and/or piped into the Export-Document cmdlet.
 
The Export-Document cmdlet generates a document from the PSCustomObject in the specified formats. The following 2 examples will generate a 'Document1.txt' text document with a single paragraph in the current working directory.
 
    $MyDocument = Document 'Document1' {
        Paragraph 'Stored in a variable'
    }
    Export-Document -Document $MyDocument -Format Text
 
    ----
 
    Document 'Document1' {
        Paragraph 'Stored in a variable'
    } | Export-Document -Format Text
 
PScribo suports multiple output formats including text, html, xml and Microsoft Word. Each output format is provided by a plugin. For more details see about_Plugins.
 
SEE ALSO
    about_Plugins
    about_Styles
    about_Tables
 
# Built-in styles
# Footer style, report header
# GlobalOption settings overwritten upon each call.