1 This is semantic-user.info, produced by makeinfo version 5.2 from
4 This is the Semantic User's Manual
6 Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Eric
7 M. Ludlam Copyright (C) 2001, 2002, 2003, 2004 David Ponce Copyright (C)
8 2002, 2003 Richard Y. Kim
10 Permission is granted to copy, distribute and/or modify this
11 document under the terms of the GNU Free Documentation License,
12 Version 1.1 or any later version published by the Free Software
13 Foundation; with the Invariant Sections being list their titles,
14 with the Front-Cover Texts being list, and with the Back-Cover
15 Texts being list. A copy of the license is included in the section
16 entitled "GNU Free Documentation License".
17 INFO-DIR-SECTION Emacs
19 * Semantic User's guide: (semantic-user).
22 This is the Semantic User's Guide _Infrastructure for parser based
23 text analysis in Emacs_
25 Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004 Eric M. Ludlam,
26 David Ponce, and Richard Y. Kim
29 File: semantic-user.info, Node: Top, Next: speedbar, Up: (dir)
34 This chapter describes how to use applications enabled by semantic.
35 Many of these come with semantic, but others are distributed apart from
40 * speedbar:: How to use Semantic speedbar support
41 * ECB:: Emacs Code Browser
42 * imenu:: Special support for Imenu.
43 * senator:: The Semantic Navigator
44 * Analyzer:: Analyze local context
45 * Class Browser:: Class hierarchy browser
46 * Document:: Document generation functions
47 * Charts:: Charting code statistics
48 * Idle Scheduler:: The idle Scheduler and related modes
49 * Minor Modes:: Useful minor modes
50 * semanticdb:: Cache your parsed buffers between sessions.
51 * Speed Debug:: How to debug speed issues.
53 * GNU Free Documentation License::
57 File: semantic-user.info, Node: speedbar, Next: ECB, Prev: Top, Up: Top
62 Speedbar supports the display of tags through the Semantic parser. To
63 use this utility, add a line like this to your '.emacs' file:
65 (add-hook 'speedbar-load-hook (lambda () (require 'semantic-sb)))
67 or you can simply add:
69 (require 'semantic-sb)
71 Once installed, speedbar will use semantic to find tags, and will
72 display them appropriately. Tags from semantic will have additional
73 details which can be seen, such as return type, or arguments to
76 If you use 'semantic-load.el', you do not need to add the above lines in
79 Two additional speedbar modes are described in *note Speedbar
80 Analysis::, and *note Class Browser::.
83 File: semantic-user.info, Node: ECB, Next: imenu, Prev: speedbar, Up: Top
88 From the ECB Website: <http://ecb.sourceforge.net>:
90 ECB is a source code browser for Emacs. It is a global minor-mode
91 which displays a couple of windows that can be used to browse
92 directories, files and file-contents like methods and variables.
95 File: semantic-user.info, Node: imenu, Next: senator, Prev: ECB, Up: Top
100 There is special support for creating Imenu entries using semantic.
101 This is a highly customizable tool which can create specialized menu
102 systems for navigating your source file.
104 By default, each language that wants special imenu support will set
105 itself up for it. To setup imenu for your buffers, use this command in
108 (add-hook 'semantic-init-hooks (lambda ()
109 (imenu-add-to-menubar "TAGS")))
111 Also supported is "which-func-mode". This usually uses imenu tags to
112 show the current function. The semantic support for this function uses
113 overlays, which is much faster.
115 If you use 'semantic-load.el', you do not need to add the above lines in
118 You can customize imenu with the following options:
120 -- Option: semantic-imenu-summary-function
121 Function to use when creating items in Imenu. Some useful
122 functions are found in 'semantic-format-tag-functions'.
124 -- Option: semantic-imenu-bucketize-file
125 Non-'nil' if tags in a file are to be grouped into buckets.
127 -- Option: semantic-imenu-buckets-to-submenu
128 Non-'nil' if buckets of tags are to be turned into submenus. This
129 option is ignored if 'semantic-imenu-bucketize-file' is nil.
131 -- Option: semantic-imenu-expand-type-members
132 Non-'nil' if types should have submenus with members in them.
134 -- Option: semantic-imenu-bucketize-type-members
135 Non-'nil' if members of a type should be grouped into buckets.
136 'nil' means to keep them in the same order. Overriden to 'nil' if
137 'semantic-imenu-bucketize-file' is nil.
139 -- Option: semantic-imenu-sort-bucket-function
140 Function to use when sorting tags in the buckets of functions. See
141 "semantic-bucketize" and the FILTER argument for more details on
144 -- Option: semantic-imenu-index-directory
145 Non 'nil' to index the entire directory for tags. Doesn't actually
146 parse the entire directory, but displays tags for all files
147 currently listed in the current Semantic database. This variable
148 has no meaning if semanticdb is not active.
150 -- Option: semantic-imenu-auto-rebuild-directory-indexes
151 If non-'nil' automatically rebuild directory index imenus. That is
152 when a directory index imenu is updated, automatically rebuild
153 other buffer local ones based on the same semanticdb.
155 When adding support to a language, this variable may need to be set:
157 -- Variable: semantic-imenu-expandable-tag-classes
158 List of expandable tag classes. Tags of those classes will be
159 given submenu with children. By default, a 'type' has interesting
160 children. In Texinfo, however, a 'section' has interesting
164 File: semantic-user.info, Node: senator, Next: Analyzer, Prev: imenu, Up: Top
169 Senator stands for SEmantic NAvigaTOR and was written by David Ponce.
171 This library defines commands and a minor mode to navigate and manage
172 semantic language tags in the current buffer.
177 The following user level commands are provided by Senator.
182 -- Function: senator-next-tag
183 Navigate to the next Semantic tag. Return the tag or 'nil' if at
186 -- Function: senator-previous-tag
187 Navigate to the previous Semantic tag. Return the tag or 'nil' if
188 at beginning of buffer.
190 -- Function: senator-jump
191 Jump to the semantic symbol SYM.
193 If optional IN-CONTEXT is non-'nil' jump in the local type's
194 context (see function "senator-current-type-context"). If optional
195 NO-DEFAULT is non-'nil' do not provide a default value.
197 When called interactively you can combine the IN-CONTEXT and
198 NO-DEFAULT switches like this:
200 - 'C-u' IN-CONTEXT. - 'C-u' - NO-DEFAULT. - 'C-u' 'C-u'
201 IN-CONTEXT + NO-DEFAULT.
206 Searching using senator mode restricts the search only to the definition
207 text, such as the name of the functions or variables in a given buffer.
209 -- Command: senator-isearch-toggle-semantic-mode
210 Toggle semantic searching on or off in isearch mode. 'C-c , i'
211 toggle semantic searching.
213 -- Command: senator-search-forward what &optional bound noerror count
214 -- Command: senator-search-backward what &optional bound noerror count
215 Search semantic tags forward or backward from point for string
216 WHAT. Set point to the end of the occurrence found, and return
217 point. See "search-forward" for details and the meaning of BOUND
218 NOERROR and COUNT. COUNT is just ignored in the current
221 -- Command: re-search-forward regex
222 -- Command: re-search-backward regex
223 Search forward and backward for a token matching the regular
226 -- Command: word-search-forward word
227 -- Command: word-search-backward word
228 Search forward and backward for a token whose name matches WORD.
233 Completion in senator scans all known definitions in the local file, and
234 uses that information to provide the completion.
236 -- Command: senator-complete-symbol &optional cycle-once
237 Complete the current symbol under point. If optional argument
238 CYCLE-ONCE is non-'nil', only cycle through the list of completions
239 once, doing nothing where there are no more matches.
241 -- Command: senator-completion-menu-popup
242 Popup a completion menu for the symbol at point. The popup menu
243 displays all of the possible completions for the symbol it was
244 invoked on. To automatically split large menus this function use
245 "imenu-mouse-menu" to handle the popup menu.
250 Token Copy/Paste is a high level form of the typical copy yank used by
251 Emacs. Copying a tag saves the meta-information related to the function
252 or item the cursor is currently in. When that information is yanked
253 into a new buffer, the form of the text created is based on the current
254 status of the programming buffer.
256 For example, pasting a function into a different file results in a
257 function call template to be inserted. In a Texinfo file, a @deffn is
258 created with documentation for that function or command.
260 -- Command: senator-copy-tag
261 Take the current tag, and place it in the tag ring.
263 -- Command: senator-kill-tag
264 Take the current tag, place it in the tag ring, and kill it.
265 Killing the tag removes the text for that tag, and places it into
266 the kill ring. Retrieve that text with 'C-y'.
268 -- Command: senator-yank-tag
269 Yank a tag from the tag ring. The form the tag takes is differnet
270 depending on where it is being yanked to.
272 -- Command: senator-copy-tag-to-register register &optional kill-flag
273 Copy the current tag into REGISTER. Optional argument KILL-FLAG
274 will delete the text of the tag to the kill ring.
276 For programmers, to provide specialized pasting, created an override
277 function for 'insert-foreign-tag' (see *note (semantic-langdev)Writing
283 -- Command: senator-minor-mode
284 Toggle the SEmantic NAvigaTOR key bindings in the current buffer.
286 The following default key bindings are provided when semantic minor
294 senator-isearch-toggle-semantic-mode
296 semantic-complete-jump-local
298 semantic-complete-jump
300 senator-complete-symbol
302 senator-completion-menu-popup
317 To enable the Senator keymap in all modes that support semantic parsing,
320 (add-hook 'semantic-init-hooks 'senator-minor-mode)
322 If you use 'semantic-load.el', you do not need to add the above lines in
325 To customize navigation around different types of tokens, use the
328 -- Option: senator-step-at-tag-classes
329 List of tag classes where to step. A tag class is a symbol like
330 ''variable', ''function', ''type', or other. If 'nil' navigation
331 steps at any tag found. This is a buffer local variable. It can
332 be set in a mode hook to get a specific langage navigation.
334 -- Option: senator-step-at-start-end-tag-classes
335 List of tag classes where to step at start and end. A tag class is
336 a symbol like ''variable', ''function', ''type', or other. If
337 'nil', navigation only step at beginning of tags. If 't', step at
338 start and end of any tag where it is allowed to step. Also,
339 stepping at start and end of a tag prevent stepping inside its
340 components. This is a buffer local variable. It can be set in a
341 mode hook to get a specific langage navigation.
343 To have a mode specific customization, do something like this in a hook:
347 (setq senator-step-at-tag-classes '(function variable))
348 (setq senator-step-at-start-end-tag-classes '(function))
351 This will cause navigation and search commands to stop only between
352 functions and variables, and to step at start and end of functions only.
355 File: semantic-user.info, Node: Analyzer, Next: Class Browser, Prev: senator, Up: Top
360 The semantic analyzer is a library tool that performs context analysis
361 and can derive useful information.
363 -- Command: semantic-analyze-current-context position
364 Analyze the current context at POSITION. If called interactively,
365 display interesting information about POSITION in a separate
366 buffer. Returns an object based on symbol
367 "semantic-analyze-context".
369 While this can be used as a command, it is mostly useful while debugging
370 the analyzer, or tools using the return value. Use the Emacs command
371 "describe-class" to learn more about using 'semantic-analyze-context'.
373 Another command that uses the analyzer context can derive a completion
376 -- Command: semantic-analyze-possible-completions context
377 Return a list of semantic tags which are possible completions.
378 CONTEXT is either a position (such as point), or a precalculated
379 context. Passing in a context is useful if the caller also needs
380 to access parts of the analysis. Completions run through the
382 Elements currently in scope
383 Constants currently in scope
384 Elements match the ':prefix' in the CONTEXT.
385 Type of the completion matches the type of the context.
386 Context type matching can identify the following:
388 Assignment into a variable of some type.
389 Argument to a function with type constraints.
390 When called interactively, displays the list of possible
391 completions in a buffer.
395 * Smart Completion:: Functions you can bind to keys for completion
396 * Smart Idle Completion:: Automatic completion popups
397 * Speedbar Analysis:: Speedbar provided completion
400 File: semantic-user.info, Node: Smart Completion, Next: Smart Idle Completion, Up: Analyzer
405 The file 'semantic-ia.el' contains two commands for performing smart
406 completion using the analysis library. Analysis to calculate these
407 completions are done through the analyzer and completion mechanism.
408 These functions just provide commands that can be bound to key bindings.
410 -- Command: semantic-ia-complete-symbol point
411 Complete the current symbol at POINT. Completion options are
412 calculated with "semantic-analyze-possible-completions".
414 -- Command: semantic-ia-complete-symbol-menu point
415 Complete the current symbol via a menu based at POINT. Completion
416 options are calculated with
417 "semantic-analyze-possible-completions".
419 -- Command: semantic-ia-complete-tip point
420 Pop up a tooltip for completion at POINT.
422 -- Command: semantic-ia-show-summary point
423 Display a summary for the symbol under POINT.
425 -- Command: semantic-ia-show-doc point
426 Display the code-level documentation for the symbol at POINT.
429 File: semantic-user.info, Node: Smart Idle Completion, Next: Speedbar Analysis, Prev: Smart Completion, Up: Analyzer
431 5.2 Smart Idle Completion
432 =========================
434 You can get smart completions or summary information to automatically
435 popup without explicity pressing a key or running a function.
437 This is accomplished through the Idle Scheduler and related features.
438 See *note Idle Scheduler:: for more on the Scheduler.
440 Summaries are provided with 'semantic-idle-summary-mode'. See *note
443 Completions are provided with 'semantic-idle-completions-mode'. See
444 *note Idle Completions Mode::.
447 File: semantic-user.info, Node: Speedbar Analysis, Prev: Smart Idle Completion, Up: Analyzer
449 5.3 Speedbar Analysis
450 =====================
452 The Analyzer output can be used through a speedbar interface. This
453 interface lists details about the analysis, such as the current
454 function, local arguments and variables, details on the prefix (the
455 symbol the cursor is on), and a list of all possible completions.
456 Completions are specified in "semantic-analyze-possible-completions"
459 Each entry can be jumped to by clicking on the name. For strongly typed
460 languages, this means you will jump to the definition of the variable,
461 slot, or type definition.
463 In addition each entry has an <i> button. Clicking on this will display
464 a summary of everything that is known about the variable or type
465 displayed on that line.
467 If you click on the name of a variable in the "Completions" menu, then
468 the text that was recently analyzed will be replaced with the name of
469 the token that was clicked on in speedbar.
471 -- Command: semantic-speedbar-analysis
472 Start Speedbar in semantic analysis mode. The analyzer displays
473 information about the current context, plus a smart list of
474 possible completions.
476 You can also enter speedbar analyzer mode by selecting "Analyze" from
477 the "Display" menu item on speedbar's menu.
480 File: semantic-user.info, Node: Class Browser, Next: Document, Prev: Analyzer, Up: Top
485 The semantic class browser is a library that can covert a project file
486 group into an object structure that contains links between structures so
487 that the inheritance links between semantic tags can be easily
490 The core to this library is one function in 'semantic-cb.el'.
492 -- Function: semantic-cb-new-class-browser
493 Create an object representing this project's organization. The
494 object returned is of type "semantic-cb-project", which contains
495 the slot ':types', a list of all top-level types. Each element is
496 a class of type "semantic-cb-token", or "semantic-cb-type".
498 Use the Emacs function "describe-class" to learn more about these
501 You can access the class inheritance structure through a speedbar
502 interface. You can choose the "Class Browser" option from Speedbar's
503 "Display" menu item, or use the following command:
505 -- Command: semantic-cb-speedbar-mode
506 Bring speedbar up, and put it into Class Browser mode. This will
507 use the Class Browser logic applied to the current Semantic project
508 database to build the available relations. The structure of the
509 class hierarchy can then be navigated using traditional speedbar
513 File: semantic-user.info, Node: Document, Next: Charts, Prev: Class Browser, Up: Top
518 The document program uses semantic tag tables to aid in the creation of
519 texinfo documentation. For example, the following is a code fragment
520 from 'document.el' that comes with semantic:
522 (defun document (&optional resetfile)
523 "Document the function or variable the cursor is in.
524 Optional argument RESETFILE is provided w/ universal argument.
525 When non-nil, query for a new documentation file."
529 While visiting 'document.el', put the cursor somewhere within the
530 function shown above. Then type 'M-x document'. After asking for the
531 texinfo file name, which in this case is 'semantic.texi', this will
532 update the texinfo documentation of the 'document' function in that
533 file. The result is that the following texinfo text will be either
534 created or updated in 'user-guide.texi' file:
536 @deffn Command document &optional resetfile
537 Document the function or variable the cursor is in.
538 Optional argument @var{RESETFILE} is provided w/ universal argument.
539 When non-@code{nil}, query for a new documentation file.
542 Note that the function name, arguments and documentation string is put
543 in the right place. Within the doc-string, the function arguments are
544 marked with the @var command and the 'nil' code fragment is marked with
545 @code command. This example provides just a glimpse of what is possible
546 with the syntactic information provided by semantic.
548 The main entry point for the documentation generator are the following
551 -- Command: document &optional resetfile
552 Document the function or variable the cursor is in. Optional
553 argument RESETFILE is provided w/ universal argument. When
554 non-'nil', query for a new documentation file.
556 -- Command: document-inline
557 Document the current function with an inline comment.
559 -- Command: document-insert-defun-comment tag buffer
560 Insert mode-comment documentation about TAG from BUFFER.
562 -- Command: document-insert-new-file-header header
563 Insert a new header file into this buffer. Add reference to
564 HEADER. Used by 'prototype' if this file doesn't have an
565 introductory comment.
567 In addition to these base documentation commands, the texinfo semantic
568 parser includes a two convenience functions when working directly with
571 -- Command: semantic-texi-update-doc &optional tag
572 Update the documentation for TAG. If the current buffer is a
573 texinfo file, then find the source doc, and update it. If the
574 current buffer is a source file, then get the documentation for
575 this item, find the existing doc in the associated manual, and
578 -- Command: semantic-texi-goto-source &optional tag
579 Jump to the source for the definition in the texinfo file TAG. If
580 TAG is 'nil', it is derived from the deffn under POINT.
583 File: semantic-user.info, Node: Charts, Next: Idle Scheduler, Prev: Document, Up: Top
588 Some commands to draw charts of statistics generated from parsing:
590 -- Command: semantic-chart-tags-by-class &optional tagtable
591 Create a bar chart representing the number of tags for a given tag
592 class. Each bar represents how many toplevel tags in TAGTABLE
593 exist with a given class. See 'semantic-symbol->name-assoc-list'
594 for tokens which will be charted. TAGTABLE is passedto
595 "semantic-something-to-tag-table".
597 -- Command: semantic-chart-database-size &optional tagtable
598 Create a bar chart representing the size of each file in
599 semanticdb. Each bar represents how many toplevel nonterminals in
600 TAGTABLE exist in each database entry. TAGTABLE is passedto
601 "semantic-something-to-tag-table".
603 -- Command: semantic-chart-tag-complexity &optional class tagtable
604 Create a bar chart representing the complexity of some tokens.
605 Complexity is calculated for tokens with a tag of CLASS. Each bar
606 represents the complexity of some nonterminal in TAGTABLE. Only
607 the most complex items are charted. TAGTABLE is passedto
608 "semantic-something-to-tag-table".
611 File: semantic-user.info, Node: Idle Scheduler, Next: Minor Modes, Prev: Charts, Up: Top
616 The Idle Scheduler in Semantic 2.0 replaces what was once Auto-Parse
617 mode. The Idle Scheduler now performs multiple duties.
619 The primary job is to schedule buffer parsing in idle time. The first
620 buffer whose cache is checked is the current buffer. After this, all
621 other buffers are checked.
623 Once that has been accomplished, sheduled idle processes that use the
624 semantic tag tables are run.
626 -- Command: global-semantic-idle-scheduler-mode &optional arg
627 Toggle global use of option "semantic-idle-scheduler-mode". The
628 idle scheduler with automatically reparse buffers in idle time, and
629 then schedule other jobs setup with "semantic-idle-scheduler-add".
630 If ARG is positive, enable, if it is negative, disable. If ARG is
633 *Compatibility*: 'global-semantic-idle-scheduler-mode' introduced
634 in semantic version 2.0 supercedes
635 'global-semantic-auto-parse-mode' which is now obsolete.
638 *Compatibility*: 'semantic-idle-scheduler-mode' introduced in semantic
639 version 2.0 supercedes 'semantic-auto-parse-mode' which is now obsolete.
641 -- Option: semantic-idle-scheduler-idle-time
642 Time in seconds of idle before scheduling events. This time should
643 be short enough to ensure that idle-scheduler will be run as soon
646 -- Option: semantic-idle-scheduler-mode-hook
647 Hook run at the end of function "semantic-idle-scheduler-mode".
649 You can add new functionality to the idle scheduler by reading the
650 Application Developers Guide *note (semantic-appdev.info)Idle
655 * Reparsing Options::
656 * Idle Summary Mode::
657 * Idle Completions Mode::
660 File: semantic-user.info, Node: Reparsing Options, Next: Idle Summary Mode, Up: Idle Scheduler
662 9.1 Reparsing Options
663 =====================
665 The Idle Scheduler will automatically reparse all buffers that need it.
666 User input at any time will cancel the operations and return to normal
669 9.1.1 Reparse Configuration
670 ---------------------------
672 -- Option: semantic-idle-scheduler-max-buffer-size
673 Maximum size in bytes of buffers automatically reparsed. If this
674 value is less than or equal to 0, buffers are automatically
675 reparsed regardless of their size.
677 9.1.2 Reparse Messages
678 ----------------------
680 -- Option: semantic-idle-scheduler-no-working-message
681 If non-'nil', disable display of working messages during parse.
683 -- Option: semantic-idle-scheduler-working-in-modeline-flag
684 Non-'nil' means show working messages in the mode line. Typically,
685 parsing will show messages in the minibuffer. This will move the
686 parse message into the modeline.
688 9.1.3 Reprasing Hooks
689 ---------------------
691 -- Variable: semantic-before-idle-scheduler-reparse-hooks
692 Hooks run before option 'semantic-idle-scheduler' begins parsing.
693 If any hook throws an error, this variable is reset to nil. This
694 hook is not protected from lexical errors.
696 -- Variable: semantic-after-idle-scheduler-reparse-hooks
697 Hooks run after option 'semantic-idle-scheduler' has parsed. If
698 any hook throws an error, this variable is reset to nil. This hook
699 is not protected from lexical errors.
702 File: semantic-user.info, Node: Idle Summary Mode, Next: Idle Completions Mode, Prev: Reparsing Options, Up: Idle Scheduler
704 9.2 Idle Summary Mode
705 =====================
707 A summary describes a tag in a useful way. These can be displayed for
708 the lexical token under the cursor in idle time using this mode.
710 -- semantic-idle-summary-mode: &optional arg
711 Display a tag summary of the lexical token under the cursor. This
712 means for getting the current tag to display information can be
713 overriden with 'idle-summary-current-symbol-info'. This is a minor
714 mode which performs actions during idle time. With prefix argument
715 ARG, turn on if positive, otherwise off. The minor mode can be
716 turned on only if semantic feature is available and the current
717 buffer was set up for parsing. Return non-nil if the minor mode is
721 *Compatibility*: 'semantic-idle-summary-mode' introduced in semantic
722 version 2.0 supercedes 'semantic-summary-mode' which is now obsolete.
724 -- Option: semantic-idle-summary-function
725 Function to use when displaying tag information during idle time.
726 Some useful functions are found in 'semantic-format-tag-functions'.
729 File: semantic-user.info, Node: Idle Completions Mode, Prev: Idle Summary Mode, Up: Idle Scheduler
731 9.3 Idle Completions Mode
732 =========================
734 The definition of completion lists is described in the Analyzer section
737 The Idle Completions mode will calculate the list of possible
738 completions in idle time, and display them in a popup list, and also
739 highlight the symbol that needs completion.
741 -- semantic-idle-completions-mode: &optional arg
742 Display a tooltip with a list of possible completions near the
743 cursor. There is no convenience for performing a completion
744 replacement. For that you should bind
745 'semantic-ia-complete-symbol'. This is a minor mode which performs
746 actions during idle time. With prefix argument ARG, turn on if
747 positive, otherwise off. The minor mode can be turned on only if
748 semantic feature is available and the current buffer was set up for
749 parsing. Return non-nil if the minor mode is enabled
751 This mode operates by using the command
752 'semantic-complete-inline-analyzer'.
755 File: semantic-user.info, Node: Minor Modes, Next: semanticdb, Prev: Idle Scheduler, Up: Top
760 Semantic comes with a wide range of minor-modes which use various
761 features of semantic. These modes vary widly in utility.
763 There are some core modes that are required for smooth operations. Some
764 of these are discussed in other chapters, such as *note Idle
765 Scheduler::, and *note semanticdb::
769 * Code Helpers:: Modes for assisting in authoring code.
770 * Development Modes:: Modes for assisting in developing/debugging Semantic.
773 File: semantic-user.info, Node: Code Helpers, Next: Development Modes, Prev: Minor Modes, Up: Minor Modes
778 Code Helpers are minor modes that augment basic Emacs behavior in ways
779 that can assist in programming Semantic supported langauges.
783 * Sticky Function Mode::
784 * Tag Decoration Mode::
785 * MRU Bookmarks Mode::
787 Senator is another mode which can assist in programming *note senator::.
790 File: semantic-user.info, Node: Development Modes, Prev: Code Helpers, Up: Minor Modes
792 10.2 Development Modes
793 ======================
797 * Highlight Edits Mode::
799 * Unmatched Syntax Highlighting::
802 File: semantic-user.info, Node: Sticky Function Mode, Next: Tag Decoration Mode, Prev: Code Helpers, Up: Code Helpers
804 10.2.1 Sticky Function Headers
805 ------------------------------
807 -- Command: semantic-stickyfunc-mode &optional arg
808 Minor mode to show the title of a tag in the header line.
809 Enables/disables making the header line of functions sticky. A
810 function (or other tag class specified by
811 'semantic-stickyfunc-sticky-classes') has a header line, meaning
812 the first line which describes the rest of the construct. This
813 first line is what is displayed in the Emacs 21 header line.
815 With prefix argument ARG, turn on if positive, otherwise off. The
816 minor mode can be turned on only if semantic feature is available
817 and the current buffer was set up for parsing. Return non-'nil' if
818 the minor mode is enabled.
820 -- Variable: semantic-stickyfunc-sticky-classes
821 List of tag classes which sticky func will display in the header
825 File: semantic-user.info, Node: Tag Decoration Mode, Next: MRU Bookmarks Mode, Prev: Sticky Function Mode, Up: Code Helpers
827 10.2.2 Tag Decoration Mode
828 --------------------------
830 Decoration mode is a harness that allows any parsed tag to be
831 highlighted based on some arbitrary feature of that tag. Decoration
832 mode is actually a full harness for providing any kind of decoration on
833 a tag based on a prefix function.
835 -- Command: semantic-decoration-mode &optional arg
836 Minor mode for decorating tags. Decorations are specified in
837 'semantic-decoration-styles'. You can define new decoration styles
838 with "define-semantic-decoration-style". With prefix argument ARG,
839 turn on if positive, otherwise off. The minor mode can be turned
840 on only if semantic feature is available and the current buffer was
841 set up for parsing. Return non-'nil' if the minor mode is enabled.
843 To enable or disable specific decorations, you can use this function:
845 -- Command: semantic-toggle-decoration-style name &optional arg
846 Turn on/off the decoration style with NAME. Decorations are
847 specified in 'semantic-decoration-styles'. With prefix argument
848 ARG, turn on if positive, otherwise off. Return non-'nil' if the
849 decoration style is enabled.
851 You can create new types of decorations using the following function:
853 -- Function: define-semantic-decoration-style name doc &rest flags
854 Define a new decoration style with NAME. DOC is a documentation
855 string describing the decoration style NAME. It is appended to
856 auto-generated doc strings. An Optional list of FLAGS can also be
857 specified. Flags are: ':enabled' <value> - specify the default
858 enabled value for NAME.
860 This defines two new overload functions respectively called
861 'NAME-p' and 'NAME-highlight', for which you must provide a default
862 implementation in respectively the functions 'NAME-p-default' and
863 'NAME-highlight-default'. Those functions are passed a tag.
864 'NAME-p' must return non-'nil' to indicate that the tag should be
865 decorated by 'NAME-highlight'.
867 To put primary decorations on a tag 'NAME-highlight' must use
868 functions like "semantic-set-tag-face",
869 "semantic-set-tag-intangible", etc., found in the semantic-decorate
872 To add other kind of decorations on a tag, 'NAME-highlight' must
873 use "semantic-decorate-tag", and other functions of the semantic
874 decoration API found in this library.
877 File: semantic-user.info, Node: MRU Bookmarks Mode, Prev: Tag Decoration Mode, Up: Code Helpers
879 10.2.3 MRU Bookmarks Mode
880 -------------------------
882 MRU stands for Most Recently Used. Semantic MRU Bookmarks track the
883 tags you edit and maintain a ring of things you've been working on. You
884 can then switch back to tags you've worked on recently by name.
886 -- Command: semantic-mru-bookmark-mode &optional arg
887 Minor mode for tracking tag-based bookmarks automatically. Tag
888 based bookmarks a tracked based on editing and viewing habits and
889 can then be navigated via the MRU bookmark keymap.
891 With prefix argument ARG, turn on if positive, otherwise off. The
892 minor mode can be turned on only if semantic feature is available
893 and the current buffer was set up for parsing. Return non-'nil' if
894 the minor mode is enabled.
896 Once this mode is enbled, any edit, or mark setting will add the current
897 tag to your MRU bookmark ring.
900 This keysequence is like 'switch-to-buffer', but uses a capital 'B'
901 instead of lower case. This lets you type in a tag name, or use
902 'M-p' and 'M-n' to cycle through the bookmark list in MRU order.
905 File: semantic-user.info, Node: Highlight Edits Mode, Next: Parser State, Prev: Development Modes, Up: Development Modes
907 10.2.4 Highlight Edits Mode
908 ---------------------------
910 Highlight edits mode is useful mostly for debugging the incremental
911 parser. As you change text, that effected text is highlighted, and you
912 can visual predict what actions the incremental parser will need to
915 -- Command: semantic-highlight-edits-mode &optional arg
916 Minor mode for highlighting changes made in a buffer. Changes are
917 tracked by semantic so that the incremental parser can work
918 properly. With prefix argument ARG, turn on if positive, otherwise
919 off. The minor mode can be turned on only if semantic feature is
920 available and the current buffer was set up for parsing. Return
921 non-'nil' if the minor mode is enabled.
923 -- Face: semantic-highlight-edits-face
924 Face used to show dirty tokens in 'semantic-highlight-edits-mode'.
927 File: semantic-user.info, Node: Parser State, Next: Unmatched Syntax Highlighting, Prev: Highlight Edits Mode, Up: Development Modes
932 -- Command: semantic-show-parser-state-mode &optional arg
933 Minor mode for displaying parser cache state in the modeline. The
934 cache can be in one of three states. They are Up to date, Partial
935 reprase needed, and Full reparse needed. The state is indicated in
936 the modeline with the following characters:
938 The cache is up to date.
940 The cache requires a full update.
942 The cache needs to be incrementally parsed.
944 The buffer is not lexically parseable.
946 Auto-parse in progress (not set here.)
947 With prefix argument ARG, turn on if positive, otherwise off. The
948 minor mode can be turned on only if semantic feature is available
949 and the current buffer was set up for parsing. Return non-'nil' if
950 the minor mode is enabled.
953 File: semantic-user.info, Node: Unmatched Syntax Highlighting, Prev: Parser State, Up: Development Modes
955 10.2.6 Unmatched Syntax Highlighting
956 ------------------------------------
958 -- Command: semantic-show-unmatched-syntax-mode &optional arg
959 Minor mode to highlight unmatched syntax tokens. When a parser
960 executes, some elements in the buffer may not match any parser
961 rules. These text characters are considered unmatched syntax.
962 Often time, the display of unmatched syntax can expose coding
963 problems before the compiler is run.
965 With prefix argument ARG, turn on if positive, otherwise off. The
966 minor mode can be turned on only if semantic feature is available
967 and the current buffer was set up for parsing. Return non-'nil' if
968 the minor mode is enabled.
970 'C-c , `' "semantic-show-unmatched-syntax-next"
972 -- Option: semantic-unmatched-syntax-face
973 Face used to show unmatched-syntax in. The face is used in
974 "semantic-show-unmatched-syntax-mode".
977 File: semantic-user.info, Node: semanticdb, Next: Speed Debug, Prev: Minor Modes, Up: Top
982 Semanticdb is a utility which tracks your parsed files, and saves the
983 parsed information to disk. When you reload your source files,
984 semanticdb automatically associates the file with the cached copy,
985 saving time by not re-parsing your buffer.
987 Semanticdb also provides an API for programs to use to look up
988 information about a tag. These functions can return tag information
989 without loading the source file into memory.
991 Lastly, the semanticdb interface allows programmers to create alternate
992 back ends. Such a back end could allow access to tag information in
993 binary files, not normally accessable to semantic. A back end could
994 also be written to store tag information in an alternate form of
997 To use semanticdb, add the following to your '.emacs' file:
999 (require 'semanticdb)
1000 (global-semanticdb-minor-mode 1)
1002 If you use 'semantic-load.el', or the default CEDET install mechanism,
1003 you do not need to add the above lines in your '.emacs' file.
1005 The Semantic Database has several user level configuration options that
1006 controls it's use. From the user perspective, it appears to be one
1007 large application. Internally it is divided into sections.
1010 These core tables for semanticdb are not associated with files, or
1011 backends. They define the basic behavior of a database and table.
1013 These databases are what are generally used in semantic to store
1014 information to disk.
1016 These databases and tables are interfaces to some other source of
1017 tagging information, such as the symbols loaded in Emacs Lisp, or
1018 perhaps symbols in a Java '.class' file.
1020 You can execute hooks when semanticdb is activated using its mode hook.
1022 -- Option: semanticdb-mode-hooks
1023 Hooks run whenever "global-semanticdb-minor-mode" is run. Use
1024 "semanticdb-minor-mode-p" to determine if the mode has been turned
1029 * Semanticdb Tag Storage::
1030 * Semanticdb Search Configuration::
1031 * Semanticdb System Backends::
1032 * Changing Backends::
1033 * Script Generated Cache Files::
1034 * Create System Databases::
1037 File: semantic-user.info, Node: Semanticdb Tag Storage, Next: Semanticdb Search Configuration, Up: semanticdb
1039 11.1 Semanticdb Tag Storage
1040 ===========================
1042 Once you have tables of tags parsed from your files, the default action
1043 is to save them when Emacs exits. You can control the file name and
1044 directories where the caches are stored.
1046 -- Option: semanticdb-default-file-name
1047 File name of the semantic tag cache.
1049 -- Option: semanticdb-default-save-directory
1050 Directory name where semantic cache files are stored. If this
1051 value is 'nil', files are saved in the current directory. If the
1052 value is a valid directory, then it overrides
1053 'semanticdb-default-file-name' and stores caches in a coded file
1054 name in this directory.
1056 -- Option: semanticdb-persistent-path
1057 List of valid paths that semanticdb will cache tags to. When
1058 "global-semanticdb-minor-mode" is active, tag lists will be saved
1059 to disk when Emacs exits. Not all directories will have tags that
1060 should be saved. The value should be a list of valid paths. A
1061 path can be a string, indicating a directory in which to save a
1062 variable. An element in the list can also be a symbol. Valid
1063 symbols are 'never', which will disable any saving anywhere,
1064 'always', which enables saving everywhere, or 'project', which
1065 enables saving in any directory that passes a list of predicates in
1066 'semanticdb-project-predicate-functions'.
1068 -- Variable: semanticdb-project-predicate-functions
1069 List of predicates to try that indicate a directory belongs to a
1070 project. This list is used when 'semanticdb-persistent-path'
1071 contains the value ''project'. If the predicate list is 'nil',
1072 then presume all paths are valid.
1074 Project Management software (such as EDE and JDE) should add their
1075 own predicates with "add-hook" to this variable, and semanticdb
1076 will save tag caches in directories controlled by them.
1078 -- Option: semanticdb-save-database-hooks
1079 Hooks run after a database is saved. Each function is called with
1080 one argument, the object representing the database recently
1084 File: semantic-user.info, Node: Semanticdb Search Configuration, Next: Semanticdb System Backends, Prev: Semanticdb Tag Storage, Up: semanticdb
1086 11.2 Semanticdb Search Configuration
1087 ====================================
1089 When different tools such as smart completion or tag jumping needs to
1090 find a tag, those routines call semanticdb search routines. Some time
1091 usually needs to be spent making sure semanticdb can find the files your
1094 The search path should include:
1097 2. a table for each #include file
1098 3. if 'recursive is in the throttle, then all include files included
1101 Include files or equivalent are found in:
1103 1. current directory
1104 2. directories specified by your project. (such as EDE, or the
1105 'semanticdb-project-roots' variable.)
1106 3. system directories
1108 In C code, semantic tries to distinguish between project and system
1109 headers based on '""' or '<>' delimiters. Each language can distinguish
1110 using it's own rules.
1112 The system directory is set up via the variable
1113 'semantic-dependency-system-include-path'. The path is also modified by
1114 some system database create routines, such as
1115 'semanticdb-create-ebrowse-database'. *Note Include paths::.
1117 You can use the command:
1119 M-x semantic-add-system-include RET /some/path
1121 to add more paths interactively into the current mode's path. This will
1122 allow semantic to find more files w/out using system databases.
1126 * Semanticdb Roots:: Specifying the root of different projects
1127 * Include paths:: Add/Remove directories to include search paths
1128 * Search Throttle:: Controlling how semanticdb searches occur
1129 * Semanticdb search debugging commands::
1132 File: semantic-user.info, Node: Semanticdb Roots, Next: Include paths, Up: Semanticdb Search Configuration
1134 11.2.1 SemanticDB project roots
1135 -------------------------------
1137 Project roots specify where different code projects start. Searching
1138 for files usually stops within a single project, so specifying these
1139 roots is important if you want semantic to find tags in other related
1142 -- Option: semanticdb-project-roots
1143 List of directories, where each directory is the root of some
1144 project. All subdirectories of a root project are considered a
1145 part of one project. Values in this string can be overriden by
1146 project management programs via the
1147 'semanticdb-project-root-functions' variable.
1149 -- Variable: semanticdb-project-root-functions
1150 List of functions used to determine a given directories project
1151 root. Functions in this variable can override
1152 'semanticdb-project-roots'. Functions set in the variable are
1153 given one argument (a directory) and must return a string, (the
1154 root directory) or a list of strings (multiple root directories in
1155 a more complex system). This variable should be used by project
1156 management programs like EDE or JDE.
1159 File: semantic-user.info, Node: Include paths, Next: Search Throttle, Prev: Semanticdb Roots, Up: Semanticdb Search Configuration
1161 11.2.2 Include Paths
1162 --------------------
1164 You can add and remove system include paths based on major mode using
1165 the following commands:
1167 -- Command: semantic-add-system-include dir &optional mode
1168 Add a system include DIR to path for MODE. Modifies a mode-local
1169 version of 'semantic-dependency-system-include-path'.
1171 -- Command: semantic-remove-system-include dir &optional mode
1172 Add a system include DIR to path for MODE. Modifies a mode-local
1173 version of 'semantic-dependency-system-include-path'.
1176 File: semantic-user.info, Node: Search Throttle, Next: Semanticdb search debugging commands, Prev: Include paths, Up: Semanticdb Search Configuration
1178 11.2.3 SemanticDB Search Throttle
1179 ---------------------------------
1181 The semanticdb find throttle is a configuration variable that may often
1182 be configured by a language support author. If you need to customize
1183 this for yourself, you may need to override the mode values in a mode
1186 -- Variable: semanticdb-find-default-throttle
1187 The default throttle for 'semanticdb-find' routines. The throttle
1188 controls how detailed the list of database tables is for a symbol
1189 lookup. The value is a list with the following keys:
1192 The file the search is being performed from. This option is
1193 here for completeness only, and is assumed to always be on.
1195 Tables from the same local directory are included. This
1196 includes files directly referenced by a file name which might
1197 be in a different directory.
1199 Tables from the same local project are included If 'project'
1200 is specified, then 'local' is assumed.
1202 If a table is not in memory, load it. If it is not cached on
1203 disk either, get the source, parse it, and create the table.
1205 Tables from system databases. These are specifically tables
1206 from system header files, or language equivalent.
1208 For include based searches, includes tables referenced by
1211 Included system databases which are omniscience, or somehow
1212 know everything. Omniscience databases are found in
1213 'semanticdb-project-system-databases'. The Emacs Lisp system
1214 DB is an omniscience database.
1216 To set the throttle, use a command like this:
1218 (setq-mode-local c-mode
1219 semanticdb-find-default-throttle
1220 '(project unloaded system recursive))
1223 File: semantic-user.info, Node: Semanticdb search debugging commands, Prev: Search Throttle, Up: Semanticdb Search Configuration
1225 11.2.4 Semanticdb search debugging commands
1226 -------------------------------------------
1228 You can use 'M-x semanticdb-dump-all-table-summary RET' to see the list
1229 of databases that will be searched from a given buffer. It should
1230 include DBs for the directories you expect. You can follow up with 'M-x
1231 semanticdb-find-test-translate-path RET' to then make sure specific
1232 tables from the path are discovered correctly.
1234 -- Command: semanticdb-dump-all-table-summary
1235 Dump a list of all databases in Emacs memory.
1237 -- Command: semanticdb-find-test-translate-path &optional arg
1238 Call and output results of "semanticdb-find-translate-path" With
1239 ARG non-'nil', specify a BRUTISH translation.
1241 Lastly, you can test an explicit search term using this command:
1243 -- Command: semantic-adebug-searchdb regex
1244 Search the semanticdb for REGEX for the current buffer. Display
1245 the results as a debug list.
1248 File: semantic-user.info, Node: Semanticdb System Backends, Next: Changing Backends, Prev: Semanticdb Search Configuration, Up: semanticdb
1250 11.3 Semanticdb System Backends
1251 ===============================
1253 -- Variable: semanticdb-project-system-databases
1254 List of databases containing system library information. Mode
1255 authors can create their own system databases which know detailed
1256 information about the system libraries for querying purposes. Put
1257 those into this variable as a buffer-local, or mode-local value.
1259 These system databases are a part of the 'omniscience' throttle value.
1261 While these are enabled with 'semanticdb-find-default-throttle', a
1262 secondary flag is needed for internal controls that prevent recursive
1265 -- Variable: semanticdb-search-system-databases
1266 Non 'nil' if search routines are to include a system database.
1269 File: semantic-user.info, Node: Changing Backends, Next: Script Generated Cache Files, Prev: Semanticdb System Backends, Up: semanticdb
1271 11.4 Changing Backends
1272 ======================
1274 If you want to use some other form of backend, you can use this variable
1275 to choose which back end class to use for your general tag storage.
1277 -- Variable: semanticdb-new-database-class
1278 The default type of database created for new files. This can be
1279 changed on a per file basis, so that some directories are saved
1280 using one mechanism, and some directories via a different
1284 File: semantic-user.info, Node: Script Generated Cache Files, Next: Create System Databases, Prev: Changing Backends, Up: semanticdb
1286 11.5 Script Generated Cache Files
1287 =================================
1289 You can create new semantic databases with the 'semanticdb.sh' script
1290 file. Give this script the directory you want parsed, and it will
1291 create a cache file for you.
1293 $ semanticdb.sh *.el
1296 File: semantic-user.info, Node: Create System Databases, Prev: Script Generated Cache Files, Up: semanticdb
1298 11.6 Create System Databases
1299 ============================
1301 If your supported langauge stores the system libraries in readilly
1302 available parsable source code, you can pre-generate database files for
1303 them once, which will be used over and over for tools such as
1304 summary-mode, or the analyzer.
1306 Use the following command to create new system databases:
1308 -- Command: semanticdb-create-system-database path &optional class
1309 Create a system database starting at PATH. PATH should be a top
1310 level directory for a series of files containing declarations for
1311 SYSTEM files. In C, this would be header filaes. CLASS is the
1312 class for the database to create. Only child classes of symbol
1313 "semanticdb-project-database-system" are accepted.
1315 -- Command: semanticdb-create-ebrowse-database dir
1316 Create an EBROSE database for directory DIR. The database file is
1317 stored in ~/.semanticdb, or whichever directory is specified by
1318 'semanticdb-default-system-save-directory'.
1320 The CLASS requested here is a bit of archana representing the class name
1321 for the language the entry is for. Use completion 'SPC' to see the ones
1322 available. The name of the language should be part of the class name.
1325 File: semantic-user.info, Node: Speed Debug, Next: Customizing, Prev: semanticdb, Up: Top
1327 12 Debugging Speed Problems
1328 ***************************
1330 If aspects of semantic cause your Emacs to slow down or block editing,
1331 there are several things that may be happening. The most time consuming
1332 aspect of semantic is usually the parsing of files for tag information,
1333 and this action can be triggered from many possible sources.
1335 A simple way to determine where the problem lies is to use the command
1336 'M-x debug-on-quit RET' and then just hit 'C-g' next time it gets
1337 'stuck' somewhere. It will give you a stack and one of the many
1338 semantic mode functions will likely show up in that stack trace.
1340 From a simple standpoint, your next action might be to use the the
1341 Senator menu under 'Modes' and just toggle suspected modes on and off.
1343 12.1 Interruptibility
1344 =====================
1346 One of the goals with the semantic based minor modes and auto parse is
1347 that it should be interruptible. Thus, a keyboard action should
1348 interrupt any active parsing or mode activity. In practice, I've found
1349 this doesn't always work and I've been a bit stymied as to why.
1351 You can test the interruptibility framework by running 'M-x
1352 semantic-test-throw-on-input RET' and seeing that you can press any key
1353 to break out of the loop.
1355 12.2 Incremental parsing
1356 ========================
1358 The incremental parser used by semantic will reparse only small sections
1359 of a file you have edited, which eliminates the need to reparse entire
1360 files. This speeds up minor modes that need the local buffer to be up
1361 to date, such as speedbar or ECB.
1363 If the incremental parsing is not always working for you (meaning it
1364 will parse the whole file frequently while you edit) then perhaps you
1365 need to customize 'semantic-edits-verbose-flag' to enable some friendly
1366 debug output. Additionally using
1367 'semantic-load-enable-semantic-debugging-helpers' to help identify
1368 possible problem areas by enabling highlight edits mode and show parser
1369 state mode *note (semantic-langdev.info)Incremental Parser Debugging::
1374 There are many minor modes that have special behaviors tied into the
1375 current parser state, with the most complex modes being the summary and
1376 completion modes. These modes can initiate parsing not only in the
1377 current buffer, but in other buffers that are referred to in the current
1378 source by some form of include statement.
1380 If they turn out not to be useful in the language mode you are operating
1381 in, then it may be best to disable them.
1383 Alternately, you can control how these major modes, and other modes like
1384 them parse alternate files by adjusting
1385 'semanticdb-find-default-throttle'. You can read more in *note
1386 (semantic-appdev.info)DB Search Paths::.
1389 File: semantic-user.info, Node: Customizing, Next: GNU Free Documentation License, Prev: Speed Debug, Up: Top
1394 Customizations can be divided into two categories. * M-x customize *
1398 File: semantic-user.info, Node: GNU Free Documentation License, Next: Index, Prev: Customizing, Up: Top
1400 Appendix A GNU Free Documentation License
1401 *****************************************
1403 Version 1.1, March 2000
1405 Copyright (C) 2000 Free Software Foundation, Inc.
1406 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
1408 Everyone is permitted to copy and distribute verbatim copies
1409 of this license document, but changing it is not allowed.
1413 The purpose of this License is to make a manual, textbook, or other
1414 written document "free" in the sense of freedom: to assure everyone
1415 the effective freedom to copy and redistribute it, with or without
1416 modifying it, either commercially or noncommercially. Secondarily,
1417 this License preserves for the author and publisher a way to get
1418 credit for their work, while not being considered responsible for
1419 modifications made by others.
1421 This License is a kind of "copyleft", which means that derivative
1422 works of the document must themselves be free in the same sense.
1423 It complements the GNU General Public License, which is a copyleft
1424 license designed for free software.
1426 We have designed this License in order to use it for manuals for
1427 free software, because free software needs free documentation: a
1428 free program should come with manuals providing the same freedoms
1429 that the software does. But this License is not limited to
1430 software manuals; it can be used for any textual work, regardless
1431 of subject matter or whether it is published as a printed book. We
1432 recommend this License principally for works whose purpose is
1433 instruction or reference.
1436 1. APPLICABILITY AND DEFINITIONS
1438 This License applies to any manual or other work that contains a
1439 notice placed by the copyright holder saying it can be distributed
1440 under the terms of this License. The "Document", below, refers to
1441 any such manual or work. Any member of the public is a licensee,
1442 and is addressed as "you".
1444 A "Modified Version" of the Document means any work containing the
1445 Document or a portion of it, either copied verbatim, or with
1446 modifications and/or translated into another language.
1448 A "Secondary Section" is a named appendix or a front-matter section
1449 of the Document that deals exclusively with the relationship of the
1450 publishers or authors of the Document to the Document's overall
1451 subject (or to related matters) and contains nothing that could
1452 fall directly within that overall subject. (For example, if the
1453 Document is in part a textbook of mathematics, a Secondary Section
1454 may not explain any mathematics.) The relationship could be a
1455 matter of historical connection with the subject or with related
1456 matters, or of legal, commercial, philosophical, ethical or
1457 political position regarding them.
1459 The "Invariant Sections" are certain Secondary Sections whose
1460 titles are designated, as being those of Invariant Sections, in the
1461 notice that says that the Document is released under this License.
1463 The "Cover Texts" are certain short passages of text that are
1464 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
1465 that says that the Document is released under this License.
1467 A "Transparent" copy of the Document means a machine-readable copy,
1468 represented in a format whose specification is available to the
1469 general public, whose contents can be viewed and edited directly
1470 and straightforwardly with generic text editors or (for images
1471 composed of pixels) generic paint programs or (for drawings) some
1472 widely available drawing editor, and that is suitable for input to
1473 text formatters or for automatic translation to a variety of
1474 formats suitable for input to text formatters. A copy made in an
1475 otherwise Transparent file format whose markup has been designed to
1476 thwart or discourage subsequent modification by readers is not
1477 Transparent. A copy that is not "Transparent" is called "Opaque".
1479 Examples of suitable formats for Transparent copies include plain
1480 ASCII without markup, Texinfo input format, LaTeX input format,
1481 SGML or XML using a publicly available DTD, and standard-conforming
1482 simple HTML designed for human modification. Opaque formats
1483 include PostScript, PDF, proprietary formats that can be read and
1484 edited only by proprietary word processors, SGML or XML for which
1485 the DTD and/or processing tools are not generally available, and
1486 the machine-generated HTML produced by some word processors for
1487 output purposes only.
1489 The "Title Page" means, for a printed book, the title page itself,
1490 plus such following pages as are needed to hold, legibly, the
1491 material this License requires to appear in the title page. For
1492 works in formats which do not have any title page as such, "Title
1493 Page" means the text near the most prominent appearance of the
1494 work's title, preceding the beginning of the body of the text.
1498 You may copy and distribute the Document in any medium, either
1499 commercially or noncommercially, provided that this License, the
1500 copyright notices, and the license notice saying this License
1501 applies to the Document are reproduced in all copies, and that you
1502 add no other conditions whatsoever to those of this License. You
1503 may not use technical measures to obstruct or control the reading
1504 or further copying of the copies you make or distribute. However,
1505 you may accept compensation in exchange for copies. If you
1506 distribute a large enough number of copies you must also follow the
1507 conditions in section 3.
1509 You may also lend copies, under the same conditions stated above,
1510 and you may publicly display copies.
1512 3. COPYING IN QUANTITY
1514 If you publish printed copies of the Document numbering more than
1515 100, and the Document's license notice requires Cover Texts, you
1516 must enclose the copies in covers that carry, clearly and legibly,
1517 all these Cover Texts: Front-Cover Texts on the front cover, and
1518 Back-Cover Texts on the back cover. Both covers must also clearly
1519 and legibly identify you as the publisher of these copies. The
1520 front cover must present the full title with all words of the title
1521 equally prominent and visible. You may add other material on the
1522 covers in addition. Copying with changes limited to the covers, as
1523 long as they preserve the title of the Document and satisfy these
1524 conditions, can be treated as verbatim copying in other respects.
1526 If the required texts for either cover are too voluminous to fit
1527 legibly, you should put the first ones listed (as many as fit
1528 reasonably) on the actual cover, and continue the rest onto
1531 If you publish or distribute Opaque copies of the Document
1532 numbering more than 100, you must either include a machine-readable
1533 Transparent copy along with each Opaque copy, or state in or with
1534 each Opaque copy a publicly-accessible computer-network location
1535 containing a complete Transparent copy of the Document, free of
1536 added material, which the general network-using public has access
1537 to download anonymously at no charge using public-standard network
1538 protocols. If you use the latter option, you must take reasonably
1539 prudent steps, when you begin distribution of Opaque copies in
1540 quantity, to ensure that this Transparent copy will remain thus
1541 accessible at the stated location until at least one year after the
1542 last time you distribute an Opaque copy (directly or through your
1543 agents or retailers) of that edition to the public.
1545 It is requested, but not required, that you contact the authors of
1546 the Document well before redistributing any large number of copies,
1547 to give them a chance to provide you with an updated version of the
1552 You may copy and distribute a Modified Version of the Document
1553 under the conditions of sections 2 and 3 above, provided that you
1554 release the Modified Version under precisely this License, with the
1555 Modified Version filling the role of the Document, thus licensing
1556 distribution and modification of the Modified Version to whoever
1557 possesses a copy of it. In addition, you must do these things in
1558 the Modified Version:
1560 A. Use in the Title Page (and on the covers, if any) a title
1561 distinct from that of the Document, and from those of previous
1562 versions (which should, if there were any, be listed in the History
1563 section of the Document). You may use the same title as a previous
1564 version if the original publisher of that version gives permission.
1565 B. List on the Title Page, as authors, one or more persons or
1566 entities responsible for authorship of the modifications in the
1567 Modified Version, together with at least five of the principal
1568 authors of the Document (all of its principal authors, if it has
1570 C. State on the Title page the name of the publisher of the
1571 Modified Version, as the publisher.
1572 D. Preserve all the copyright notices of the Document.
1573 E. Add an appropriate copyright notice for your modifications
1574 adjacent to the other copyright notices.
1575 F. Include, immediately after the copyright notices, a license
1576 notice giving the public permission to use the Modified Version
1577 under the terms of this License, in the form shown in the Addendum
1579 G. Preserve in that license notice the full lists of Invariant
1580 Sections and required Cover Texts given in the Document's license
1582 H. Include an unaltered copy of this License.
1583 I. Preserve the section entitled "History", and its title, and add
1584 to it an item stating at least the title, year, new authors, and
1585 publisher of the Modified Version as given on the Title Page. If
1586 there is no section entitled "History" in the Document, create one
1587 stating the title, year, authors, and publisher of the Document as
1588 given on its Title Page, then add an item describing the Modified
1589 Version as stated in the previous sentence.
1590 J. Preserve the network location, if any, given in the Document for
1591 public access to a Transparent copy of the Document, and likewise
1592 the network locations given in the Document for previous versions
1593 it was based on. These may be placed in the "History" section.
1594 You may omit a network location for a work that was published at
1595 least four years before the Document itself, or if the original
1596 publisher of the version it refers to gives permission.
1597 K. In any section entitled "Acknowledgements" or "Dedications",
1598 preserve the section's title, and preserve in the section all the
1599 substance and tone of each of the contributor acknowledgements
1600 and/or dedications given therein.
1601 L. Preserve all the Invariant Sections of the Document, unaltered
1602 in their text and in their titles. Section numbers or the
1603 equivalent are not considered part of the section titles.
1604 M. Delete any section entitled "Endorsements". Such a section may
1605 not be included in the Modified Version.
1606 N. Do not retitle any existing section as "Endorsements" or to
1607 conflict in title with any Invariant Section.
1609 If the Modified Version includes new front-matter sections or
1610 appendices that qualify as Secondary Sections and contain no
1611 material copied from the Document, you may at your option designate
1612 some or all of these sections as invariant. To do this, add their
1613 titles to the list of Invariant Sections in the Modified Version's
1614 license notice. These titles must be distinct from any other
1617 You may add a section entitled "Endorsements", provided it contains
1618 nothing but endorsements of your Modified Version by various
1619 parties-for example, statements of peer review or that the text has
1620 been approved by an organization as the authoritative definition of
1623 You may add a passage of up to five words as a Front-Cover Text,
1624 and a passage of up to 25 words as a Back-Cover Text, to the end of
1625 the list of Cover Texts in the Modified Version. Only one passage
1626 of Front-Cover Text and one of Back-Cover Text may be added by (or
1627 through arrangements made by) any one entity. If the Document
1628 already includes a cover text for the same cover, previously added
1629 by you or by arrangement made by the same entity you are acting on
1630 behalf of, you may not add another; but you may replace the old
1631 one, on explicit permission from the previous publisher that added
1634 The author(s) and publisher(s) of the Document do not by this
1635 License give permission to use their names for publicity for or to
1636 assert or imply endorsement of any Modified Version.
1638 5. COMBINING DOCUMENTS
1640 You may combine the Document with other documents released under
1641 this License, under the terms defined in section 4 above for
1642 modified versions, provided that you include in the combination all
1643 of the Invariant Sections of all of the original documents,
1644 unmodified, and list them all as Invariant Sections of your
1645 combined work in its license notice.
1647 The combined work need only contain one copy of this License, and
1648 multiple identical Invariant Sections may be replaced with a single
1649 copy. If there are multiple Invariant Sections with the same name
1650 but different contents, make the title of each such section unique
1651 by adding at the end of it, in parentheses, the name of the
1652 original author or publisher of that section if known, or else a
1653 unique number. Make the same adjustment to the section titles in
1654 the list of Invariant Sections in the license notice of the
1657 In the combination, you must combine any sections entitled
1658 "History" in the various original documents, forming one section
1659 entitled "History"; likewise combine any sections entitled
1660 "Acknowledgements", and any sections entitled "Dedications". You
1661 must delete all sections entitled "Endorsements."
1663 6. COLLECTIONS OF DOCUMENTS
1665 You may make a collection consisting of the Document and other
1666 documents released under this License, and replace the individual
1667 copies of this License in the various documents with a single copy
1668 that is included in the collection, provided that you follow the
1669 rules of this License for verbatim copying of each of the documents
1670 in all other respects.
1672 You may extract a single document from such a collection, and
1673 distribute it individually under this License, provided you insert
1674 a copy of this License into the extracted document, and follow this
1675 License in all other respects regarding verbatim copying of that
1678 7. AGGREGATION WITH INDEPENDENT WORKS
1680 A compilation of the Document or its derivatives with other
1681 separate and independent documents or works, in or on a volume of a
1682 storage or distribution medium, does not as a whole count as a
1683 Modified Version of the Document, provided no compilation copyright
1684 is claimed for the compilation. Such a compilation is called an
1685 "aggregate", and this License does not apply to the other
1686 self-contained works thus compiled with the Document, on account of
1687 their being thus compiled, if they are not themselves derivative
1688 works of the Document.
1690 If the Cover Text requirement of section 3 is applicable to these
1691 copies of the Document, then if the Document is less than one
1692 quarter of the entire aggregate, the Document's Cover Texts may be
1693 placed on covers that surround only the Document within the
1694 aggregate. Otherwise they must appear on covers around the whole
1699 Translation is considered a kind of modification, so you may
1700 distribute translations of the Document under the terms of section
1701 4. Replacing Invariant Sections with translations requires special
1702 permission from their copyright holders, but you may include
1703 translations of some or all Invariant Sections in addition to the
1704 original versions of these Invariant Sections. You may include a
1705 translation of this License provided that you also include the
1706 original English version of this License. In case of a
1707 disagreement between the translation and the original English
1708 version of this License, the original English version will prevail.
1712 You may not copy, modify, sublicense, or distribute the Document
1713 except as expressly provided for under this License. Any other
1714 attempt to copy, modify, sublicense or distribute the Document is
1715 void, and will automatically terminate your rights under this
1716 License. However, parties who have received copies, or rights,
1717 from you under this License will not have their licenses terminated
1718 so long as such parties remain in full compliance.
1720 10. FUTURE REVISIONS OF THIS LICENSE
1722 The Free Software Foundation may publish new, revised versions of
1723 the GNU Free Documentation License from time to time. Such new
1724 versions will be similar in spirit to the present version, but may
1725 differ in detail to address new problems or concerns. See
1726 http://www.gnu.org/copyleft/.
1728 Each version of the License is given a distinguishing version
1729 number. If the Document specifies that a particular numbered
1730 version of this License "or any later version" applies to it, you
1731 have the option of following the terms and conditions either of
1732 that specified version or of any later version that has been
1733 published (not as a draft) by the Free Software Foundation. If the
1734 Document does not specify a version number of this License, you may
1735 choose any version ever published (not as a draft) by the Free
1736 Software Foundation.
1738 ADDENDUM: How to use this License for your documents
1739 ====================================================
1741 To use this License in a document you have written, include a copy of
1742 the License in the document and put the following copyright and license
1743 notices just after the title page:
1746 Copyright (C) YEAR YOUR NAME.
1747 Permission is granted to copy, distribute and/or modify this document
1748 under the terms of the GNU Free Documentation License, Version 1.1
1749 or any later version published by the Free Software Foundation;
1750 with the Invariant Sections being LIST THEIR TITLES, with the
1751 Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
1752 A copy of the license is included in the section entitled ``GNU
1753 Free Documentation License''.
1754 If you have no Invariant Sections, write "with no Invariant Sections"
1755 instead of saying which ones are invariant. If you have no Front-Cover
1756 Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
1757 LIST"; likewise for Back-Cover Texts.
1759 If your document contains nontrivial examples of program code, we
1760 recommend releasing these examples in parallel under your choice of free
1761 software license, such as the GNU General Public License, to permit
1762 their use in free software.
1765 File: semantic-user.info, Node: Index, Prev: GNU Free Documentation License, Up: Top
1773 * &optional: Idle Summary Mode. (line 9)
1774 * &optional <1>: Idle Completions Mode.
1776 * Analyzer: Analyzer. (line 6)
1777 * Charts: Charts. (line 6)
1778 * Class Browser: Class Browser. (line 6)
1779 * customizing: Customizing. (line 6)
1780 * define-semantic-decoration-style: Tag Decoration Mode. (line 29)
1781 * Document: Document. (line 6)
1782 * document: Document. (line 39)
1783 * document-inline: Document. (line 44)
1784 * document-insert-defun-comment: Document. (line 47)
1785 * document-insert-new-file-header: Document. (line 50)
1786 * ECB: ECB. (line 6)
1787 * global-semantic-idle-scheduler-mode: Idle Scheduler. (line 16)
1788 * Idle Scheduler: Idle Scheduler. (line 6)
1789 * imenu: imenu. (line 6)
1790 * Minor Modes: Minor Modes. (line 6)
1791 * re-search-backward: senator. (line 59)
1792 * re-search-forward: senator. (line 58)
1793 * semantic-add-system-include: Include paths. (line 9)
1794 * semantic-adebug-searchdb: Semanticdb search debugging commands.
1796 * semantic-after-idle-scheduler-reparse-hooks: Reparsing Options.
1798 * semantic-analyze-current-context: Analyzer. (line 9)
1799 * semantic-analyze-possible-completions: Analyzer. (line 22)
1800 * semantic-before-idle-scheduler-reparse-hooks: Reparsing Options.
1802 * semantic-cb-new-class-browser: Class Browser. (line 13)
1803 * semantic-cb-speedbar-mode: Class Browser. (line 26)
1804 * semantic-chart-database-size: Charts. (line 15)
1805 * semantic-chart-tag-complexity: Charts. (line 21)
1806 * semantic-chart-tags-by-class: Charts. (line 8)
1807 * semantic-decoration-mode: Tag Decoration Mode. (line 6)
1808 * semantic-decoration-mode <1>: Tag Decoration Mode. (line 11)
1809 * semantic-highlight-edits-face: Highlight Edits Mode.
1811 * semantic-highlight-edits-mode: Highlight Edits Mode.
1813 * semantic-ia-complete-symbol: Smart Completion. (line 11)
1814 * semantic-ia-complete-symbol-menu: Smart Completion. (line 15)
1815 * semantic-ia-complete-tip: Smart Completion. (line 20)
1816 * semantic-ia-show-doc: Smart Completion. (line 26)
1817 * semantic-ia-show-summary: Smart Completion. (line 23)
1818 * semantic-idle-scheduler-idle-time: Idle Scheduler. (line 31)
1819 * semantic-idle-scheduler-max-buffer-size: Reparsing Options. (line 13)
1820 * semantic-idle-scheduler-mode-hook: Idle Scheduler. (line 36)
1821 * semantic-idle-scheduler-no-working-message: Reparsing Options.
1823 * semantic-idle-scheduler-working-in-modeline-flag: Reparsing Options.
1825 * semantic-idle-summary-function: Idle Summary Mode. (line 23)
1826 * semantic-imenu-auto-rebuild-directory-indexes: imenu. (line 56)
1827 * semantic-imenu-bucketize-file: imenu. (line 30)
1828 * semantic-imenu-bucketize-type-members: imenu. (line 40)
1829 * semantic-imenu-buckets-to-submenu: imenu. (line 33)
1830 * semantic-imenu-expand-type-members: imenu. (line 37)
1831 * semantic-imenu-expandable-tag-classes: imenu. (line 63)
1832 * semantic-imenu-index-directory: imenu. (line 50)
1833 * semantic-imenu-sort-bucket-function: imenu. (line 45)
1834 * semantic-imenu-summary-function: imenu. (line 26)
1835 * semantic-mru-bookmark-mode: MRU Bookmarks Mode. (line 6)
1836 * semantic-mru-bookmark-mode <1>: MRU Bookmarks Mode. (line 10)
1837 * semantic-remove-system-include: Include paths. (line 13)
1838 * semantic-show-parser-state-mode: Parser State. (line 6)
1839 * semantic-show-unmatched-syntax-mode: Unmatched Syntax Highlighting.
1841 * semantic-speedbar-analysis: Speedbar Analysis. (line 25)
1842 * semantic-stickyfunc-mode: Sticky Function Mode.
1844 * semantic-stickyfunc-sticky-classes: Sticky Function Mode.
1846 * semantic-texi-goto-source: Document. (line 66)
1847 * semantic-texi-update-doc: Document. (line 59)
1848 * semantic-toggle-decoration-style: Tag Decoration Mode. (line 21)
1849 * semantic-unmatched-syntax-face: Unmatched Syntax Highlighting.
1851 * semanticdb: semanticdb. (line 6)
1852 * semanticdb-create-ebrowse-database: Create System Databases.
1854 * semanticdb-create-system-database: Create System Databases.
1856 * semanticdb-default-file-name: Semanticdb Tag Storage.
1858 * semanticdb-default-save-directory: Semanticdb Tag Storage.
1860 * semanticdb-dump-all-table-summary: Semanticdb search debugging commands.
1862 * semanticdb-find-default-throttle: Search Throttle. (line 11)
1863 * semanticdb-find-test-translate-path: Semanticdb search debugging commands.
1865 * semanticdb-mode-hooks: semanticdb. (line 46)
1866 * semanticdb-new-database-class: Changing Backends. (line 9)
1867 * semanticdb-persistent-path: Semanticdb Tag Storage.
1869 * semanticdb-project-predicate-functions: Semanticdb Tag Storage.
1871 * semanticdb-project-root-functions: Semanticdb Roots. (line 18)
1872 * semanticdb-project-roots: Semanticdb Roots. (line 11)
1873 * semanticdb-project-system-databases: Semanticdb System Backends.
1875 * semanticdb-save-database-hooks: Semanticdb Tag Storage.
1877 * semanticdb-search-system-databases: Semanticdb System Backends.
1879 * senator: senator. (line 6)
1880 * senator-complete-symbol: senator. (line 73)
1881 * senator-completion-menu-popup: senator. (line 78)
1882 * senator-copy-tag: senator. (line 97)
1883 * senator-copy-tag-to-register: senator. (line 109)
1884 * senator-isearch-toggle-semantic-mode: senator. (line 46)
1885 * senator-jump: senator. (line 27)
1886 * senator-kill-tag: senator. (line 100)
1887 * senator-minor-mode: senator. (line 120)
1888 * senator-next-tag: senator. (line 19)
1889 * senator-previous-tag: senator. (line 23)
1890 * senator-search-backward: senator. (line 51)
1891 * senator-search-forward: senator. (line 50)
1892 * senator-step-at-start-end-tag-classes: senator. (line 171)
1893 * senator-step-at-tag-classes: senator. (line 165)
1894 * senator-yank-tag: senator. (line 105)
1895 * speedbar: speedbar. (line 6)
1896 * word-search-backward: senator. (line 64)
1897 * word-search-forward: senator. (line 63)
1903 Node: speedbar
\7f2153
1906 Ref: semantic-imenu-expandable-tag-classes
\7f5865
1907 Node: senator
\7f6086
1908 Node: Analyzer
\7f12834
1909 Node: Smart Completion
\7f14638
1910 Ref: semantic-ia-complete-symbol
\7f15105
1911 Ref: semantic-ia-complete-symbol-menu
\7f15287
1912 Ref: semantic-ia-complete-tip
\7f15483
1913 Ref: semantic-ia-show-summary
\7f15575
1914 Ref: semantic-ia-show-doc
\7f15667
1915 Node: Smart Idle Completion
\7f15735
1916 Node: Speedbar Analysis
\7f16362
1917 Node: Class Browser
\7f17697
1918 Node: Document
\7f19034
1919 Node: Charts
\7f21985
1920 Node: Idle Scheduler
\7f23223
1921 Ref: global-semantic-idle-scheduler-mode
\7f23812
1922 Ref: semantic-idle-scheduler-idle-time
\7f24491
1923 Ref: semantic-idle-scheduler-mode-hook
\7f24705
1924 Node: Reparsing Options
\7f25021
1925 Ref: semantic-idle-scheduler-max-buffer-size
\7f25429
1926 Ref: semantic-idle-scheduler-no-working-message
\7f25708
1927 Ref: semantic-idle-scheduler-working-in-modeline-flag
\7f25839
1928 Ref: semantic-before-idle-scheduler-reparse-hooks
\7f26126
1929 Ref: semantic-after-idle-scheduler-reparse-hooks
\7f26375
1930 Node: Idle Summary Mode
\7f26562
1931 Ref: semantic-idle-summary-mode
\7f26921
1932 Ref: semantic-idle-summary-function
\7f27617
1933 Node: Idle Completions Mode
\7f27762
1934 Ref: semantic-idle-completions-mode
\7f28237
1935 Node: Minor Modes
\7f28839
1936 Node: Code Helpers
\7f29417
1937 Node: Development Modes
\7f29856
1938 Node: Sticky Function Mode
\7f30082
1939 Node: Tag Decoration Mode
\7f31087
1940 Ref: semantic-decoration-mode
\7f31563
1941 Ref: semantic-toggle-decoration-style
\7f32130
1942 Ref: define-semantic-decoration-style
\7f32511
1943 Node: MRU Bookmarks Mode
\7f33588
1944 Ref: semantic-mru-bookmark-mode
\7f34004
1945 Node: Highlight Edits Mode
\7f34777
1946 Node: Parser State
\7f35744
1947 Node: Unmatched Syntax Highlighting
\7f36775
1948 Node: semanticdb
\7f37795
1949 Ref: semanticdb-mode-hooks
\7f39698
1950 Node: Semanticdb Tag Storage
\7f40042
1951 Ref: semanticdb-default-file-name
\7f40439
1952 Ref: semanticdb-default-save-directory
\7f40528
1953 Ref: semanticdb-persistent-path
\7f40857
1954 Ref: semanticdb-project-predicate-functions
\7f41581
1955 Ref: semanticdb-save-database-hooks
\7f42073
1956 Node: Semanticdb Search Configuration
\7f42225
1957 Node: Semanticdb Roots
\7f43930
1958 Ref: semanticdb-project-roots
\7f44368
1959 Ref: semanticdb-project-root-functions
\7f44714
1960 Node: Include paths
\7f45157
1961 Ref: semantic-add-system-include
\7f45492
1962 Ref: semantic-remove-system-include
\7f45686
1963 Node: Search Throttle
\7f45817
1964 Ref: semanticdb-find-default-throttle
\7f46317
1965 Node: Semanticdb search debugging commands
\7f47844
1966 Ref: semanticdb-dump-all-table-summary
\7f48443
1967 Ref: semanticdb-find-test-translate-path
\7f48558
1968 Ref: semantic-adebug-searchdb
\7f48790
1969 Node: Semanticdb System Backends
\7f48895
1970 Ref: semanticdb-project-system-databases
\7f49156
1971 Ref: semanticdb-search-system-databases
\7f49710
1972 Node: Changing Backends
\7f49779
1973 Ref: semanticdb-new-database-class
\7f50155
1974 Node: Script Generated Cache Files
\7f50374
1975 Node: Create System Databases
\7f50777
1976 Ref: semanticdb-create-system-database
\7f51310
1977 Ref: semanticdb-create-ebrowse-database
\7f51698
1978 Node: Speed Debug
\7f52107
1979 Node: Customizing
\7f54878
1980 Node: GNU Free Documentation License
\7f55114