1 09/12/85  indent, ind
 2 
 3 Syntax as a command:  ind oldpath {newpath} {-control_args}
 4 
 5 
 6 Function:  improves the readability of a PL/I source segment by
 7 indenting it according to a set of standard conventions described
 8 below.
 9 
10 
11 Arguments:
12 oldpath
13    is the pathname of the input source segment.  Source segments with
14    suffixes for PL/I, create_data_segment, and reductions are
15    recognized.  If the segment does not have a recognized suffix,
16    indent uses a segment of .pl1, name.cds, or name.rd, in that order.
17 newpath
18    is the pathname of the output source segment.  The output segment
19    must have the same suffix as the input segment.  If you omit
20    newpath, the indented copy of the program replaces the original one
21    in oldpath.  However, if errors are detected during indentation and
22    you don't give newpath, the original copy is not replaced; instead,
23    the pathname of the temporary file containing the indented copy is
24    printed in an error message.
25 
26 
27 Control arguments:
28 -brief, -bf
29    suppresses warning comments on invalid or non-PL/I characters found
30    outside of a string or comment; such characters are never removed.
31    When you select -brief, those errors whose warning messages are
32    suppressed do not prevent the original copy from being replaced.
33 -comment STR, -cm STR
34    sets the comment column to STR.  Comments are lined up in this
35    column unless they occur in the beginning of a line or are preceded
36    by a blank line.  If -comment is omitted, the default is 61.
37 
38 
39 -indent STR, -ind STR
40    sets indentation for each level to STR.  Each do, begin, proc, and
41    procedure statement indents additional STR spaces until the matching
42    end statement is encountered.  If omitted, the default is five.
43 -lmargin STR, -lm STR
44    sets the left margin (indentation for normal program statements) to
45    STR.  If omitted, the default is 11.
46 
47 
48 Notes on conventions:  Declaration statements are indented five spaces
49 for dcl declarations and 10 for declare declarations.  Identifiers
50 appearing on different lines of the same declare statement are lined up
51 under the first identifier on the first line of the statement.
52 Structure declarations are indented according to level number; after
53 level two, each additional level is indented two additional spaces.
54 
55 An additional level of indentation is also provided for the then clause
56 of an if statement; else clauses are lined up with the corresponding
57 if.  Statements continuing over more than one line have an additional
58 five spaces of indentation for the second line and all succeeding ones.
59 
60 
61 Multiple spaces are replaced by a single space except within strings or
62 for nonleading spaces and tabs in comments.  Trailing spaces and tabs
63 are removed from all lines.  Spaces are inserted before left
64 parentheses, after commas, and around the constructs =, ->, <=, >=, and
65 ^=.  Spaces are deleted if they are found after a left parenthesis or
66 before a right parenthesis.  Tabs are used wherever possible to
67 conserve storage in the output segment.
68 
69 Parentheses are counted and balanced at every semicolon.  If they do
70 not balance or if the input segment ends in a string or comment, a
71 warning message is printed.  Language keywords (do, begin, end, etc.)
72 are recognized only at parenthesis level zero, and most keywords are
73 recognized only if they appear to begin a statement.
74 
75 
76 The indent command treats comments which begin with /****^ as
77 unindentable comments.  These comments are copied directly into the
78 indented source program without reformatting or indentation.  This
79 follows the format_pl1 convention for identifying comments which are
80 never to be reformatted.
81 
82 
83 Notes on restrictions:  The only case in which indent splits a line is
84 when lines are longer than 350 characters, since they overflow indent's
85 buffer size.
86 
87 Labeled end statements do not close multiple open do statements.
88 
89 This command assumes that the identifiers begin, end, procedure, proc,
90 declare, and dcl are reserved words when they appear at the beginning
91 of a statement.  If the input contains a statement like
92    do = do + 1;
93 indent interprets it to mean that the statement delimits a do group and
94 does not indent correctly.
95 
96 Structure level numbers greater than 99 do not indent correctly.