format Parameter

Specifies the format controls for the current element.

Scope: Element

Syntax

query format 
set format [absolute Level|before Number] [after Number] 
           [break|nobreak] [final|nofinal] [flow|noflow]
           [postspace|nopostspace] [prespace|noprespace] 
           [solid|nosolid] [spill|nospill] 

Options

absolute Level 
Set the Level of the current and subsequent elements. Level must not be negative.
after Number 
Change the level of subsequent elements by Number relative to the current element. Number can be positive (higher level ) or negative (lower level).
before Number 
Change the level of the current and subsequent elements by Number relative to the previous element. Number can be positive (lower level) or negative (higher level). Both before and after values can be specified for the same element.
break 
Always start this element on a new line, even if format flow is set, or the element would otherwise be flowed because of the setting of the flow parameter.
final 
Always start the next element on a new line, even if it has format flow set, or the element would otherwise be flowed because of the setting of flow parameter.
flow 
Wrap this element to follow the preceding element unless break or final is set on the previous line.
postspace 
Include a blank line after this element, and always start the next element on a new line.
prespace 
Include a blank line before this element, and always start this element on a new line.
solid 
Indicates that the element is solid. The formatter must not split the element at blanks (or elsewhere) except when there is no other way to format the element.
spill 
Indicates that the element can be spilled. That is, the element can be formatted at the spill width rather than at the formwidth.

Description

The format parameter sets or replaces the formatting controls for the current element. Formatting controls are used to enhance the displayed document. The last option specified has the highest priority.

Note: The set formatter command must be set to on to display the formatting controls.
Important! This parameter is intended for use by programmers writing structured parsers. Formatting controls are not checked until they are used. Inconsistencies may lead to unexpected results.

Examples

The following examples refer to these elements:

start line 1---------------------end line 1 
start line 2---------------------end line 2 
start line 3---------------------end line 3 
start line 4---------------------end line 4 
start line 5---------------------end line 5 
  1. To ensure that line 3 always starts on a new line, place the cursor on line 3 and type:
    set format break 
  2. Suppose you have already used the format parameter to ensure line 3 always starts on a new line. To ensure that line 3 always starts on a new line and that it can be spilled, type:
    set format break spill 

    Simply typing format spill would have deleted the previous break option, so break had to be repeated in the latest command.

  3. To reverse a previously issued set format break setting for line 3, place the cursor on line 3 and type:
    set format nobreak 
  4. To indicate that line 3 can be spilled, if it were extended, type:
    set format spill 
  5. To set the level of lines 3, 4, and 5 to level 4, place the cursor on line 3 and type:
    set format absolute 4 

    Lines 3, 4, and 5 are indented by the number of spaces appropriate for level 4 elements (if indent is set to a value other than zero). This is shown below:

    start line 1---------------------end line 1 
    start line 2---------------------end line 2 
            start line 3---------------------end line 3 
            start line 4---------------------end line 4 
            start line 5---------------------end line 5 
  6. To set the level of line 3 to three levels lower than level 2, but two levels higher than subsequent elements, place the cursor on line 3 and type:
    set format after 2 before 3 

    The before option sets line 3, 4, and 5 to level 3 and the after option sets lines 4 and 5 to two levels lower that the level set for line 3. This is shown in the following:

    start line 1---------------------end line 1 
    start line 2---------------------end line 2 
          start line 3---------------------end line 3 
              start line 4---------------------end line 4 
              start line 5---------------------end line 5 
Note: Indentation spaces will be represented by a fill character. The default fill character is a period, but you can define your own fill character by using the fill parameter. In the examples above, the fill character is defined to be a blank.

API Return Codes

-2 
The current element is a header element in the document and cannot be changed.
-12 
This command requires an open document. First open a document then issue the command.
-2 
The option specified with the parameter was not valid. Check the syntax requirements for the parameter and try the set command again.
-5 
You cannot make changes to the document because the readonly parameter is set to on.

fill Parameter
formwidth Parameter
indent Parameter
level Parameter
spill Parameter
wrap Parameter