11506 smatch resync

          --- old/usr/src/tools/smatch/src/Documentation/sparse-README.txt
          +++ new/usr/src/tools/smatch/src/Documentation/sparse-README.txt
   1    1  
   2      -  sparse (spärs), adj,., spars-er, spars-est.
        2 +  sparse (spärs), adj,., spars-er, spars-est.
   3    3          1. thinly scattered or distributed; "a sparse population"
   4    4          2. thin; not thick or dense: "sparse hair"
   5    5          3. scanty; meager.
   6    6          4. semantic parse
   7    7          [ from Latin: spars(us) scattered, past participle of
   8    8            spargere 'to sparge' ]
   9    9  
  10   10          Antonym: abundant
  11   11  
  12   12  Sparse is a semantic parser of source files: it's neither a compiler

  13   13  (although it could be used as a front-end for one) nor is it a
  14   14  preprocessor (although it contains as a part of it a preprocessing
  15   15  phase). 
  16   16  
  17   17  It is meant to be a small - and simple - library.  Scanty and meager,
  18   18  and partly because of that easy to use.  It has one mission in life:
  19   19  create a semantic parse tree for some arbitrary user for further
  20   20  analysis.  It's not a tokenizer, nor is it some generic context-free
  21   21  parser.  In fact, context (semantics) is what it's all about - figuring
  22   22  out not just what the grouping of tokens are, but what the _types_ are
  23   23  that the grouping implies.
  24   24  
  25   25  And no, it doesn't use lex and yacc (or flex and bison).  In my personal
  26   26  opinion, the result of using lex/yacc tends to end up just having to
  27   27  fight the assumptions the tools make. 
  28   28  
  29   29  The parsing is done in five phases:
  30   30  
  31   31   - full-file tokenization
  32   32   - pre-processing (which can cause another tokenization phase of another
  33   33     file)
  34   34   - semantic parsing.
  35   35   - lazy type evaluation
  36   36   - inline function expansion and tree simplification
  37   37  
  38   38  Note the "full file" part. Partly for efficiency, but mostly for ease of
  39   39  use, there are no "partial results". The library completely parses one
  40   40  whole source file, and builds up the _complete_ parse tree in memory.
  41   41  
  42   42  Also note the "lazy" in the type evaluation.  The semantic parsing
  43   43  itself will know which symbols are typedefines (required for parsing C
  44   44  correctly), but it will not have calculated what the details of the
  45   45  different types are.  That will be done only on demand, as the back-end
  46   46  requires the information. 
  47   47  
  48   48  This means that a user of the library will literally just need to do
  49   49  
  50   50    struct string_list *filelist = NULL;
  51   51    char *file;
  52   52  
  53   53    action(sparse_initialize(argc, argv, filelist));
  54   54  
  55   55    FOR_EACH_PTR_NOTAG(filelist, file) {
  56   56      action(sparse(file));
  57   57    } END_FOR_EACH_PTR_NOTAG(file);
  58   58  
  59   59  and he is now done - having a full C parse of the file he opened.  The
  60   60  library doesn't need any more setup, and once done does not impose any
  61   61  more requirements.  The user is free to do whatever he wants with the
  62   62  parse tree that got built up, and needs not worry about the library ever
  63   63  again.  There is no extra state, there are no parser callbacks, there is
  64   64  only the parse tree that is described by the header files. The action
  65   65  funtion takes a pointer to a symbol_list and does whatever it likes with it.
  66   66  
  67   67  The library also contains (as an example user) a few clients that do the
  68   68  preprocessing, parsing and type evaluation and just print out the
  69   69  results.  These clients were done to verify and debug the library, and
  70   70  also as trivial examples of what you can do with the parse tree once it
  71   71  is formed, so that users can see how the tree is organized. 

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX