1 C Cross Referencing & Documenting tool. Version 1.6 - cxref
2 ===========================================================
3
4A program that can automatically generate documentation and cross references for
5a C program.
6
7The input is any C program with appropriate comments and the output is LaTeX,
8HTML, RTF or SGML files.
9
10--------------------------------------------------------------------------------
11------------------------------- Program Options --------------------------------
12--------------------------------------------------------------------------------
13
14The name of the program is cxref.
15
16Usage: cxref filename [ ... filename]
17 [-Odirname] [-Nbasename] [-Rdirname]
18 [-all-comments] [-no-comments]
19 [-verbatim-comments] [-block-comments]
20 [-xref[-all][-file][-func][-var][-type]]
21 [-warn[-all][-comment][-xref]]
22 [-index[-all][-file][-func][-var][-type]]
23 [-raw]
24 [-latex]
25 [-html[-src]]
26 [-rtf]
27 [-sgml]
28 [-Idirname] [-Ddefine] [-Udefine]
29 [-CPP cpp_program] [-- cpp_arg [ ... cpp_arg]]
30
31Usage: cxref filename [ ... filename] -delete
32 [-Odirname] [-Nbasename] [-Rdirname]
33
34filename The name of the file to document, any number of files may be
35 documented at a time.
36
37-delete The files named are to be deleted from the output directory and
38 their entries in the cross reference database and main output
39 files are to be removed.
40
41-Odirname The name of a directory to use for the output latex files and
42 the location of the cross reference files that are created.
43
44-Nbasename The name to use for the first part of the output and cross
45 reference files instead of cxref, the file extensions remain
46 the same.
47
48-Rdirname When the source files are in more than one directory, set
49 dirname to the name of the root directory of the source tree
50 (use relative path if easier e.g. `-R../..'). This will then
51 run cxref from that root directory and the `-Odirname' must be
52 relative to that directory.
53
54-all-comments In case you think that the existing comments might work,
55 (see below for description of special comments).
56 [Danger! This option can produce weird results.]
57
58-no-comments Ignores all comments, useful if you just want the cross
59 references and not the documentation.
60
61-verbatim-comments When the comments that you have in the code are formatted
62 in a predetermined style that you want to preserve on the
63 output, this option will force them not to be reformatted.
64 [Note, this is for file and function comments only.]
65
66-block-comments When the comments in the program are formatted in the `block'
67 style (with a leading `*' character on every line), this option
68 will remove that character from the output.
69 [Works for a single `*', `+', `|' or `:' on each line.]
70
71-xref Produce cross referencing information (see below).
72 -all All cross references.
73 -file Cross references for files.
74 -func Cross references for functions.
75 -var Cross references for variables.
76 -type Cross references for types.
77
78-warn Produce warnings, the options must be concatenated together:
79 -all All warnings.
80 -comment Warn of missing comments.
81 -xref Warn of missing cross references.
82
83-index Produce a cross reference index, the options must be
84 concatenated together:
85 -all All indexes.
86 -file Index of files.
87 -func Index of functions.
88 -var Index of variables.
89 -type Index of types.
90
91-raw Produce a raw form of output, not really of much use except
92 with -warn.
93
94-latex Produce a LaTeX file to document each of the source files and
95 also an extra file that includes each of these files.
96
97-html Produce an HTML 4.01 file to document each of the source files
98 and a main file to reference each of these files.
99-html-src Produce the HTML output and an HTML version of the source file
100 with links into it.
101
102-rtf Produce a Rich Text Format (RTF) file to document the source
103 file.
104
105-sgml Produce an SGML file to document the source file. (Using the
106 LinuxDoc DTD).
107
108-Idirname GCC option to specify the path for include files.
109-Ddefine GCC option to define a pre-processor symbol.
110-Udefine GCC option to undefine a pre-processor symbol.
111
112-CPP program The name of the program to use instead of the compile time
113 default. The program must be able to perform all of the actions
114 that `gcc -E -C -dD' does to work. If the program takes
115 arguments then the whole thing needs to be in quotes so that it
116 is interpreted as a single argument to cxref.
117
118-- arg ... arg Extra arguments to be passed to the pre-processor can be placed
119 after the `--' separator.
120
121--------------------------------------------------------------------------------
122----------------------- C Compiler Replacement cxref-cc ------------------------
123--------------------------------------------------------------------------------
124
125To simplify using cxref on existing source code, there is now a shell script
126that will call the C compiler and then call cxref to process the source file.
127This means that it can be used as a drop in replacement for CC in Makefiles and
128the like.
129
130Usage: cxref-cc [usual cc options]
131
132The name of the source file is extracted from the list of options as well as the
133`-D*', `-I*', `-U*' flags and when the C compiler exits succesfully cxref will
134be called. The name of the C compiler to use is controlled by the CXREFCC
135environment variable, or if this is not set then the CC environment variable, or
136failing this just gcc.
137
138Using this script requires the use of a `.cxref' configuration file to contain
139the options since there is nowhere to put the options on the command line for
140the C compiler.
141
142This will only cross-reference and document the C source files since they are
143the only ones that are compiled, but it will make sure that they are
144cross-referenced with the correct options etc.
145
146--------------------------------------------------------------------------------
147----------------------- Cxref configuration File .cxref ------------------------
148--------------------------------------------------------------------------------
149
150These command line arguments can also be put into a file named `.cxref' instead
151of on the command line. When cxref is run the arguments to the program are
152interpreted in the following order.
153
1541) Those on the command line.
1552) Those in the `.cxref' file in the current directory.
1563) Those in the `.cxref' file in the source tree root specified by `-R'.
157
158This means that in a multi-directory source tree, each sub-directory can have a
159`.cxref' file containing just the line `-R..' or appropriate. The main
160directory can have a `.cxref' file containing the remainder of the options.
161This removes completely the need to have any options on the command line apart
162from the source file names.
163
164The format of the `.cxref' file is any number of lines, each one containing a
165single command line argument (equivalent to one of the argv). The only options
166that cannot be used are the names of source files themselves and the `-delete'
167option. Blank lines are ignored and lines starting with a '#' are comments.
168
169--------------------------------------------------------------------------------
170------------------------ Program Documentation Comments ------------------------
171--------------------------------------------------------------------------------
172
173The documentation for the program is produced from comments in the code that are
174appropriately formatted. The cross referencing comes from the code itself and
175requires no extra work.
176
177The special comments are `/**** ****/' (for a file) and `/*++++ ++++*/' (for a
178data object) any number of `*' or `+' can be used inside of the standard `/*'
179and `*/' comment delimiters in the comments, they are ignored.
180
181If a comment line starts with whitespace and is followed by `+html+' then the
182rest of the line is included only in the HTML output, and is not processed so it
183can include HTML markup, `-html-' means that the rest of the line is included in
184all except the HTML output. The same also applies to the other output formats,
185`+none+' can be used for lines not to appear in any output. The exception to
186this is that the raw output does not do any checking and will output all lines.
187
188In any situation where a comment follows a `,', `;' or `)' separated only by
189spaces and tabs, the comment is pushed to before the punctuation to apply to
190object there.
191
192The program is implemented using a full ANSI C grammar parser with some GCC
193extensions, this means that the style of the code is unimportant, only the
194content and comments.
195
196--------------------------------------------------------------------------------
197------------------------- Automated Comment Insertion --------------------------
198--------------------------------------------------------------------------------
199
200To simplify the insertion of comments that will be parsed by cxref, the file
201cxref.el provides a number of Emacs lisp functions. To use them add the line
202`(load "cxref")' to your `.emacs' file or type `M-x load-file cxref.el' from
203within Emacs.
204
205The functions and key bindings are:
206
207Control-C Control-F - Adds file comments, a /** **/ header at the top of the
208 file and if it is a .h file then it also adds a #ifndef,
209 #define at the beginning and #endif at the end to stop
210 multiple inclusions.
211
212Control-C f - Adds comments to a function, the cursor must be on the
213 line containing the start of the function definition when
214 this function is called. The /*+ ... +*/ comment that is
215 added is of the header type (see the examples) not inline.
216
217Control-C v - Adds a leading comment to the variable or other definition
218 on the current line.
219
220Control-C e - Adds a trailing comment at the end of the line.
221
222Control-C i - Adds an inline comment that is ignored by cxref.
223
224--------------------------------------------------------------------------------
225-------------------------------- C Preprocessor --------------------------------
226--------------------------------------------------------------------------------
227
228To improve the output that is available a modified version of the GNU CPP V2.7.2
229is supplied (named cxref-cpp).
230
231This modified C preprocessor allows for a finer control over some features of
232the preprocessing that are not important for a compiler. In a standard
233preprocessor, the preprocessor directives are intended for use only by the
234preprocessor, so passing the information through is not important.
235
236With cxref-cpp, there are two features that are different to the standard GNU
237CPP:
238
2391) The #include directives from the file are output in the same way as the
240 #defines are output. An extra flag has been added to cpp to do this, '-dI',
241 it works in the same way as the existing '-dD' flag for #defines.
242
2432) Comments trailing a #include or a #define are dropped with GNU CPP even if -C
244 is used. This is not important while compiling but is useful for documenting.
245
246--------------------------------------------------------------------------------
247------------------------------ Cross Referencing -------------------------------
248--------------------------------------------------------------------------------
249
250The cross referencing is performed for the following items
251
252Files - The files that the current file is included in
253 (even when included via other files).
254
255#includes - Files included in the current file.
256 - Files included by these files etc.
257
258Variables - The location of the definition of external variables.
259 - The files that have visibility of global variables.
260 - The files / functions that use the variable.
261
262Functions - The file that the function is prototyped in.
263 - The functions that the function calls.
264 - The functions that call the function.
265 - The files and functions that reference the function.
266 - The variables that are used in the function.
267
268Each of these items is cross referenced in the output.
269
270The cross referencing uses files `cxref.variable', `cxref.function',
271`cxref.include' and `cxref.typedef' in the output directory.
272These are a complete list of the function and variable usage in the program and
273could be used to generate a function call hierarchy or variable usage diagram
274for example.
275Two cxref passes of each file is needed, the first to build up the cross
276referencing files and the second to use them.
277
278(The file names are different if the `-N' option is used.)
279
280--------------------------------------------------------------------------------
281--------------------------------- LaTeX Output ---------------------------------
282--------------------------------------------------------------------------------
283
284The default LaTeX output is a file for each of the source files with one extra
285file `cxref.tex' that includes each of the other files. This is to allow a
286makefile to only update the changed files (although the references may require
287all of the files to be checked again). When the cxref.tex file has been written
288it can be modified by the user, any new files that are added are added at the
289end of the source code section, the rest of the file being unchanged.
290
291The index is written to a file called `cxref.apdx.tex' and cxref.tex is updated
292to refer to it.
293
294Also written out are three LaTeX style files `page.sty', `fonts.sty' and
295`cxref.sty'. These set up the page to use a smaller margin and smaller fonts to
296allow more to appear on a page and also define the new commands for typesetting
297the cxref output.
298
299(The file names `cxref.tex' and `cxref.apdx.tex' are different if the `-N'
300option is used.)
301
302--------------------------------------------------------------------------------
303--------------------------------- HTML Output ----------------------------------
304--------------------------------------------------------------------------------
305
306The default HTML output is a file for each of the source files with one extra
307file `cxref.html' that includes each of the other files. This is to allow a
308makefile to only update the changed files (although the references may require
309all of the files to be checked again). When the cxref.html file has been
310written it can be modified by the user, any new files that are added are added
311at the end before the table of contents, the rest of the file being unchanged.
312
313The index is written to a file called `cxref.apdx.html' and cxref.html is
314updated to refer to it.
315
316(The file names `cxref.html' and `cxref.apdx.html' are different if the `-N'
317option is used.)
318
319The HTML output uses the HTML 4.01 standard and all pages validate correctly.
320
321--------------------------------------------------------------------------------
322--------------------------------- RTF Output -----------------------------------
323--------------------------------------------------------------------------------
324
325Rich Text Format is a fairly low level page description format devised by
326Microsoft. It is not a well defined and easy to understand standard as are the
327other formats, but it is popular for document exchange.
328
329There is a single output file for each of the source files and an index file.
330
331--------------------------------------------------------------------------------
332--------------------------------- SGML Output ----------------------------------
333--------------------------------------------------------------------------------
334
335Since SGML is a meta-language it is necessary to define the layout elements as
336well as provide the information. The cxref output uses the LinuxDoc document
337format and is designed for use with the SGMLtools programs
338(http://www.sgmltools.org/).
339
340There is a single output file for each of the source files and an index file.
341
342--------------------------------------------------------------------------------
343--------------------------- Example Special Comments ---------------------------
344--------------------------------------------------------------------------------
345
346See the `README.c' file, to see that the comments are indeed seen in the code,
347run `cxref README.c -raw', the comments are indicated in chevrons `<<< >>>'.
348
349--------------------------------------------------------------------------------
350----------------------------- Further Information ------------------------------
351--------------------------------------------------------------------------------
352
353There is a list of frequently asked questions and their answers for the cxref
354program in the FAQ file. A list of improvements planned for future versions of
355the program are listed in the file TODO.
356
357More up-to-date information can be found on the cxref homepage
358http://www.gedanken.org.uk/software/cxref/.
359
360--------------------------------------------------------------------------------
361----------------------------- Author and Copyright -----------------------------
362--------------------------------------------------------------------------------
363
364The cxref program was written by Andrew M. Bishop in 1995-2011.
365
366The cxref program is copyright Andrew M. Bishop 1995-2011.
367
368The cxref-cpp program is copyright Free Software Foundation, Inc.
369
370The cxref and cxref-cpp programs can be freely distributed according to the
371terms of the GNU General Public License (see the file `COPYING').
372