diff options
Diffstat (limited to 'doc')
34 files changed, 1640 insertions, 250 deletions
diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index efb70f3b09b..2a46642f0dc 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,35 +1,33 @@ -2014-05-29 Glenn Morris <rgm@gnu.org> +2014-06-02 Glenn Morris <rgm@gnu.org> * macos.texi (Mac / GNUstep Customization): Mention ns custom group. (Customization options specific to Mac OS / GNUstep): Remove section. -2014-05-28 Glenn Morris <rgm@gnu.org> - - * macos.texi (Mac / GNUstep Customization): Mention some new features. - -2014-05-27 Glenn Morris <rgm@gnu.org> - * abbrevs.texi (Expanding Abbrevs): Update re abbrev-expand-function. -2014-05-21 Eli Zaretskii <eliz@gnu.org> +2014-05-26 Eli Zaretskii <eliz@gnu.org> * frames.texi (Fonts): Clarify which frames are affected by setting font from the menu and in default-frame-alist. (Bug#17532) -2014-05-12 Eli Zaretskii <eliz@gnu.org> +2014-05-14 Eli Zaretskii <eliz@gnu.org> - * mule.texi (Language Environments): Remove unused @anchor. - (Bug#17479) + * mule.texi (Language Environments): Remove unused @anchor. (Bug#17479) -2014-05-02 Eli Zaretskii <eliz@gnu.org> +2014-05-04 Eli Zaretskii <eliz@gnu.org> * trouble.texi (Lossage, DEL Does Not Delete, Stuck Recursive) (Screen Garbled, Text Garbled, After a Crash, Emergency Escape) (Bug Criteria, Understanding Bug Reporting, Checklist, Service): Improve indexing. -2014-04-29 Eli Zaretskii <eliz@gnu.org> +2014-05-04 Leo Liu <sdl.web@gmail.com> + + * cal-xtra.texi (Non-Gregorian Diary): Document new features for + Chinese calendar and diary. + +2014-04-30 Eli Zaretskii <eliz@gnu.org> * trouble.texi (Quitting, DEL Does Not Delete, Emergency Escape) (Bug Criteria): Fix usage of @kbd and @key. (Bug#17362) @@ -104,12 +102,10 @@ * anti.texi (Antinews): Fix usage of @kbd and @key. -2014-04-26 Eli Zaretskii <eliz@gnu.org> - * sending.texi (Mail Signature): Document signature variables used by Message mode. (Bug#17308) -2014-04-21 Eli Zaretskii <eliz@gnu.org> +2014-04-22 Eli Zaretskii <eliz@gnu.org> * buffers.texi (Uniquify): Clarify the default uniquification. @@ -119,23 +115,39 @@ EMACSLOADPATH. Index all the environment variables. (Misc Variables): Index all the environment variables. -2014-04-13 Eli Zaretskii <eliz@gnu.org> +2014-04-17 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in (infoclean): Be consistent about reporting failures. + Do not fail merely because the info directory does not exist, + but do fail if it exists and can't be cleaned. + +2014-04-16 Eli Zaretskii <eliz@gnu.org> * display.texi (Cursor Display): Explain better how to customize 'blink-cursor-blinks'. -2014-04-05 Glenn Morris <rgm@gnu.org> +2014-04-07 Glenn Morris <rgm@gnu.org> * trouble.texi (Checklist): Dribble files may contain passwords. -2014-04-04 Glenn Morris <rgm@gnu.org> - * files.texi (Backup Names): * arevert-xtra.texi (Supporting additional buffers): Update for default values of some -function vars no longer being nil. (Supporting additional buffers): Update for buffer-stale-function also applying to file-buffers. +2014-03-28 Glenn Morris <rgm@gnu.org> + + * custom.texi (Terminal Init): Mention term-file-aliases. + +2014-03-26 Glenn Morris <rgm@gnu.org> + + * ack.texi (Acknowledgments): Remove reference to obsolete file. + +2014-03-22 Glenn Morris <rgm@gnu.org> + + * help.texi (Help Files): Update C-h g description. + 2014-03-16 Dmitry Gutov <dgutov@yandex.ru> * programs.texi (Matching): Update the missed spot. (Bug#17008) diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in index 4a59ebed521..9006ba1fbed 100644 --- a/doc/emacs/Makefile.in +++ b/doc/emacs/Makefile.in @@ -199,7 +199,10 @@ distclean: clean ## In the standalone tarfile, the clean rule runs this. infoclean: - -cd $(buildinfodir) && rm -f emacs$(INFO_EXT) emacs$(INFO_EXT)-[1-9] emacs$(INFO_EXT)-[1-9][0-9] + rm -f \ + $(buildinfodir)/emacs$(INFO_EXT) \ + $(buildinfodir)/emacs$(INFO_EXT)-[1-9] \ + $(buildinfodir)/emacs$(INFO_EXT)-[1-9][0-9] maintainer-clean: distclean infoclean diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi index 0ec2cf8624a..ef4e202cea9 100644 --- a/doc/emacs/ack.texi +++ b/doc/emacs/ack.texi @@ -1181,9 +1181,8 @@ written @file{easymenu.el}, a facility for defining Emacs menus; color; and also co-authored portions of CC mode. @item -Sam Steingold wrote @file{gulp.el}, a facility for asking package -maintainers for updated versions of their packages via e-mail, and -@file{midnight.el}, a package for running a command every midnight. +Sam Steingold wrote @file{midnight.el}, a package for running a +command every midnight. @item Ake Stenhoff and Lars Lindberg wrote @file{imenu.el}, a framework for diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi index 82864859473..cf1eba17dec 100644 --- a/doc/emacs/cal-xtra.texi +++ b/doc/emacs/cal-xtra.texi @@ -517,7 +517,7 @@ the fourth pattern. @subsection Diary Entries Using non-Gregorian Calendars As well as entries based on the standard Gregorian calendar, your -diary can have entries based on Bahá'í, Hebrew, or Islamic dates. +diary can have entries based on Bahá'í, Chinese, Hebrew, or Islamic dates. Recognition of such entries can be time-consuming, however, and since most people don't use them, you must explicitly enable their use. If you want the diary to recognize Hebrew-date diary entries, for example, @@ -531,22 +531,27 @@ you must do this: @findex diary-islamic-mark-entries @findex diary-bahai-list-entries @findex diary-bahai-mark-entries +@findex diary-chinese-list-entries +@findex diary-chinese-mark-entries @smallexample (add-hook 'diary-nongregorian-listing-hook 'diary-hebrew-list-entries) (add-hook 'diary-nongregorian-marking-hook 'diary-hebrew-mark-entries) @end smallexample @noindent -Similarly, for Islamic and Bahá'í entries, add -@code{diary-islamic-list-entries} and @code{diary-islamic-mark-entries}, or -@code{diary-bahai-list-entries} and @code{diary-bahai-mark-entries}. +Similarly, for Islamic, Bahá'í and Chinese entries, add +@code{diary-islamic-list-entries} and @code{diary-islamic-mark-entries}, +@code{diary-bahai-list-entries} and @code{diary-bahai-mark-entries}, +or @code{diary-chinese-list-entries} and @code{diary-chinese-mark-entries}. @vindex diary-bahai-entry-symbol +@vindex diary-chinese-entry-symbol @vindex diary-hebrew-entry-symbol @vindex diary-islamic-entry-symbol These diary entries have the same formats as Gregorian-date diary entries; except that @code{diary-bahai-entry-symbol} (default @samp{B}) -must precede a Bahá'í date, @code{diary-hebrew-entry-symbol} (default +must precede a Bahá'í date, @code{diary-chinese-entry-symbol} (default +@samp{C}) a Chinese date, @code{diary-hebrew-entry-symbol} (default @samp{H}) a Hebrew date, and @code{diary-islamic-entry-symbol} (default @samp{I}) an Islamic date. Moreover, non-Gregorian month names may not be abbreviated (because the first three letters are often not unique). @@ -573,7 +578,7 @@ nonmarking if preceded by @code{diary-nonmarking-symbol} (default Here is a table of commands used in the calendar to create diary entries that match the selected date and other dates that are similar in -the Bahá'í, Hebrew, or Islamic calendars: +the Bahá'í, Chinese, Hebrew, or Islamic calendars: @table @kbd @item i h d @@ -594,6 +599,14 @@ the Bahá'í, Hebrew, or Islamic calendars: @code{diary-bahai-insert-monthly-entry} @item i B y @code{diary-bahai-insert-yearly-entry} +@item i C d +@code{diary-chinese-insert-entry} +@item i C m +@code{diary-chinese-insert-monthly-entry} +@item i C y +@code{diary-chinese-insert-yearly-entry} +@item i C a +@code{diary-chinese-insert-anniversary-entry} @end table @findex diary-hebrew-insert-entry @@ -605,6 +618,11 @@ the Bahá'í, Hebrew, or Islamic calendars: @findex diary-bahai-insert-entry @findex diary-bahai-insert-monthly-entry @findex diary-bahai-insert-yearly-entry +@findex diary-chinese-insert-entry +@findex diary-chinese-insert-monthly-entry +@findex diary-chinese-insert-yearly-entry +@findex diary-chinese-insert-anniversary-entry + These commands work much like the corresponding commands for ordinary diary entries: they apply to the date that point is on in the calendar window, and what they do is insert just the date portion of a diary diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 9b78128d323..0d0013f5ace 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -2445,9 +2445,13 @@ harmless, so those do not need a conditional. @node Terminal Init @subsection Terminal-specific Initialization +@vindex term-file-aliases Each terminal type can have a Lisp library to be loaded into Emacs when it is run on that type of terminal. For a terminal type named -@var{termtype}, the library is called @file{term/@var{termtype}} and it is +@var{termtype}, the library is called @file{term/@var{termtype}}. +(If there is an entry of the form @code{(@var{termtype} . @var{alias})} +in the @code{term-file-aliases} association list, Emacs uses +@var{alias} in place of @var{termtype}.) The library is found by searching the directories @code{load-path} as usual and trying the suffixes @samp{.elc} and @samp{.el}. Normally it appears in the subdirectory @file{term} of the directory where most Emacs libraries are diff --git a/doc/emacs/emacsver.texi b/doc/emacs/emacsver.texi index cba7c1eb168..6329f8aa0e6 100644 --- a/doc/emacs/emacsver.texi +++ b/doc/emacs/emacsver.texi @@ -1,4 +1,4 @@ @c It would be nicer to generate this using configure and @version@. @c However, that would mean emacsver.texi would always be newer @c then the info files in release tarfiles. -@set EMACSVER 24.3.91 +@set EMACSVER 24.4.50 diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index 19f0c41ec60..e6cf46acbe5 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -605,7 +605,8 @@ Display information about where to get external packages @item C-h C-f Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}). @item C-h g -Display information about the GNU Project (@code{describe-gnu-project}). +Visit a @uref{http://www.gnu.org} page with information about the GNU +Project (@code{describe-gnu-project}). @item C-h C-m Display information about ordering printed copies of Emacs manuals (@code{view-order-manuals}). diff --git a/doc/lispintro/ChangeLog b/doc/lispintro/ChangeLog index 6ca9eb4c93f..a5878fc7568 100644 --- a/doc/lispintro/ChangeLog +++ b/doc/lispintro/ChangeLog @@ -1,3 +1,7 @@ +2014-04-17 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in (infoclean): Be consistent about reporting failures. + 2014-02-25 Glenn Morris <rgm@gnu.org> * emacs-lisp-intro.texi (X11 Colors): Don't use setq with hooks. diff --git a/doc/lispintro/Makefile.in b/doc/lispintro/Makefile.in index c041cd17e02..c1c6ef71fa2 100644 --- a/doc/lispintro/Makefile.in +++ b/doc/lispintro/Makefile.in @@ -116,7 +116,9 @@ distclean: clean rm -f Makefile infoclean: - -cd $(buildinfodir) && rm -f eintr$(INFO_EXT) eintr$(INFO_EXT)-[1-9] + rm -f \ + $(buildinfodir)/eintr$(INFO_EXT) \ + $(buildinfodir)/eintr$(INFO_EXT)-[1-9] maintainer-clean: distclean infoclean diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index e4f5c60c2d1..9099d69ab3f 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,4 +1,4 @@ -2014-05-27 Glenn Morris <rgm@gnu.org> +2014-06-02 Glenn Morris <rgm@gnu.org> * text.texi (Buffer Contents): Update for filter-buffer-substring changes. @@ -6,53 +6,117 @@ * abbrevs.texi (Abbrev Expansion): Update for expand-abbrev changes. * functions.texi (Advising Functions): Standardize menu case. -2014-05-17 Eli Zaretskii <eliz@gnu.org> +2014-05-26 Eli Zaretskii <eliz@gnu.org> * display.texi (Invisible Text): Clarify the description of line-move-ignore-invisible. (Bug#17511) -2014-05-07 Paul Eggert <eggert@cs.ucla.edu> +2014-05-22 Leo Liu <sdl.web@gmail.com> + + * sequences.texi (Sequence Functions): Don't mention when and how + SEQ to nreverse is mutated. + +2014-05-21 Leo Liu <sdl.web@gmail.com> + + * sequences.texi (Sequence Functions): Update nreverse. + +2014-05-19 Paul Eggert <eggert@cs.ucla.edu> + + Allow any non-nil value to count as true in bool-vector. + * sequences.texi (Bool-Vectors): Coalesce discussion of how to + print them. bool-vector's args need not be t or nil. + +2014-05-19 Dmitry Antipov <dmantipov@yandex.ru> + + * sequences.texi (Bool-vectors): Mention bool-vector. + +2014-05-17 Paul Eggert <eggert@cs.ucla.edu> + + Assume C99 or later (Bug#17487). + * internals.texi (C Dialect): Document this. + +2014-05-15 Dmitry Antipov <dmantipov@yandex.ru> + + * lists.texi (Building Cons Cells and Lists): Remove + description of `reverse' and `'nreverse' to generalize them... + * sequences.texi (Sequences): ...for sequences here. + +2014-05-14 Glenn Morris <rgm@gnu.org> + + * files.texi (Changing Files): Mention with-file-modes. + +2014-05-08 Paul Eggert <eggert@cs.ucla.edu> * internals.texi (C Dialect): New section. (C Integer Types): Mention bool_bf. -2014-04-29 Stefan Monnier <monnier@iro.umontreal.ca> +2014-04-30 Stefan Monnier <monnier@iro.umontreal.ca> * processes.texi (Filter Functions, Sentinels): Advertise add-function. -2014-04-24 Eli Zaretskii <eliz@gnu.org> +2014-04-29 Stefan Monnier <monnier@iro.umontreal.ca> + + * windows.texi (Window Configurations, Window Configurations): + Window configs don't store marks any more. + +2014-04-25 Eli Zaretskii <eliz@gnu.org> * strings.texi (Text Comparison): Mention equal-including-properties for when text properties of the strings matter for comparison. -2014-04-21 Eli Zaretskii <eliz@gnu.org> +2014-04-22 Eli Zaretskii <eliz@gnu.org> * text.texi (Registers): Document register-read-with-preview. * internals.texi (Building Emacs): Improve indexing. -2014-04-15 Stefan Monnier <monnier@iro.umontreal.ca> +2014-04-17 Daniel Colascione <dancol@dancol.org> - * display.texi (Overlay Properties): Reword the doc of `priority'. - (Finding Overlays): Document new arg of `overlays-at'. + * frames.texi (Terminal Parameters): Document new + tty-mode-set-strings and tty-mode-reset-strings terminal + parameters. -2014-04-05 Glenn Morris <rgm@gnu.org> +2014-04-17 Paul Eggert <eggert@cs.ucla.edu> - * os.texi (Recording Input): Dribble files may contain passwords. + * Makefile.in (infoclean): Be consistent about reporting failures. + +2014-04-09 Daniel Colascione <dancol@dancol.org> + + * errors.texi (Standard Errors): Document required error + parameters for `scan-error'. + + * positions.texi (List Motion): Explain new `up-list' arguments. + Mention `backward-up-list'. -2014-04-04 Glenn Morris <rgm@gnu.org> +2014-04-08 Daniel Colascione <dancol@dancol.org> + + * minibuf.texi (Programmed Completion): Improve phrasing, remove + incorrect bullet count. + +2014-04-07 Glenn Morris <rgm@gnu.org> + + * os.texi (Recording Input): Dribble files may contain passwords. * backups.texi (Making Backups, Reverting): Update for default values of some -function vars no longer being nil. (Reverting): Update for buffer-stale-function also applying to file-buffers. -2014-03-25 Eli Zaretskii <eliz@gnu.org> +2014-03-31 Daniel Colascione <dancol@dancol.org> + + * minibuf.texi (Completion in Buffers): Discuss using lazy + completion tables for inline completion. + +2014-03-28 Glenn Morris <rgm@gnu.org> + + * os.texi (Terminal-Specific): Mention term-file-aliases. + +2014-03-26 Eli Zaretskii <eliz@gnu.org> * files.texi (Kinds of Files): Improve documentation of file-symlink-p. (Bug#17073) Add cross-references. -2014-03-24 Barry O'Reilly <gundaetiapo@gmail.com> +2014-03-26 Barry O'Reilly <gundaetiapo@gmail.com> * markers.texi (Moving Marker Positions): The 2014-03-02 doc change mentioning undo's inability to handle relocated markers no @@ -60,8 +124,18 @@ * text.texi (Undo): Expand documentation of (TEXT . POS) and (MARKER . ADJUSTMENT) undo elements. +2014-03-26 Glenn Morris <rgm@gnu.org> + + * files.texi (File Locks): All systems support locking. + 2014-03-22 Glenn Morris <rgm@gnu.org> + * commands.texi (Defining Commands): + Mention that interactive-only also affects describe-function. + + * functions.texi (Declare Form): Add interactive-only. + * commands.texi (Defining Commands) Mention declare. + * commands.texi (Defining Commands): List interactive-only values. 2014-03-22 Eli Zaretskii <eliz@gnu.org> @@ -69,7 +143,7 @@ * functions.texi (Core Advising Primitives): Fix cross-reference in last change. -2014-03-21 Stefan Monnier <monnier@iro.umontreal.ca> +2014-03-22 Stefan Monnier <monnier@iro.umontreal.ca> * functions.texi (Advising Functions): Explain a bit more how arguments work. diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in index bb8d4f82884..e7bfedfa583 100644 --- a/doc/lispref/Makefile.in +++ b/doc/lispref/Makefile.in @@ -171,7 +171,10 @@ distclean: clean rm -f Makefile infoclean: - -cd $(buildinfodir) && rm -f elisp$(INFO_EXT) elisp$(INFO_EXT)-[1-9] elisp$(INFO_EXT)-[1-9][0-9] + rm -f \ + $(buildinfodir)/elisp$(INFO_EXT) \ + $(buildinfodir)/elisp$(INFO_EXT)-[1-9] \ + $(buildinfodir)/elisp$(INFO_EXT)-[1-9][0-9] maintainer-clean: distclean infoclean diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 38a6970e6f4..721a485382e 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -122,16 +122,19 @@ function symbol's @code{interactive-form} property. A non-@code{nil} value for this property takes precedence over any @code{interactive} form in the function body itself. This feature is seldom used. +@anchor{The interactive-only property} @cindex @code{interactive-only} property Sometimes, a function is only intended to be called interactively, never directly from Lisp. In that case, give the function a -non-@code{nil} @code{interactive-only} property. This causes the -byte compiler to warn if the command is called from Lisp. The value -of the property can be: a string, which the byte-compiler will -use directly in its warning (it should end with a period, -and not start with a capital, e.g. ``use @dots{} instead.''); @code{t}; -any other symbol, which should be an alternative function to use in -Lisp code. +non-@code{nil} @code{interactive-only} property, either directly +or via @code{declare} (@pxref{Declare Form}). This causes the +byte compiler to warn if the command is called from Lisp. The output +of @code{describe-function} will include similar information. +The value of the property can be: a string, which the byte-compiler +will use directly in its warning (it should end with a period, and not +start with a capital, e.g. ``use @dots{} instead.''); @code{t}; any +other symbol, which should be an alternative function to use in Lisp +code. @menu * Using Interactive:: General rules for @code{interactive}. diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index e00496e3478..dba8d219774 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -157,7 +157,10 @@ The message is @samp{Attempt to modify a protected file}. @item scan-error The message is @samp{Scan error}. This happens when certain syntax-parsing functions find invalid syntax or mismatched -parentheses. @xref{List Motion}, and @xref{Parsing Expressions}. +parentheses. Conventionally raised with three argument: a +human-readable error message, the start of the obstacle that cannot be +moved over, and the end of the obstacle. @xref{List Motion}, and +@xref{Parsing Expressions}. @item search-failed The message is @samp{Search failed}. @xref{Searching and Matching}. diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 278b49e51e0..fcfd37e987d 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -709,15 +709,15 @@ some other job. This function locks the file @var{filename}, if the current buffer is modified. The argument @var{filename} defaults to the current buffer's visited file. Nothing is done if the current buffer is not visiting a -file, or is not modified, or if the system does not support locking. +file, or is not modified, or if the option @code{create-lockfiles} is +@code{nil}. @end defun @defun unlock-buffer This function unlocks the file being visited in the current buffer, if the buffer is modified. If the buffer is not modified, then the file should not be locked, so this function does nothing. It also -does nothing if the current buffer is not visiting a file, or if the -system does not support locking. +does nothing if the current buffer is not visiting a file, or is not locked. @end defun @defopt create-lockfiles @@ -1688,6 +1688,16 @@ version of an existing file; saving a file preserves its existing permissions. @end defun +@defmac with-file-modes mode body@dots{} +This macro evaluates the @var{body} forms with the default +permissions for new files temporarily set to @var{modes} (whose value +is as for @code{set-file-modes} above). When finished, it restores +the original default file permissions, and returns the value of the +last form in @var{body}. + +This is useful for creating private files, for example. +@end defmac + @defun default-file-modes This function returns the default file permissions, as an integer. @end defun diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index b6513426909..b95a5ccdb92 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -1334,6 +1334,18 @@ terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}. @item terminal-initted After the terminal is initialized, this is set to the terminal-specific initialization function. +@item tty-mode-set-strings +When present, a list of strings containing escape sequences that Emacs +will output while configuring a tty for rendering. Emacs emits these +strings only when configuring a terminal: if you want to enable a mode +on a terminal that is already active (for example, while in +@code{tty-setup-hook}), explicitly output the necessary escape +sequence using @code{send-string-to-terminal} in addition to adding +the sequence to @code{tty-mode-set-strings}. +@item tty-mode-reset-strings +When present, a list of strings that undo the effects of the strings +in @code{tty-mode-set-strings}. Emacs emits these strings when +exiting, deleting a terminal, or suspending itself. @end table @node Frame Titles diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 019c75ba021..91fdcc63cbe 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1209,7 +1209,7 @@ ways to do it. The added function is also called an @emph{advice}. @menu * Core Advising Primitives:: Primitives to manipulate advice. * Advising Named Functions:: Advising named functions. -* Advice combinators:: Ways to compose advices. +* Advice combinators:: Ways to compose advice. * Porting old advices:: Adapting code using the old defadvice. @end menu @@ -1743,6 +1743,10 @@ Indent calls to this function or macro according to @var{indent-spec}. This is typically used for macros, though it works for functions too. @xref{Indenting Macros}. +@item (interactive-only @var{value}) +Set the function's @code{interactive-only} property to @var{value}. +@xref{The interactive-only property}. + @item (obsolete @var{current-name} @var{when}) Mark the function or macro as obsolete, similar to a call to @code{make-obsolete} (@pxref{Obsolete Functions}). @var{current-name} diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index bfc9d491c5e..3a5bd4aea7e 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -580,15 +580,14 @@ Emacs session. @section C Dialect @cindex C programming language -The C part of Emacs is portable to C89: C99-specific features such as -@samp{<stdbool.h>} and @samp{inline} are not used without a check, +The C part of Emacs is portable to C99 or later: C11-specific features such +as @samp{<stdalign.h>} and @samp{_Noreturn} are not used without a check, typically at configuration time, and the Emacs build procedure -provides a substitute implementation if necessary. Some C99 features, -such as declarations after statements, are too difficult to provide -substitutes for, so they are avoided entirely. +provides a substitute implementation if necessary. Some C11 features, +such as anonymous structures and unions, are too difficult to emulate, +so they are avoided entirely. -At some point in the not-too-distant future the base C dialect will -change from C89 to C99, and eventually it will no doubt change to C11. +At some point in the future the base C dialect will no doubt change to C11. @node Writing Emacs Primitives @section Writing Emacs Primitives diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index cde7d9ce44c..f724d5bd902 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -601,25 +601,6 @@ not a list, the sequence's elements do not become elements of the resulting list. Instead, the sequence becomes the final @sc{cdr}, like any other non-list final argument. -@defun reverse list -This function creates a new list whose elements are the elements of -@var{list}, but in reverse order. The original argument @var{list} is -@emph{not} altered. - -@example -@group -(setq x '(1 2 3 4)) - @result{} (1 2 3 4) -@end group -@group -(reverse x) - @result{} (4 3 2 1) -x - @result{} (1 2 3 4) -@end group -@end example -@end defun - @defun copy-tree tree &optional vecp This function returns a copy of the tree @code{tree}. If @var{tree} is a cons cell, this makes a new cons cell with the same @sc{car} and @@ -1143,58 +1124,6 @@ each time you run it! Here is what happens: @end smallexample @end defun -@defun nreverse list -@cindex reversing a list - This function reverses the order of the elements of @var{list}. -Unlike @code{reverse}, @code{nreverse} alters its argument by reversing -the @sc{cdr}s in the cons cells forming the list. The cons cell that -used to be the last one in @var{list} becomes the first cons cell of the -value. - - For example: - -@example -@group -(setq x '(a b c)) - @result{} (a b c) -@end group -@group -x - @result{} (a b c) -(nreverse x) - @result{} (c b a) -@end group -@group -;; @r{The cons cell that was first is now last.} -x - @result{} (a) -@end group -@end example - - To avoid confusion, we usually store the result of @code{nreverse} -back in the same variable which held the original list: - -@example -(setq x (nreverse x)) -@end example - - Here is the @code{nreverse} of our favorite example, @code{(a b c)}, -presented graphically: - -@smallexample -@group -@r{Original list head:} @r{Reversed list:} - ------------- ------------- ------------ -| car | cdr | | car | cdr | | car | cdr | -| a | nil |<-- | b | o |<-- | c | o | -| | | | | | | | | | | | | - ------------- | --------- | - | -------- | - - | | | | - ------------- ------------ -@end group -@end smallexample -@end defun - @defun sort list predicate @cindex stable sort @cindex sorting lists diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 5b4e29c57a3..19f941ba68d 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -1734,7 +1734,7 @@ possible match, and ignore the match if the predicate returns @item A flag specifying the type of completion operation to perform. This -is one of the following four values: +flag may be one of the following values. @table @code @item nil @@ -1873,11 +1873,34 @@ next function in @code{completion-at-point-functions} instead of reporting a completion failure. @end table +Supplying a function for @var{collection} is strongly recommended if +generating the list of completions is an expensive operation. Emacs +may internally call functions in @code{completion-at-point-functions} +many times, but care about the value of @var{collection} for only some +of these calls. By supplying a function for @var{collection}, Emacs +can defer generating completions until necessary. You can use +@var{completion-table-dynamic} to create a wrapper function: + +@smallexample +;; Avoid this pattern. +(let ((beg ...) (end ...) (my-completions (my-make-completions))) + (list beg end my-completions)) + +;; Use this instead. +(let ((beg ...) (end ...)) + (list beg + end + (completion-table-dynamic + (lambda (_) + (my-make-completions))))) +@end smallexample + A function in @code{completion-at-point-functions} may also return a -function. In that case, that returned function is called, with no -argument, and it is entirely responsible for performing the -completion. We discourage this usage; it is intended to help convert -old code to using @code{completion-at-point}. +function instead of a list as described above. In that case, that +returned function is called, with no argument, and it is entirely +responsible for performing the completion. We discourage this usage; +it is intended to help convert old code to using +@code{completion-at-point}. The first function in @code{completion-at-point-functions} to return a non-@code{nil} value is used by @code{completion-at-point}. The diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index c80dfda096c..b63b932b4da 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -430,10 +430,13 @@ This variable holds the name of the @file{.emacs.d} directory. It is run on that type of terminal. The library's name is constructed by concatenating the value of the variable @code{term-file-prefix} and the terminal type (specified by the environment variable @env{TERM}). -Normally, @code{term-file-prefix} has the value -@code{"term/"}; changing this is not recommended. Emacs finds the file -in the normal manner, by searching the @code{load-path} directories, and -trying the @samp{.elc} and @samp{.el} suffixes. +Normally, @code{term-file-prefix} has the value @code{"term/"}; +changing this is not recommended. If there is an entry matching +@env{TERM} in the @code{term-file-aliases} association list, +Emacs uses the associated value in place of @env{TERM}. +Emacs finds the file in the normal manner, by searching the +@code{load-path} directories, and trying the @samp{.elc} and +@samp{.el} suffixes. @cindex Termcap The usual role of a terminal-specific library is to enable special @@ -462,7 +465,7 @@ a normal hook that Emacs runs after initializing a new text terminal. You could use this hook to define initializations for terminals that do not have their own libraries. @xref{Hooks}. -@defvar term-file-prefix +@defopt term-file-prefix @cindex @env{TERM} environment variable If the value of this variable is non-@code{nil}, Emacs loads a terminal-specific initialization file as follows: @@ -477,7 +480,14 @@ init file if you do not wish to load the terminal-initialization file. On MS-DOS, Emacs sets the @env{TERM} environment variable to @samp{internal}. -@end defvar +@end defopt + +@defopt term-file-aliases +This variable is an an association list mapping terminal types to +their aliases. For example, an element of the form @code{("vt102" +. "vt100")} means to treat a terminal of type @samp{vt102} like one of +type @samp{vt100}. +@end defopt @defvar tty-setup-hook This variable is a normal hook that Emacs runs after initializing a diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index f83173e2038..5a77b37e7e1 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -647,9 +647,19 @@ parentheses. (Other syntactic entities such as words or paired string quotes are ignored.) @end deffn -@deffn Command up-list &optional arg -This function moves forward out of @var{arg} (default 1) levels of parentheses. -A negative argument means move backward but still to a less deep spot. +@deffn Command up-list &optional arg escape-strings no-syntax-crossing +This function moves forward out of @var{arg} (default 1) levels of +parentheses. A negative argument means move backward but still to a +less deep spot. If @var{escape-strings} is non-nil (as it is +interactively), move out of enclosing strings as well. If +@var{no-syntax-crossing} is non-nil (as it is interactively), prefer +to break out of any enclosing string instead of moving to the start of +a list broken across multiple strings. On error, location of point is +unspecified. +@end deffn + +@deffn Command backward-up-list &optional arg escape-strings no-syntax-crossing +This function is just like @code{up-list}, but with a negated argument. @end deffn @deffn Command down-list &optional arg diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 01de4ccb0cd..cafdb7fc53d 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -217,6 +217,116 @@ y @result{} [foo (69 2)] @end example @end defun +@defun reverse seq +@cindex string reverse +@cindex list reverse +@cindex vector reverse +@cindex sequence reverse +This function creates a new sequence whose elements are the elements +of @var{seq}, but in reverse order. The original argument @var{seq} +is @emph{not} altered. Note that char-table cannot be reversed. + +@example +@group +(setq x '(1 2 3 4)) + @result{} (1 2 3 4) +@end group +@group +(reverse x) + @result{} (4 3 2 1) +x + @result{} (1 2 3 4) +@end group +@group +(setq x [1 2 3 4]) + @result{} [1 2 3 4] +@end group +@group +(reverse x) + @result{} [4 3 2 1] +x + @result{} [1 2 3 4] +@end group +@group +(setq x "xyzzy") + @result{} "xyzzy" +@end group +@group +(reverse x) + @result{} "yzzyx" +x + @result{} "xyzzy" +@end group +@end example +@end defun + +@defun nreverse seq +@cindex reversing a string +@cindex reversing a list +@cindex reversing a vector + This function reverses the order of the elements of @var{seq}. +Unlike @code{reverse} the original @var{seq} may be modified. + + For example: + +@example +@group +(setq x '(a b c)) + @result{} (a b c) +@end group +@group +x + @result{} (a b c) +(nreverse x) + @result{} (c b a) +@end group +@group +;; @r{The cons cell that was first is now last.} +x + @result{} (a) +@end group +@end example + + To avoid confusion, we usually store the result of @code{nreverse} +back in the same variable which held the original list: + +@example +(setq x (nreverse x)) +@end example + + Here is the @code{nreverse} of our favorite example, @code{(a b c)}, +presented graphically: + +@smallexample +@group +@r{Original list head:} @r{Reversed list:} + ------------- ------------- ------------ +| car | cdr | | car | cdr | | car | cdr | +| a | nil |<-- | b | o |<-- | c | o | +| | | | | | | | | | | | | + ------------- | --------- | - | -------- | - + | | | | + ------------- ------------ +@end group +@end smallexample + + For the vector, it is even simpler because you don't need setq: + +@example +(setq x [1 2 3 4]) + @result{} [1 2 3 4] +(nreverse x) + @result{} [4 3 2 1] +x + @result{} [4 3 2 1] +@end example + +Note that unlike @code{reverse}, this function doesn't work with strings. +Although you can alter string data by using @code{aset}, it is strongly +encouraged to treat strings as immutable. + +@end defun + @node Arrays @section Arrays @cindex array @@ -699,7 +809,7 @@ value into an element of the bool-vector, the effect is to store and the length cannot be changed once the bool-vector is created. Bool-vectors are constants when evaluated. - There are two special functions for working with bool-vectors; aside + Several functions work specifically with bool-vectors; aside from that, you manipulate them with same functions used for other kinds of arrays. @@ -708,6 +818,11 @@ Return a new bool-vector of @var{length} elements, each one initialized to @var{initial}. @end defun +@defun bool-vector &rest objects +This function creates and returns a bool-vector whose elements are the +arguments, @var{objects}. +@end defun + @defun bool-vector-p object This returns @code{t} if @var{object} is a bool-vector, and @code{nil} otherwise. @@ -761,9 +876,29 @@ or @code{nil}, and @var{i} is an index into @code{a}. Return the number of elements that are @code{t} in bool vector @var{a}. @end defun - Here is an example of creating, examining, and updating a -bool-vector. Note that the printed form represents up to 8 boolean -values as a single character. + The printed form represents up to 8 boolean values as a single +character: + +@example +@group +(bool-vector t nil t nil) + @result{} #&4"^E" +(bool-vector) + @result{} #&0"" +@end group +@end example + +You can use @code{vconcat} to print a bool-vector like other vectors: + +@example +@group +(vconcat (bool-vector nil t nil t)) + @result{} [nil t nil t] +@end group +@end example + + Here is another example of creating, examining, and updating a +bool-vector: @example (setq bv (make-bool-vector 5 t)) diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index e4177836fa8..f2fe5c85a93 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -3655,7 +3655,7 @@ This function returns the top pixel edge of window @var{window}. A @dfn{window configuration} records the entire layout of one frame---all windows, their sizes, which buffers they contain, how those -buffers are scrolled, and their values of point and the mark; also their +buffers are scrolled, and their value of point; also their fringes, margins, and scroll bar settings. It also includes the value of @code{minibuffer-scroll-window}. As a special exception, the window configuration does not record the value of point in the selected window @@ -3731,13 +3731,13 @@ This function returns @code{t} if @var{object} is a window configuration. @defun compare-window-configurations config1 config2 This function compares two window configurations as regards the -structure of windows, but ignores the values of point and mark and the +structure of windows, but ignores the values of point and the saved scrolling positions---it can return @code{t} even if those aspects differ. The function @code{equal} can also compare two window configurations; it regards configurations as unequal if they differ in any respect, even a -saved point or mark. +saved point. @end defun @defun window-configuration-frame config diff --git a/doc/man/emacs.1 b/doc/man/emacs.1 index 12dc0707ed0..45bdb64d8b0 100644 --- a/doc/man/emacs.1 +++ b/doc/man/emacs.1 @@ -1,5 +1,5 @@ .\" See section COPYING for copyright and redistribution information. -.TH EMACS 1 "2007 April 13" "GNU Emacs 24.3.91" +.TH EMACS 1 "2007 April 13" "GNU Emacs 24.4.50" . . .SH NAME diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index ca0a3c4faa5..a0aa2879b5f 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,9 +1,13 @@ -2014-05-24 Paul Eggert <eggert@cs.ucla.edu> +2014-05-27 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update from gnulib. + +2014-05-26 Paul Eggert <eggert@cs.ucla.edu> Specify coding if Latin-1 Emacs would misinterpret (Bug#17575). * htmlfontify.texi, org.texi: Add "coding: utf-8". -2014-05-23 Stephen Berman <stephen.berman@gmx.net> +2014-05-26 Stephen Berman <stephen.berman@gmx.net> * todo-mode.texi: Update in light of changes due to bug#17482. Replace numerous mistaken uses of literal quotes with proper @@ -11,23 +15,36 @@ (Todo Mode Entry Points): Comment out reference to using find-file or Dired to visit Todo files, since this has been disabled (bug#17482). -2014-05-06 Michael Albinus <michael.albinus@gmx.de> +2014-05-20 Leo Liu <sdl.web@gmail.com> + + * cl.texi (List Functions, Efficiency Concerns): Update cl-endp. + +2014-05-13 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update from gnulib. + +2014-05-08 Michael Albinus <michael.albinus@gmx.de> * tramp.texi (Frequently Asked Questions): Mention HISTFILE setting in ~/.ssh/environment. -2014-05-02 Stephen Berman <stephen.berman@gmx.net> +2014-05-04 Stephen Berman <stephen.berman@gmx.net> * todo-mode.texi: Update, improve exposition, add cross references, fix typos. (Inserting New Items, Editing Item Headers and Text): Rewrite to document new user interface. -2014-05-01 Glenn Morris <rgm@gnu.org> +2014-05-04 Glenn Morris <rgm@gnu.org> * autotype.texi (Skeleton Language): * message.texi (Header Commands): Replace `iff'. +2014-05-02 Paul Eggert <eggert@cs.ucla.edu> + + * vhdl-mode.texi: Add "@documentencoding UTF-8", + since this is a toplevel .texi file. + 2014-04-22 Bastien Guerry <bzg@gnu.org> * org.texi (Installation): Be more clear on why installing Org @@ -56,14 +73,71 @@ * org.texi (Top, Exporting): Org has its own documentation and should therefore be removed from "Other build-in back-ends". +2014-04-22 Stefan Monnier <monnier@iro.umontreal.ca> + + * cl.texi (Structures): Remove cl-struct-set-slot-value. + +2014-04-20 Daniel Colascione <dancol@dancol.org> + + * cl.texi (Declarations): Document changes to `cl-the' and defstruct functions. + +2014-04-17 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in (infoclean): Be consistent about reporting failures. + +2014-03-27 Glenn Morris <rgm@gnu.org> + + * Makefile.in (INFO_COMMON): Add vhdl-mode. + (vhdl_mode_deps, vhdl-mode, $(buildinfodir)/vhdl-mode$(INFO_EXT)) + (vhdl-mode.dvi, vhdl-mode.pdf, vhdl-mode.html): New rules/variables. + + * vhdl-mode.texi: General clean-up. Set copyright to FSF, add license. + Remove hand-written node pointers. Remove info re old Emacs versions. + Markup fixes. + (Getting Connected): Remove irrelevant info. + (Indentation Commands, Requirements): Remove empty/irrelevant nodes. + (Frequently Asked Questions): Electric indent is now enabled. + +2014-03-27 Reto Zimmermann <reto@gnu.org> + Rod Whitby <software.vhdl-mode@rwhitby.net> + + * vhdl-mode.texi: New file, imported from upstream vhdl-mode. + 2014-03-26 Paul Eggert <eggert@cs.ucla.edu> * texinfo.tex: Update from gnulib. -2014-03-24 Michael Albinus <michael.albinus@gmx.de> +2014-03-26 Michael Albinus <michael.albinus@gmx.de> * tramp.texi (Frequently Asked Questions): Add fish shell settings. +2014-03-23 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Ma Gnus): Mention header attachment buttons. + +2014-03-23 Lars Ingebrigtsen <larsi@gnus.org> + + * emacs-mime.texi (MML Definition): Document recipient-filename. + +2014-03-23 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (MIME Commands): Mention + gnus-mime-buttonize-attachments-in-header and + gnus-mime-display-attachment-buttons-in-header. + +2014-03-23 Lars Ingebrigtsen <larsi@gnus.org> + + * message.texi (Forwarding): Mention + `message-forward-included-headers'. + +2014-03-23 Lars Ingebrigtsen <larsi@gnus.org> + + * gnus.texi: w3 is no longer supported by Gnus. + +2014-03-22 Glenn Morris <rgm@gnu.org> + + * efaq.texi (Informational files for Emacs): Do not mention etc/GNU. + 2014-03-21 Glenn Morris <rgm@gnu.org> * ede.texi (ede-linux): diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index e5f56be5016..f74d7eaa2d1 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -70,7 +70,7 @@ INFO_COMMON = ada-mode auth autotype bovine calc ccmode cl \ mairix-el message mh-e newsticker nxml-mode octave-mode \ org pcl-cvs pgg rcirc remember reftex sasl \ sc semantic ses sieve smtpmail speedbar srecode todo-mode tramp \ - url vip viper widget wisent woman + url vhdl-mode vip viper widget wisent woman ## Info files to install on current platform. INFO_INSTALL = $(INFO_COMMON) $(DOCMISC_INFO_W32) @@ -792,6 +792,18 @@ url.pdf: $(url_deps) url.html: $(url_deps) $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/url.texi +vhdl_mode_deps = ${srcdir}/vhdl-mode.texi ${gfdl} +vhdl-mode : $(buildinfodir)/vhdl-mode$(INFO_EXT) +$(buildinfodir)/vhdl-mode$(INFO_EXT): $(vhdl_mode_deps) + $(mkinfodir) + $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/vhdl-mode.texi +vhdl-mode.dvi: $(vhdl_mode_deps) + $(ENVADD) $(TEXI2DVI) ${srcdir}/vhdl-mode.texi +vhdl-mode.pdf: $(vhdl_mode_deps) + $(ENVADD) $(TEXI2PDF) ${srcdir}/vhdl-mode.texi +vhdl-mode.html: $(vhdl_mode_deps) + $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/vhdl-mode.texi + vip_deps = ${srcdir}/vip.texi ${gfdl} vip : $(buildinfodir)/vip$(INFO_EXT) $(buildinfodir)/vip$(INFO_EXT): $(vip_deps) @@ -870,9 +882,12 @@ distclean: clean ## buildinfodir is relative to srcdir. infoclean: - cd $(buildinfodir); for file in $(INFO_TARGETS); do \ + for file in $(INFO_TARGETS); do \ file=`echo $${file} | sed 's/\.info$$//'`${INFO_EXT}; \ - rm -f $${file} $${file}-[1-9] $${file}-[1-9][0-9]; \ + rm -f \ + $(buildinfodir)/$${file} \ + $(buildinfodir)/$${file}-[1-9] \ + $(buildinfodir)/$${file}-[1-9][0-9]; \ done maintainer-clean: distclean infoclean diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 4eb8508fd3c..83e007d8975 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -2627,10 +2627,10 @@ In this package, @code{cl-locally} is no different from @code{progn}. @end defmac @defmac cl-the type form -Type information provided by @code{cl-the} is ignored in this package; -in other words, @code{(cl-the @var{type} @var{form})} is equivalent to -@var{form}. Future byte-compiler optimizations may make use of this -information. +@code{cl-the} returns the value of @code{form}, first checking (if +optimization settings permit) that it is of type @code{type}. Future +byte-compiler optimizations may also make use of this information to +improve runtime efficiency. For example, @code{mapcar} can map over both lists and arrays. It is hard for the compiler to expand @code{mapcar} into an in-line loop @@ -3679,10 +3679,8 @@ This function is a synonym for @code{(cdr @var{x})}. @end defun @defun cl-endp x -Common Lisp defines this function to act like @code{null}, but -signaling an error if @code{x} is neither a @code{nil} nor a -cons cell. This package simply defines @code{cl-endp} as a synonym -for @code{null}. +This function acts like @code{null}, but signals an error if @code{x} +is neither a @code{nil} nor a cons cell. @end defun @defun cl-list-length x @@ -4247,6 +4245,40 @@ of the included type and the first new slot. Except as noted, the @code{cl-defstruct} facility of this package is entirely compatible with that of Common Lisp. +The @code{cl-defstruct} package also provides a few structure +introspection functions. + +@defun cl-struct-sequence-type struct-type +This function returns the underlying data structure for +@code{struct-type}, which is a symbol. It returns @code{vector} or +@code{list}, or @code{nil} if @code{struct-type} is not actually a +structure. +@end defun + +@defun cl-struct-slot-info struct-type +This function returns a list of slot descriptors for structure +@code{struct-type}. Each entry in the list is @code{(name . opts)}, +where @code{name} is the name of the slot and @code{opts} is the list +of slot options given to @code{defstruct}. Dummy entries represent +the slots used for the struct name and that are skipped to implement +@code{:initial-offset}. +@end defun + +@defun cl-struct-slot-offset struct-type slot-name +Return the offset of slot @code{slot-name} in @code{struct-type}. The +returned zero-based slot index is relative to the start of the +structure data type and is adjusted for any structure name and +:initial-offset slots. Signal error if struct @code{struct-type} does +not contain @code{slot-name}. +@end defun + +@defun cl-struct-slot-value struct-type slot-name inst +Return the value of slot @code{slot-name} in @code{inst} of +@code{struct-type}. @code{struct} and @code{slot-name} are symbols. +@code{inst} is a structure instance. This routine is also a +@code{setf} place. Can signal the same errors as @code{cl-struct-slot-offset}. +@end defun + @node Assertions @chapter Assertions and Errors @@ -4415,12 +4447,11 @@ supposed to arise in complying programs; implementations are strongly encouraged but not required to signal an error in these situations. This package sometimes omits such error checking in the interest of compactness and efficiency. For example, @code{cl-do} variable -specifiers are supposed to be lists of one, two, or three forms; -extra forms are ignored by this package rather than signaling a -syntax error. The @code{cl-endp} function is simply a synonym for -@code{null} in this package. Functions taking keyword arguments -will accept an odd number of arguments, treating the trailing -keyword as if it were followed by the value @code{nil}. +specifiers are supposed to be lists of one, two, or three forms; extra +forms are ignored by this package rather than signaling a syntax +error. Functions taking keyword arguments will accept an odd number +of arguments, treating the trailing keyword as if it were followed by +the value @code{nil}. Argument lists (as processed by @code{cl-defun} and friends) @emph{are} checked rigorously except for the minor point just diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi index 51d2cc00d5a..2e136017039 100644 --- a/doc/misc/efaq.texi +++ b/doc/misc/efaq.texi @@ -861,7 +861,6 @@ You can get Tkinfo at @cindex Files included with Emacs @cindex @file{COPYING}, description of file @cindex @file{DISTRIB}, description of file -@cindex @file{GNU}, description of file @cindex @file{MACHINES}, description of file @cindex @file{NEWS}, description of file @@ -883,9 +882,6 @@ GNU General Public License @item DISTRIB Emacs Availability Information -@item GNU -The GNU Manifesto - @item MACHINES Status of Emacs on Various Machines and Systems diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi index 19cdd43882e..bb831f5deda 100644 --- a/doc/misc/emacs-mime.texi +++ b/doc/misc/emacs-mime.texi @@ -405,7 +405,7 @@ variable will cause @samp{text/html} parts to be treated as attachments. @item mm-text-html-renderer @vindex mm-text-html-renderer This selects the function used to render @acronym{HTML}. The predefined -renderers are selected by the symbols @code{gnus-article-html}, @code{w3}, +renderers are selected by the symbols @code{gnus-article-html}, @code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more information about emacs-w3m}, @code{links}, @code{lynx}, @code{w3m-standalone} or @code{html2text}. If @code{nil} use an @@ -418,11 +418,11 @@ Some @acronym{HTML} mails might have the trick of spammers using @samp{<img>} tags. It is likely to be intended to verify whether you have read the mail. You can prevent your personal information from leaking by setting this option to @code{nil} (which is the default). -It is currently ignored by Emacs/w3. For emacs-w3m, you may use the -command @kbd{t} on the image anchor to show an image even if it is -@code{nil}.@footnote{The command @kbd{T} will load all images. If you -have set the option @code{w3m-key-binding} to @code{info}, use @kbd{i} -or @kbd{I} instead.} +For emacs-w3m, you may use the command @kbd{t} on the image anchor to +show an image even if it is @code{nil}.@footnote{The command @kbd{T} +will load all images. If you have set the option +@code{w3m-key-binding} to @code{info}, use @kbd{i} or @kbd{I} +instead.} @item mm-w3m-safe-url-regexp @vindex mm-w3m-safe-url-regexp @@ -648,6 +648,12 @@ The @acronym{MIME} type of the part (@code{Content-Type}). Use the contents of the file in the body of the part (@code{Content-Disposition}). +@item recipient-filename +Use this as the file name in the generated @acronym{MIME} message for +the recipient. That is, even if the file is called @file{foo.txt} +locally, use this name instead in the @code{Content-Disposition} in +the sent message. + @item charset The contents of the body of the part are to be encoded in the character set specified (@code{Content-Type}). @xref{Charset Translation}. diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi index 858ce8c2a50..a053164691f 100644 --- a/doc/misc/gnus-faq.texi +++ b/doc/misc/gnus-faq.texi @@ -723,7 +723,7 @@ POP3 mail source. See @pxref{Mail Source Specifiers} for VALUE. the top of the article buffer? * FAQ 4-6:: I'd like Gnus NOT to render HTML-mails but show me the text part if it's available. How to do it? -* FAQ 4-7:: Can I use some other browser than w3 to render my +* FAQ 4-7:: Can I use some other browser than shr to render my HTML-mails? * FAQ 4-8:: Is there anything I can do to make poorly formatted mails more readable? @@ -868,12 +868,12 @@ too. @node FAQ 4-7 @subsubheading Question 4.7 -Can I use some other browser than w3 to render my HTML-mails? +Can I use some other browser than w3m to render my HTML-mails? @subsubheading Answer Only if you use Gnus 5.10 or younger. In this case you've got the -choice between w3, w3m, links, lynx and html2text, which +choice between shr, w3m, links, lynx and html2text, which one is used can be specified in the variable mm-text-html-renderer, so if you want links to render your mail say diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index fa8078a2867..b2dce6db2bc 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -704,7 +704,6 @@ Browsing the Web * Archiving Mail:: * Web Searches:: Creating groups from articles that match a string. * RSS:: Reading RDF site summary. -* Customizing W3:: Doing stuff to Emacs/W3 from Gnus. Other Sources @@ -9140,9 +9139,6 @@ Use Gnus simple html renderer. @item gnus-w3m Use Gnus rendered based on w3m. -@item w3 -Use Emacs/W3. - @item w3m Use @uref{http://emacs-w3m.namazu.org/, emacs-w3m}. @@ -9805,6 +9801,19 @@ Make all the @acronym{MIME} parts have buttons in front of them. This is mostly useful if you wish to save (or perform other actions) on inlined parts. +@item W M h +@kindex W M h (Summary) +@findex gnus-mime-buttonize-attachments-in-header +@vindex gnus-mime-display-attachment-buttons-in-header +Display @acronym{MIME} part buttons in the end of the header of an +article (@code{gnus-mime-buttonize-attachments-in-header}). This +command toggles the display. Note that buttons to be added to the +header are only the ones that aren't inlined in the body. If you want +those buttons always to be displayed, set +@code{gnus-mime-display-attachment-buttons-in-header} to non-@code{nil}. +The default is @code{t}. To change the appearance of buttons, customize +@code{gnus-header-face-alist}. + @item K m @kindex K m (Summary) @findex gnus-summary-repair-multipart @@ -16841,12 +16850,8 @@ interfaces to these sources. * Archiving Mail:: * Web Searches:: Creating groups from articles that match a string. * RSS:: Reading RDF site summary. -* Customizing W3:: Doing stuff to Emacs/W3 from Gnus. @end menu -All the web sources require Emacs/W3 and the url library or those -alternatives to work. - The main caveat with all these web sources is that they probably won't work for a very long time. Gleaning information from the @acronym{HTML} data is guesswork at best, and when the layout is altered, the Gnus back end @@ -16922,10 +16927,6 @@ make money off of advertisements, not to provide services to the community. Since @code{nnweb} washes the ads off all the articles, one might think that the providers might be somewhat miffed. We'll see. -You must have the @code{url} and @code{W3} package or those alternatives -(try @code{customize-group} on the @samp{mm-url} variable group) -installed to be able to use @code{nnweb}. - Virtual server variables: @table @code @@ -17123,38 +17124,6 @@ Parameters}) in order to display @samp{text/html} parts only in @end lisp -@node Customizing W3 -@subsection Customizing W3 -@cindex W3 -@cindex html -@cindex url -@cindex Netscape - -Gnus uses the url library to fetch web pages and Emacs/W3 (or those -alternatives) to display web pages. Emacs/W3 is documented in its own -manual, but there are some things that may be more relevant for Gnus -users. - -For instance, a common question is how to make Emacs/W3 follow links -using the @code{browse-url} functions (which will call some external web -browser like Netscape). Here's one way: - -@lisp -(eval-after-load "w3" - '(progn - (fset 'w3-fetch-orig (symbol-function 'w3-fetch)) - (defun w3-fetch (&optional url target) - (interactive (list (w3-read-url-with-default))) - (if (eq major-mode 'gnus-article-mode) - (browse-url url) - (w3-fetch-orig url target))))) -@end lisp - -Put that in your @file{.emacs} file, and hitting links in W3-rendered -@acronym{HTML} in the Gnus article buffers will use @code{browse-url} to -follow the link. - - @node Other Sources @section Other Sources @@ -26338,7 +26307,7 @@ XEmacs is distributed as a collection of packages. You should install whatever packages the Gnus XEmacs package requires. The current requirements are @samp{gnus}, @samp{mail-lib}, @samp{xemacs-base}, @samp{eterm}, @samp{sh-script}, @samp{net-utils}, @samp{os-utils}, -@samp{dired}, @samp{mh-e}, @samp{sieve}, @samp{ps-print}, @samp{W3}, +@samp{dired}, @samp{mh-e}, @samp{sieve}, @samp{ps-print}, @samp{pgg}, @samp{mailcrypt}, @samp{ecrypto}, and @samp{sasl}. @@ -28415,6 +28384,19 @@ New features in Ma Gnus: @itemize @bullet +@item Changes in summary and article mode +@c ************************************** + +@itemize @bullet + +@item +By default, @acronym{MIME} part buttons for attachments (if any) will +appear in the end of the article header in addition to the bottom of the +article body, so you can easily find them without scrolling the article +again and again. @xref{MIME Commands}. + +@end itemize + @item Changes in Message mode and related Gnus features @c **************************************************** diff --git a/doc/misc/message.texi b/doc/misc/message.texi index 700acfc9b54..88d8566137a 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -310,7 +310,13 @@ news. @table @code @item message-forward-ignored-headers @vindex message-forward-ignored-headers -All headers that match this regexp will be deleted when forwarding a message. +In non-@code{nil}, all headers that match this regexp will be deleted +when forwarding a message. + +@item message-forward-included-headers +@vindex message-forward-included-headers +In non-@code{nil}, only headers that match this regexp will be kept +when forwarding a message. @item message-make-forward-subject-function @vindex message-make-forward-subject-function diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index 0f2673c849e..6312dadbce0 100644 --- a/doc/misc/texinfo.tex +++ b/doc/misc/texinfo.tex @@ -3,7 +3,7 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2014-03-17.07} +\def\texinfoversion{2014-05-20.16} % % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, @@ -2146,7 +2146,7 @@ end \let\tenttsl=\secttsl \def\curfontsize{sec}% \def\lsize{subsec}\def\lllsize{reduced}% - \resetmathfonts \setleading{16pt}} + \resetmathfonts \setleading{17pt}} \def\subsecfonts{% \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc @@ -8856,20 +8856,20 @@ end { \catcode`\_ = \active \globaldefs=1 -\parseargdef\documentlanguage{\begingroup - \let_=\normalunderscore % normal _ character for filenames +\parseargdef\documentlanguage{% \tex % read txi-??.tex file in plain TeX. % Read the file by the name they passed if it exists. + \let_ = \normalunderscore % normal _ character for filename test \openin 1 txi-#1.tex \ifeof 1 - \documentlanguagetrywithoutunderscore{#1_\finish}% + \documentlanguagetrywithoutunderscore #1_\finish \else \globaldefs = 1 % everything in the txi-LL files needs to persist \input txi-#1.tex \fi \closein 1 \endgroup % end raw TeX -\endgroup} +} % % If they passed de_DE, and txi-de_DE.tex doesn't exist, % try txi-de.tex. diff --git a/doc/misc/vhdl-mode.texi b/doc/misc/vhdl-mode.texi new file mode 100644 index 00000000000..5b01afc4664 --- /dev/null +++ b/doc/misc/vhdl-mode.texi @@ -0,0 +1,1022 @@ +\input texinfo @c -*- texinfo -*- + +@setfilename ../../info/vhdl-mode +@settitle VHDL Mode, an Emacs mode for editing VHDL code +@documentencoding UTF-8 + +@c Adapted from the VHDL Mode texinfo manual version 2 by Rodney J. Whitby. +@c Adapted from the CC Mode texinfo manual by Barry A. Warsaw. + +@copying +This file documents VHDL Mode, an Emacs mode for editing VHDL code. + +Copyright @copyright{} 1995--2008, 2010, 2012, 2014 Free Software +Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License.'' + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual.'' +@end quotation +@end copying + +@dircategory Emacs editing modes +@direntry +* VHDL Mode: (vhdl-mode). Emacs mode for editing VHDL code. +@end direntry + +@finalout + +@titlepage +@title VHDL Mode +@sp 2 +@subtitle A GNU Emacs mode for editing VHDL code. +@sp 2 +@author Reto Zimmermann +@author @email{reto@@gnu.org} +@author Rod Whitby +@author @email{software.vhdl-mode@@rwhitby.net} + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top VHDL Mode, an Emacs mode for editing VHDL code + +@insertcopying +@end ifnottex + +@menu +* Introduction:: +* Getting Connected:: +* New Indentation Engine:: +* Customizing Indentation:: +* Syntactic Symbols:: +* Frequently Asked Questions:: +* Getting the latest VHDL Mode release:: +* Sample .emacs File:: +* Limitations and Known Bugs:: +* Mailing Lists and Submitting Bug Reports:: +* GNU Free Documentation License:: The license for this documentation. +* Concept Index:: +* Command Index:: Command Index +* Key Index:: Key Index +* Variable Index:: Variable Index +@end menu + +@node Introduction +@chapter Introduction +@cindex Introduction + +Welcome to VHDL Mode. This is a GNU Emacs mode for editing files +containing VHDL code. + +This manual will describe the following: + +@itemize @bullet +@item +How to get started using VHDL Mode. + +@item +How the indentation engine works. + +@item +How to customize the indentation engine. + +@end itemize + +@findex vhdl-version +The major version number was incremented to 3 with the addition of +many new features for editing VHDL code to the new indentation engine, +which was introduced in major version 2. To find the minor revision +number of this release, use @kbd{M-x vhdl-version RET}. + +A special word of thanks goes to Rod Whitby, who wrote the +VHDL Mode indentation engine, and to Barry Warsaw, who wrote +the CC Mode indentation engine that formed the basis +thereof. Their manuals were also the basis for this manual. + +This manual is not very up-to-date. It basically contains the +indentation machine documentation by Rod Whitby with only minor +adaptions. A short documentation of the entire VHDL Mode is available +within the mode itself by typing @kbd{C-c C-h}. Also, all commands and +customization of most variables are available through the menu, which +makes everything highly self-explaining. + +@node Getting Connected +@chapter Getting Connected +@cindex Getting Connected + +To get started, simply visit a @file{.vhd} file in Emacs; or type +@kbd{M-x vhdl-mode RET}. + +@node New Indentation Engine +@chapter New Indentation Engine +@cindex New Indentation Engine + +VHDL Mode has a new indentation engine, providing a simplified, yet +flexible and general mechanism for customizing indentation. It breaks +indentation calculation into two steps. First for the line of code being +indented, VHDL Mode analyzes what kind of language construct it's +looking at, then it applies user defined offsets to the current line +based on this analysis. + +This section will briefly cover how indentation is calculated in +VHDL Mode. It is important to understand the indentation model +being used so that you will know how to customize VHDL Mode for +your personal coding style. + +@menu +* Syntactic Analysis:: Step 1 -- Syntactic Analysis +* Indentation Calculation:: Step 2 -- Indentation Calculation +@end menu + +@node Syntactic Analysis +@section Syntactic Analysis +@cindex Syntactic Analysis + +@vindex vhdl-offsets-alist +@vindex offsets-alist (vhdl-) +@cindex relative buffer position +@cindex syntactic symbol +@cindex syntactic component +@cindex syntactic component list +@cindex relative buffer position +The first thing VHDL Mode does when indenting a line of code, is +to analyze the line, determining the @dfn{syntactic component list} of +the construct on that line. A @dfn{syntactic component} consists of a +pair of information (in lisp parlance, a @emph{cons cell}), where the +first part is a @dfn{syntactic symbol}, and the second part is a +@dfn{relative buffer position}. Syntactic symbols describe elements of +VHDL code, e.g. @code{statement}, @code{comment}, @code{block-open}, +@code{block-close}, etc. @xref{Syntactic Symbols}, for a complete list +of currently recognized syntactic symbols and their semantics. Also, +the variable @code{vhdl-offsets-alist} contains the list of currently +supported syntactic symbols. + +Conceptually, a line of VHDL code is always indented relative to the +indentation of some line higher up in the buffer. This is represented +by the relative buffer position in the syntactic component. + +It might help to see an example. Suppose we had the following code as +the only thing in a VHDL Mode buffer @footnote{The line numbers +in this and future examples don't actually appear in the buffer.}: +@example +@group + + 1: inverter : process + 2: begin + 3: q <= not d; + 4: wait on d; + 5: end inverter; + +@end group +@end example + +@kindex C-c C-x +@findex vhdl-show-syntactic-information +@findex show-syntactic-information (vhdl-) +We can use the command @kbd{C-c C-x} +(@code{vhdl-show-syntactic-information}) to simply report what the +syntactic analysis is for the current line. Running this command on +line 4 of example 1, we'd see in the echo area: +@example + +((statement . 28)) + +@end example + +This tells us that the line is a statement and it is indented relative +to buffer position 28, which happens to be the @samp{q} on line 3. If +you were to move point to line 3 and hit @kbd{C-c C-x}, you would see: +@example + +((statement-block-intro . 20)) + +@end example + +This indicates that line 3 is the first statement in a block, and is +indented relative to buffer position 20, which is the @samp{b} in the +@code{begin} keyword on line 2. + +@cindex comment only line +Syntactic component lists can contain more than one component, and +individual syntactic compenents need not have relative buffer positions. +The most common example of this is a line that contains a @dfn{comment +only line}. +@example +@group + +%%% TBD %%% + +@end group +@end example + +@noindent +Hitting @kbd{C-c C-x} on line 3 of the example gives us: +@example + +((comment-intro) (block-intro . 46)) + +@end example + +@noindent +so you can see that the syntactic component list contains two syntactic +components. Also notice that the first component, +@samp{(comment-intro)} has no relative buffer position. + +@node Indentation Calculation +@section Indentation Calculation +@cindex Indentation Calculation + +@vindex vhdl-offsets-alist +@vindex offsets-alist (vhdl-) +Indentation for the current line is calculated using the syntactic +component list derived in step 1 above (see @ref{Syntactic +Analysis}). Each component contributes to the final total indentation +of the line in two ways. + +First, the syntactic symbols are looked up in the @code{vhdl-offsets-alist} +variable, which is an association list of syntactic symbols and the +offsets to apply for those symbols. These offsets are added to the +running total. + +Second, if the component has a relative buffer position, VHDL Mode +adds the column number of that position to the running total. By adding +up the offsets and columns for every syntactic component on the list, +the final total indentation for the current line is computed. + +Let's use our code example above to see how this works. Here is our +example again. +@example +@group + + 1: inverter : process + 2: begin + 3: q <= not d; + 4: wait on d; + 5: end inverter; + +@end group +@end example + +@kindex TAB +Let's say point is on line 3 and we hit the @key{TAB} key to re-indent +the line. Remember that the syntactic component list for that +line is: +@example + +((statement-block-intro . 20)) + +@end example + +@noindent +VHDL Mode looks up @code{statement-block-intro} in the +@code{vhdl-offsets-alist} variable. Let's say it finds the value @samp{2}; +it adds this to the running total (initialized to zero), yielding a +running total indentation of 2 spaces. + +Next VHDL Mode goes to buffer position 20 and asks for the +current column. Since the @code{begin} keyword at buffer position 20 is +in column zero, it adds @samp{0} to the running total. Since there is +only one syntactic component on the list for this line, indentation +calculation is complete, and the total indentation for the line is 2 +spaces. +Simple, huh? + +Actually, the mode usually just does The Right Thing without you having +to think about it in this much detail. But when customizing +indentation, it's helpful to understand the general indentation model +being used. + +@vindex vhdl-echo-syntactic-information-p +@vindex echo-syntactic-information-p (vhdl-) +@cindex TAB +To help you configure VHDL Mode, you can set the variable +@code{vhdl-echo-syntactic-information-p} to non-@code{nil} so that the +syntactic component list and calculated offset will always be echoed in +the minibuffer when you hit @kbd{TAB}. + + +@ignore +@node Indentation Commands +@chapter Indentation Commands +@cindex Indentation Commands + +@strong{<TBD>} +@end ignore + + +@node Customizing Indentation +@chapter Customizing Indentation +@cindex Customizing Indentation + +@cindex vhdl-set-offset +@cindex set-offset (vhdl-) +The @code{vhdl-offsets-alist} variable is where you customize all your +indentations. You simply need to decide what additional offset you want +to add for every syntactic symbol. You can use the command @kbd{C-c +O} (@code{vhdl-set-offset}) as the way to set offsets, both +interactively and from your mode hook. Also, you can set up +@emph{styles} of indentation. Most likely, you'll find one of the +pre-defined styles will suit your needs, but if not, this section will +describe how to set up basic editing configurations. @xref{Styles}, for +an explanation of how to set up named styles. + +@cindex vhdl-basic-offset +@cindex basic-offset (vhdl-) +As mentioned previously, the variable @code{vhdl-offsets-alist} is an +association list between syntactic symbols and the offsets to be applied +for those symbols. In fact, these offset values can be an integer, a +function or variable name, or one of the following symbols: @code{+}, +@code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The symbol +values have the following meanings: + +@itemize @bullet + +@item +@code{+} -- 1 x @code{vhdl-basic-offset} +@item +@code{-} -- -1 x @code{vhdl-basic-offset} +@item +@code{++} -- 2 x @code{vhdl-basic-offset} +@item +@code{--} -- -2 x @code{vhdl-basic-offset} +@item +@code{*} -- 0.5 x @code{vhdl-basic-offset} +@item +@code{/} -- -0.5 x @code{vhdl-basic-offset} + +@end itemize + +@noindent +So, for example, because most of the default offsets are defined in +terms of @code{+}, @code{-}, and @code{0}, if you like the general +indentation style, but you use 2 spaces instead of 4 spaces per level, +you can probably achieve your style just by changing +@code{vhdl-basic-offset} like so (in your @file{.emacs} file): +@example + +(setq vhdl-basic-offset 2) + +@end example + +To change indentation styles more radically, you will want to change the +value associated with the syntactic symbols in the +@code{vhdl-offsets-alist} variable. First, I'll show you how to do that +interactively, then I'll describe how to make changes to your +@file{.emacs} file so that your changes are more permanent. + +@menu +* Interactive Customization:: +* Permanent Customization:: +* Styles:: +* Advanced Customizations:: +@end menu + +@node Interactive Customization +@section Interactive Customization +@cindex Interactive Customization + +As an example of how to customize indentation, let's change the +style of the example above from: +@example +@group + + 1: inverter : process + 2: begin + 3: q <= not d; + 4: wait on d; + 5: end inverter; + +@end group +@end example +@noindent +to: +@example +@group + + 1: inverter : process + 2: begin + 3: q <= not d; + 4: wait on d; + 5: end inverter; + +@end group +@end example + +In other words, we want to change the indentation of the statments +inside the inverter process. Notice that the construct we want to +change starts on line 3. To change the indentation of a line, we need +to see which syntactic component affect the offset calculations for that +line. Hitting @kbd{C-c C-x} on line 3 yields: +@example + +((statement-block-intro . 20)) + +@end example + +@findex vhdl-set-offset +@findex set-offset (vhdl-) +@kindex C-c O +@noindent +So we know that to change the offset of the first signal assignment, we need to +change the indentation for the @code{statement-block-intro} syntactic +symbol. To do this interactively, just hit @kbd{C-c O} +(@code{vhdl-set-offset}). This prompts you for the syntactic symbol to +change, providing a reasonable default. In this case, the default is +@code{statement-block-intro}, which is just the syntactic symbol we want to +change! + +After you hit return, VHDL Mode will then prompt you for the new +offset value, with the old value as the default. The default in this +case is @samp{+}, so hit backspace to delete the @samp{+}, then hit +@samp{++} and @kbd{RET}. This will associate an offset of twice the +basic indent with the syntactic symbol @code{statement-block-intro} in +the @code{vhdl-offsets-alist} variable. + +@findex vhdl-indent-defun +@findex indent-defun (vhdl-) +To check your changes quickly, just enter @kbd{M-x vhdl-indent-defun} to +reindent the entire function. The example should now look like: +@example +@group + + 1: inverter : process + 2: begin + 3: q <= not d; + 4: wait on d; + 5: end inverter; + +@end group +@end example + +Notice how just changing the offset on line 3 is all we needed to do. +Since the other affected lines are indented relative to line 3, they are +automatically indented the way you'd expect. For more complicated +examples, this may not always work. The general approach to take is to +always start adjusting offsets for lines higher up in the file, then +re-indent and see if any following lines need further adjustments. + +@node Permanent Customization +@section Permanent Indentation +@cindex Permanent Indentation + +@vindex vhdl-mode-hook +@cindex hooks +To make this change permanent, you need to add some lisp code to your +@file{.emacs} file. VHDL Mode provides a @code{vhdl-mode-hook} +that you can use to customize your language editing styles. This hook +gets run as the last thing when you enter VHDL Mode. + +Here's a simplified example of what you can add to your @file{.emacs} +file to make the changes described in the previous section +(@ref{Interactive Customization}) more permanent. See the Emacs +manuals for more information on customizing Emacs via hooks. +@xref{Sample .emacs File}, for a more complete sample @file{.emacs} file. + +@example +@group + +(defun my-vhdl-mode-hook () + ;; my customizations for all of vhdl-mode + (vhdl-set-offset 'statement-block-intro '++) + ;; other customizations can go here + ) +(add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook) + +@end group +@end example + +For complex customizations, you will probably want to set up a +@emph{style} that groups all your customizations under a single +name. @xref{Styles}. + +The offset value can also be a function, and this is how power users +gain enormous flexibility in customizing indentation. @xref{Advanced +Customizations}. + +@node Styles +@section Styles +@cindex Styles + +Most people only need to edit code formatted in just a few well-defined +and consistent styles. For example, their organization might impose a +``blessed'' style that all its programmers must conform to. Similarly, +people who work on GNU software will have to use the GNU coding style on +C code. Some shops are more lenient, allowing some variety of coding +styles, and as programmers come and go, there could be a number of +styles in use. For this reason, VHDL Mode makes it convenient for +you to set up logical groupings of customizations called @dfn{styles}, +associate a single name for any particular style, and pretty easily +start editing new or existing code using these styles. This chapter +describes how to set up styles and how to edit your C code using styles. + +@menu +* Built-in Styles:: +* Adding Styles:: +* File Styles:: +@end menu + + +@node Built-in Styles +@subsection Built-in Styles +@cindex Built-in Styles + +If you're lucky, one of VHDL Mode's built-in styles might be just +what you're looking for. Some of the most common VHDL styles are +already built-in. These include: + +@itemize @bullet +@item +@cindex IEEE style +@code{GNU} -- the coding style in the IEEE Language Reference Manual. + +@end itemize + +@findex vhdl-set-style +@findex set-style (vhdl-) +If you'd like to experiment with these built-in styles you can simply +type @kbd{M-x vhdl-set-style RET} in a VHDL Mode buffer. + +You will be prompted for one of the above styles (with completion). +Enter one of the styles and hit @kbd{RET}. Note however that setting a +style in this way does @emph{not} automatically re-indent your file. +@ignore +For commands that you can use to view the effect of your changes, see +@ref{Indentation Commands}. +@end ignore + +Once you find a built-in style you like, you can make the change +permanent by adding a call to your @file{.emacs} file. Let's say for +example that you want to use the @code{IEEE} style in all your +files. You would add this: +@example +@group + +(defun my-vhdl-mode-hook () + ;; use IEEE style for all VHDL code + (vhdl-set-style "IEEE") + ;; other customizations can go here + ) +(add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook) + +@end group +@end example + +@noindent +@xref{Permanent Customization}. + +@node Adding Styles +@subsection Adding Styles +@cindex Adding Styles + +@vindex vhdl-style-alist +@vindex style-alist (vhdl-) +@findex vhdl-add-style +@findex add-style (vhdl-) +If none of the built-in styles is appropriate, you'll probably want to +add a new style definition. Styles are kept in the @code{vhdl-style-alist} +variable, but you probably won't want to modify this variable directly. +VHDL Mode provides a function, called @code{vhdl-add-style}, that you +can use to easily add new styles or update existing styles. This +function takes two arguments, a @var{stylename} string, and an +association list @var{description} of style customizations. If +@var{stylename} is not already in @code{vhdl-style-alist}, the new style is +added, otherwise the style already associated with @var{stylename} is +changed to the new @var{description}. This function also takes an +optional third argument, which if non-@code{nil}, automatically +institutes the new style in the current buffer. + +The sample @file{.emacs} file provides a concrete example of how a new +style can be added and automatically set. @xref{Sample .emacs File}. + +@node File Styles +@subsection File Styles +@cindex File Styles + +@cindex local variables +The Emacs manual describes how you can customize certain variables on a +per-file basis by including a @dfn{Local Variable} block at the end of +the file. So far, you've only seen a functional interface to +VHDL Mode, which is highly inconvenient for use in a Local Variable +block. VHDL Mode provides two variables that make it easier for +you to customize your style on a per-file basis. + +@vindex vhdl-file-style +@vindex file-style (vhdl-) +@vindex vhdl-file-offsets +@vindex file-offsets (vhdl-) + +The variable @code{vhdl-file-style} can be set to a style name string as +described in @ref{Built-in Styles}. When the file is visited, +VHDL Mode will automatically set the file's style to this style +using @code{vhdl-set-style}. + +@vindex vhdl-offsets-alist +@vindex offsets-alist (vhdl-) +@findex vhdl-set-offset +@findex set-offset (vhdl-) +Another variable, @code{vhdl-file-offsets}, takes an association list +similar to what is allowed in @code{vhdl-offsets-alist}. When the file is +visited, VHDL Mode will automatically institute these offets using +@code{vhdl-set-offset}. @xref{Customizing Indentation}. + +Note that file style settings (i.e. @code{vhdl-file-style}) are applied +before file offset settings (i.e. @code{vhdl-file-offsets}). + + +@node Advanced Customizations +@section Advanced Customizations +@cindex Advanced Customizations + +@vindex vhdl-style-alist +@vindex style-alist (vhdl-) +@vindex vhdl-basic-offset +@vindex basic-offset (vhdl-) +For most users, VHDL Mode will support their coding styles with +very little need for customizations. Usually, one of the standard +styles defined in @code{vhdl-style-alist} will do the trick. Sometimes, +one of the syntactic symbol offsets will need to be tweeked slightly, or +perhaps @code{vhdl-basic-offset} will need to be changed. However, some +styles require a more advanced ability for customization, and one of the +real strengths of VHDL Mode is that the syntactic analysis model +provides a very flexible framework for customizing indentation. This +allows you to perform special indentation calculations for situations +not handled by the mode directly. + +@menu +* Custom Indentation Functions:: +* Other Special Indentations:: +@end menu + +@node Custom Indentation Functions +@subsection Custom Indentation Functions +@cindex Custom Indentation Functions + +@cindex custom indentation functions +One of the most common ways to customize VHDL Mode is by writing +@dfn{custom indentation functions} and associating them with specific +syntactic symbols (see @ref{Syntactic Symbols}). VHDL Mode itself +uses custom indentation functions to provide more sophisticated +indentation, for example when lining up selected signal assignments: +@example +@group + +%%% TBD %%% + +@end group +@end example + +In this example, the @code{statement-cont} syntactic symbol has an +offset of @code{+}, and @code{vhdl-basic-offset} is 2, so lines 4 +through 6 are simply indented two spaces to the right of line 3. But +perhaps we'd like VHDL Mode to be a little more intelligent so +that it offsets the waveform descriptions relative to the signal +assignment operator in line 3. To do this, we have to write a custom +indentation function which finds the column of signal assignment +operator on the first line of the statement. Here is the lisp code +(from the @file{vhdl-mode.el} source file) that implements this: +@example +@group + +(defun vhdl-lineup-statement-cont (langelem) + ;; line up statement-cont after the assignment operator + (save-excursion + (let* ((relpos (cdr langelem)) + (assignp (save-excursion + (goto-char (vhdl-point 'boi)) + (and (re-search-forward "\\(<\\|:\\)=" + (vhdl-point 'eol) t) + (- (point) (vhdl-point 'boi))))) + (curcol (progn + (goto-char relpos) + (current-column))) + foundp) + (while (and (not foundp) + (< (point) (vhdl-point 'eol))) + (re-search-forward "\\(<\\|:\\)=\\|(" (vhdl-point 'eol) 'move) + (if (vhdl-in-literal (cdr langelem)) + (forward-char) + (if (= (preceding-char) ?\() + ;; skip over any parenthesized expressions + (goto-char (min (vhdl-point 'eol) + (scan-lists (point) 1 1))) + ;; found an assignment operator (not at eol) + (setq foundp (not (looking-at "\\s-*$")))))) + (if (not foundp) + ;; there's no assignment operator on the line + vhdl-basic-offset + ;; calculate indentation column after assign and ws, unless + ;; our line contains an assignment operator + (if (not assignp) + (progn + (forward-char) + (skip-chars-forward " \t") + (setq assignp 0))) + (- (current-column) assignp curcol)) + ))) + +@end group +@end example +@noindent +Custom indent functions take a single argument, which is a syntactic +component cons cell (see @ref{Syntactic Analysis}). The +function returns an integer offset value that will be added to the +running total indentation for the lne. Note that what actually gets +returned is the difference between the column that the signal assignment +operator is on, and the column of the buffer relative position passed in +the function's argument. Remember that VHDL Mode automatically +adds in the column of the component's relative buffer position and we +don't want that value added into the final total twice. + +@cindex statement-cont syntactic symbol +@findex vhdl-lineup-statement-cont +@findex lineup-statement-cont (vhdl-) +Now, to associate the function @code{vhdl-lineup-statement-cont} with the +@code{statement-cont} syntactic symbol, we can add something like the +following to our @code{vhdl-mode-hook}: +@example + +(vhdl-set-offset 'statement-cont 'vhdl-lineup-statement-cont) + +@end example + +@findex vhdl-indent-defun +Now the function looks like this after re-indenting (using @kbd{M-x +vhdl-indent-defun}): +@example +@group + +%%% TBD %%% + +@end group +@end example + +@vindex vhdl-offsets-alist +@vindex offsets-alist (vhdl-) +Custom indentation functions can be as simple or as complex as you like, +and any syntactic symbol that appears in @code{vhdl-offsets-alist} can have +a custom indentation function associated with it. Note however that +using many custom indentation functions may have a performance impact on +VHDL Mode. + +@node Other Special Indentations +@subsection Other Special Indentations +@cindex Other Special Indentations + +@vindex vhdl-special-indent-hook +@vindex special-indent-hook (vhdl-) +One other variable is available for you to customize VHDL Mode: +@code{vhdl-special-indent-hook}. This is a standard hook variable that +is called after every line is indented by VHDL Mode. You can use +it to do any special indentation or line adjustments your style +dictates, such as adding extra indentation to the port map clause in a +component instantiation, etc. Note however, that you should not change +@code{point} or @code{mark} inside your @code{vhdl-special-indent-hook} +functions. + + +@node Syntactic Symbols +@chapter Syntactic Symbols +@cindex Syntactic Symbols + +@vindex vhdl-offsets-alist +The complete list of recognized syntactic symbols is described in the +@code{vhdl-offsets-alist} variable. This chapter will provide some +examples to help clarify these symbols. + +@cindex -open syntactic symbols +@cindex -close syntactic symbols +Most syntactic symbol names follow a general naming convention. When a +line begins with a @code{begin} or @code{end} keyword, the syntactic +symbol will contain the suffix @code{-open} or @code{-close} +respectively. + +@cindex -intro syntactic symbols +@cindex -cont syntactic symbols +@cindex -block-intro syntactic symbols +Usually, a distinction is made between the first line that introduces a +construct and lines that continue a construct, and the syntactic symbols +that represent these lines will contain the suffix @code{-intro} or +@code{-cont} respectively. As a sub-classification of this scheme, a +line which is the first of a particular block construct will contain the +suffix @code{-block-intro}. + +@strong{<TBD> include the name and a brief example of every syntactic +symbol currently recognized} + +@node Frequently Asked Questions +@chapter Frequently Asked Questions +@cindex Frequently Asked Questions + +@kindex C-x h +@kindex ESC C-\ +@kindex ESC C-q +@kindex ESC C-u +@kindex RET +@kindex LFD +@findex newline-and-indent +@quotation + +@strong{Q.} @emph{How do I re-indent the whole file?} + +@strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole +buffer. Then hit @kbd{@key{ESC} C-\} to re-indent the entire region +which you've just marked. Or just enter @kbd{M-x vhdl-indent-buffer}. +@sp 2 + +@strong{Q.} @emph{How do I re-indent the entire function?} + +@strong{A.} Hit @kbd{@key{ESC} C-h} to mark the entire function. Then +hit @kbd{@key{ESC} C-\} to re-indent the entire region which you've just +marked. +@sp 2 + +@strong{Q.} @emph{How do I re-indent the current block?} + +@strong{A.} First move to the brace which opens the block with +@kbd{@key{ESC} C-u}, then re-indent that expression with +@kbd{@key{ESC} C-q}. +@sp 2 + +@strong{Q.} @emph{How do I re-indent the current statement?} + +@strong{A.} First move to the beginning of the statement with +@kbd{@key{ESC} a}, then re-indent that expression with @kbd{@key{ESC} +C-q}. +@sp 2 + +@strong{Q.} @emph{I put @code{(vhdl-set-offset 'statement-cont 0)} +in my @file{.emacs} file but I get an error saying that +@code{vhdl-set-offset}'s function definition is void.} + +@strong{A.} This means that VHDL Mode wasn't loaded into your +Emacs session by the time the @code{vhdl-set-offset} call was reached, +mostly likely because VHDL Mode is being autoloaded. Instead +of putting the @code{vhdl-set-offset} line in your top-level +@file{.emacs} file, put it in your @code{vhdl-mode-hook}, or +simply add the following to the top of your @file{.emacs} file: +@example + +(require 'vhdl-mode) + +@end example + +See the sample @file{.emacs} file @ref{Sample .emacs File} for +details. + +@end quotation + + +@node Getting the latest VHDL Mode release +@chapter Getting the latest VHDL Mode release +@cindex Getting the latest VHDL Mode release + +The best way to be sure you always have the latest VHDL Mode release +is to join the @code{vhdl-mode-announce} mailing list. If you are a +brave soul, and wish to participate in beta testing of new releases of +VHDL Mode, you may also join the @code{vhdl-mode-victims} mailing +list. Send email to the maintainer @email{reto@@gnu.org} to join +either of these lists. + +The official Emacs VHDL Mode Home Page can be found at +@uref{http://www.iis.ee.ethz.ch/~zimmi/emacs/vhdl-mode.html}. + +@node Sample .emacs File +@chapter Sample @file{.emacs} file +@cindex Sample @file{.emacs} file + +Most customizations can be done using the `Customize' entry in the +VHDL Mode menu, which requires no editing of the .emacs file. +If you want to customize indentation, here you go: + +@example +;; Here's a sample .emacs file that might help you along the way. Just +;; copy this region and paste it into your .emacs file. You may want to +;; change some of the actual values. + +(defconst my-vhdl-style + '((vhdl-tab-always-indent . t) + (vhdl-comment-only-line-offset . 4) + (vhdl-offsets-alist . ((arglist-close . vhdl-lineup-arglist) + (statement-cont . 0) + (case-alternative . 4) + (block-open . 0))) + (vhdl-echo-syntactic-information-p . t) + ) + "My VHDL Programming Style") + +;; Customizations for vhdl-mode +(defun my-vhdl-mode-hook () + ;; add my personal style and set it for the current buffer + (vhdl-add-style "PERSONAL" my-vhdl-style t) + ;; offset customizations not in my-vhdl-style + (vhdl-set-offset 'statement-case-intro '++) + ;; other customizations + (setq tab-width 8 + ;; this will make sure spaces are used instead of tabs + indent-tabs-mode nil) + ;; keybindings for VHDL are put in vhdl-mode-map + (define-key vhdl-mode-map "\C-m" 'newline-and-indent) + ) + +(add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook) +@end example + +@node Limitations and Known Bugs +@chapter Limitations and Known Bugs +@cindex Limitations and Known Bugs + +@itemize @bullet +@item +Re-indenting large regions or expressions can be slow. + +@ignore +@item +The index menu does not work on my XEmacs installation (don't know why). +@end ignore + +@end itemize + +@node Mailing Lists and Submitting Bug Reports +@chapter Mailing Lists and Submitting Bug Reports +@cindex Mailing Lists and Submitting Bug Reports + +@kindex C-c C-b +@findex vhdl-submit-bug-report +@findex submit-bug-report (vhdl-) +@cindex beta testers mailing list +@cindex announcement mailing list +To report bugs, use the @kbd{C-c C-b} (@code{vhdl-submit-bug-report}) +command. This provides vital information I need to reproduce your +problem. Make sure you include a concise, but complete code example. +Please try to boil your example down to just the essential code needed +to reproduce the problem, and include an exact recipe of steps needed to +expose the bug. Be especially sure to include any code that appears +@emph{before} your bug example. + +For other help or suggestions, send a message to @email{reto@@gnu.org}. + +Send an add message to @email{reto@@gnu.org} to get on the +@code{vhdl-mode-victims} beta testers list where beta releases of +VHDL Mode are posted. Note that you shouldn't expect beta +releases to be as stable as public releases. + +There is also an announce only list where the latest public releases +of VHDL Mode are posted. Send an add message to +@email{reto@@gnu.org} to be added to this list. + + +@node GNU Free Documentation License +@appendix GNU Free Documentation License +@include doclicense.texi + + +@node Concept Index +@unnumbered Concept Index + +@printindex cp + + +@node Command Index +@unnumbered Command Index + +Since all VHDL Mode commands are prepended with the string +@samp{vhdl-}, each appears under its @code{vhdl-<thing>} name and its +@code{<thing> (vhdl-)} name. +@iftex +@sp 2 +@end iftex +@printindex fn + + +@node Key Index +@unnumbered Key Index + +@printindex ky + + +@node Variable Index +@unnumbered Variable Index + +Since all VHDL Mode variables are prepended with the string +@samp{vhdl-}, each appears under its @code{vhdl-<thing>} name and its +@code{<thing> (vhdl-)} name. +@iftex +@sp 2 +@end iftex +@printindex vr + +@bye |