[CEDET-devel] request for ede and semantic document clarifications

[Richard K. <em...@gm...>]

I would like to ask some questions by way of a diff against the texinfo
files. 

One suggested change to explain "/include" syntax is also included.
I used 20 line context by specifying "-U 20" hoping that that would
provide sufficient context to orient the readers properly.

Can someone answer my questions?
Thanks.



$ bzr diff --diff-opt='-U 20'
=== modified file 'ede/ede.texi'
--- ede/ede.texi	2010-07-25 14:12:32 +0000
+++ ede/ede.texi	2010-09-07 04:03:55 +0000
@@ -569,58 +569,86 @@
 @code{ede-cpp-root-project} and add your own tweaks in just a few
 lines.  See the end of this file for an example.

 In the most basic case, add this to your @file{.emacs} file, modifying
 appropriate bits as needed.

 @example
 (ede-cpp-root-project "SOMENAME" :file "/dir/to/some/file")
 @end example

 Replace @var{SOMENAME} with whatever name you want, and the filename
 to an actual file at the root of your project.  It might be a
 Makefile, a README file.  Whatever.  It doesn't matter.  It's just a
 key to hang the rest of @ede{} off of.

 The most likely reason to create this project, is to speed up
 searching for includes files, or to simplify bootstrapping @semantic{}'s
 ability to find files without much user interaction.  In conjunction
 with @semantic{} completion, having a short include path is key.  You can
 override the default include path and system include path like this:
+@c What is the ``default include path''?

 @example
 (ede-cpp-root-project "NAME" :file "FILENAME"
     :include-path '( "/include" "../include" "/c/include" )
     :system-include-path '( "/usr/include/c++/3.2.2/" )
     :spp-table '( ("MOOSE" . "")
                   ("CONST" . "const") ) )
 @end example

  In this case each item in the include path list is searched.  If the
-directory starts with "/", then that expands to the project root
-directory.  If a directory does not start with "/", then it is
-relative to the default-directory of the current buffer when the file
+directory starts with "/", it does not mean start of absolute path.
+Instead it means ``relative to the project root
+directory'', i.e., ``/include'' means ``include'' subdirectory of the
+project root directory.  If a directory does not start with "/", then it is
+relative to the @var{default-directory} of the current buffer when the file
 name is expanded.

  The include path only affects C/C++ header files.  Use the slot
 @code{:header-match-regexp} to change it.

+@c I can guess that directories listed in :include-path are searched for files
+@c whose name matches the regexp specified by :header-match-regexp.
+@c What is the significance of the match?  For gcc we know what it means to
+@c add -I/a/b/c.  For gcc you never have to worry about other implementation
+@c files when you are compiling a file; you only care about relevant header
+@c files.  For EDE and semantic however that is not the case or so it seems to
+@c me.  We care about 
+@c header and implementation files equally since we are looking for symbols of
+@c interest for semantic wherever they may be.  So what does it mean to be part of
+@c :include-path?  Does it mean that clicking on lines with #include will do
+@c the ``right thing'' whatever that means?
+@c
+@c If I just want to tell semantic that all files in this and that directories
+@c are part of the same project and all C/C++ files in those directories
+@c (whether or not they are header or implementation files) are to be included
+@c when I execute command such as semantic-complete-jump, then how do I do
+@c that?  I don't understand why one would ever want to distinguish between
+@c header and implementation files for semantic other than dealing with
+@c #include tags.
+@c
+@c If a project has deep subdirectory hierarchy, then it would be awkward to
+@c have to list all the subdirectories with :include-path.
+@c Is there a way to tell EDE to use a directory and all subdirectories
+@c under it going down recursively?
+
 The @code{:system-include-path} allows you to specify full directory
 names to include directories where system header files can be found.
 These will be applied to files in this project only.

 The @code{:spp-table} provides a list of project specific #define
 style macros that are unique to this project, passed in to the
 compiler on the command line, or are in special headers.
 See the @code{semantic-lex-c-preprocessor-symbol-map} for more
 on how to format this entry.

 If there is a single file in your project, you can instead set the
 @code{:spp-files} to a list of file names relative to the root of your
 project.  Specifying this is like setting the variable
 @code{semantic-lex-c-preprocessor-symbol-file} in semantic.

 If you want to override the file-finding tool with your own
 function you can do this:

 @example
 (ede-cpp-root-project "NAME" :file "FILENAME" :locate-fcn 'MYFCN)

=== modified file 'semantic/doc/user-guide.texi'
--- semantic/doc/user-guide.texi	2010-06-13 01:19:18 +0000
+++ semantic/doc/user-guide.texi	2010-09-07 04:15:29 +0000
@@ -1794,40 +1794,44 @@
   You can test the interruptibility framework by running
 @kbd{M-x semantic-test-throw-on-input RET} and seeing that you can
 press any key to break out of the loop.

 @section Incremental parsing

 The incremental parser used by semantic will reparse only small
 sections of a file you have edited, which eliminates the need to
 reparse entire files.  This speeds up minor modes that need the local
 buffer to be up to date, such as speedbar or ECB.

 If the incremental parsing is not always working for you (meaning it
 will parse the whole file frequently while you edit) then perhaps you
 need to customize @code{semantic-edits-verbose-flag} to enable some
 friendly debug output.  Additionally using
 @code{semantic-load-enable-semantic-debugging-helpers} to help
 identify possible problem areas by enabling highlight edits mode and
 show parser state mode 
 @inforef{Incremental Parser Debugging, ,semantic-langdev.info}

+@c This is all good, but what if I want the other extreme where I want all
+@c files in the project (regardless which directory they are in) to be parsed
+@c that have not yet been parsed?  Is there a command for it?
+
 @section Profiling

 To help identify speed issues with the @semantic{} analyzer, you can
 use the @file{semantic-elp.el} tool.  To use it type:

 @example
 M-x semantic-elp-analyze RET
 @end example

 It will do a full run for each stage of analysis keeping profiling
 information.  The analysis will be done at point, so be sure to
 position the cursor at the location where the slowdown occurs.

 Once done, it will ask you to save the profiler information.  It will
 then show you the profile information in ADEBUG mode, so you can
 navigate through the results.

 Use @kbd{SPC} to open sections of the tree.  Use @kbd{SPC} on the sort
 option to change sorting of the results table.


$