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 DocumentOption 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 numbes.
        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 A.
 
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 'Exported straight into a text document'
        } | Export-Document -Format Text
 
    PScribo suports multiple output formats including text, html, xml and Microsoft Word. Each output format is
    provided by a separate plugin. For more details see about_Plugins.
 
SEE ALSO
    about_Plugins
    about_Styles
    about_Tables
 
# Built-in styles
# Footer style, report header
# DocumentOption settings overwritten upon each call.