source: buchla-68k/orig/doc/Utilities/CPG.TXT@ 0170798

Last change on this file since 0170798 was 3ae31e9, checked in by Thomas Lopatic <thomas@…>, 7 years ago

Imported original source code.
  • Property mode set to 100755
File size: 5.2 KB
Line 
1NAME cpg - C source listing formatter
2
3SYNOPSIS
4
5 cpg [ -b<asename> ] [ -t tabstop ] [ file... ]
6
7DESCRIPTION
8
9cpg is a C language source listing formatter. It employs certain
10triggers to perform its formatting. Those same triggers may be used to
11extract in-line documentation to create documentation. At the end of
12the listing produced by cpg is a table of contents of all files and
13functions contained in the current listing. The table of contents is
14sorted alphabetically by function and file.
15
16
17The listing produced by cpg includes on each line a line number. On each
18line containing any braces ({}), there will also be a
19nesting level indicator. The nesting level indicator includes a number
20(the current nesting level) and a directional character. The
21directional characters are:
22
23 > 6 The nesting level increased on this line
24 < 6 The nesting level decreased on this line
25 * 6 The nesting level changed both ways, with a net change of zero
26
27The triggers that cpg recognizes are itemized below. Each must appear
28in column 1.
29
30<formfeed>
31
32 A formfeed will cause a new page to be started with a full header.
33
34/*F filename *<anything>
35
36 The file name may be specified in a comment preceding a descriptive
37 header block. The filename argument must be delimited by asterisks in
38 the trigger. The filename will appear in all page headings up to the
39 next filename trigger or the next file. A filename comment block
40 MUST be terminated by the endofblock trigger (see below).
41
42 This trigger will print as a line in the listing. This trigger causes
43 the start of a new page (form feed) in the listing, with printing of the
44 page header including the current file name.
45
46
47/*H funcname *<anything>
48
49 The function name may be specified in a comment preceding a descriptive
50 header block. The funcname argument must be delimited by asterisks in
51 the trigger. The funcname will appear in all page headings up to the
52 next funcname trigger or the next file. A funcname comment block
53 MUST be terminated by the endofblock trigger (see below).
54
55 This trigger will print as a line in the listing. This trigger causes
56 the start of a new page (form feed) in the listing, with printing of the
57 page header including the current function name.
58
59/*E*/
60
61 This is the endofblock trigger. Everything between the last filename or
62 funcname trigger and the endofblock trigger will be passed straight
63 through by cpg without evaluation of nesting levels, comments, or quoted
64 strings. Thus, a header block is treated as one long comment by cpg.
65
66 This trigger will print as a line in the listing.
67
68/*P*/
69
70 This is a page eject trigger. It will not print in the listing, but
71 will be counted for line numbering purposes. This trigger causes the
72 page heading, title, and subtitle to be reprinted based on their current
73 values (see title and subtitle below).
74
75/*S <text> */
76
77 This is the subtitle trigger. It determines the contents of the second
78 title line on the page header. All characters after the initial space
79 and up to but not including the following asterisk (required) are
80 included as part of the subtitle. This trigger will not print in the
81 listing but will be counted for line numbering purposes.
82
83/*T <text> */
84
85 This is the title trigger. It determines the contents of the first
86 title line on the page header. All characters after the initial space
87 and up to but not including the following asterisk (required) are
88 included as part of the title. This trigger will not print in the
89 listing but will be counted for line numbering purposes.
90
91
92OPTIONS
93
94-b
95
96 The basename option causes cpg to use only the basename portion of
97 the filename (whether obtained from the fileheader trigger or the
98 current filename) in page headers as well as the table of contents.
99 Thus, if a file is printed using "cpg -bt4 `pwd`/xyz.c", only "xyz.c"
100 will show up in the page header.
101
102-t tabstop
103
104 The tabstop argument to the -t option specifies how to expand tabs. The
105 expansion is performed automatically with a tabstop of 8 if none is
106 specified.
107
108ARGUMENTS
109
110file
111
112 Any number of file names may be specified on the command line (within
113 limits set by whichever shell is used). Each file will be formatted and
114 its name added to the table of contents. If no file names are
115 specified, cpg will read the standard input.
116
117FILES
118
119/tmp/toc_XXXXXX
120
121 temporary file for building the table of contents.
122
123
124SEE ALSO
125
126 dtab(1), nl(1), pr(1), sort(1)
127
128NOTES
129
130 This tool was developed at Benetics Corporation.
131
132 A side note: cpg also properly processes comments in shell scripts and
133 makefiles. These comments are correctly handled when the comment
134 character (# or :) is the first nonblank character on a line. In order
135 to facilitate documentation of shell scripts, cpg recognizes the
136 sequences #{ and #} as the beginning and ending of nesting, and treats
137 them as it does in C program sources. Thus lengthy for, if, while, and
138 case statements may be more clearly documented as to nesting levels,
139 particulary in shell scripts.
140
141AUTHOR
142
143 Steven M. List
144 Benetics Corporation
145 Mountain View, CA.
146 {cdp,idi,greipa,oliveb,sun,tolerant}!bene!luke!steven
147
148 Modified to run under GEMDOS by: D.N. Lynx Crowe
Note: See TracBrowser for help on using the repository browser.