From b5cbb05d00e242aa653460a100715f7948396a64 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Tue, 11 Oct 2011 11:13:02 +0300 Subject: Change to double-space sentence spacing in cflow.texi. --- doc/cflow.texi | 367 +++++++++++++++++++++++++++++---------------------------- 1 file 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() : @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() : @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() : @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() : @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() : @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 -- cgit v1.2.1