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. |