annotate etc/ETAGS.EBNF @ 83004:7900111db01c

Converted display hooks to be display-local. Plus many bugfixes. lib-src/emacsclient.c (window_change_signal): Renamed to pass_signal_to_emacs. (init_signal): Pass SIGINT and SIGQUIT to the emacs process. lisp/faces.el (face-valid-attribute-values): Use the window-system function, not the variable. (read-face-attribute, face-spec-set-match-display, frame-set-background-mode) (face-set-after-frame-default): Ditto. lisp/frame.el (make-frame-on-tty): Added interactive declaration (suggested by Robert J. Chassell). Use tty-create-frame-with-faces, not make-terminal-frame. src/termhooks.h (struct display_method): Renamed to display for brevity. (struct display): Added all display hook variables as members of this structure. Added next_display, reference_count, type and display_info components. (FRAME_MUST_WRITE_SPACES, FRAME_FAST_CLEAR_END_OF_LINE, FRAME_LINE_INS_DEL_OK) (FRAME_CHAR_INS_DEL_OK, FRAME_SCROLL_REGION_OK, FRAME_SCROLL_REGION_COST) (FRAME_MEMORY_BELOW_FRAME, FRAME_RIF): Updated for struct display. (FRAME_DISPLAY): New macro. (create_display, delete_display): New prototypes. src/frame.h (struct frame): Added `display' member, removed display_method. (FRAME_LIVE_P): Look at f->display, not f->output_data. src/termchar.h (struct tty_display_info): Removed display_method component. (FRAME_TTY): Use the display structure, not output_data. src/term.c (display_list): New variable. (cursor_to_hook, raw_cursor_to_hook, clear_to_end_hook, clear_frame_hook) (clear_end_of_line_hook, ins_del_lines_hook, delete_glyphs_hook) (ring_bell_hook, reset_terminal_modes_hook, set_terminal_modes_hook) (update_begin_hook, update_end_hook, set_terminal_window_hook) (insert_glyphs_hook, write_glyphs_hook, delete_glyphs_hoo, read_socket_hook) (frame_up_to_date_hook, mouse_position_hook, frame_rehighlight_hook) (frame_raise_lower_hook, set_vertical_scroll_bar_hook, condemn_scroll_bars_hook) (redeem_scroll_bar_hook, judge_scroll_bars_hook): Moved to struct display. (tty_display_method_template): Removed. (syms_of_term): Don't initialize tty_display_method_template. (ring_bell, set_terminal_modes, reset_terminal_modes, update_begin) (update_end, set_terminal_window, cursor_to, raw_cursor_to, clear_to_end) (clear_frame, clear_end_of_line, write_glyphs, insert_glyphs) (delete_glyphs, ins_del_lines): Access display hooks through the frame pointer. (Ftty_display_color_p): Use the frame given as a parameter, or else return nil. (Ftty_display_color_cells): Ditto. (get_named_tty): Renamed to get_named_tty_display, changed return type to struct display. (term_dummy_init): Renamed to initial_term_init. Create and return an initial display. (term_init): Initialize a new struct display and return a pointer to it instead of tty_display_info. Removed frame initialization kludge. (Fdelete_tty): Updated for struct display. (delete_tty): The parameter type is now struct display, not tty_display_info. Delete the display, too. (create_tty_output): New function for creating tty_output structures. (delete_tty_output): New function for deleting tty_output structures. (create_display): New function for creating and registering display structures. (delete_display): New function for deleting and unregistering display structures. src/dispextern.h: Updated prototypes. src/dispnew.c: Include frame.h before termhooks.h. (init_display): Updated term_init call to new signature. src/emacs.c: Include frame.h (for termhooks.h). src/keymap.c: Ditto. src/lread.c: Ditto. src/xsmfns.c: Ditto. src/process.c: Include frame.h before termhooks.h. src/frame.c (Fwindow_system): New function. (syms_of_frame): Initialize it. (make_terminal_frame): Open the terminal device before creating the new frame. Disable scrollbars here, term_init cannot do that anymore. (Fdelete_frame): Use the new delete_frame_hook, don't do display-specific frame deletion here. Ditto for delete_display_hook. (Fmouse_position, Fmouse_pixel_position, Fraise_frame, Flower_frame) (Fredirect_frame_focus): Access display hooks through the frame pointer. src/keyboard.c: Include frame.h before termhooks.h. (start_polling, input_polling_used, stop_polling, gobble_input): Ignore read_socket_hook. (kbd_buffer_get_event, Fset_input_mode): Access display hooks through the frame pointer. (read_avail_input): Loop through all display devices for and call all read_socket_hook functions. Check ttys even if read_socket_hook returned an error. src/sysdep.c (discard_tty_input): Ignore read_socket_hook. (stuff_char): Don't do anything if the current frame is not on a termcap display. (request_sigio, unrequest_sigio): Ignore read_socket_hook. (init_sys_modes): Always call narrow_foreground_group. Set up terminal modes and sigio even under X. src/xdisp.c (message2_nolog, message3_nolog, redisplay_internal) (set_vertical_scroll_bar, redisplay_window): Access display hooks through the frame pointer. (echo_area_display): Don't be afraid of termcap frames during an X+tty combo session. src/xfaces.c: Include termhooks.h. (Ftty_supports_face_attributes_p): Use the given frame, not selected_frame. src/xfns.c (x_set_scroll_bar_foreground, x_set_scroll_bar_background): Access display hooks through the frame pointer. (Fx_create_frame, x_create_tip_frame): Initialize the frame's display structure. src/xmenu.c: Include termhooks.h after frame.h. src/xselect.c (x_own_selection, some_frame_on_display, x_get_foreign_selection) (Fx_disown_selection_internal, Fx_get_cut_buffer_internal) (Fx_store_cut_buffer_internal, Fx_rotate_cut_buffers_internal): Don't do anything if the selected frame is not an X frame. src/xterm.c (x_display_method): Removed. (x_create_frame_display, x_delete_frame_display): New functions for handling struct display objects. (x_term_init): Set up a new struct display object, too. (x_delete_display): Delete the struct display corresponding to the X display. (x_initialize): Moved hook initialization to x_create_frame_display. src/xterm.h (x_display_method): Removed. (struct x_display_info): Added frame_display component. git-archimport-id: [e-mail]--2004/emacs--multi-tty--0--patch-44

-*- indented-text -*-

This file contains two sections:

1) An EBNF (Extended Backus Normal Form) description of the format of
    the tags file created by etags.c and interpreted by etags.el;
2) A discussion of tag names and implicit tag names.

====================== 1) EBNF tag file description =====================

Productions created from current behaviour to aid extensions
Francesco Potorti` <[e-mail]> 2002
----------------

FF ::= #x0c				   /* tag section starter */

LF ::= #x0a				   /* line terminator */

DEL ::= #x7f				   /* pattern terminator */

SOH ::= #x01				   /* name terminator */

regchar ::= [^#x0a#x0c#x7f]		   /* regular character */

regstring ::= { regchar }		   /* regular string */

unsint ::= [0-9] { [0-9] }		   /* non-negative integer */



tagfile ::= { tagsection }		   /* a tags file */

tagsection ::= FF LF ( includesec | regularsec ) LF

includesec ::= filename ",include" [ LF fileprop ]

regularsec ::= filename "," [ unsint ] [ LF fileprop ] { LF tag }

filename ::= regchar regstring		   /* a file name */

fileprop ::= "(" regstring ")"		   /* an elisp alist */

tag ::= directtag | patterntag

directtag ::= DEL realposition		   /* no pattern */

patterntag ::= pattern DEL [ tagname SOH ] position

pattern ::= regstring			   /* a tag pattern */

tagname ::= regchar regstring		   /* a tag name */

position ::= realposition | "," 	   /* charpos,linepos */

realposition ::= "," unsint | unsint "," | unsint "," unsint

==================== end of EBNF tag file description ====================



======================= 2) discussion of tag names =======================

- WHAT ARE TAG NAMES
Tag lines in a tags file are usually made from the above defined pattern
and by an optional tag name.  The pattern is a string that is searched
in the source file to find the tagged line.

- WHY TAG NAMES ARE GOOD
When a user looks for a tag, Emacs first compares the tag with the tag
names contained in the tags file.  If no match is found, Emacs compares
the tag with the patterns.  The tag name is then the preferred way to
look for tags in the tags file, because when the tag name is present
Emacs can find a tag faster and more accurately.  These tag names are
part of tag lines in the tags file, so we call them "explicit".

- WHY IMPLICIT TAG NAMES ARE EVEN BETTER
When a tag line has no name, but a name can be deduced from the pattern,
we say that the tag line has an implicit tag name.  Often tag names are
redundant; this happens when the name of a tag is an easily guessable
substring of the tag pattern.  We define a set of rules to decide
whether it is possible to deduce the tag name from the pattern, and make
an unnamed tag in those cases.  The name deduced from the pattern of an
unnamed tag is the implicit name of that tag.
  When the user looks for a tag, and Emacs founds no explicit tag names
that match it, Emacs then looks for an tag whose implicit tag name
matches the request.  etags.c uses implicit tag names when possible, in
order to reduce the size of the tags file.
  An implicit tag name is deduced from the pattern by discarding the
last character if it is one of ` \f\t\n\r()=,;', then taking all the
rightmost consecutive characters in the pattern which are not one of
those.

===================== end of discussion of tag names =====================