X-Git-Url: https://git.hcoop.net/bpt/coccinelle.git/blobdiff_plain/5636bb2c2537506718da74f85a2b81a5ff3df16f..17ba07880e1838028b4516ba7a2db2147b3aa1c9:/docs/manual/spatch_options.tex

diff --git a/docs/manual/spatch_options.tex b/docs/manual/spatch_options.tex
index fd2eb5c..bccafb1 100644
--- a/docs/manual/spatch_options.tex
+++ b/docs/manual/spatch_options.tex
@@ -21,22 +21,22 @@ follows, for a semantic match {\tt foo.cocci}, a C file {\tt foo.c}, and a
 directory {\tt foodir}:
 
 \begin{itemize}
-\item {\tt spatch -parse\_cocci foo.cocci}: Check that the semantic patch
+\item {\tt spatch --parse-cocci foo.cocci}: Check that the semantic patch
   is syntactically correct.
-\item {\tt spatch -parse\_c foo.c}: Check that the C file
+\item {\tt spatch --parse-c foo.c}: Check that the C file
   is syntactically correct.  The Coccinelle C parser tries to recover
   during the parsing process, so if one function does not parse, it will
   start up again with the next one.  Thus, a parse error is often not a
   cause for concern, unless it occurs in a function that is relevant to the
   semantic patch.
