summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org.ua>2011-10-11 08:13:02 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2011-10-11 08:13:02 (GMT)
commitb5cbb05d00e242aa653460a100715f7948396a64 (patch) (side-by-side diff)
tree1d8ca8cd9b85257609a43ef719f7d16ba1018354
parentb6e09eeabb9ffa99d4d7017ebe36533b4a729da2 (diff)
downloadcflow-b5cbb05d00e242aa653460a100715f7948396a64.tar.gz
cflow-b5cbb05d00e242aa653460a100715f7948396a64.tar.bz2
Change to double-space sentence spacing in cflow.texi.
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--doc/cflow.texi367
1 files changed, 188 insertions, 179 deletions
diff --git a/doc/cflow.texi b/doc/cflow.texi
index 99e7bb4..82bd028 100644
--- a/doc/cflow.texi
+++ b/doc/cflow.texi
@@ -22,7 +22,7 @@
@end direntry
@dircategory Emacs
@direntry
-* cflow mode: (cflow)cflow mode. Major mode for visiting cflow charts.
+* cflow mode: (cflow)cflow mode. Major mode for visiting cflow charts.
@end direntry
@end ifinfo
@@ -90,7 +90,16 @@ Appendices
* Copying This Manual:: The GNU Free Documentation License.
* Concept Index:: Index of Concepts.
+@detailmenu
+ --- The Detailed Node Listing ---
+Controlling Symbol Types
+
+* Syntactic classes::
+* Symbol aliases::
+* GCC Initialization::
+
+@end detailmenu
@end menu
@node Intro
@@ -106,10 +115,10 @@ dependencies between various functions.
@cindex reverse graph defined
@cindex reverse tree defined
The program is able to produce two kind of graphs: direct
-and reverse. @dfn{Direct graph} begins with the main function
+and reverse. @dfn{Direct graph} begins with the main function
(@code{main}), and displays recursively all functions called by it.
In contrast, @dfn{reverse graph} is a set of subgraphs, charting for
-each function its callers, in the reverse order. Due to their
+each function its callers, in the reverse order. Due to their
tree-like appearance, graphs can also be called @dfn{trees}.
In addition to these two output modes, @command{cflow} is able to
@@ -118,7 +127,7 @@ in the input files.
The utility also provides a detailed control over symbols that will
appear in its output, allowing to omit those that are of no interest
-to the user. The exact appearance of the output graphs is also
+to the user. The exact appearance of the output graphs is also
configurable.
@FIXME{Some notes about when the user might need the utility? For
@@ -126,14 +135,14 @@ example, to get a quick acquaintance with the program, etc.}
@FIXME{The utility should also be able to process following input file
formats: @command{yacc} and @command{lex} sources, and object
-files. It is a good idea to add a node @samp{POSIX} discussing this.}
+files. It is a good idea to add a node @samp{POSIX} discussing this.}
@node Quick Start
@chapter Simple Ways to Analyze Programs with @command{cflow}.
Let's begin our acquaintance with the GNU @command{cflow} utility
-with an example. Suppose you have a simple implementation of
+with an example. Suppose you have a simple implementation of
@command{whoami} command and you wish to obtain a graph of function
-dependencies. Here is the program:
+dependencies. Here is the program:
@smallexample
@verbatiminclude whoami.c
@@ -159,12 +168,12 @@ main() <int main (int argc,char **argv) at whoami.c:26>:
@cindex GNU Output Format described
@anchor{GNU Output Format}
This is a direct call graph showing @dfn{caller---callee} dependencies
-in the input file. Each line starts with a function name, followed by
-a pair of parentheses to indicate that it is a function. If this
+in the input file. Each line starts with a function name, followed by
+a pair of parentheses to indicate that it is a function. If this
function is defined in one of the input files, the line continues by
displaying, within a pair of angle brackets, a function
-@dfn{signature} and the location of its definition. If the function
-calls another functions, the line ends with a colon. For example, the
+@dfn{signature} and the location of its definition. If the function
+calls another functions, the line ends with a colon. For example, the
line
@smallexample
@@ -173,23 +182,23 @@ main() <int main (int argc,char **argv) at whoami.c:25>:
@noindent
shows that function @code{main} is defined in file @file{whoami.c}
-at line 25, as @code{int main (int argc, char **argv)}. Terminating
+at line 25, as @code{int main (int argc, char **argv)}. Terminating
colon indicates that @code{main} invokes other functions.
The lines following this one show which functions are called by
-@code{main}. Each such line is indented by fixed amount of white space
+@code{main}. Each such line is indented by fixed amount of white space
(by default four spaces) for each nesting level.
@cindex @option{--omit-symbol-names} option introduced
@cindex @option{--omit-arguments} option introduced
@anchor{omit signature parts}
- Usually @command{cflow} prints a full function signature. However,
-sometimes you may wish to omit some part of it. Several options are
-provided for this purpose. To print signatures without function names,
-use @option{--omit-symbol-names} option. To omit argument list, use
-@option{--omit-arguments}. These options can be needed for a variety
+ Usually @command{cflow} prints a full function signature. However,
+sometimes you may wish to omit some part of it. Several options are
+provided for this purpose. To print signatures without function names,
+use @option{--omit-symbol-names} option. To omit argument list, use
+@option{--omit-arguments}. These options can be needed for a variety
of reasons, one of them being to make the resulting graph more
-compact. To illustrate their effect, here is how would the first line of the
+compact. To illustrate their effect, here is how would the first line of the
above graph look if you had used both @option{--omit-} options:
@smallexample
@@ -201,12 +210,12 @@ main() <int () at whoami.c:25>:
@cindex @option{-m} command line option introduced
@anchor{start symbol}
By default, @command{cflow} starts outputting direct graph from
-the function called @code{main}. It is convenient when analyzing a set
-of input files comprising an entire @code{C} program. However, there
+the function called @code{main}. It is convenient when analyzing a set
+of input files comprising an entire @code{C} program. However, there
are circumstances where a user would want to see only a part of
-the graph starting on particular function. @command{Cflow}
+the graph starting on particular function. @command{Cflow}
allows to select such function using @option{--main} (@option{-m})
-command line option. Thus, running
+command line option. Thus, running
@smallexample
cflow --main who_am_i whoami.c
@@ -231,11 +240,11 @@ who_am_i() <int who_am_i (void) at whoami.c:8>:
@cindex @option{--reverse}
@cindex @option{-r}
In the previous chapter we have discussed @dfn{direct graphs},
-displaying @i{caller---callee} dependencies. Another type of
+displaying @i{caller---callee} dependencies. Another type of
@command{cflow} output, called @dfn{reverse graph}, charts
-@dfn{callee---caller} dependencies. To produce a reverse graph, run
+@dfn{callee---caller} dependencies. To produce a reverse graph, run
@command{cflow} with @option{--reverse} (@option{-r}) command line
-option. For example, using a sample @file{whoami.c}:
+option. For example, using a sample @file{whoami.c}:
@cindex reverse graph, example
@cindex reverse tree, example
@@ -265,9 +274,9 @@ who_am_i() <int who_am_i (void) at whoami.c:8>:
@end smallexample
This output consists of several subgraphs, each describing callers
-for a particular function. Thus, the first subgraph tells that the
+for a particular function. Thus, the first subgraph tells that the
function @code{fprintf} is called from two functions: @code{who_am_i}
-and @code{main}. First of them is, in turn, also called directly by
+and @code{main}. First of them is, in turn, also called directly by
@code{main}.
@cindex @option{--brief} command line option introduced
@@ -275,8 +284,8 @@ and @code{main}. First of them is, in turn, also called directly by
@anchor{--brief}
The first thing that draws attention in the above output is that
the subgraph starting with @code{who_am_i} function is repeated several
-times. This is @dfn{verbose} output. To make it brief, use
-@option{--brief} (@option{-b}) command line option. For example:
+times. This is @dfn{verbose} output. To make it brief, use
+@option{--brief} (@option{-b}) command line option. For example:
@cindex brief output, an example of
@smallexample
@@ -310,10 +319,10 @@ expanded subgraph can be found.
@anchor{--number}
If the output graph is large it can be tedious to find out the
required line number (unless you use @dfn{Emacs cflow-mode},
-@pxref{Emacs}). For such cases a special option
+@pxref{Emacs}). For such cases a special option
@option{--number} (@option{-n}) is provided, which makes
@command{cflow} begin each line of the output with a @dfn{reference
-number}, that is the ordinal number of this line in the output. With
+number}, that is the ordinal number of this line in the output. With
this option, the above output will look like:
@smallexample
@@ -344,18 +353,18 @@ take effect for both direct and reverse flow graphs.
@cindex POSIX Output described
@anchor{POSIX Output Format}
The output format described in previous chapters is called
-@dfn{GNU Output}. Beside this, @command{cflow} is also
+@dfn{GNU Output}. Beside this, @command{cflow} is also
able to produce output format defined in POSIX standard
(@url{http://www.opengroup.org/onlinepubs/009695399/utilities/cflow.html,The
Open Group Base Specifications Issue 6: cflow utility}).
In this format, each line of output
begins with a @dfn{reference number}, i.e. the ordinal number of this
line in the output, followed by indentation of fixed amount of columns
-per level (@pxref{setting indentation}). Following this are the
+per level (@pxref{setting indentation}). Following this are the
name of the function, a colon and the function definition, if
-available. The function definition is followed by the location of the
-definition (file name and line number). Both definition and location
-are enclosed in angle brackets. If the function definition is not
+available. The function definition is followed by the location of the
+definition (file name and line number). Both definition and location
+are enclosed in angle brackets. If the function definition is not
found, the line ends with an empty pair of angle brackets.
@cindex @option{--format=posix}
@@ -383,23 +392,23 @@ $ @kbd{cflow --format=posix whoami.c}
It is not clear from the @acronym{POSIX} specification whether
the output should contain argument lists in function declarations, or
-not. By default @command{cflow} will print them. However, some programs,
-analyzing @command{cflow} output expect them to be absent. If you use
+not. By default @command{cflow} will print them. However, some programs,
+analyzing @command{cflow} output expect them to be absent. If you use
such a program, add @option{--omit-arguments} option to
@command{cflow} command line (@pxref{omit signature parts}).
@FIXME{Discuss the differences and the reason
-for existence of each output format. Explain that more formats
+for existence of each output format. Explain that more formats
will appear in the future.}
Future versions of @command{cflow} will offer more output
formats, including @acronym{XML} and @acronym{HTML}
-outputs. Currently, you can use @command{VCG} tool
+outputs. Currently, you can use @command{VCG} tool
(@url{http://rw4.cs.uni-sb.de/@/users/@/sander/@/html/gsvcg1.html})
-to create graphical representation of the produced graphs. To
+to create graphical representation of the produced graphs. To
transform @command{cflow} output to @command{xvcg} input syntax, use
@command{cflow2vcg} program
-(@url{http://cflow2vcg.sourceforge.net/}). Both programs are available
+(@url{http://cflow2vcg.sourceforge.net/}). Both programs are available
under GPL.
@cindex @command{cflow2vcg}, using with @command{cflow}
@@ -407,7 +416,7 @@ under GPL.
@command{Cflow2vcg} expects @acronym{POSIX} call graphs, indented
with exactly one horizontal tabulation character per nesting level,
with an additional tab character for zeroth level and without argument
-lists in function declaration. So, to produce an output suitable for
+lists in function declaration. So, to produce an output suitable for
@command{cflow2vcg}, invoke @command{cflow} as
follows@footnote{(@xref{ASCII Tree, level-indent}, for the detailed
description of @option{--level-indent} option}:
@@ -438,11 +447,11 @@ cflow --format=posix --omit-arguments \
@chapter Handling Recursive Calls.
@cindex Recursive functions
Sometimes programs contain functions that recursively call
-themselves. GNU output format provides a special indication for such
-functions. The definition of the recursive function is marked with an
-@samp{(R)} at the end of line (before terminating colon). Subsequent
+themselves. GNU output format provides a special indication for such
+functions. The definition of the recursive function is marked with an
+@samp{(R)} at the end of line (before terminating colon). Subsequent
recursive calls to this function are marked with a @samp{(recursive: see
-@var{refline})} at the end of line. Here, @var{refline} stands for the
+@var{refline})} at the end of line. Here, @var{refline} stands for the
reference line number where the @dfn{recursion root} definition was
displayed.
@@ -483,16 +492,16 @@ $ @kbd{cflow --number d.c}
@end smallexample
The @code{printdir} description in line 4 shows that the function
-is recursive. The recursion call is shown in line 18.
+is recursive. The recursion call is shown in line 18.
@node Symbols
@chapter Controlling Symbol Types
An alert reader has already noticed something strange in the
above output: the function @code{_exit} is missing, although according
-to the source file it is called twice by @code{printdir}. It is
+to the source file it is called twice by @code{printdir}. It is
because by default @command{cflow} omits from its output all symbols
-beginning with underscore character. To include these symbols as well,
+beginning with underscore character. To include these symbols as well,
specify @option{-i _} (or @option{--include _}) command line option.
Continuing our example:
@@ -527,22 +536,22 @@ $ @kbd{cflow --number -i _ d.c}
@cindex Symbol classes defined
@anchor{--include}
In general, @option{--include} takes an argument specifying a
-list of @dfn{symbol classes}. Default option behavior is to include
-the requested classes to the output. If the argument begins with a
+list of @dfn{symbol classes}. Default option behavior is to include
+the requested classes to the output. If the argument begins with a
minus or caret sign, this behavior is reversed and the requested
symbol classes are excluded from the output.
@cindex Including symbols that begin with an underscore
@cindex Excluding symbol classes
The symbol class @samp{_} includes symbols whose names begin with an
-underscore. Another useful symbol class is @samp{s}, representing
-@dfn{static functions or data}. By default, static functions are
-always included in the output. To omit them, one can give
+underscore. Another useful symbol class is @samp{s}, representing
+@dfn{static functions or data}. By default, static functions are
+always included in the output. To omit them, one can give
@option{-i ^s} (or @option{-i -s}@footnote{Notice that @option{-i -s}
is a single option, in spite of @code{-s} beginning with a minus sign.
Since this might be confusing, we prefer using @samp{^} instead of
@samp{-} to denote symbol exclusion.})
-command line option. Our sample program @file{d.c} defines static
+command line option. Our sample program @file{d.c} defines static
function @code{isdir}, running @command{cflow -i ^s}, completely omits
this function and its callees from the resulting graph:
@@ -568,17 +577,17 @@ $ @kbd{cflow --number -i ^s d.c}
@end smallexample
Actually, the exclusion sign (@samp{^} or @samp{-}) can be used
-any place in @option{-i} argument, not only at the beginning. Thus,
+any place in @option{-i} argument, not only at the beginning. Thus,
option @option{-i _^s} means ``@i{include symbols, beginning with
-underscore and exclude static functions}''. Several @option{-i} options
+underscore and exclude static functions}''. Several @option{-i} options
accumulate, so the previous example can also be written as
@option{-i _ -i ^s}.
It is important to notice that by default @command{cflow} graphs
-contain only functions. You can, however, request displaying variables
-as well, by using symbol class @samp{x}. This class contains all @dfn{data
+contain only functions. You can, however, request displaying variables
+as well, by using symbol class @samp{x}. This class contains all @dfn{data
symbols}, both global and static, so to include these in the output,
-use option @option{-i x}. For example:
+use option @option{-i x}. For example:
@anchor{x flowchart}
@smallexample
@@ -614,20 +623,20 @@ $ @kbd{cflow --number -i x d.c}
@end smallexample
Now, lines 3, 4, 16 and 23 show data symbols, with their
-definitions when available. Notice, however, lines 7 and 8. Why both
+definitions when available. Notice, however, lines 7 and 8. Why both
type name @code{DIR} and automatic variable @code{dir} are listed as
data?
To answer this question, let's first describe the @command{cflow}
-notion of symbols. The program keeps its @dfn{symbol tables}, which
-are initially filled with @code{C} predefined keywords. When parsing
-input files, @command{cflow} updates these tables. In particular, upon
+notion of symbols. The program keeps its @dfn{symbol tables}, which
+are initially filled with @code{C} predefined keywords. When parsing
+input files, @command{cflow} updates these tables. In particular, upon
encountering a @code{typedef}, it registers the defined symbol as a
@dfn{type}.
Now, @code{DIR} is not declared in @file{d.c}, so @command{cflow}
-has no way of knowing it is a data type. So, it supposes it is a
-variable. But then the input:
+has no way of knowing it is a data type. So, it supposes it is a
+variable. But then the input:
@smallexample
DIR *dir;
@@ -637,19 +646,19 @@ variable. But then the input:
is parsed as an @emph{expression}, meaning ``multiply @code{DIR} by
@code{dir}''.
- Of course, it is wrong. There are two ways to help
-@command{cflow} out of this confusion. You can either explicitly
+ Of course, it is wrong. There are two ways to help
+@command{cflow} out of this confusion. You can either explicitly
declare @code{DIR} as data type, or let @command{cflow} run
preprocessor, so it sees the contents of the include files and
-determines it by itself. Running preprocessor is covered by the next
-chapter (@pxref{Preprocessing}). In the present chapter we will
+determines it by itself. Running preprocessor is covered by the next
+chapter (@pxref{Preprocessing}). In the present chapter we will
concentrate on the first method.
@cindex @option{-s} introduced
@cindex @option{--symbol} introduced
@anchor{--symbol}
The command line option @option{--symbol} (@option{-s}) declares a
-@dfn{syntactic class} of the symbol. Its argument consists of two
+@dfn{syntactic class} of the symbol. Its argument consists of two
strings separated by a colon:
@smallexample
@@ -658,10 +667,10 @@ strings separated by a colon:
@noindent
The first string, @var{sym} is a @code{C} identifier to be recorded in
-the symbol table. The second string, @var{class}, specifies a class to
-be associated with this symbol. In particular, if @var{class} is
+the symbol table. The second string, @var{class}, specifies a class to
+be associated with this symbol. In particular, if @var{class} is
@samp{type}, the symbol @var{sym} will be recorded as a @code{C} type
-definition. Thus, to fix the above output, run:
+definition. Thus, to fix the above output, run:
@smallexample
$ @kbd{cflow --number -i x --symbol DIR:type d.c}
@@ -669,10 +678,10 @@ $ @kbd{cflow --number -i x --symbol DIR:type d.c}
@cindex Parameter wrapper defined
@cindex @code{__P}, special handling using @option{--symbol}
- Another important symbol type is a @dfn{parameter wrapper}. It is
+ Another important symbol type is a @dfn{parameter wrapper}. It is
a kind of a macro, often used in sources that are meant to be
compatible with pre-@acronym{ANSI} compilers to protect parameter
-declarations in function prototypes. For example, in the declaration
+declarations in function prototypes. For example, in the declaration
below, taken from @file{/usr/include/resolv.h}, @code{__P} is a
parameter wrapper:
@@ -799,12 +808,12 @@ options for use with @command{gcc}. We suggest you to put them in your
@cindex @option{--cpp} option introduced
@cindex @option{--preprocess} option introduced
@command{Cflow} can preprocess input files before analyzing them,
-the same way @command{cc} does before compiling. Doing so allows
+the same way @command{cc} does before compiling. Doing so allows
@command{cflow} to correctly process all symbol declarations, thus
avoiding the necessity to define special symbols using
-@option{--symbol} option, described in the previous chapter. To enable
+@option{--symbol} option, described in the previous chapter. To enable
preprocessing, run the utility with @option{--cpp}
-(@option{--preprocess}) command line option. For our sample file
+(@option{--preprocess}) command line option. For our sample file
@file{d.c}, this mode gives:
@cindex @option{--cpp} option, an example
@@ -834,20 +843,20 @@ $ @kbd{cflow --cpp -n d.c}
@end smallexample
Compare this graph with the one obtained without @option{--cpp}
-option (@pxref{sample flowchart}). As you see, the reference to
-@code{S_ISDIR} is gone: the macro has been expanded. Now, try
+option (@pxref{sample flowchart}). As you see, the reference to
+@code{S_ISDIR} is gone: the macro has been expanded. Now, try
running @code{cflow --cpp --number -i x d.c} and compare the result
with the graph obtained without preprocessing (@pxref{x
-flowchart}). You will see that it produces correct results without
+flowchart}). You will see that it produces correct results without
using @option{--symbol} option.
@FIXME{To preprocess or not to preprocess?}
@cindex Default preprocessor command
@cindex Preprocessor command, overriding the default
- By default @option{--cpp} runs @file{/usr/bin/cpp}. If you wish
+ By default @option{--cpp} runs @file{/usr/bin/cpp}. If you wish
to run another preprocessor command, specify it as an argument to the
-option, after an equal sign. For example, @command{cflow --cpp='cc
+option, after an equal sign. For example, @command{cflow --cpp='cc
-E'} will run the @code{C} compiler as a preprocessor.
@node ASCII Tree
@@ -857,10 +866,10 @@ option, after an equal sign. For example, @command{cflow --cpp='cc
@cindex configuring output indentation level
@anchor{setting indentation}
You can configure the exact appearance of @command{cflow}
-output flow graph using @option{--level-indent} option. The simplest
+output flow graph using @option{--level-indent} option. The simplest
use for this option is to change the default indentation per nesting
-level. To do so, give the option a numeric argument specifying the
-number of columns to indent for each nesting level. For example, the
+level. To do so, give the option a numeric argument specifying the
+number of columns to indent for each nesting level. For example, the
following command sets the indentation level to 2, which is half of
the default:
@@ -872,15 +881,15 @@ cflow --level-indent 2 d.c
It can be used, for instance, to keep the graph within the page
margins.
- However, @option{--level-indent} can do much more than that. Each
+ However, @option{--level-indent} can do much more than that. Each
line in the flow graph consists of the following graphical elements: a
@dfn{start marker}, an @dfn{end marker}, with several @dfn{indent fills}
-between them. By default, both start and end markers are empty, and
+between them. By default, both start and end markers are empty, and
each indent fill contains four spaces.
If the argument to @option{--level-indent} option has the form
@var{element}=@var{string}, it specifies a character string that
-should be output in place of a given graph element. The element names
+should be output in place of a given graph element. The element names
are:
@cindex @option{--level-indent} keywords
@@ -901,7 +910,7 @@ are:
that the flow graph represents a call tree, so it contains terminal
nodes (@dfn{leaves}), i.e. the calls that end a function, and
non-terminal nodes (the calls followed by another ones on the same
-nesting level). The @dfn{end marker 0} is for non-terminal nodes, and
+nesting level). The @dfn{end marker 0} is for non-terminal nodes, and
@dfn{end marker 1} is for terminal nodes.
As for indent fills, @dfn{indent fill 1} is used to represent
@@ -930,14 +939,14 @@ Now, let's represent line elements by the following strings:
@cindex @option{--level-indent} string syntax
The corresponding command line will be: @code{cflow --level
begin=:: --level '0= ' --level '1=| ' --level end0='+-' --level
-end1='\\-' foo.c}. Notice escaping the backslash characters in
+end1='\\-' foo.c}. Notice escaping the backslash characters in
@code{end1}: generally speaking, @var{string} in
@option{--level-option} can contain usual @code{C} escape sequences,
-so the backslash character itself must be escaped. Another shortcut,
+so the backslash character itself must be escaped. Another shortcut,
allowed in @var{string} is the notation @code{@var{C}x@var{N}}, where
-@var{C} is any single character and @var{N} is a decimal number. This
+@var{C} is any single character and @var{N} is a decimal number. This
notation means ``@i{repeat character @var{C} @var{N}
-times}''. However, character @samp{x} looses its special meaning if
+times}''. However, character @samp{x} looses its special meaning if
used at the beginning of the string.
This command will produce the following output:
@@ -954,10 +963,10 @@ used at the beginning of the string.
@cindex @option{--tree} introduced
@cindex @option{-T} introduced
Thus, we obtained an @dfn{ASCII art} representation of the call
-tree. GNU @command{cflow} provides a special option @option{--tree}
+tree. GNU @command{cflow} provides a special option @option{--tree}
(@option{-T}), which is a shortcut for @code{--level '0= ' --level
-'1=| ' --level end0='+-' --level end1='\\-'}. The following is an
-example of flow graph produced with this option. The source file
+'1=| ' --level end0='+-' --level end1='\\-'}. The following is an
+example of flow graph produced with this option. The source file
@file{wc.c} is a simple implementation of UNIX @command{wc} command,
@xref{Source of wc command}.
@@ -1001,12 +1010,12 @@ $ @kbd{cflow --tree --brief --cpp wc.c}
@cindex @option{--xref} option introduced
@cindex @option{-x} option introduced
GNU @command{cflow} is also able to produce @dfn{cross-reference
-listings}. This mode is enabled by @option{--xref} (@option{-x})
-command line option. Cross-reference output lists each symbol
-occurrence on a separate line. Each line shows the identifier and the
-source location where it appears. If this location is where the symbol
+listings}. This mode is enabled by @option{--xref} (@option{-x})
+command line option. Cross-reference output lists each symbol
+occurrence on a separate line. Each line shows the identifier and the
+source location where it appears. If this location is where the symbol
is defined, it is additionally marked with an asterisk and followed by
-the definition. For example, here is a fragment of cross-reference
+the definition. For example, here is a fragment of cross-reference
output for @file{d.c} program:
@smallexample
@@ -1019,7 +1028,7 @@ printdir d.c:102
and referenced twice, in lines 74 and 102.
The symbols included in cross-reference listings are controlled
-by @option{--include} option (@pxref{--include}). In addition to
+by @option{--include} option (@pxref{--include}). In addition to
character classes discussed in chapter ``Controlling Symbol Types''
(@pxref{Symbols}), an additional symbol class @code{t} controls
listing of type names defined by @code{typedef} keyword.
@@ -1027,16 +1036,16 @@ listing of type names defined by @code{typedef} keyword.
@node Configuration
@chapter Configuration Files and Variables.
As shown in the previous chapters, GNU @command{cflow} is highly
-configurable. Different command line options have different effects,
+configurable. Different command line options have different effects,
as specifying new operation modes or altering some aspects of the
-output. You will likely use some options frequently, while you will
+output. You will likely use some options frequently, while you will
use others from time to time, or not at all (@xref{Options}, for a
full list of options).
@vindex CFLOW_OPTIONS
@cindex @file{.profile}
The @env{CFLOW_OPTIONS} environment variable specifies default
-options to be placed in front of any explicit options. For example,
+options to be placed in front of any explicit options. For example,
if you set @code{CFLOW_OPTIONS="--format=posix --cpp"} in your
@file{.profile}, @command{cflow} will behave as if the two options
@option{--format=posix} and @option{--cpp} had been specified before
@@ -1046,27 +1055,27 @@ any explicit options.
@vindex CFLOWRC
@cindex @file{.cflowrc}
There is also another possibility to specify your default
-options. After incorporating eventual content of @env{CFLOW_OPTIONS}
+options. After incorporating eventual content of @env{CFLOW_OPTIONS}
variable, @command{cflow} checks the value of the environment variable
-@env{CFLOWRC}. This value, if not empty, specifies the name of
-the @dfn{configuration file} to read. If @env{CFLOWRC} is not defined or
+@env{CFLOWRC}. This value, if not empty, specifies the name of
+the @dfn{configuration file} to read. If @env{CFLOWRC} is not defined or
is empty, the program attempts to read file @file{.cflowrc} in the
-user's home directory. It is not an error if any of these
-files does not exist. However, if the file does exist but cannot be
+user's home directory. It is not an error if any of these
+files does not exist. However, if the file does exist but cannot be
processed, @command{cflow} will issue an explicit error message.
@cindex Configuration file format
- The configuration file is read line by line. Empty lines and
+ The configuration file is read line by line. Empty lines and
lines beginning with usual @command{shell} comment character
-(@samp{#}) are ignored. Otherwise, the line is split into @dfn{words},
+(@samp{#}) are ignored. Otherwise, the line is split into @dfn{words},
the same way @command{shell} does, and the resulting words are
placed in the command line after any options taken from
@env{CFLOW_OPTIONS} variable, but before any explicit options.
Pay attention when using such options as @option{-D} in the
-configuration file. The value of the @option{-D} option will be added to
+configuration file. The value of the @option{-D} option will be added to
the preprocessor command line and will be processed by the shell, so
-be careful to properly quote its argument. The rule of thumb is:
+be careful to properly quote its argument. The rule of thumb is:
``@i{use the same quoting you would have used in the shell command line}''.
For example, to run @command{cc -E} as a preprocessor, you can use the
following configuration file:
@@ -1081,11 +1090,11 @@ following configuration file:
@cindex Option cancellation
It may sometimes be necessary to cancel the effect of a command
-line option. For example, you might specify @option{--brief} in your
+line option. For example, you might specify @option{--brief} in your
configuration file, but then occasionally need to obtain verbose
-graph. To cancel effect of any GNU @command{cflow} option that does
+graph. To cancel effect of any GNU @command{cflow} option that does
not take arguments, prepend @samp{no-} to the corresponding long
-option name. Thus, specifying @option{--no-brief} cancels the effect
+option name. Thus, specifying @option{--no-brief} cancels the effect
of the previous @option{--brief} option.
@node Makefiles
@@ -1093,8 +1102,8 @@ of the previous @option{--brief} option.
@cindex @file{Makefile.am}
If you wish to use @command{cflow} to analyze your project
sources, @file{Makefile} or @file{Makefile.am} is the right place to
-do so. In this chapter we will describe a generic rule for
-@file{Makefile.am}. If you do not use @command{automake}, you can
+do so. In this chapter we will describe a generic rule for
+@file{Makefile.am}. If you do not use @command{automake}, you can
deduce the rule for plain @file{Makefile} from this one.
Here is a check list of steps to do to set up a @file{Makefile.am}
@@ -1105,7 +1114,7 @@ framework:
variable.
@item Add variable @code{CFLOW_FLAGS} with any special @command{cflow}
-options you wish to use. The variable can be empty, its main purpose
+options you wish to use. The variable can be empty, its main purpose
is making it possible to override @command{cflow} options by running
@command{make CFLOW_FLAGS=@dots{} chart}.
@@ -1127,7 +1136,7 @@ for which you want to generate a flow chart, add the following statements:
@noindent
Replace @var{program} with program name and
@var{path-to-your-cflow.rc} with the full file name of your
-@file{cflow.rc} file (if any). If you do not wish to use
+@file{cflow.rc} file (if any). If you do not wish to use
preprocessing, remove from the @command{cflow} command line all
variables, except @code{CFLOW_FLAGS}.
@@ -1163,12 +1172,12 @@ cflow.cflow: $(cflow_CFLOW_INPUT) cflow.rc Makefile
This chapter contains an alphabetical listing of all
@command{cflow} command line options, with brief descriptions and cross
references to more in-depth explanations in the body of the
-manual. Both short and long option forms are listed, so you can use
+manual. Both short and long option forms are listed, so you can use
this table as a quick reference.
Most of the options have a @dfn{negation counterpart}, an option
-with a reverse meaning. The name of a negation option is formed by
-prefixing the corresponding long option name with a @option{no-}. This
+with a reverse meaning. The name of a negation option is formed by
+prefixing the corresponding long option name with a @option{no-}. This
feature is provided to cancel default options specified in the
configuration file.
@@ -1181,54 +1190,54 @@ with a bullet (@bullet{}).
@cindex @option{--no-ansi}
@item -a
@itemx --ansi
- @bullet{} Assume input to be written in @acronym{ANSI} @code{C}. Currently
+ @bullet{} Assume input to be written in @acronym{ANSI} @code{C}. Currently
this means disabling code that parses @dfn{K&R function
-declarations}. This might speed up the processing in some cases.
+declarations}. This might speed up the processing in some cases.
@cindex @option{-b}
@cindex @option{--brief}
@cindex @option{--no-brief}
@item -b
@itemx --brief
- @bullet{} Brief output. @xref{--brief}.
+ @bullet{} Brief output. @xref{--brief}.
@cindex @option{--cpp}
@cindex @option{--no-cpp}
@anchor{--cpp}
@item --cpp[=@var{command}]
- @bullet{} Run the specified preprocessor command. @xref{Preprocessing}.
+ @bullet{} Run the specified preprocessor command. @xref{Preprocessing}.
@cindex @option{-D}
@cindex @option{--define}
@item -D @var{name}[=@var{defn}]
@itemx --define=@var{name}[=@var{defn}]
- Predefine @var{name} as a macro. Implies @option{-cpp}
+ Predefine @var{name} as a macro. Implies @option{-cpp}
(@pxref{Preprocessing}).
@cindex @option{-d}
@cindex @option{--depth}
@item -d @var{number}
@itemx --depth=@var{number}
- Set the depth at which the flow graph is cut off. For example,
+ Set the depth at which the flow graph is cut off. For example,
@option{--depth=5} means the graph will contain function calls up to
the 5th nesting level.
@cindex @option{--debug}
@item --debug[=@var{number}]
- Set debugging level. Default @var{number} is 1. Use this option
+ Set debugging level. Default @var{number} is 1. Use this option
if you are developing and/or debugging @command{cflow}.
@cindex @option{--emacs}
@cindex @option{--no-emacs}
@item --emacs
@bullet{} Prepend the output with a line telling Emacs to use @code{cflow}
-mode when visiting this file. Implies @option{--format=gnu}. @xref{--emacs}.
+mode when visiting this file. Implies @option{--format=gnu}. @xref{--emacs}.
@cindex @option{-f}
@cindex @option{--format}
@item -f @var{name}
@itemx --format=@var{name}
- Use given output format @var{name}. Valid names are @code{gnu}
+ Use given output format @var{name}. Valid names are @code{gnu}
(@pxref{GNU Output Format}) and @code{posix} (@pxref{POSIX Output Format}).
@cindex @option{-?}
@@ -1242,15 +1251,15 @@ mode when visiting this file. Implies @option{--format=gnu}. @xref{--emacs}.
@item -I @var{dir}
@itemx --include-dir=@var{dir}
Add the directory @var{dir} to the list of directories to be
-searched for header files. Implies @option{--cpp} (@pxref{Preprocessing}).
+searched for header files. Implies @option{--cpp} (@pxref{Preprocessing}).
@cindex @option{-i}
@cindex @option{--include}
@item -i @var{spec}
@itemx --include=@var{spec}
- Control the number of included symbols. @var{Spec} is a string
+ Control the number of included symbols. @var{Spec} is a string
consisting of characters, specifying what class of symbols to
-include in the output. Valid @var{spec} symbols are:
+include in the output. Valid @var{spec} symbols are:
@table @asis
@item -
@@ -1281,36 +1290,36 @@ For more information, @xref{Symbols}.
@cindex @option{--level-indent}
@item --level-indent=@var{string}
- Use @var{string} when indenting to each new level. @xref{ASCII Tree}.
+ Use @var{string} when indenting to each new level. @xref{ASCII Tree}.
@cindex @option{-m}
@cindex @option{--main}
@item -m @var{name}
@item --main=@var{name}
- Assume main function to be called @var{name}. @xref{start symbol}.
+ Assume main function to be called @var{name}. @xref{start symbol}.
@cindex @option{-n}
@cindex @option{--number}
@cindex @option{--no-number}
@item -n
@itemx --number
- @bullet{} Print line numbers. @xref{--number}.
+ @bullet{} Print line numbers. @xref{--number}.
@cindex @option{-o}
@cindex @option{--output}
@item -o @var{file}
@itemx --output=@var{file}
- Set output file name. Default is @samp{-}, meaning standard output.
+ Set output file name. Default is @samp{-}, meaning standard output.
@cindex @option{--omit-arguments}
@item --ommit-arguments
@bullet{} Do not print argument lists in function
-declarations. @xref{omit signature parts}.
+declarations. @xref{omit signature parts}.
@cindex @option{--omit-symbol-names}
@item --omit-symbol-names
- @bullet{} Do not print symbol names in declarations. @xref{omit
-signature parts}. This option is turned on in @samp{posix} output
+ @bullet{} Do not print symbol names in declarations. @xref{omit
+signature parts}. This option is turned on in @samp{posix} output
mode (@pxref{POSIX Output Format}.
@FIXME{I am not sure whether the one below is needed:
@@ -1319,8 +1328,8 @@ mode (@pxref{POSIX Output Format}.
@cindex @option{--print}
@item -P @var{opt}
@itemx --print=@var{opt}
- Set printing option. Valid @var{opt} values are: @samp{xref} (or
-@samp{cross-ref}) and @samp{tree}. Any unambiguous abbreviation of the
+ Set printing option. Valid @var{opt} values are: @samp{xref} (or
+@samp{cross-ref}) and @samp{tree}. Any unambiguous abbreviation of the
above is also accepted.
@end verbatim
}
@@ -1330,27 +1339,27 @@ above is also accepted.
@cindex @option{--no-reverse}
@item -r
@itemx --reverse
- @bullet{} Print reverse call graph. @xref{Direct and Reverse}.
+ @bullet{} Print reverse call graph. @xref{Direct and Reverse}.
@cindex @option{-x}
@cindex @option{--xref}
@cindex @option{--no-xref}
@item -x
@itemx --xref
- @bullet{} Produce cross-reference listing only. @xref{Cross-References}.
+ @bullet{} Produce cross-reference listing only. @xref{Cross-References}.
@cindex @option{-p}
@cindex @option{--pushdown}
@item -p @var{number}
@itemx --pushdown=@var{number}
- Set initial token stack size to @var{number} tokens. Default is
-64. The token stack grows automatically when it needs to accommodate
+ Set initial token stack size to @var{number} tokens. Default is
+64. The token stack grows automatically when it needs to accommodate
more tokens than its current size, so it is seldom necessary to
use this option.
@cindex @option{--preprocess}
@item --preprocess[=@var{command}]
- Run the specified preprocessor command. @xref{--cpp}.
+ Run the specified preprocessor command. @xref{--cpp}.
@cindex @option{-s}
@cindex @option{--symbol}
@@ -1359,9 +1368,9 @@ use this option.
@itemx --symbol=@var{newsym}:=@var{oldsym}
@anchor{symbol types}
In first form, registers symbol @var{sym} in the syntactic class
-@var{class}. Valid class names are: @samp{keyword} (or @samp{kw}),
+@var{class}. Valid class names are: @samp{keyword} (or @samp{kw}),
@samp{modifier}, @samp{qualifier}, @samp{identifier}, @samp{type},
-@samp{wrapper}. Any unambiguous abbreviation of the above is also
+@samp{wrapper}. Any unambiguous abbreviation of the above is also
accepted. @xref{Syntactic classes}.
In the second form (with the @samp{:=} separator), defines
@@ -1375,16 +1384,16 @@ this option.
@cindex @option{--no-use-indentation}
@item -S
@itemx --use-indentation
- @bullet{} Use source file indentation as a hint. Currently this means that
+ @bullet{} Use source file indentation as a hint. Currently this means that
the closing curly brace (@samp{@}}) in the column zero forces
-@command{cflow} to close current function definition. Use this option
+@command{cflow} to close current function definition. Use this option
sparingly, it may cause misinterpretation of some sources.
@cindex @option{-U}
@cindex @option{--undefine}
@item -U @var{name}
@itemx --undefine=@var{name}
- Cancel any previous definition of @var{name}. Implies
+ Cancel any previous definition of @var{name}. Implies
@option{--cpp} (@pxref{Preprocessing}).
@cindex @option{--print-level}
@@ -1393,7 +1402,7 @@ sparingly, it may cause misinterpretation of some sources.
@item --print-level
@itemx -l
@anchor{--print-level}
- @bullet{} Print nesting level along with the call graph. The level is
+ @bullet{} Print nesting level along with the call graph. The level is
printed after output line number (if @option{--number} or
@option{--format=posix} is used, enclosed in curly braces.
@@ -1402,7 +1411,7 @@ printed after output line number (if @option{--number} or
@cindex @option{--no-tree}
@item -T
@itemx --tree
- @bullet{} Use ASCII art to print graph. @xref{ASCII Tree}.
+ @bullet{} Use ASCII art to print graph. @xref{ASCII Tree}.
@cindex @option{--usage}
@item --usage
@@ -1413,9 +1422,9 @@ printed after output line number (if @option{--number} or
@cindex @option{--no-verbose}
@item -v
@itemx --verbose
- @bullet{} Verbosely list any errors encountered in the input files. The
+ @bullet{} Verbosely list any errors encountered in the input files. The
@command{cflow} notion of an error does not match that of @code{C}
-compiler, so by default error messages are turned off. It is useful to
+compiler, so by default error messages are turned off. It is useful to
enable them if you suspect that @command{cflow} misinterprets the
sources.
@@ -1431,9 +1440,9 @@ sources.
@cindex cflow-mode introduced
@cindex Emacs
GNU @command{cflow} comes with an @command{emacs} module
-providing a major mode for visiting flow charts in GNU Emacs. If you
+providing a major mode for visiting flow charts in GNU Emacs. If you
have a working @command{emacs} on your machine, the module will be
-installed somewhere in your Emacs @code{load-path}. To load the module
+installed somewhere in your Emacs @code{load-path}. To load the module
at startup, add the following lines to your @file{.emacs} or
@file{site-start.el} file:
@@ -1449,39 +1458,39 @@ at startup, add the following lines to your @file{.emacs} or
@cindex @option{--emacs} introduced
@anchor{--emacs}
The second statement associates @code{cflow-mode} with any file having
-suffix @file{.cflow}. If you prefer to have another suffix for flow
-graph files, use it instead. You can also omit this option, if you do
-not use any special suffix for your graph files. In this case we
-recommend using @option{--emacs} command line option. This option
+suffix @file{.cflow}. If you prefer to have another suffix for flow
+graph files, use it instead. You can also omit this option, if you do
+not use any special suffix for your graph files. In this case we
+recommend using @option{--emacs} command line option. This option
generates the first line telling Emacs to use @code{cflow} major mode
when visiting the file.
- The buffer opened in @code{cflow} mode is made read-only. The
+ The buffer opened in @code{cflow} mode is made read-only. The
following key bindings are defined:
@table @key
@item E
Temporarily exits from @code{cflow} mode and allows you to edit
-the graph file. To resume @code{cflow} mode type @key{M-x} cflow-mode
-@key{RET}. This option is provided mainly for debugging
-purposes. We do not recommend you to edit chart files, since this
+the graph file. To resume @code{cflow} mode type @key{M-x} cflow-mode
+@key{RET}. This option is provided mainly for debugging
+purposes. We do not recommend you to edit chart files, since this
will change line numbering and thus prevent @code{cflow} mode from
correctly tracing line references.
@item x
- Go to expansion of the current graph vertex. Use this key if the
-point stands on a line ending with @samp{[see @var{N}]} reference. It
-will bring you directly to the referenced line. Use
+ Go to expansion of the current graph vertex. Use this key if the
+point stands on a line ending with @samp{[see @var{N}]} reference. It
+will bring you directly to the referenced line. Use
@code{exchange-point-and-mark} (by default @key{C-x C-x}) to return to
the line you examined.
@item R
If the point is standing on a recursive function, go to the next
-recursion. Sets mark.
+recursion. Sets mark.
@item r
If the point is standing on a recursive function, return to its
-definition (a @dfn{recursion root}). Sets mark.
+definition (a @dfn{recursion root}). Sets mark.
@item s
Visit the referenced source file and find the function definition.
@@ -1493,7 +1502,7 @@ definition (a @dfn{recursion root}). Sets mark.
Send bug reports via electronic mail to @email{bug-cflow@@gnu.org}.
As the purpose of bug reporting is to improve software, please be sure
-to include maximum information when reporting a bug. The minimal
+to include maximum information when reporting a bug. The minimal
information needed is:
@itemize

Return to:

Send suggestions and report system problems to the System administrator.