***************************************************************************

         A GILDAS database to navigate through the sources
	              (J.Pety, 12-oct-2004)

***************************************************************************

I Global description
--------------------

     A "tags table" is a description of how a multi-file program is broken
  up into files.  It lists the names of the component files and the names
  and positions of the functions (or other named subunits) in each file.
  Grouping the related files makes it possible to search or replace through
  all the files with one command.  Recording the function names and
  positions makes possible the command which finds the definition of a
  function by looking up which of the files it is in.

     Tags tables are stored in files called "tags table files".  The
  conventional name for a tags table file is `TAGS'.

     Each entry in the tags table records the name of one tag, the name
  of the file that the tag is defined in (implicitly), and the position
  in that file of the tag's definition.

     Just what names from the described files are recorded in the tags
  table depends on the programming language of the described file.  They
  normally include all functions and subroutines, and may also include
  global variables, data types, and anything else convenient.  Each name
  recorded is called a "tag".

II How to produce a good global database for GILDAS
---------------------------------------------------

o Through the GILDAS makefile system:

    prompt-shell> gag -s dev     # Load GILDAS compilation environment
    prompt-shell> cd $gagsrcdir  # Go to the GILDAS root directory of the source tree
    prompt-shell> make tags      # Make the tags file

    The three previous lines will create a global GILDAS database named
    $gagsrcdir/TAGS.

    prompt-shell> gag -s dev     # Load GILDAS compilation environment
    prompt-shell> go class       # Go to the root directory of the CLASS package
    prompt-shell> make tags      # Make the tags file

    The three previous lines will create a database dedicated to CLASS.

o Frequency:

    It is useful to update the TAGS database only once in a while when you
    see that the database is highly unsynchronized. Indeed, most of GILDAS
    code is seldom modified.

o Commands:

    If you want to achieve the same results manually, just type:

    prompt-shell> cd $gagsrcdir
    prompt-shell> ctags -e -R --langmap=fortran:.inc.incpp.f.fpp.f90.f90pp --fortran-types=-l --totals=yes .

o Quick explanations:

    -e 
         Makes an output TAGS file in format compatible with emacs (else
         the format is compatible with vi and derivatives)

    -R
          Recursively search through the directory tree

    --langmap=fortran:.inc.incpp.f.fpp.f90.f90pp
          Associates the ".inc.incpp.f.fpp.f90.f90pp" list of file
          extensions to the FORTRAN language (not done by default)

    --fortran-types=-l 

          Do NOT tag labels (halve the number of TAG in GILDAS).  You can
          selectively tags the following FORTRAN feature (- is off and + is
          on)
		b block data 
		c common blocks 
		e entry points 
		f functions 
		i interfaces 
		k type components
		l labels 
		L local and common block variables [off]
		m modules 
		n namelists 
		p programs 
		s subroutines 
		t derived types 
		v module variables

    --file-tags=yes 
          Tag the file names (useful to automatically goes to the include
          files when you do not know the name of the searched common)

    --totals=yes 
          Produce statistics as follows for GILDAS (as of 12.10.04)

	         1635 files, 1075158 lines (36441 kB) scanned in 6.2 seconds
		 (5887 kB/s) 45052 tags added to tag file

          You can see that producing the database is a question of second
          on my AMD 1.5 GHz PC.

o Others interesting options

    -L - 
         ctags will use standard input to define files. Can be used with
         find (not obvious whether this can be useful). For example:

         find . \( -name "*.[cf]" -o -name "*.inc" -o -name "*.f90" \) -print | ctags -e -L -

    -x 
         Makes a human readable ouput if you want a global or local view of
         your project.

    --links=yes|no 
         Indicates whether symbolic link should be followed.

    and many more information at http://ctags.sourceforge.net/

o Alternative:

    ctags is installed by default on our linux RedHat version (7.3). If
    ctags is not installed on your system, you can use etags which is
    always bundle with the emacs package (i.e. if emacs is installed, etags
    is also installed). You then can achieve a similar result as above
    with:

    prompt-shell> cd $gagsrcdir
    prompt-shell> find . \( -name '*.[chf]' -o -name '*.f90' -o -name '*.fpp' -o -name '*.f90pp' \) -print | etags --ignore-indentation --output=./TAGS -
    prompt-shell> find . \( -name "*.inc" -o -name '*.incpp' \)  -print | etags --ignore-indentation --language=fortran --append --output=./TAGS -

    However this is less flexible than ctags... Just in case, the "make
    etags" command will execute those commands instead of the "ctags" one.

III How to use the database in emacs
------------------------------------

  Emacs will, by default, expect a tag file by the name "TAGS" in the
  current directory. Once the tag file is built, the following commands
  exercise the tag indexing feature:

  M-x visit-tags-table <RET> FILE <RET> 
        Select the tag file, "FILE", to use. 
  M-. [TAG] <RET> 
        Find the first definition of TAG. The default tag is the identifier
        under the cursor. Usual emacs completion works based on the content
        of the database.
  M-* Pop back to where you previously invoked "M-.". 
  C-u M-. 
        Find the next definition for the last defined tag (if the same name
        is define several times). 
  M-x tags-search <RET> REGEXP <RET>
        Search through all files listed in tags table for match for REGEXP
        (in first approximation, part of a string in Emacs language).
        Stops when a match is found.  To continue searching for next match,
        use command M-,.
  M-x tags-query-replace <RET> FROM <RET> TO <RET>
        Query-replace-regexp FROM with TO through all files listed in tags
        table.  If you exit (C-g or ESC), you can resume the query-replace
        with the command M-,.
  M-x tags-apropos <RET> REGEXP <RET>
        Display list of all tags in tags table REGEXP matches.

  For example, if you are searching for the main entry point of mapping,
  you can do:

  M-x tags-apropos <RET> main <RET>

      Tags matching regexp `SIC_KE':

      ENTRY SIC_KE(
      SUBROUTINE SIC_KEYW 
      COMMON_EXE = sic_keyboard sic_spy gtv_xwindow
      kernel/libexec/sic_keyboard.c,574

  M-. SIC_KE <RET>

      And you directly end up into the file "argumexp.fpp" in the following
      directory "$gagsrcdir/kernel/lib/sic/". Who would have guessed it?

  For more commands, see the Tags topic in the Emacs info document
  (C-h i m emacs <RET> m tags <RET>).

***************************************************************************