-\item {\tt spatch -sp\_file foo.cocci foo.c}: Apply the semantic patch {\tt
+\item {\tt spatch --sp-file foo.cocci foo.c}: Apply the semantic patch {\tt
     foo.cocci} to the file {\tt foo.c} and print out any transformations as a
-  diff.
-\item {\tt spatch -sp\_file foo.cocci foo.c -debug}:  The same as the
+  diff.  {\tt --sp-file} is optional in this and the following cases.
+\item {\tt spatch --sp-file foo.cocci foo.c --debug}:  The same as the
   previous case, but print out some information about the matching process.
-\item {\tt spatch -sp\_file foo.cocci -dir foodir}:  Apply the semantic
+\item {\tt spatch --sp-file foo.cocci --dir foodir}:  Apply the semantic
   patch {\tt foo.cocci} to all of the C files in the directory {\tt foodir}.
-\item {\tt spatch -sp\_file foo.cocci -dir foodir -include\_headers}:  Apply
+\item {\tt spatch --sp-file foo.cocci --dir foodir --include-headers}:  Apply
   the semantic patch {\tt foo.cocci} to all of the C files and header files
   in the directory {\tt foodir}. 
 \end{itemize}
@@ -57,97 +57,113 @@ understanding the effect of a semantic patch.
 
 \subsection{Standalone options}
 
-\normal{-parse\_cocci $\langle$file$\rangle$}{ Parse a semantic
+\normal{--parse-cocci $\langle$file$\rangle$}{ Parse a semantic
 patch file and print out some information about it.}
 
 \subsection{The semantic patch}
 
-\minimum{-sp\_file $\langle$file$\rangle$, -c $\langle$file$\rangle$, 
--cocci\_file $\langle$file$\rangle$}{ Specify the name of the file
+\minimum{--sp-file $\langle$file$\rangle$, -c $\langle$file$\rangle$, 
+-cocci-file $\langle$file$\rangle$}{ Specify the name of the file
   containing the semantic patch.  The file name should end in {\tt .cocci}.
-All three options do the same thing; the last two are deprecated.}
+All three options do the same thing.  These options are optional.  If they
+are not used, the single file whose name ends in \texttt{.cocci} is
+assoumed to be the name of the file containing the semantic patch.}
+
+\rare{--sp ``semantic patch string''}{Specify a semantic match as a
+  command-line argument.  See the section ``Command-line semantic match''
+  in the manual.}
 
 \subsection{Isomorphisms}
 
-\rare{-iso, -iso\_file}{ Specify a file containing isomorphisms to be used in
+\rare{--iso, --iso-file}{ Specify a file containing isomorphisms to be used in
 place of the standard one.  Normally one should use the {\tt using}
 construct within a semantic patch to specify isomorphisms to be used {\em
   in addition to} the standard ones.}
 
-\rare{-iso\_limit $\langle$int$\rangle$} Limit the depth of application of
+\rare{--iso-limit $\langle$int$\rangle$} Limit the depth of application of
 isomorphisms to the specified integer.
 
-\rare{-no\_iso\_limit} Put no limit on the number of times that
+\rare{--no-iso-limit} Put no limit on the number of times that
 isomorphisms can be applied. This is the default.
 
-\developer{-track\_iso}{ Gather information about isomorphism usage.}
+\rare{--disable-iso}{Disable a specific isomorphism from the command line.
+  This option can be specified multiple times.}
+
+\developer{--track-iso}{ Gather information about isomorphism usage.}
 
-\developer{-profile\_iso}{ Gather information about the time required for
+\developer{--profile-iso}{ Gather information about the time required for
 isomorphism expansion.}
 
 \subsection{Display options}
 
-\rare{-show\_cocci}{Show the semantic patch that is being processed before
+\rare{--show-cocci}{Show the semantic patch that is being processed before
   expanding isomorphisms.}
 
-\rare{-show\_SP}{Show the semantic patch that is being processed after
+\rare{--show-SP}{Show the semantic patch that is being processed after
   expanding isomorphisms.}
 
-\rare{-show\_ctl\_text}{ Show the representation
+\rare{--show-ctl-text}{ Show the representation
 of the semantic patch in CTL.}
 
-\rare{-ctl\_inline\_let}{ Sometimes {\tt let} is used to name
+\rare{--ctl-inline-let}{ Sometimes {\tt let} is used to name
 intermediate terms CTL representation.  This option causes the let-bound
 terms to be inlined at the point of their reference.
-This option implicitly sets {\bf -show\_ctl\_text}.}
+This option implicitly sets {\bf --show-ctl-text}.}
 
-\rare{-ctl\_show\_mcodekind}{ Show
+\rare{--ctl-show-mcodekind}{ Show
 transformation information within the CTL representation
-of the semantic patch. This option implicitly sets {\bf -show\_ctl\_text}.}
+of the semantic patch. This option implicitly sets {\bf --show-ctl-text}.}
 
-\rare{-show\_ctl\_tex}{ Create a LaTeX files showing the representation
+\rare{--show-ctl-tex}{ Create a LaTeX files showing the representation
 of the semantic patch in CTL.}
 
 \section{Selecting and parsing the C files}
 
 \subsection{Standalone options}
 
-\normal{-parse\_c $\langle$file/dir$\rangle$}{ Parse a {\tt .c} file or all
+\normal{--parse-c $\langle$file/dir$\rangle$}{ Parse a {\tt .c} file or all
   of the {\tt .c} files in a directory.  This generates information about
   any parse errors encountered.}
 
-\normal{-parse\_h $\langle$file/dir$\rangle$}{ Parse a {\tt .h} file or all
+\normal{--parse-h $\langle$file/dir$\rangle$}{ Parse a {\tt .h} file or all
   of the {\tt .h} files in a directory.  This generates information about
   any parse errors encountered.}
 
-\normal{-parse\_ch $\langle$file/dir$\rangle$}{ Parse a {\tt .c} or {\tt
+\normal{--parse-ch $\langle$file/dir$\rangle$}{ Parse a {\tt .c} or {\tt
     .h} file or all of the {\tt .c} or {\tt .h} files in a directory.  This
   generates information about any parse errors encountered.}
 
-\normal{-control\_flow $\langle$file$\rangle$, -control\_flow
+\normal{--control-flow $\langle$file$\rangle$, --control-flow
 $\langle$file$\rangle$:$\langle$function$\rangle$}{ Print a control-flow
 graph for all of the functions in a file or for a specific function in a
 file.  This requires {\tt dot} (http://www.graphviz.org/) and {\tt gv}.}
 
-\rare{-type\_c $\langle$file$\rangle$}{ Parse a C file and pretty-print a
+\rare{--control-flow-to-file $\langle$file$\rangle$,
+  --control-flow-to-file
+  $\langle$file$\rangle$:$\langle$function$\rangle$}{ Like --control-flow
+  but just puts the dot output in a file in the {\em current} directory.
+  For PATH/file.c, this produces file:xxx.dot for each (selected) function
+  xxx in PATH/file.c.}
+
+\rare{--type-c $\langle$file$\rangle$}{ Parse a C file and pretty-print a
 version including type information.}
 
-\developer{-tokens\_c $\langle$file$\rangle$}{Prints the tokens in a C
+\developer{--tokens-c $\langle$file$\rangle$}{Prints the tokens in a C
   file.}
 
-\developer{-parse\_unparse $\langle$file$\rangle$}{Parse and then reconstruct
+\developer{--parse-unparse $\langle$file$\rangle$}{Parse and then reconstruct
   a C file.}
 
-\developer{-compare\_c $\langle$file$\rangle$ $\langle$file$\rangle$,
-  -compare\_c\_hardcoded}{Compares one C file to another, or compare the
+\developer{--compare-c $\langle$file$\rangle$ $\langle$file$\rangle$,
+  --compare-c-hardcoded}{Compares one C file to another, or compare the
 file tests/compare1.c to the file tests/compare2.c.}
 
-\developer{-test\_cfg\_ifdef $\langle$file$\rangle$}{Do some special
+\developer{--test-cfg-ifdef $\langle$file$\rangle$}{Do some special
 processing of \#ifdef and display the resulting control-flow graph.  This
 requires {\tt dot} and {\tt gv}.}
 
-\developer{-test\_attributes $\langle$file$\rangle$,
-           -test\_cpp $\langle$file$\rangle$}{
+\developer{--test-attributes $\langle$file$\rangle$,
+           --test-cpp $\langle$file$\rangle$}{
 Test the parsing of cpp code and attributes, respectively.}
 
 \subsection{Selecting C files}
@@ -160,74 +176,81 @@ second semantic patch rule is applied to all functions in all files, etc.
 If a directory is specified then no files may be specified and only the
 rightmost directory specified is used.
 
-\normal{-include\_headers}{ This option causes header files to be processed
+\normal{--include-headers}{ This option causes header files to be processed
 independently.  This option only makes sense if a directory is specified
-using {\bf -dir}.}
+using {\bf --dir}.}
 
-\normal{-use\_glimpse}{ Use a glimpse index to select the files to which
+\normal{--use-glimpse}{ Use a glimpse index to select the files to which
 a semantic patch may be relevant.  This option requires that a directory is
 specified.  The index may be created using the script {\tt
-  coccinelle/scripts/ glimpseindex\_cocci.sh}.  Glimpse is available at
-http://webglimpse.net/.  In conjunction with the option {\bf -patch\_cocci}
+  coccinelle/scripts/ glimpseindex-cocci.sh}.  Glimpse is available at
+http://webglimpse.net/.  In conjunction with the option {\bf --patch-cocci}
 this option prints the regular expression that will be passed to glimpse.}
 
-\rare{-dir}{ Specify a directory containing C files to process.  A trailing
+\normal{--use-idutils}{ Use an id-utils index created using lid to select
+  the files to which a semantic patch may be relevant.  This option
+  requires that a directory is specified.  The index may be created using
+  the script {\tt coccinelle/scripts/ idindex-cocci.sh}.  In conjunction
+  with the option {\bf --patch-cocci} this option prints the regular
+  expression that will be passed to glimpse.}
+
+\rare{--dir}{ Specify a directory containing C files to process.  A trailing
   {\tt /} is permitted on the directory name and has no impact on the
   result.  By default, the include path will be set to the ``include''
   subdirectory of this directory.  A different include path can be
-  specified using the option {\bf -I}.  {\bf -dir} only considers the
+  specified using the option {\bf -I}.  {\bf --dir} only considers the
   rightmost directory in the argument list.  This behavior is convenient
   for creating a script that always works on a single directory, but allows
   the user of the script to override the provided directory with another
   one.  Spatch collects the files in the directory using {\tt find} and
   does not follow symbolic links.}
 
-\developer{-kbuild\_info $\langle$file$\rangle$}{ The specified file
+\developer{--kbuild-info $\langle$file$\rangle$}{ The specified file
   contains information about which sets of files should be considered in
   parallel.}
 
-\developer{-disable\_worth\_trying\_opt}{Normally, a C file is only
+\developer{--disable-worth-trying-opt}{Normally, a C file is only
   processed if it contains some keywords that have been determined to be
   essential for the semantic patch to match somewhere in the file.  This
   option disables this optimization and tries the semantic patch on all files.}
 
-\developer{-test $\langle$file$\rangle$}{ A shortcut for running Coccinelle
+\developer{--test $\langle$file$\rangle$}{ A shortcut for running Coccinelle
 on the semantic patch ``file{\tt{.cocci}}'' and the C file ``file{\tt{.c}}''.}
 
-\developer{-testall}{A shortcut for running Coccinelle on all files in a
+\developer{--testall}{A shortcut for running Coccinelle on all files in a
   subdirectory {\tt tests} such that there are all of a {\tt .cocci} file, a {\tt
     .c} file, and a {\tt .res} file, where the {\tt .res} contains the
   expected result.}
 
-\developer{-test\_okfailed, -test\_regression\_okfailed} Other options for
+\developer{--test-okfailed, --test-regression-okfailed} Other options for
 keeping track of tests that have succeeded and failed.
 
-\developer{-compare\_with\_expected}{Compare the result of applying
+\developer{--compare-with-expected}{Compare the result of applying
   Coccinelle to file{\tt{.c}} to the file file{\tt{.res}} representing the
   expected result.}
 
-\developer{-expected\_score\_file $\langle$file$\rangle$}{
+\developer{--expected-score-file $\langle$file$\rangle$}{
 which score file to compare with in the testall run}
 
 \subsection{Parsing C files}
 
-\rare{-show\_c}{Show the C code that is being processed.}
+\rare{--show-c}{Show the C code that is being processed.}
 
-\rare{-parse\_error\_msg}{Show parsing errors in the C file.}
+\rare{--parse-error-msg}{Show parsing errors in the C file.}
 
-\rare{-verbose\_parsing}{Show parsing errors in the C file, as well as
+\rare{--verbose-parsing}{Show parsing errors in the C file, as well as
   information about attempts to accomodate such errors.  This implicitly
-  sets -parse\_error\_msg.}
+  sets --parse-error-msg.}
 
-\rare{-type\_error\_msg}{Show information about where the C type checker
+\rare{--type-error-msg}{Show information about where the C type checker
   was not able to determine the type of an expression.}
 
-\rare{-int\_bits $\langle$n$\rangle$, -long\_bits
+\rare{--int-bits $\langle$n$\rangle$, --long-bits
 $\langle$n$\rangle$}{Provide integer size information. n is the number of
 bits in an unsigned integer or unsigned long, respectively.  If only the
-option {\bf -int\_bits} is used, unsigned longs will be assumed to have
+option {\bf --int-bits} is used, unsigned longs will be assumed to have
 twice as many bits as unsigned integers.  If only the option {\bf
--long\_bits} is used, unsigned ints will be assumed to have half as many
+-long-bits} is used, unsigned ints will be assumed to have half as many
 bits as unsigned integers.  This information is only used in determining
 the types of integer constants, according to the ANSI C standard (C89).  If
 neither is provided, the type of an integer constant is determined by the
@@ -235,20 +258,30 @@ sequence of ``u'' and ``l'' annotations following the constant.  If there
 is none, the constant is assumed to be a signed integer.  If there is only
 ``u'', the constant is assumed to be an unsigned integer, etc.}
 
-\rare{-no\_loops}{Drop back edges for loops.  This may make a semantic
+\rare{--no-loops}{Drop back edges for loops.  This may make a semantic
   patch/match run faster, at the cost of not finding matches that wrap
   around loops.}
 
-\developer{-use\_cache} Use preparsed versions of the C files that are
-stored in a cache.
+\developer{--use-cache}{Use preparsed versions of the C files that are
+stored in a cache.}
 
-\developer{-debug\_cpp, -debug\_lexer, -debug\_etdt,
-  -debug\_typedef}{Various options for debugging the C parser.}
+\developer{--cache-prefix}{Specify the directory in which to store 
+preparsed versions of the C files.  This sets {--use-cache}}
 
-\developer{-filter\_msg, -filter\_define\_error,
-  -filter\_passed\_level}{Various options for debugging the C parser.}
+\developer{--cache-limit}{Specify the maximum number of
+preparsed C files to store.  The cache is cleared of all files with names
+ending in .ast-raw and .depend-raw on reaching this limit.  Only
+effective if --cache-prefix is used as well.  This is most useful when
+iteration is used to process a file multiple times within a single run of
+Coccinelle.}
 
-\developer{-only\_return\_is\_error\_exit}{In matching ``{\tt{\ldots}}'' in
+\developer{--debug-cpp, --debug-lexer, --debug-etdt,
+  --debug-typedef}{Various options for debugging the C parser.}
+
+\developer{--filter-msg, --filter-define-error,
+  --filter-passed-level}{Various options for debugging the C parser.}
+
+\developer{--only-return-is-error-exit}{In matching ``{\tt{\ldots}}'' in
   a semantic patch or when forall is specified, a rule must match all
   control-flow paths starting from a node matching the beginning of the
   rule.  This is relaxed, however, for error handling code.  Normally, error
@@ -261,114 +294,126 @@ stored in a cache.
 
 \subsubsection*{Macros and other preprocessor code}
 
-\normal{-macro\_file $\langle$file$\rangle$}{
+\normal{--macro-file $\langle$file$\rangle$}{
   Extra macro definitions to be taken into account when parsing the C
-  files.}
+  files.  This uses the provided macro definitions in addition to those in
+  the default macro file.}
 
-\normal{-macro\_file\_builtins $\langle$file$\rangle$}{
+\normal{--macro-file-builtins $\langle$file$\rangle$}{
   Builtin macro definitions to be taken into account when parsing the C
-  files.}
+  files.  This causes the macro definitions provided in the default macro
+  file to be ignored and the ones in the specified file to be used instead.}
 
-\rare{-ifdef\_to\_if,-no\_ifdef\_to\_if}{
-The option {\bf -ifdef\_to\_if}
+\rare{--ifdef-to-if,-no-ifdef-to-if}{
+The option {\bf --ifdef-to-if}
 represents an {\tt \#ifdef} in the source code as a conditional in the
 control-flow graph when doing so represents valid code.  {\bf
--no\_ifdef\_to\_if} disables this feature.  {\bf -ifdef\_to\_if} is the
+-no-ifdef-to-if} disables this feature.  {\bf --ifdef-to-if} is the
 default.
 }
 
-\rare{-use\_if0\_code}{ Normally code under \#if 0 is ignored.  If this
+\rare{--use-if0-code}{ Normally code under \#if 0 is ignored.  If this
 option is set then the code is considered, just like the code under any
 other \#ifdef.}
 
-\developer{-noadd\_typedef\_root}{This seems to reduce the scope of a
+\developer{--noadd-typedef-root}{This seems to reduce the scope of a
   typedef declaration found in the C code.}
 
 \subsubsection*{Include files}
 
-\normal{-all\_includes, -local\_includes, -no\_includes}{
-These options control which include files mentioned in a C file are taken into
-account.  {\bf -all\_includes} indicates that all included files will be
-processed.  {\bf -local\_includes} indicates that only included files in
-the current directory will be processed.  {\bf -no\_includes} indicates
-that no included files will be processed.  If the semantic patch contains
-type specifications on expression metavariables, then the default is {\bf
--local\_includes}.  Otherwise the default is {\bf -no\_includes}.  At most
-one of these options can be specified.}
+\normal{--recursive-includes, --all-includes, --local-includes,
+  --no-includes}{ These options control which include files mentioned in a
+  C file are taken into account.  {\bf --recursive-includes} indicates
+  that all included files mentioned in the .c file(s) or any included files
+  will be processed.  {\bf --all-includes} indicates that all included
+  files mentioned in the .c file(s) will be processed.  {\bf
+    --local-includes} indicates that only included files in the current
+  directory will be processed.  {\bf --no-includes} indicates that no
+  included files will be processed.  If the semantic patch contains type
+  specifications on expression metavariables, then the default is {\bf
+    --local-includes}.  Otherwise the default is {\bf --no-includes}.  At
+  most one of these options can be specified.}
 
 \normal{-I $\langle$path$\rangle$}{ This option specifies a directory
   in which to find non-local include files.  This option can be used
   several times.}
 
-\rare{-relax\_include\_path}{This option when combined with -all\_includes
+\rare{--relax-include-path}{This option when combined with --all-includes
   causes the search for local
-  include files to consider the directory specified using {\bf -I} if the
-  included file is not found in the current directory.}
+  include files to consider the current directory, even if the include
+  patch specifies a subdirectory.  This is really only useful for testing,
+  eg with the option {\bf --testall}}
+
+\rare{--c++}{Make an extremely minimal effort to parse C++ code.  Currently,
+  this is limited to allowing identifiers to contain ``::'', tilde, and
+  template invocations.  Consider testing your code first with spatch
+  --type-c to see if there are any type annotations in the code you are
+  interested in processing.  If not, then it was probably not parsed.}
 
 \section{Application of the semantic patch to the C code}
 
 \subsection{Feedback at the rule level during the application of the
   semantic patch}
 
-\normal{-show\_bindings}{
+\normal{--show-bindings}{
 Show the environments with respect to which each rule is applied and the
 bindings that result from each such application.}
 
-\normal{-show\_dependencies}{ Show the status (matched or unmatched) of the
-rules on which a given rule depends.  {\bf -show\_dependencies} implicitly
-sets {\bf -show\_bindings}, as the values of the dependencies are
+\normal{--show-dependencies}{ Show the status (matched or unmatched) of the
+rules on which a given rule depends.  {\bf --show-dependencies} implicitly
+sets {\bf --show-bindings}, as the values of the dependencies are
 environment-specific.}
 
-\normal{-show\_trying}{
+\normal{--show-trying}{
 Show the name of each program element to which each rule is applied.}
 
-\normal{-show\_transinfo}{
+\normal{--show-transinfo}{
 Show information about each transformation that is performed.
 The node numbers that are referenced are the number of the nodes in the
-control-flow graph, which can be seen using the option {\bf -control\_flow}
-(the initial control-flow graph only) or the option {\bf -show\_flow} (the
+control-flow graph, which can be seen using the option {\bf --control-flow}
+(the initial control-flow graph only) or the option {\bf --show-flow} (the
 control-flow graph before and after each rule application).}
 
-\normal{-show\_misc}{Show some miscellaneous information.}
+\normal{--show-misc}{Show some miscellaneous information.}
 
-\rare{-show\_flow $\langle$file$\rangle$, -show\_flow
+\rare{--show-flow $\langle$file$\rangle$, --show-flow
   $\langle$file$\rangle$:$\langle$function$\rangle$} Show the control-flow
 graph before and after the application of each rule.
 
-\developer{-show\_before\_fixed\_flow}{This is similar to {\bf
-    -show\_flow}, but shows a preliminary version of the control-flow graph.}
+\developer{--show-before-fixed-flow}{This is similar to {\bf
+    --show-flow}, but shows a preliminary version of the control-flow graph.}
 
 \subsection{Feedback at the CTL level during the application of the
   semantic patch}
 
-\normal{-verbose\_engine}{Show a trace of the matching of atomic terms to C
+\normal{--verbose-engine}{Show a trace of the matching of atomic terms to C
   code.}
 
-\rare{-verbose\_ctl\_engine}{Show a trace of the CTL matching process.
+\rare{--verbose-ctl-engine}{Show a trace of the CTL matching process.
   This is unfortunately rather voluminous and not so helpful for someone
   who is not familiar with CTL in general and the translation of SmPL into
   CTL specifically.  This option implicitly sets the option {\bf
-    -show\_ctl\_text}.}
+    --show-ctl-text}.}
 
-\rare{-graphical\_trace}{Create a pdf file containing the control flow
+\rare{--graphical-trace}{Create a pdf file containing the control flow
   graph annotated with the various nodes matched during the CTL matching
   process.  Unfortunately, except for the most simple examples, the output
   is voluminous, and so the option is not really practical for most
   examples.  This requires {\tt dot} (http://www.graphviz.org/) and {\tt
   pdftk}.}
 
-\rare{-gt\_without\_label}{The same as {\bf -graphical\_trace}, but the PDF
+\rare{--gt-without-label}{The same as {\bf --graphical-trace}, but the PDF
   file does not contain the CTL code.}
 
-\rare{-partial\_match}{
+\rare{--partial-match}{
 Report partial matches of the semantic patch on the C file.  This can
   be substantially slower than normal matching.}
 
-\rare{-verbose\_match}{
+\rare{--verbose-match}{
 Report on when CTL matching is not applied to a function or other program
 unit because it does not contain some required atomic pattern.
 This can be viewed as a simpler, more efficient, but less informative
-version of {\bf -partial\_match}.}
+version of {\bf --partial-match}.}
 
 \subsection{Actions during the application of the semantic patch}
 
@@ -384,13 +429,13 @@ version of {\bf -partial\_match}.}
   identifier metavariable can be designated as being virtual by giving it
   the rule name {\tt virtual}.  An example is in demos/vm.coci}
 
-\rare{-allow\_inconsistent\_paths}{Normally, a term that is transformed
+\rare{--allow-inconsistent-paths}{Normally, a term that is transformed
   should only be accessible from other terms that are matched by the
   semantic patch.  This option removes this constraint.  Doing so, is
   unsafe, however, because the properties that hold along the matched path
   might not hold at all along the unmatched path.}
 
-\rare{-disallow\_nested\_exps}{In an expression that contains repeated
+\rare{--disallow-nested-exps}{In an expression that contains repeated
   nested subterms, {\em e.g.} of the form {\tt f(f(x))}, a pattern can
   match a single expression in multiple ways, some nested inside others.
   This option causes the matching process to stop immediately at the
@@ -398,80 +443,93 @@ version of {\bf -partial\_match}.}
   that the pattern {\tt f(E)}, with metavariable {\tt E}, matches with {\tt
     E} as {\tt x} will not be considered.}
 
-\rare{-no\_safe\_expressions}{normally, we check that an expression does
+\rare{--no-safe-expressions}{normally, we check that an expression does
        not match something earlier in the disjunction.  But for large
        disjunctions, this can result in a very big CTL formula.  So this
        option give the user the option to say he doesn't want this feature,
        if that is the case.}
 
-\rare{-pyoutput coccilib.output.Gtk, -pyoutput coccilib.output.Console}{
+\rare{--pyoutput coccilib.output.Gtk, --pyoutput coccilib.output.Console}{
 This controls whether Python output is sent to Gtk or to the console.  {\bf
-  -pyoutput coccilib.output.Console} is the default.  The Gtk option is
+  --pyoutput coccilib.output.Console} is the default.  The Gtk option is
 currently not well supported.}
 
-\developer{-loop}{When there is ``{\tt{\ldots}}'' in the semantic patch,
+\developer{--loop}{When there is ``{\tt{\ldots}}'' in the semantic patch,
   the CTL operator {\sf AU} is used if the current function does not
   contain a loop, and {\sf AW} may be used if it does.  This option causes
   {\sf AW} always to be used.}
 
-\developer{-steps $\langle$int$\rangle$}{
+\rare{--ocaml-regexps}{Use the regular expressions provided by the OCaml
+  \texttt{Str} library.  This is the default if the PCRE library is not
+  available.  Otherwise PCRE regular expressions are used by default.}
+
+\developer{--steps $\langle$int$\rangle$}{
 This limits the number of steps performed by the CTL engine to the
 specified number.  This option is unsafe as it might cause a rule to fail
 due to running out of steps rather than due to not matching.}
 
-\developer{-bench $\langle$int$\rangle$}{This collects various information
+\developer{--bench $\langle$int$\rangle$}{This collects various information
   about the operations performed during the CTL matching process.}
 
-\developer{-popl, -popl\_mark\_all, -popl\_keep\_all\_wits}{
-These options use a simplified version of the SmPL language.  {\bf
-  -popl\_mark\_all} and {\bf -popl\_keep\_all\_wits} implicitly set {\bf
-  -popl}.}
+% \developer{--popl, --popl-mark-all, --popl-keep-all-wits}{
+% These options use a simplified version of the SmPL language.  {\bf
+%   --popl-mark-all} and {\bf --popl-keep-all-wits} implicitly set {\bf
+%   --popl}.}
 
 \section{Generation of the result}
 
-Normally, the only output is a diff printed to standard output.
+Normally, the only output is a diff printed to standard output, containing
+the differences between the original code and the transformed code.  If
+stars are used in column 0 rather than {\tt -} and {\tt +}, then the {\tt
+  -} lines in the diff are the lines that matched the stars.
 
-\normal{-keep\_comments}{Don't remove comments adjacent to removed code.}
+\normal{--keep-comments}{Don't remove comments adjacent to removed code.}
 
-\normal{-linux\_spacing, -smpl\_spacing}{Control the spacing within the code
-  added by the semantic patch.  The option {\bf -linux\_spacing} causes
+\normal{--linux-spacing, --smpl-spacing}{Control the spacing within the code
+  added by the semantic patch.  The option {\bf --linux-spacing} causes
   spatch to follow the conventions of Linux, regardless of the spacing in
   the semantic patch.  This is the default.  The option {\bf
-  -smpl\_spacing} causes spatch to follow the spacing given in the semantic
+  --smpl-spacing} causes spatch to follow the spacing given in the semantic
   patch, within individual lines.}
 
-\rare{-o $\langle$file$\rangle$}{ The output file.}
+\rare{-o $\langle$file$\rangle$}{ This causes the transformed code to be
+  placed in the file {\tt file}.  A diff is still printed to the standard
+  output.  This option only makes sense when {\tt -} and {\tt +} are used.}
 
-\rare{-in\_place}{ Modify the input file.  By default, the input file is
-  overwritten, with no backup.}
+\rare{--in-place}{ Modify the input file to contain the transformed code.
+  A diff is still printed to the standard output.  By default, the input
+  file is overwritten when using this option, with no backup.  This option
+  only makes sense when {\tt -} and {\tt +} are used.}
 
-\rare{-backup\_suffix}{The suffix of the file to use in making a backup of
+\rare{--backup-suffix}{The suffix of the file to use in making a backup of
   the original file(s).  This suffix should include the leading ``.'', if
   one is desired.  This option only has an effect when the option
-  {\tt -in\_place} is also used.}
+  {\tt --in-place} is also used.}
 
-\rare{-out\_place}{ Store modifications in a .cocci\_res file.}
+\rare{--out-place}{ Store the result of modifying the code in a .cocci-res
+  file.  A diff is still printed to the standard output.  This option only
+  makes sense when {\tt -} and {\tt +} are used.}
 
-\rare{-no\_show\_diff}{ Normally, a diff between the original and transformed
+\rare{--no-show-diff}{ Normally, a diff between the original and transformed
 code is printed on the standard output.  This option causes this not to be
 done.}
 
 \rare{-U}{ Set number of diff context lines.}
 
-\rare{-patch $\langle$path$\rangle$}{The prefix of the pathname of the
+\rare{--patch $\langle$path$\rangle$}{The prefix of the pathname of the
   directory or file name that should dropped from the diff line in the
   generated patch.  This is useful if you want to apply a patch only to a
   subdirectory of a source code tree but want to create a patch that can be
   applied at the root of the source code tree.  An example could be {\tt
-  spatch -sp\_file foo.cocci -dir /var/linuxes/linux-next/drivers -patch
+  spatch --sp-file foo.cocci --dir /var/linuxes/linux-next/drivers --patch
   /var/linuxes/linux-next}.  A trailing {\tt /} is permitted on the
   directory name and has no impact on the result.}
 
-\rare{-save\_tmp\_files}{Coccinelle creates some temporary
+\rare{--save-tmp-files}{Coccinelle creates some temporary
   files in {\tt /tmp} that it deletes after use.  This option causes these
   files to be saved.}
 
-\developer{-debug\_unparsing}{Show some debugging information about the
+\developer{--debug-unparsing}{Show some debugging information about the
   generation of the transformed code.  This has the side-effect of
   deleting the transformed code.}
 
@@ -480,51 +538,52 @@ done.}
 
 \subsection{Version information}
 
-\normal{-version}{ The version of Coccinelle.  No other options are
+\normal{--version}{ The version of Coccinelle.  No other options are
 allowed.}
 
-\normal{-date}{ The date of the current version of Coccinelle. No other
+\normal{--date}{ The date of the current version of Coccinelle. No other
 options are allowed.}
 
 \subsection{Help}
 
-\minimum{-h, -shorthelp}{ The most useful commands.}
+\minimum{--h, --shorthelp}{ The most useful commands.}
 
-\minimum{-help, --help, -longhelp}{ A complete listing of the available
+\minimum{--help, --help, --longhelp}{ A complete listing of the available
 commands.}
 
 \subsection{Controlling the execution of Coccinelle}
 
-\normal{-timeout $\langle$int$\rangle$}{ The maximum time in seconds for
+\normal{--timeout $\langle$int$\rangle$}{ The maximum time in seconds for
   processing a single file.}
 
-\rare{-max $\langle$int$\rangle$}{This option informs Coccinelle of the
+\rare{--max $\langle$int$\rangle$}{This option informs Coccinelle of the
   number of instances of Coccinelle that will be run concurrently.  This
-  option requires {\bf -index}.  It is usually used with {\bf -dir}.}
+  option requires {\bf --index}.  It is usually used with {\bf --dir}.}
 
-\rare{-index $\langle$int$\rangle$}{This option informs Coccinelle of
+\rare{--index $\langle$int$\rangle$}{This option informs Coccinelle of
   which of the concurrent instances is the current one.  This option
-  requires {\bf -max}.}
+  requires {\bf --max}.}
 
-\rare{-mod\_distrib}{When multiple instances of Coccinelle are run in
+\rare{--mod-distrib}{When multiple instances of Coccinelle are run in
   parallel, normally the first instance processes the first $n$ files, the
   second instance the second $n$ files, etc.  With this option, the files
   are distributed among the instances in a round-robin fashion.}
 
-\developer{-debugger}{Option for running Coccinelle from within the OCaml
+\developer{--debugger}{Option for running Coccinelle from within the OCaml
   debugger.}
 
-\developer{-profile}{ Gather timing information about the main Coccinelle
+\developer{--profile}{ Gather timing information about the main Coccinelle
 functions.}
 
-\developer{-disable\_once}{Print various warning messages every time some
+\developer{--disable-once}{Print various warning messages every time some
 condition occurs, rather than only once.}
 
 \subsection{Miscellaneous}
 
-\rare{-quiet}{Suppress most output.  This is the default.}
+\rare{--quiet}{Suppress most output.  This is the default.}
 
-\developer{-pad, -hrule $\langle$dir$\rangle$, -xxx, -l1}{}
+%\developer{--pad, -hrule $\langle$dir$\rangle$, -xxx, -l1}{}
+\developer{--pad, --xxx, --l1}{}
 
 
 %%% Local Variables:
