diff options
Diffstat (limited to 'doc')
118 files changed, 5678 insertions, 2016 deletions
diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 50ea80b1678..b7853a7f118 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,36 +1,113 @@ -2014-12-22 Eli Zaretskii <eliz@gnu.org> +2015-01-27 Ivan Shmakov <ivan@siamics.net> + + * files.texi (File Archives): Document "I" for tar-new-entry. + (Bug#19274) + +2014-12-31 Paul Eggert <eggert@cs.ucla.edu> + + Less 'make' chatter for Emacs doc + * Makefile.in (AM_DEFAULT_VERBOSITY, AM_V_GEN, am__v_GEN_) + (am__v_GEN_0, am__v_GEN_1): New macros, from ../../src/Makefile.in. + (ENVADD, $(buildinfodir)/emacs.info, emacs.html): + Use them. + +2014-12-27 Eli Zaretskii <eliz@gnu.org> * buffers.texi (Kill Buffer): Improve indexing. -2014-11-19 Paul Eggert <eggert@cs.ucla.edu> +2014-12-24 Stephen Leake <stephen_leake@stephe-leake.org> + + * trouble.texi: Move user-level information from CONTRIBUTE here. + +2014-12-14 Alan Mackenzie <acm@muc.de> + + * display.texi (Scrolling): fast-but-imprecise-scrolling. + Describe new variable. + +2014-12-14 Cameron Desautels <camdez@gmail.com> + + * custom.texi (Saving Customizations): Mention + `custom-prompt-customize-unsaved-options'. + +2014-12-08 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * misc.texi (Network Security): Mention the new protocol-level + `high' NSM checks. + +2014-12-08 Eric S. Raymond <esr@snark.thyrsus.com> + + * maintaining.texi: Suopport fo Arch has been moved to obosolete, + remove references that imply otherwise. + +2014-11-29 Paul Eggert <eggert@cs.ucla.edu> Lessen focus on ChangeLog files, as opposed to change log entries. * maintaining.texi (Change Log): Mention that ChangeLog files may be copied to or from a version control system. * trouble.texi (Sending Patches): Point to the commit messages. -2014-11-19 Eli Zaretskii <eliz@gnu.org> +2014-11-29 Eli Zaretskii <eliz@gnu.org> * maintaining.texi (Switching Branches): Mention "C-x v r". Correct commands for switching branches in various VCSs. -2014-11-16 Tassilo Horn <tsdh@gnu.org> +2014-11-27 Tassilo Horn <tsdh@gnu.org> * misc.texi (DocView Slicing): Describe how to slice with the mouse. Fix command mentioned by slice by BoundingBox paragraph. (Bug#18040) +2014-11-25 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * misc.texi (Network Security): Use "untrustworthy" instead of + "unsafe". + +2014-11-24 Eli Zaretskii <eliz@gnu.org> + + * misc.texi (Network Security): Improve wording and indexing of + last change. + +2014-11-24 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * misc.texi (Gnus Summary Buffer): Move the Network Security + Manager stuff here from the lispref manual. + +2014-11-21 Eli Zaretskii <eliz@gnu.org> + + * maintaining.texi (Version Control Systems): Move "@end itemize" + past the last @item. + +2014-11-21 H. Dieter Wilhelm <dieter@duenenhof-wilhelm.de> + + * maintaining.texi (Version Control Systems): Fix a typo. + +2014-11-20 Eric S. Raymond <esr@snark.thyrsus.com> + + * maintaining.texi: Document SRC support. + +2014-11-10 Glenn Morris <rgm@gnu.org> + + * Makefile.in (top_srcdir, version): New, set by configure. + (doc-emacsver): New rule. + (bootstrap-clean, maintainer-clean): Delete emacsver.texi. + (emacsver.texi.in): Rename from emacsver.texi. + +2014-11-09 Juri Linkov <juri@jurta.org> + + * search.texi (Other Repeating Search): Add documentation for + multi-isearch-files and multi-isearch-files-regexp. (Bug#13592) + 2014-11-09 Glenn Morris <rgm@gnu.org> * Makefile.in (version): Remove variable. (clean): No longer delete dist tarfile. (dist): Remove rule; replace with code in admin.el. -2014-11-01 Glenn Morris <rgm@gnu.org> +2014-11-03 Glenn Morris <rgm@gnu.org> * programs.texi (Misc for Programs): Fix typo. -2014-10-24 Eli Zaretskii <eliz@gnu.org> +2014-10-30 Eli Zaretskii <eliz@gnu.org> * frames.texi (Scroll Bars): Improve indexing of faces. @@ -41,42 +118,46 @@ * display.texi (Standard Faces, Text Display) (Useless Whitespace): Improve indexing of faces. -2014-10-23 Tassilo Horn <tsdh@gnu.org> - - * misc.texi (Document View): Adapt to latest doc-view changes wrt - viewing the document's plain text contents. [Backport] - -2014-10-23 Eli Zaretskii <eliz@gnu.org> - * frames.texi (Frame Commands): Document and index 'frame-resize-pixelwise'. * windows.texi (Split Window): Document and index 'window-resize-pixelwise'. -2014-10-20 Glenn Morris <rgm@gnu.org> +2014-10-22 Tassilo Horn <tsdh@gnu.org> - * ack.texi (Acknowledgments): Remove some obsolete items. - * misc.texi (Emulation): Remove section. + * misc.texi (Document View): Adapt to latest doc-view changes wrt + viewing the document's plain text contents. 2014-10-20 Glenn Morris <rgm@gnu.org> - * Version 24.4 released. + * Merge in all changes up to 24.4 release. 2014-10-13 Glenn Morris <rgm@gnu.org> * Makefile.in (dist): Update for new output variables. -2014-10-06 Glenn Morris <rgm@gnu.org> +2014-10-12 Paul Eggert <eggert@cs.ucla.edu> + + * macos.texi (Mac OS / GNUstep, Mac / GNUstep Basics) + (Mac / GNUstep Customization): Mac OS X 10.6 or later now required. + +2014-10-09 Glenn Morris <rgm@gnu.org> * package.texi (Package Menu): The package list was changed to not say "unsigned" any more. -2014-10-04 Glenn Morris <rgm@gnu.org> +2014-10-05 Glenn Morris <rgm@gnu.org> * misc.texi (Sorting): * search.texi (Query Replace): Markup fixes. +2014-10-04 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Scroll Bars): Describe use of horizontal scroll bars. + +2014-10-04 Glenn Morris <rgm@gnu.org> + * cmdargs.texi (Misc X): * display.texi (Optional Mode Line): * misc.texi (emacsclient Options): @@ -89,28 +170,74 @@ * frames.texi (Frame Commands): * cmdargs.texi (Window Size X): Mention the use of - `frame-resize-pixelwise' to make frames truly fullscreen or - maximized. + `frame-resize-pixelwise' to make frames truly fullscreen or maximized. -2014-10-01 Glenn Morris <rgm@gnu.org> +2014-10-02 Glenn Morris <rgm@gnu.org> * package.texi (Package Installation): Mention etc/package-keyring.gpg. +2014-09-29 Eli Zaretskii <eliz@gnu.org> + + * emacsver.texi (EMACSVER): Bump to 20.0.50. + +2014-09-15 Daniel Colascione <dancol@dancol.org> + + * regs.texi (Text Registers): Update end-user documentation + to reflect `insert-register' interface change. + +2014-08-07 Reuben Thomas <rrt@sc3d.org> + + * programs.texi (Program Modes): Don't advertise VMS DCL support + any more. + +2014-08-07 Reuben Thomas <rrt@sc3d.org> + + Refer to MS-DOS using the same name everywhere. + + * Makefile.in (EMACSSOURCES): ``MS-DOG'', ``MSDOG'' and ``msdog'' + become ``MS-DOS''; ``msdog'' in filenames becomes ``msdos''. + * emacs-xtra.texi: ditto. + * emacs.texi: ditto. + * makefile.w32-in: ditto. + * msdog-xtra.texi: ditto, and rename file. + * msdog.texi: ditto, and rename file. + 2014-07-21 Glenn Morris <rgm@gnu.org> * emacs.texi (Intro): Workaround makeinfo 4 @acronym bug. (Bug#18040) -2014-07-03 Juri Linkov <juri@jurta.org> +2014-07-09 Juri Linkov <juri@jurta.org> * search.texi (Regexp Search): Update lax space matching that is not active in regexp search by default now. (Bug#17901) -2014-06-29 Glenn Morris <rgm@gnu.org> +2014-07-03 Glenn Morris <rgm@gnu.org> * help.texi (Misc Help): * trouble.texi (Checklist): "Online" help doesn't mean what it used to any more. +2014-06-23 Glenn Morris <rgm@gnu.org> + + * Makefile.in (%.texi): Disable implicit rules. + (mkinfodir): Remove. + (.dvi.ps): Replace with pattern rule. + (${buildinfodir}): New rule. + ($(buildinfodir)/emacs.info): Use order-only prereq for output dir. + Use $<. + (emacs.dvi, emacs.pdf, emacs.html, emacs-xtra.dvi, emacs-xtra.pdf): + Use $<. + (%.ps): New rule. + +2014-06-15 Glenn Morris <rgm@gnu.org> + + * Makefile.in (bootstrap-clean): New. + +2014-06-10 Glenn Morris <rgm@gnu.org> + + * Makefile.in (INFO_EXT): Remove and replace by ".info" throughout. + (INFO_OPTS): Set directly rather than with configure. + 2014-06-08 Glenn Morris <rgm@gnu.org> * entering.texi (Entering Emacs): Small fix re initial-buffer-choice. @@ -133,58 +260,53 @@ * ack.texi (Acknowledgments): * emacs.texi (Acknowledgments): Updates. -2014-06-07 Glenn Morris <rgm@gnu.org> +2014-06-08 Glenn Morris <rgm@gnu.org> + + * ack.texi (Acknowledgments): + * emacs.texi (Acknowledgments): Updates. * programs.texi (Prettifying Symbols): Remove node. (Misc for Programs): Mention more briefly here. * emacs.texi (Top): Update menu. -2014-06-05 Glenn Morris <rgm@gnu.org> - * package.texi (Package Menu, Package Installation): Mention signed packages. - -2014-06-03 Glenn Morris <rgm@gnu.org> - - * package.texi (Package Installation): Mention package-pinned-packages. + (Package Installation): Mention package-pinned-packages. 2014-06-02 Glenn Morris <rgm@gnu.org> + * ack.texi (Acknowledgments): Remove some obsolete items. * misc.texi [iftex]: Update chapter summary. - (Emulation): Remove ludicrously outdated claim. - -2014-05-29 Glenn Morris <rgm@gnu.org> + (Emulation): Remove section. * 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) @@ -259,12 +381,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. @@ -274,23 +394,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) @@ -302,8 +438,8 @@ 2014-03-13 Paul Eggert <eggert@cs.ucla.edu> - * mule.texi (International, Language Environments): Update - the list of language environments to what Emacs currently + * mule.texi (International, Language Environments): + Update the list of language environments to what Emacs currently supports. Add the full list to the index. Suggest C-h L for details rather than trying to give very brief details here. @@ -595,8 +731,8 @@ * indent.texi (Tab Stops): Mention recent changes about `tab-stop-list'. - * frames.texi (Scroll Bars): Document - `scroll-bar-adjust-thumb-portion'. + * frames.texi (Scroll Bars): + Document `scroll-bar-adjust-thumb-portion'. 2013-12-21 Chong Yidong <cyd@gnu.org> @@ -622,8 +758,8 @@ * entering.texi: Document `initial-buffer-choice' changes. - * misc.texi (emacsclient Options): Document - `initial-buffer-choice' changes. + * misc.texi (emacsclient Options): + Document `initial-buffer-choice' changes. * help.texi: Document that `?' now also shows subcommands of prefix keys. @@ -1106,8 +1242,8 @@ * misc.texi (Terminal emulator): Document Term mode faces. - * mini.texi (Basic Minibuffer): New node. Document - minibuffer-electric-default-mode. + * mini.texi (Basic Minibuffer): New node. + Document minibuffer-electric-default-mode. * display.texi (Visual Line Mode): Fix index entry. @@ -3167,7 +3303,7 @@ * Makefile.in (MAKEINFO): Now controlled by `configure'. (MAKEINFO_OPTS): New variable. Use it where appropriate. - (ENVADD): Updated. + (ENVADD): Update. 2011-01-18 Glenn Morris <rgm@gnu.org> @@ -9062,7 +9198,7 @@ * text.texi (Format Faces): Replace old M-g key prefix with M-o. - * emacs.texi (Acknowledgments): Updated. + * emacs.texi (Acknowledgments): Update. * anti.texi: Total rewrite. @@ -10169,7 +10305,7 @@ * frames.texi (Dialog Boxes): Add use-file-dialog. -2003-11-22 Martin Stjernholm <bug-cc-mode@gnu.org> +2003-11-22 Martin Stjernholm <mast@lysator.liu.se> * ack.texi: Note that Alan Mackenzie contributed the AWK support in CC Mode. diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in index 7b5d00fe0ce..9f04f0d7704 100644 --- a/doc/emacs/Makefile.in +++ b/doc/emacs/Makefile.in @@ -26,6 +26,10 @@ SHELL = @SHELL@ # of the source tree. This is set by configure's `--srcdir' option. srcdir=@srcdir@ +top_srcdir = @top_srcdir@ + +version = @version@ + ## Where the output files go. ## Note that the setfilename command in the .texi files assumes this. ## This is a bit funny. Because the info files are in the @@ -51,12 +55,11 @@ GZIP_PROG = @GZIP_PROG@ HTML_OPTS = --no-split --html -INFO_EXT=@INFO_EXT@ # Options used only when making info output. # --no-split is only needed because of MS-DOS. # For a possible alternative, see # http://lists.gnu.org/archive/html/emacs-devel/2011-01/msg01182.html -INFO_OPTS=@INFO_OPTS@ +INFO_OPTS= --no-split INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ @@ -70,8 +73,15 @@ TEXI2DVI = texi2dvi TEXI2PDF = texi2pdf DVIPS = dvips +# 'make' verbosity. +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(TEXINPUTS)" \ +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = + +ENVADD = $(AM_V_GEN)TEXINPUTS="$(srcdir):$(texinfodir):$(TEXINPUTS)" \ MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" DVI_TARGETS = emacs.dvi emacs-xtra.dvi @@ -89,7 +99,7 @@ EMACS_XTRA= \ $(srcdir)/vc-xtra.texi \ $(srcdir)/vc1-xtra.texi \ $(srcdir)/fortran-xtra.texi \ - $(srcdir)/msdog-xtra.texi + $(srcdir)/msdos-xtra.texi EMACSSOURCES= \ ${srcdir}/emacs.texi \ @@ -133,53 +143,65 @@ EMACSSOURCES= \ ${srcdir}/xresources.texi \ ${srcdir}/anti.texi \ ${srcdir}/macos.texi \ - ${srcdir}/msdog.texi \ + ${srcdir}/msdos.texi \ ${srcdir}/gnu.texi \ ${srcdir}/glossary.texi \ ${srcdir}/ack.texi \ ${srcdir}/kmacro.texi \ $(EMACS_XTRA) -## The info/ directory exists in release tarfiles but not the repository. -mkinfodir = @${MKDIR_P} ${buildinfodir} +## Disable implicit rules. +%.texi: ; .PHONY: info dvi html pdf ps -.SUFFIXES: .ps .dvi - -.dvi.ps: - $(DVIPS) -o $@ $< - -info: $(buildinfodir)/emacs$(INFO_EXT) +info: $(buildinfodir)/emacs.info dvi: $(DVI_TARGETS) html: $(HTML_TARGETS) pdf: $(PDF_TARGETS) ps: $(PS_TARGETS) +## The info/ directory exists in release tarfiles but not the repository. +${buildinfodir}: + ${MKDIR_P} $@ + # Note that all the Info targets build the Info files in srcdir. # There is no provision for Info files to exist in the build directory. # In a distribution of Emacs, the Info files should be up to date. -# Note: "<" is not portable in ordinary make rules. -$(buildinfodir)/emacs$(INFO_EXT): ${EMACSSOURCES} - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/emacs.texi +$(buildinfodir)/emacs.info: ${EMACSSOURCES} | ${buildinfodir} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $< emacs.dvi: ${EMACSSOURCES} - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs.texi + $(ENVADD) $(TEXI2DVI) $< emacs.pdf: ${EMACSSOURCES} - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs.texi + $(ENVADD) $(TEXI2PDF) $< emacs.html: ${EMACSSOURCES} - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/emacs.texi + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $< emacs-xtra.dvi: $(EMACS_XTRA) - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-xtra.texi + $(ENVADD) $(TEXI2DVI) $< emacs-xtra.pdf: $(EMACS_XTRA) - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs-xtra.texi + $(ENVADD) $(TEXI2PDF) $< + +%.ps: %.dvi + $(DVIPS) -o $@ $< + +.PHONY: doc-emacsver + +# If configure were to just generate emacsver.texi from emacsver.texi.in +# in the normal way, the timestamp of emacsver.texi would always be +# newer than that of the info files, which are prebuilt in release tarfiles. +# So we use this rule, and move-if-change, to avoid that. +doc-emacsver: + sed 's/[@]version@/${version}/' \ + ${srcdir}/emacsver.texi.in > emacsver.texi.$$$$ && \ + ${top_srcdir}/build-aux/move-if-change emacsver.texi.$$$$ \ + ${srcdir}/emacsver.texi -.PHONY: mostlyclean clean distclean maintainer-clean infoclean +.PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean infoclean ## Temp files. mostlyclean: @@ -195,9 +217,13 @@ 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 \ + $(buildinfodir)/emacs.info-[1-9] \ + $(buildinfodir)/emacs.info-[1-9][0-9] -maintainer-clean: distclean infoclean +bootstrap-clean maintainer-clean: distclean infoclean + rm -f ${srcdir}/emacsver.texi .PHONY: install-dvi install-html install-pdf install-ps install-doc diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi index 500a98e42ce..f97964b6a68 100644 --- a/doc/emacs/ack.texi +++ b/doc/emacs/ack.texi @@ -1185,9 +1185,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 aa685d071f6..f271be1d226 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 d36e15ef92e..095e49be90c 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -405,6 +405,16 @@ customizations in your initialization file. This is because saving customizations from such a session would wipe out all the other customizations you might have on your initialization file. + Please note that any customizations you have not chosen to save for +future sessions will be lost when you terminate Emacs. If you'd like +to be prompted about unsaved customizations at termination time, add +the following to your initialization file: + +@example +(add-hook 'kill-emacs-query-functions + 'custom-prompt-customize-unsaved-options) +@end example + @node Face Customization @subsection Customizing Faces @cindex customizing faces @@ -2445,9 +2455,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/display.texi b/doc/emacs/display.texi index 34f84e7664a..ae723b8d68c 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -127,6 +127,19 @@ the mouse wheel (@pxref{Mouse Commands}); in general, it affects any command that has a non-@code{nil} @code{scroll-command} property. @xref{Property Lists,,, elisp, The Emacs Lisp Reference Manual}. +@vindex fast-but-imprecise-scrolling + Sometimes, particularly when you hold down keys such as @kbd{C-v} +and @kbd{M-v}, activating keyboard auto-repeat, Emacs fails to keep up +with the rapid rate of scrolling requested; the display doesn't update +and Emacs can become unresponsive to input for quite a long time. You +can counter this sluggishness by setting the variable +@code{fast-but-imprecise-scrolling} to a non-@code{nil} value. This +instructs the scrolling commands not to fontify (@pxref{Font Lock}) +any unfontified text they scroll over, instead to assume it has the +default face. This can cause Emacs to scroll to somewhat wrong buffer +positions when the faces in use are not all the same size, even with +single (i.e. without auto-repeat) scrolling operations. + @vindex scroll-up @vindex scroll-down @findex scroll-up-line diff --git a/doc/emacs/emacs-xtra.texi b/doc/emacs/emacs-xtra.texi index 083762df879..fcedf7308a8 100644 --- a/doc/emacs/emacs-xtra.texi +++ b/doc/emacs/emacs-xtra.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @comment %**start of header -@setfilename ../../info/emacs-xtra +@setfilename ../../info/emacs-xtra.info @settitle Specialized Emacs Features @c Merge all functions, variables, and keys into the concept index. @syncodeindex fn cp @@ -120,7 +120,7 @@ the Emacs manual. @include fortran-xtra.texi -@include msdog-xtra.texi +@include msdos-xtra.texi @lowersections @end iftex diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 5125510cc09..c1ad6887a68 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -1,6 +1,6 @@ \input texinfo @c -*- coding: utf-8 -*- -@setfilename ../../info/emacs +@setfilename ../../info/emacs.info @settitle GNU Emacs Manual @c The edition number appears in more than one place in this file @@ -189,6 +189,7 @@ Advanced Features * Sending Mail:: Sending mail in Emacs. * Rmail:: Reading mail in Emacs. * Gnus:: A flexible mail and news reader. +* Network Security:: Managing the network security. * Document View:: Viewing PDF, PS and DVI files. * EWW:: A web browser in Emacs. * Shell:: Executing shell commands from Emacs. @@ -1574,8 +1575,8 @@ Lisp programming. @include anti.texi @include macos.texi -@c Includes msdog-xtra. -@include msdog.texi +@c Includes msdos-xtra. +@include msdos.texi @include gnu.texi @include glossary.texi @ifnottex diff --git a/doc/emacs/emacsver.texi b/doc/emacs/emacsver.texi deleted file mode 100644 index cef51213d5e..00000000000 --- a/doc/emacs/emacsver.texi +++ /dev/null @@ -1,4 +0,0 @@ -@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.4.51 diff --git a/doc/emacs/emacsver.texi.in b/doc/emacs/emacsver.texi.in new file mode 100644 index 00000000000..fa685125301 --- /dev/null +++ b/doc/emacs/emacsver.texi.in @@ -0,0 +1,2 @@ +@c configure generates emacsver.texi from emacsver.texi.in via a Makefile rule +@set EMACSVER @version@ diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 196c6bb0092..b12b28f9c17 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -1689,6 +1689,13 @@ likewise. @kbd{v} extracts a file into a buffer in View mode another window, so you could edit the file and operate on the archive simultaneously. + The @kbd{I} key adds a new (regular) file to the archive. The file +is initially empty, but can readily be edited using the commands +above. The command inserts the new file before the current one, so +that using it on the topmost line of the Tar buffer makes the new file +the first one in the archive, and using it at the end of the buffer +makes it the last one. + @kbd{d} marks a file for deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in Dired. @kbd{C} copies a file from the archive to disk and @kbd{R} renames a file within the archive. diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index 2ff000e5576..b5b9dbd7daa 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -911,10 +911,11 @@ those are drawn by the toolkit and not directly by Emacs. @section Scroll Bars @cindex Scroll Bar mode @cindex mode, Scroll Bar +@cindex Vertical Scroll Bar - On graphical displays, there is a @dfn{scroll bar} on the side of -each Emacs window. Clicking @kbd{Mouse-1} on the scroll bar's up and -down buttons scrolls the window by one line at a time. Clicking + On graphical displays, there is a @dfn{vertical scroll bar} on the +side of each Emacs window. Clicking @kbd{Mouse-1} on the scroll bar's +up and down buttons scrolls the window by one line at a time. Clicking @kbd{Mouse-1} above or below the scroll bar's inner box scrolls the window by nearly the entire height of the window, like @kbd{M-v} and @kbd{C-v} respectively (@pxref{Moving Point}). Dragging the inner box @@ -928,23 +929,23 @@ in the scroll bar lets you drag the inner box up and down. @findex scroll-bar-mode @findex toggle-scroll-bar - To toggle the use of scroll bars, type @kbd{M-x scroll-bar-mode}. -This command applies to all frames, including frames yet to be -created. To toggle scroll bars for just the selected frame, use the -command @kbd{M-x toggle-scroll-bar}. + To toggle the use of vertical scroll bars, type @kbd{M-x +scroll-bar-mode}. This command applies to all frames, including frames +yet to be created. To toggle vertical scroll bars for just the selected +frame, use the command @kbd{M-x toggle-scroll-bar}. @vindex scroll-bar-mode - To control the use of scroll bars at startup, customize the variable -@code{scroll-bar-mode}. Its value should be either @code{right} (put -scroll bars on the right side of windows), @code{left} (put them on -the left), or @code{nil} (disable scroll bars). By default, Emacs -puts scroll bars on the right if it was compiled with GTK+ support on -the X Window System, and on MS-Windows or Mac OS; Emacs puts scroll -bars on the left if compiled on the X Window System without GTK+ -support (following the old convention for X applications). + To control the use of vertical scroll bars at startup, customize the +variable @code{scroll-bar-mode}. Its value should be either +@code{right} (put scroll bars on the right side of windows), @code{left} +(put them on the left), or @code{nil} (disable vertical scroll bars). +By default, Emacs puts scroll bars on the right if it was compiled with +GTK+ support on the X Window System, and on MS-Windows or Mac OS; Emacs +puts scroll bars on the left if compiled on the X Window System without +GTK+ support (following the old convention for X applications). @vindex scroll-bar-width -@cindex width of the scroll bar +@cindex width of the vertical scroll bar You can also use the X resource @samp{verticalScrollBars} to enable or disable the scroll bars (@pxref{Resources}). To control the scroll bar width, change the @code{scroll-bar-width} frame parameter @@ -965,6 +966,38 @@ when the entire buffer is visible. The visual appearance of the scroll bars is controlled by the @code{scroll-bar} face. +@cindex Horizontal Scroll Bar +@cindex Horizontal Scroll Bar mode + On graphical displays with toolkit support, Emacs may also supply a +@dfn{horizontal scroll bar} on the bottom of each window. Clicking +@kbd{Mouse-1} on the that scroll bar's left and right buttons scrolls +the window horizontally by one column at a time. Clicking @kbd{Mouse-1} +on the left or right of the scroll bar's inner box scrolls the window by +four columns. Dragging the inner box scrolls the window continuously. + + Note that such horizontal scrolling can make the window's position of +point disappear on the left or the right. Typing a character to insert +text or moving point with a keyboard command will usually bring it back +into view. + +@findex horizontal-scroll-bar-mode + To toggle the use of horizontal scroll bars, type @kbd{M-x +horizontal-scroll-bar-mode}. This command applies to all frames, +including frames yet to be created. To toggle horizontal scroll bars +for just the selected frame, use the command @kbd{M-x +toggle-horizontal-scroll-bar}. + +@vindex horizontal-scroll-bar-mode + To control the use of horizontal scroll bars at startup, customize the +variable @code{horizontal-scroll-bar-mode}. + +@vindex scroll-bar-height +@cindex height of the horizontal scroll bar + You can also use the X resource @samp{horizontalScrollBars} to enable +or disable horizontal scroll bars (@pxref{Resources}). To control the +scroll bar height, change the @code{scroll-bar-height} frame parameter +(@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}). + @node Drag and Drop @section Drag and Drop @cindex drag and drop diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index 29fee0e0993..d8e84c1f914 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -604,7 +604,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/emacs/macos.texi b/doc/emacs/macos.texi index 045ca3a9aee..a93cbfbe675 100644 --- a/doc/emacs/macos.texi +++ b/doc/emacs/macos.texi @@ -12,7 +12,7 @@ the GNUstep libraries on GNU/Linux or other operating systems, or on Mac OS X with native window system support. On Mac OS X, Emacs can be built either without window system support, with X11, or with the Cocoa interface; this section only applies to the Cocoa build. This -does not support versions of Mac OS X earlier than 10.4. +does not support versions of Mac OS X earlier than 10.6. For various historical and technical reasons, Emacs uses the term @samp{Nextstep} internally, instead of ``Cocoa'' or ``Mac OS X''; for @@ -84,7 +84,7 @@ set, which often causes the subprocesses it launches to behave differently than they would when launched from the shell. For the PATH and MANPATH variables, a system-wide method -of setting PATH is recommended on Mac OS X 10.5 and later, using the +of setting PATH is recommended on Mac OS X, using the @file{/etc/paths} files and the @file{/etc/paths.d} directory. @node Mac / GNUstep Customization @@ -118,7 +118,7 @@ Useful in this context is the listing of all faces obtained by @kbd{M-x list-faces-display}. @cindex Core Text, on Mac OS X -In Mac OS X 10.5 and later, Emacs uses a Core Text based font backend +In Mac OS X, Emacs uses a Core Text based font backend by default. If you prefer the older font style, enter the following at the command-line before starting Emacs: diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index dec3aa9ac3b..9074cdfb883 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -31,11 +31,11 @@ versions of a source file, storing information such as the creation time of each version, who made it, and a description of what was changed. - The Emacs version control interface is called @dfn{VC}@. VC commands -work with several different version control systems; currently, it -supports GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS, + The Emacs version control interface is called @dfn{VC}@. VC +commands work with several different version control systems; +currently, it supports Bazaar, CVS, Git, Mercurial, Monotone, RCS, SCCS/CSSC, and Subversion. Of these, the GNU project distributes CVS, -Arch, RCS, and Bazaar. +RCS, and Bazaar. VC is enabled automatically whenever you visit a file governed by a version control system. To disable VC entirely, set the customizable @@ -163,14 +163,6 @@ similar to CVS but without its problems (e.g., it supports atomic commits of filesets, and versioning of directories, symbolic links, meta-data, renames, copies, and deletes). -@cindex GNU Arch -@cindex Arch -@item -GNU Arch is one of the earliest @dfn{decentralized} version control -systems (the other being Monotone). @xref{VCS Concepts}, for a -description of decentralized version control systems. It is no longer -under active development, and has been deprecated in favor of Bazaar. - @cindex git @item Git is a decentralized version control system originally invented by @@ -191,6 +183,18 @@ exception of repository sync operations. Bazaar (bzr) is a decentralized version control system that supports both repository-based and decentralized versioning. VC supports most basic editing operations under Bazaar. + +@cindex SRC +@cindex src +@item +SRC (src) is RCS, reloaded - a specialized version-control system +designed for single-file projects worked on by only one person. It +allows multiple files with independent version-control histories to +exist in one directory, and is thus particularly well suited for +maintaining small documents, scripts, and dotfiles. While it uses RCS +for revision storage, it presents a modern user interface featuring +lockless operation and integer sequential version numbers. VC +supports almost all SRC operations. @end itemize @node VCS Concepts @@ -268,8 +272,8 @@ number and severity of conflicts that actually occur. SCCS always uses locking. RCS is lock-based by default but can be told to operate in a merging style. CVS and Subversion are merge-based by default but can be told to operate in a locking mode. -Decentralized version control systems, such as GNU Arch, Git, and -Mercurial, are exclusively merging-based. +Decentralized version control systems, such as Git and Mercurial, are +exclusively merging-based. VC mode supports both locking and merging version control. The terms ``commit'' and ``update'' are used in newer version control @@ -1014,8 +1018,6 @@ Revert the work file(s) in the current VC fileset to the last revision (@code{vc-revert}). @end table -@c `C-x v c' (vc-rollback) was removed, since it's RCS/SCCS specific. - @kindex C-x v u @findex vc-revert @vindex vc-revert-show-diff diff --git a/doc/emacs/makefile.w32-in b/doc/emacs/makefile.w32-in index 2fd64d1d33c..91f9d37a1f7 100644 --- a/doc/emacs/makefile.w32-in +++ b/doc/emacs/makefile.w32-in @@ -54,7 +54,7 @@ EMACS_XTRA=\ $(srcdir)/vc-xtra.texi \ $(srcdir)/vc1-xtra.texi \ $(srcdir)/fortran-xtra.texi \ - $(srcdir)/msdog-xtra.texi + $(srcdir)/msdos-xtra.texi EMACSSOURCES= \ $(srcdir)/emacs.texi \ @@ -97,7 +97,7 @@ EMACSSOURCES= \ $(srcdir)/xresources.texi \ $(srcdir)/anti.texi \ $(srcdir)/macos.texi \ - $(srcdir)/msdog.texi \ + $(srcdir)/msdos.texi \ $(srcdir)/gnu.texi \ $(srcdir)/glossary.texi \ $(srcdir)/ack.texi \ diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index 0431e84b5b6..e12fca7ebdd 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -6,12 +6,12 @@ @chapter Miscellaneous Commands This chapter contains several brief topics that do not fit anywhere -else: viewing ``document files'', reading Usenet news, running shell -commands and shell subprocesses, using a single shared Emacs for -utilities that expect to run an editor as a subprocess, printing -hardcopy, sorting text, editing binary files, saving an Emacs session -for later resumption, following hyperlinks, emulating other editors, -and various diversions and amusements. +else: reading Usenet news, viewing PDFs and other such documents, web +browsing, running shell commands and shell subprocesses, using a +single shared Emacs for utilities that expect to run an editor as a +subprocess, printing, sorting text, editing binary files, saving an +Emacs session for later resumption, recursive editing level, following +hyperlinks, and various diversions and amusements. @end iftex @@ -249,6 +249,126 @@ Search forward for articles containing a match for @var{regexp}. Exit the summary buffer and return to the group buffer. @end table + +@node Network Security +@section Network Security +@cindex network security manager +@cindex NSM +@cindex encryption +@cindex SSL +@cindex TLS +@cindex STARTTLS + +Whenever Emacs establishes any network connection, it passes the +established connection to the @dfn{Network Security Manager} +(@acronym{NSM}). @acronym{NSM} is responsible for enforcing the +network security under your control. + +@vindex network-security-level +The @code{network-security-level} variable determines the security +level that @acronym{NSM} enforces. If its value is @code{low}, no +security checks are performed. + +If this variable is @code{medium} (which is the default), a number of +checks will be performed. If as result @acronym{NSM} determines that +the network connection might not be trustworthy, it will make you +aware of that, and will ask you what to do about the network +connection. + +You can decide to register a permanent security exception for an +unverified connection, a temporary exception, or refuse the connection +entirely. + +Below is a list of the checks done on the @code{medium} level. + +@table @asis + +@item unable to verify a @acronym{TLS} certificate +If the connection is a @acronym{TLS}, @acronym{SSL} or +@acronym{STARTTLS} connection, @acronym{NSM} will check whether +the certificate used to establish the identity of the server we're +connecting to can be verified. + +While an invalid certificate is often the cause for concern (there +could be a Man-in-the-Middle hijacking your network connection and +stealing your password), there may be valid reasons for going ahead +with the connection anyway. For instance, the server may be using a +self-signed certificate, or the certificate may have expired. It's up +to you to determine whether it's acceptable to continue with the +connection. + +@item a self-signed certificate has changed +If you've previously accepted a self-signed certificate, but it has +now changed, that could mean that the server has just changed the +certificate, but it might also mean that the network connection has +been hijacked. + +@item previously encrypted connection now unencrypted +If the connection is unencrypted, but it was encrypted in previous +sessions, this might mean that there is a proxy between you and the +server that strips away @acronym{STARTTLS} announcements, leaving the +connection unencrypted. This is usually very suspicious. + +@item talking to an unencrypted service when sending a password +When connecting to an @acronym{IMAP} or @acronym{POP3} server, these +should usually be encrypted, because it's common to send passwords +over these connections. Similarly, if you're sending email via +@acronym{SMTP} that requires a password, you usually want that +connection to be encrypted. If the connection isn't encrypted, +@acronym{NSM} will warn you. + +@end table + +If @code{network-security-level} is @code{high}, the following checks +will be made, in addition to the above: + +@table @asis +@item a validated certificate changes the public key +Servers change their keys occasionally, and that is normally nothing +to be concerned about. However, if you are worried that your network +connections are being hijacked by agencies who have access to pliable +Certificate Authorities which issue new certificates for third-party +services, you may want to keep track of these changes. + +@item Diffie-Hellman low prime bits +When doing the public key exchange, the number of ``prime bits'' +should be high to ensure that the channel can't be eavesdropped on by +third parties. If this number is too low, you will be warned. + +@item @acronym{RC4} stream cipher +The @acronym{RC4} stream cipher is believed to be of low quality and +may allow eavesdropping by third parties. + +@item @acronym{SSL1}, @acronym{SSL2} and @acronym{SSL3} +The protocols older than @acronym{TLS1.0} are believed to be +vulnerable to a variety of attacks, and you may want to avoid using +these if what you're doing requires higher security. +@end table + +Finally, if @code{network-security-level} is @code{paranoid}, you will +also be notified the first time @acronym{NSM} sees any new +certificate. This will allow you to inspect all the certificates from +all the connections that Emacs makes. + +The following additional variables can be used to control details of +@acronym{NSM} operation: + +@table @code +@item nsm-settings-file +@vindex nsm-settings-file +This is the file where @acronym{NSM} stores details about connections. +It defaults to @file{~/.emacs.d/network-security.data}. + +@item nsm-save-host-names +@vindex nsm-save-host-names +By default, host names will not be saved for non-@code{STARTTLS} +connections. Instead a host/port hash is used to identify connections. +This means that one can't casually read the settings file to see what +servers the user has connected to. If this variable is @code{t}, +@acronym{NSM} will also save host names in the nsm-settings-file. +@end table + + @node Document View @section Document Viewing @cindex DVI file @@ -2295,7 +2415,7 @@ the order you choose. @cindex vi @cindex WordStar - GNU Emacs can be programmed to emulate (more or less) some other + GNU Emacs can be programmed to emulate (more or less) most other editors. Standard facilities can emulate these: @table @asis diff --git a/doc/emacs/msdog-xtra.texi b/doc/emacs/msdos-xtra.texi index 1033aeb700b..b0fa3e919d5 100644 --- a/doc/emacs/msdog-xtra.texi +++ b/doc/emacs/msdos-xtra.texi @@ -6,19 +6,18 @@ @c printed version) or in the main Emacs manual (for the on-line version). @node MS-DOS @section Emacs and MS-DOS -@cindex MS-DOG @cindex MS-DOS peculiarities This section briefly describes the peculiarities of using Emacs on -the MS-DOS ``operating system'' (also known as ``MS-DOG''). +the MS-DOS ``operating system''. @iftex Information about Emacs and Microsoft's current operating system -Windows (also known as ``Losedows'') is in the main Emacs manual +Windows is in the main Emacs manual (@pxref{Microsoft Windows,,, emacs, the Emacs Manual}). @end iftex @ifnottex Information about peculiarities common to MS-DOS and Microsoft's -current operating systems Windows (also known as ``Losedows'') is in +current operating systems Windows is in @ref{Microsoft Windows}. @end ifnottex diff --git a/doc/emacs/msdog.texi b/doc/emacs/msdos.texi index bf130eba7c2..b5a66503ca2 100644 --- a/doc/emacs/msdog.texi +++ b/doc/emacs/msdos.texi @@ -9,7 +9,7 @@ This section describes peculiarities of using Emacs on Microsoft Windows. Some of these peculiarities are also relevant to Microsoft's -older MS-DOS ``operating system'' (also known as ``MS-DOG''). +older MS-DOS operating system. However, Emacs features that are relevant @emph{only} to MS-DOS are described in a separate @iftex @@ -986,5 +986,5 @@ click-to-focus policy. @end ifnottex @ifnottex -@include msdog-xtra.texi +@include msdos-xtra.texi @end ifnottex diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 48217c63b8c..8f6111dfa24 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -88,8 +88,8 @@ Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont Octave, Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl, and VHDL@. An alternative mode for Perl is called CPerl mode. Modes are also available for the scripting languages of the common GNU and Unix -shells, VMS DCL, and MS-DOS/MS-Windows @samp{BAT} files, and for -makefiles, DNS master files, and various sorts of configuration files. +shells, and MS-DOS/MS-Windows @samp{BAT} files, and for makefiles, +DNS master files, and various sorts of configuration files. Ideally, Emacs should have a major mode for each programming language that you might want to edit. If it doesn't have a mode for diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi index 3c595f9d9a3..dc53c3b5248 100644 --- a/doc/emacs/regs.texi +++ b/doc/emacs/regs.texi @@ -149,9 +149,9 @@ during the collection process, you can use the following setting. @kindex C-x r i @findex insert-register @kbd{C-x r i @var{r}} inserts in the buffer the text from register -@var{r}. Normally it leaves point before the text and sets the mark -after, without activating it. With a numeric argument, it instead -puts point after the text and the mark before. +@var{r}. Normally it leaves point after the text and sets the mark +before, without activating it. With a numeric argument, it instead +puts before after the text and the mark after. @node Rectangle Registers @section Saving Rectangles in Registers diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index a2cea8c6093..e91e2c4f81f 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -1436,6 +1436,22 @@ matching that regexp. This command is just like @code{multi-isearch-buffers}, except it performs an incremental regexp search. +@item M-x multi-isearch-files +Prompt for one or more file names, ending with @key{RET}; then, +begin a multi-file incremental search in those files. (If the +search fails in one file, the next @kbd{C-s} tries searching the +next specified file, and so forth.) With a prefix argument, prompt +for a regexp and begin a multi-file incremental search in files +matching that regexp. + +@item M-x multi-isearch-files-regexp +This command is just like @code{multi-isearch-files}, except it +performs an incremental regexp search. + +In some modes that set the buffer-local variable +@code{multi-isearch-next-buffer-function} (e.g., in Change Log mode) +a multi-file incremental search is activated automatically. + @cindex Occur mode @cindex mode, Occur @item M-x occur diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi index be519df4197..2faa5d91cc6 100644 --- a/doc/emacs/trouble.texi +++ b/doc/emacs/trouble.texi @@ -1060,19 +1060,44 @@ but using it will take extra work. Maintaining GNU Emacs is a lot of work in the best of circumstances, and we can't keep up unless you do your best to help. +Every patch must have several pieces of information before we +can properly evaluate it. + +When you have all these pieces, bundle them up in a mail message and +send it to the developers. Sending it to +@email{bug-gnu-emacs@@gnu.org} (which is the bug/feature list) is +recommended, because that list is coupled to a tracking system that +makes it easier to locate patches. If your patch is not complete and +you think it needs more discussion, you might want to send it to +@email{emacs-devel@@gnu@@gnu.org} instead. If you revise your patch, +send it as a followup to the initial topic. + +We prefer to get the patches as plain text, either inline (be careful +your mail client does not change line breaks) or as MIME attachments. + @itemize @bullet @item -Send an explanation with your changes of what problem they fix or what -improvement they bring about. For a fix for an existing bug, it is +Include an explanation with your changes of what problem they fix or what +improvement they bring about. + +@itemize +@item +For a fix for an existing bug, it is best to reply to the relevant discussion on the @samp{bug-gnu-emacs} list, or the bug entry in the GNU Bug Tracker at @url{http://debbugs.gnu.org}. Explain why your change fixes the bug. @item -Always include a proper bug report for the problem you think you have -fixed. We need to convince ourselves that the change is right before -installing it. Even if it is correct, we might have trouble -understanding it if we don't have a way to reproduce the problem. +For a new feature, include a description of the feature and your +implementation. + +@item +For a new bug, include a proper bug report for the problem you think +you have fixed. We need to convince ourselves that the change is +right before installing it. Even if it is correct, we might have +trouble understanding it if we don't have a way to reproduce the +problem. +@end itemize @item Include all the comments that are appropriate to help people reading the @@ -1104,6 +1129,8 @@ right away. That gives us the option of installing it immediately if it is important. @item +The patch itself. + Use @samp{diff -c} to make your diffs. Diffs without context are hard to install reliably. More than that, they are hard to study; we must always study a patch to decide whether we want to install it. Unidiff @@ -1114,6 +1141,12 @@ If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when making diffs of C code. This shows the name of the function that each change occurs in. +If you are using the Emacs repository, make sure your copy is +up-to-date (e.g. with @code{git pull}). You can commit your changes +to a private branch and generate a patch from the master version by +using @code{git format-patch master}. Or you can leave your changes +uncommitted and use @code{git diff}. + @item Avoid any ambiguity as to which is the old version and which is the new. Please make the old version the first argument to diff, and the new @@ -1138,8 +1171,16 @@ feel that the purpose needs explaining, it probably does---but put the explanation in comments in the code. It will be more useful there. Please look at the change log entries of recent commits to see what -sorts of information to put in, and to learn the style that we use. -@xref{Change Log}. +sorts of information to put in, and to learn the style that we use. Note that, +unlike some other projects, we do require change logs for +documentation, i.e. Texinfo files. +@xref{Change Log}, +@ifset WWW_GNU_ORG +see +@url{http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html}, +@end ifset +@xref{Change Log Concepts, Change Log Concepts, +Change Log Concepts, gnu-coding-standards, GNU Coding Standards}. @item When you write the fix, keep in mind that we can't install a change that @@ -1160,11 +1201,52 @@ Please help us keep up with the workload by designing the patch in a form that is clearly safe to install. @end itemize -@c FIXME: Include the node above? @node Contributing @section Contributing to Emacs Development @cindex contributing to Emacs +Emacs is a collaborative project and we encourage contributions from +anyone and everyone. + +There are many ways to contribute to Emacs: + +@itemize +@item +find and report bugs; @xref{Bugs}. + +@item +answer questions on the Emacs user mailing list +@url{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs}. + +@item +write documentation, either on the wiki, or in the Emacs source +repository (@pxref{Sending Patches}). + +@item +check if existing bug reports are fixed in newer versions of Emacs +@url{http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs}. + +@item +fix existing bug reports +@url{http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs}. + +@item +@c etc/TODO not in WWW_GNU_ORG +implement a feature listed in the @file{etc/TODO} file in the Emacs +distribution, and submit a patch. + +@item +implement a new feature, and submit a patch. + +@item +develop a package that works with Emacs, and publish it on your own +or in Gnu ELPA (@url{https://elpa.gnu.org/}). + +@item +port Emacs to a new platform, but that is not common nowadays. + +@end itemize + If you would like to work on improving Emacs, please contact the maintainers at @ifnothtml @email{emacs-devel@@gnu.org}. @@ -1186,24 +1268,148 @@ you have not yet started work, it is useful to contact before you start; it might be possible to suggest ways to make your extension fit in better with the rest of Emacs. +When implementing a feature, please follow the Emacs coding standards; +@xref{Coding Standards}. In addition, non-trivial contributions +require a copyright assignment to the FSF; @xref{Copyright Assignment}. + The development version of Emacs can be downloaded from the repository where it is actively maintained by a group of developers. See the Emacs project page -@url{http://savannah.gnu.org/projects/emacs/} for details. +@url{http://savannah.gnu.org/projects/emacs/} for access details. + +It is important to write your patch based on the current working +version. If you start from an older version, your patch may be +outdated (so that maintainers will have a hard time applying it), or +changes in Emacs may have made your patch unnecessary. After you have +downloaded the repository source, you should read the file +@file{INSTALL.REPO} for build instructions (they differ to some extent +from a normal build). + +If you would like to make more extensive contributions, see the +@file{./CONTRIBUTE} file in the Emacs distribution for information on +how to be an Emacs developer. + +For documentation on Emacs (to understand how to implement your +desired change), refer to: + +@itemize +@item +@ifset WWW_GNU_ORG +@ifhtml +the Emacs Manual +@url{http://www.gnu.org/software/emacs/manual/emacs.html}. +@end ifhtml +@ifnothtml +@xref{Top, Emacs Manual,,emacs}. +@end ifnothtml +@end ifset +@ifclear WWW_GNU_ORG +@xref{Top, Emacs Manual,,emacs}. +@end ifclear + +@item +@ifset WWW_GNU_ORG +@ifhtml +the Emacs Lisp Reference Manual +@url{http://www.gnu.org/software/emacs/manual/elisp.html}. +@end ifhtml +@ifnothtml +@xref{Top, Emacs Lisp Reference Manual,,elisp}. +@end ifnothtml +@end ifset +@ifclear WWW_GNU_ORG +@xref{Top, Emacs Lisp Reference Manual,,elisp}. +@end ifclear + +@item +@url{http://www.gnu.org/software/emacs} + +@item +@url{http://www.emacswiki.org/} +@end itemize + +@menu +* Coding Standards:: Gnu Emacs coding standards +* Copyright Assignment:: assigning copyright to the FSF +@end menu -For more information on how to contribute, see the +@node Coding Standards +@subsection Coding Standards +@cindex coding standards + +Contributed code should follow the GNU Coding Standards +@url{http://www.gnu.org/prep/standards/}. This may also be available +in info on your system. + +If it doesn't, we'll need to find someone to fix the code before we +can use it. + +Emacs has additional style and coding conventions: + +@itemize +@item @ifset WWW_GNU_ORG @ifhtml -@url{http://gnu.org/software/emacs/CONTRIBUTE, etc/CONTRIBUTE} +the "Tips" Appendix in the Emacs Lisp Reference +@url{http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html}. @end ifhtml @ifnothtml -@file{etc/CONTRIBUTE} +@xref{Tips, "Tips" Appendix in the Emacs Lisp Reference, Tips +Appendix, elisp, Emacs Lisp Reference}. @end ifnothtml @end ifset @ifclear WWW_GNU_ORG -@file{etc/CONTRIBUTE} +@xref{Tips, "Tips" Appendix in the Emacs Lisp Reference, Tips +Appendix, elisp, Emacs Lisp Reference}. @end ifclear -file in the Emacs distribution. + +@item +Avoid using @code{defadvice} or @code{eval-after-load} for Lisp code +to be included in Emacs. + +@item +Remove all trailing whitespace in all source and text files. + +@item +Emacs has no convention on whether to use tabs in source code; please +don't change whitespace in the files you edit. + +@item +Use @code{?\s} instead of @code{? } in Lisp code for a space character. + +@end itemize + +@node Copyright Assignment +@subsection Copyright Assignment +@cindex copyright assignment + +The FSF (Free Software Foundation) is the copyright holder for GNU Emacs. +The FSF is a nonprofit with a worldwide mission to promote computer +user freedom and to defend the rights of all free software users. +For general information, see the website @url{http://www.fsf.org/}. + +Generally speaking, for non-trivial contributions to GNU Emacs we +require that the copyright be assigned to the FSF. For the reasons +behind this, see @url{http://www.gnu.org/licenses/why-assign.html}. + +Copyright assignment is a simple process. Residents of some countries +can do it entirely electronically. We can help you get started, and +answer any questions you may have (or point you to the people with the +answers), at the @email{emacs-devel@@gnu.org} mailing list. + +(Please note: general discussion about why some GNU projects ask +for a copyright assignment is off-topic for emacs-devel. +See gnu-misc-discuss instead.) + +A copyright disclaimer is also a possibility, but we prefer an assignment. +Note that the disclaimer, like an assignment, involves you sending +signed paperwork to the FSF (simply saying "this is in the public domain" +is not enough). Also, a disclaimer cannot be applied to future work, it +has to be repeated each time you want to send something new. + +We can accept small changes (roughly, fewer than 15 lines) without +an assignment. This is a cumulative limit (e.g. three separate 5 line +patches) over all your contributions. @node Service @section How To Get Help with GNU Emacs @@ -1211,8 +1417,8 @@ file in the Emacs distribution. @cindex help-gnu-emacs mailing list @cindex gnu.emacs.help newsgroup -If you need help installing, using or changing GNU Emacs, there are two -ways to find it: +If you need help installing, using or changing GNU Emacs, there are +two ways to find it: @itemize @bullet @item diff --git a/doc/lispintro/ChangeLog b/doc/lispintro/ChangeLog index 01e56d62d6b..57ab03b1155 100644 --- a/doc/lispintro/ChangeLog +++ b/doc/lispintro/ChangeLog @@ -1,3 +1,11 @@ +2014-12-31 Paul Eggert <eggert@cs.ucla.edu> + + Less 'make' chatter for Emacs doc + * Makefile.in (AM_DEFAULT_VERBOSITY, AM_V_GEN, am__v_GEN_) + (am__v_GEN_0, am__v_GEN_1): New macros, from ../../src/Makefile.in. + (ENVADD, $(buildinfodir)/eintr.info, emacs-lisp-intro.html): + Use them. + 2014-11-09 Glenn Morris <rgm@gnu.org> * Makefile.in (version): Remove variable. @@ -6,26 +14,51 @@ 2014-10-20 Glenn Morris <rgm@gnu.org> - * emacs-lisp-intro.texi (Autoload): Update loaddefs.el details. - -2014-10-20 Glenn Morris <rgm@gnu.org> - - * Version 24.4 released. + * Merge in all changes up to 24.4 release. 2014-10-13 Glenn Morris <rgm@gnu.org> * Makefile.in (dist): Update for new output variables. -2014-07-15 Álvar Jesús Ibeas Martín <alvar.ibeas@unican.es> (tiny change) +2014-07-16 Álvar Jesús Ibeas Martín <alvar.ibeas@unican.es> (tiny change) * emacs-lisp-intro.texi (Variables, Buffer Names, if & or) (Symbols as Chest, fwd-para while): Fix typos. -2014-06-29 Glenn Morris <rgm@gnu.org> +2014-07-03 Glenn Morris <rgm@gnu.org> * emacs-lisp-intro.texi (Note for Novices, Finding More, Conclusion): "Online" help doesn't mean what it used to any more. +2014-06-23 Glenn Morris <rgm@gnu.org> + + * Makefile.in (%.texi): Disable implicit rules. + (mkinfodir): Remove. + (.dvi.ps): Replace with explicit rule. + (${buildinfodir}): New rule. + (${buildinfodir}/eintr.info): Use order-only prereq for output dir. + Use $<. + (emacs-lisp-intro.dvi, emacs-lisp-intro.pdf, emacs-lisp-intro.html): + Use $<. + (emacs-lisp-intro.ps): New rule. + +2014-06-15 Glenn Morris <rgm@gnu.org> + + * Makefile.in (bootstrap-clean): New. + +2014-06-10 Glenn Morris <rgm@gnu.org> + + * Makefile.in (INFO_EXT): Remove and replace by ".info" throughout. + (INFO_OPTS): Set directly rather than with configure. + +2014-06-02 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi (Autoload): Update loaddefs.el details. + +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. @@ -556,8 +589,8 @@ 2006-11-05 Robert J. Chassell <bob@rattlesnake.com> * emacs-lisp-intro.texi: Yet more minor changes: - (defcustom): Said that `:options' is usually for a hook. Remove - extraneous space in parenthetical remark concerning + (defcustom): Said that `:options' is usually for a hook. + Remove extraneous space in parenthetical remark concerning `text-mode-hook-identify'. At end, mention other defines, too. (Beginning a .emacs File): Reverse words about comments so they parallel numbers of listed semi-colons. @@ -579,12 +612,12 @@ Center images for TeX output. (kill-new function): Remove indentation for sentence talking about momentarily skipping code. - (cons & search-fwd Review): Document @code{funcall}. Document - @code{re-search-forward} with existing @code{search-forward}. + (cons & search-fwd Review): Document @code{funcall}. + Document @code{re-search-forward} with existing @code{search-forward}. Reference chapter on regular expression searches. (Recursion with list): Specify a more recent version as being Emacs. - (Recursion with list, Every, recursive-graph-body-print): Change - `if ... progn' expression to `when'. + (Recursion with list, Every, recursive-graph-body-print): + Change `if ... progn' expression to `when'. (Recursive triangle function): For printing in small book, ensure section name is not last on bottom of preceding page. (Keep): Remove extraneous space in function definition example. @@ -593,11 +626,11 @@ function. (fwd-sentence while loops): Write a function as one, not as a form. (fwd-para let): Add `which' to sentence with `parstart' and `parsep'. - (etags): Move sentences involving `find-tag' and sources. State - location of Emacs `src' directory. + (etags): Move sentences involving `find-tag' and sources. + State location of Emacs `src' directory. (Design count-words-region): Better explain two backslashes in a row. - (Find a File): Fix grammar; add a `to' and write `to visit'. Change - `named' to `selected'. + (Find a File): Fix grammar; add a `to' and write `to visit'. + Change `named' to `selected'. (lengths-list-file): Remove extraneous parenthesis from reference. (lengths-list-many-files): Explain `expand-file-name' better. (Files List): Rephrase sentence regarding Lisp sources directory. @@ -625,8 +658,8 @@ seen' the @code{eq} function. (kill-append function): Reformat `kill-append' function definition so it prints well. - (kill-new function): Indent the sentence beginning `notice'. Replace - `the same as' with `similar to'. Repair typo. Remove obsolete + (kill-new function): Indent the sentence beginning `notice'. + Replace `the same as' with `similar to'. Repair typo. Remove obsolete references to `yank' and `yank-pop. End section with a note that `we will digress into C.' @@ -650,8 +683,8 @@ is 3.00. Did not update ISBN number. * emacs-lisp-intro.texi: Remove version reference for X colors. - Document `='. Remove mention that :eval was new in 21. Updated - instance's edition-number to 3.01. + Document `='. Remove mention that :eval was new in 21. + Updated instance's edition-number to 3.01. 2006-10-30 Robert J. Chassell <bob@rattlesnake.com> diff --git a/doc/lispintro/Makefile.in b/doc/lispintro/Makefile.in index 825df040f2f..ba63ee80197 100644 --- a/doc/lispintro/Makefile.in +++ b/doc/lispintro/Makefile.in @@ -43,9 +43,8 @@ GZIP_PROG = @GZIP_PROG@ HTML_OPTS = --no-split --html -INFO_EXT=@INFO_EXT@ # Options used only when making info output. -INFO_OPTS=@INFO_OPTS@ +INFO_OPTS= --no-split INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ @@ -56,50 +55,58 @@ TEXI2DVI = texi2dvi TEXI2PDF = texi2pdf DVIPS = dvips -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ - MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" +# 'make' verbosity. +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ + +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = + +ENVADD = \ + $(AM_V_GEN)TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ + MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" DVI_TARGETS = emacs-lisp-intro.dvi HTML_TARGETS = emacs-lisp-intro.html PDF_TARGETS = emacs-lisp-intro.pdf PS_TARGETS = emacs-lisp-intro.ps -mkinfodir = @${MKDIR_P} ${buildinfodir} - srcs = ${srcdir}/emacs-lisp-intro.texi ${srcdir}/doclicense.texi \ ${emacsdir}/emacsver.texi -.PHONY: info dvi html pdf ps - -.SUFFIXES: .ps .dvi +## Disable implicit rules. +%.texi: ; -.dvi.ps: - $(DVIPS) -o $@ $< - -info: ${buildinfodir}/eintr$(INFO_EXT) +.PHONY: info dvi html pdf ps +info: ${buildinfodir}/eintr.info dvi: $(DVI_TARGETS) html: $(HTML_TARGETS) pdf: $(PDF_TARGETS) ps: $(PS_TARGETS) +${buildinfodir}: + ${MKDIR_P} $@ + # The file name eintr must fit within 5 characters, to allow for # -NN extensions to fit into DOS 8+3 limits without clashing. -# Note: "<" is not portable in ordinary make rules. -${buildinfodir}/eintr$(INFO_EXT): ${srcs} - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/emacs-lisp-intro.texi +${buildinfodir}/eintr.info: ${srcs} | ${buildinfodir} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $< emacs-lisp-intro.dvi: ${srcs} - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-lisp-intro.texi + $(ENVADD) $(TEXI2DVI) $< emacs-lisp-intro.pdf: ${srcs} - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs-lisp-intro.texi + $(ENVADD) $(TEXI2PDF) $< emacs-lisp-intro.html: ${srcs} - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/emacs-lisp-intro.texi + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $< + +emacs-lisp-intro.ps: emacs-lisp-intro.dvi + $(DVIPS) -o $@ $< -.PHONY: mostlyclean clean distclean maintainer-clean infoclean +.PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean infoclean mostlyclean: rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ @@ -112,9 +119,11 @@ distclean: clean rm -f Makefile infoclean: - -cd $(buildinfodir) && rm -f eintr$(INFO_EXT) eintr$(INFO_EXT)-[1-9] + rm -f \ + $(buildinfodir)/eintr.info \ + $(buildinfodir)/eintr.info-[1-9] -maintainer-clean: distclean infoclean +bootstrap-clean maintainer-clean: distclean infoclean .PHONY: install-dvi install-html install-pdf install-ps install-doc diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 5a07a45468d..b6eff2de0dc 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @comment %**start of header -@setfilename ../../info/eintr +@setfilename ../../info/eintr.info @c setfilename emacs-lisp-intro.info @c sethtmlfilename emacs-lisp-intro.html @settitle Programming in Emacs Lisp diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index c4b80a03575..4c0c116ba5a 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,10 +1,41 @@ -2014-12-24 Glenn Morris <rgm@gnu.org> +2015-01-15 Eli Zaretskii <eliz@gnu.org> + + * streams.texi (Input Functions): Document 'set-binary-mode'. + (Output Functions): Cross-reference to documentation of + 'set-binary-mode'. + +2015-01-04 Paul Eggert <eggert@cs.ucla.edu> + + batch write-region no longer says "Wrote FOO" + * files.texi (Writing to Files): Document this. + +2014-12-31 Paul Eggert <eggert@cs.ucla.edu> + + Less 'make' chatter for Emacs doc + * Makefile.in (AM_DEFAULT_VERBOSITY, AM_V_GEN, am__v_GEN_) + (am__v_GEN_0, am__v_GEN_1): New macros, from ../../src/Makefile.in. + (ENVADD, $(buildinfodir)/elisp.info, elisp.html): + Use them. + +2014-12-30 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Temporary Displays): Amend description of + `with-temp-buffer-window'. Add descriptions for + `with-current-buffer-window', `with-displayed-buffer-window' and + `temp-buffer-resize-mode', `temp-buffer-max-height' and + `temp-buffer-max-width'. + +2014-12-29 Paul Eggert <eggert@cs.ucla.edu> + + * os.texi (System Environment): Update for system-name changes. + +2014-12-27 Glenn Morris <rgm@gnu.org> * control.texi (Pattern matching case statement): * os.texi (Desktop Notifications): * modes.texi (Defining Minor Modes, SMIE Lexer): Markup fixes. -2014-12-23 Eli Zaretskii <eliz@gnu.org> +2014-12-27 Eli Zaretskii <eliz@gnu.org> * windows.texi (Recombining Windows): Index subject of sections. @@ -105,44 +136,194 @@ * os.texi (Time of Day, Time Conversion, Time Parsing) (Time Calculations, Idle Timers): Index subject of sections. +2014-12-25 Martin Rudalics <rudalics@gmx.at> + + * windows.texi (Windows): Resync @menu order with @node order. + + * minibuf.texi (Minibuffer Windows): Add descriptions of + `resize-mini-windows' and `max-mini-window-height'. + +2014-12-25 Glenn Morris <rgm@gnu.org> + + * windows.texi (Windows): Sync @menu order with @node order. + + * sequences.texi (Sequence Functions): Copyedits. + + * control.texi (Pattern matching case statement): + * positions.texi (List Motion): + * streams.texi (Output Functions): + * strings.texi (Text Comparison): + * text.texi (Document Object Model): Markup fixes. + +2014-12-22 Paul Eggert <eggert@cs.ucla.edu> + + Remove obsolete references to pre-C99 builds + * internals.texi (C Integer Types): Don't mention pre-C99 compilers. + +2014-12-19 Martin Rudalics <rudalics@gmx.at> + + * windows.texi (Resizing Windows): Describe new argument of + `fit-window-to-buffer'. Move description of `window-size-fixed' + to new section below. + (Preserving Window Sizes): New section describing + `window-size-fixed' and `window-preserve-size'. + (Display Action Functions): Describe `preserve-size' alist + entry. + (Window Parameters): Describe `preserved-size' parameter. + +2014-12-18 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Low-Level Font): Document font-info and query-font. + 2014-12-18 Stefan Monnier <monnier@iro.umontreal.ca> - * display.texi (Forcing Redisplay): Remove references to - redisplay-dont-pause and redisplay-preemption-period (which doesn't - even exist). + * display.texi (Forcing Redisplay): Remove references to + redisplay-dont-pause and redisplay-preemption-period (which doesn't + even exist). + +2014-12-16 Nicolas Petton <petton.nicolas@gmail.com> + + * sequences.texi (Seq Library): Add documentation for seq.el. + +2014-12-15 Alan Mackenzie <acm@muc.de> -2014-12-11 Eli Zaretskii <eliz@gnu.org> + "Advice" is a mass noun. Amend text accordingly. + * functions.texi: (Advising Functions, Core Advising Primitives) + (Advising Named Functions, Advice combinators) + (Porting old advice): Replace, e.g., "an advice" with "advice". + +2014-12-13 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * files.texi (Relative File Names): Mention `directory-name-p'. + +2014-12-13 Eli Zaretskii <eliz@gnu.org> * text.texi (Comparing Text): Prevent a text string from being broken between 2 lines. (Bug#19257) -2014-11-19 Paul Eggert <eggert@cs.ucla.edu> +2014-12-09 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * files.texi (Contents of Directories): + Document directory-files-recursively. + +2014-12-04 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Bidirectional Display): + Document 'buffer-substring-with-bidi-context'. + + * text.texi (Buffer Contents): + Mention 'buffer-substring-with-bidi-context' with a cross-reference. + +2014-12-02 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Bidirectional Display): + Document 'bidi-find-overridden-directionality'. + +2014-11-29 Paul Eggert <eggert@cs.ucla.edu> Lessen focus on ChangeLog files, as opposed to change log entries. * intro.texi (Acknowledgments): ChangeLog file -> change log entries. * tips.texi (Library Headers): Emacs uses a version control system. +2014-11-27 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * text.texi (Document Object Model): Mention `dom-pp'. + +2014-11-26 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * text.texi (Document Object Model): New node to document dom.el. + +2014-11-24 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * processes.texi (Network Security): Made into its own section and + fleshed out. + (Network Security): Mention more NSM variables. + (Processes): Move the Network Security Manager stuff to the Emacs + manual. + +2014-11-23 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * processes.texi (Network): Mention the new :warn-unless-encrypted + parameter to `open-network-stream'. + (Network): Mention the Network Security Manager. + +2014-11-21 Ulf Jasper <ulf.jasper@web.de> + + * text.texi (Parsing HTML/XML): Document new optional parameter + 'discard-comments' of 'libxml-parse(html|xml)-region'. + +2014-11-18 Leo Liu <sdl.web@gmail.com> + + * functions.texi (Advising Named Functions): + Document define-advice. + +2014-11-17 Paul Eggert <eggert@cs.ucla.edu> + + Improve time stamp handling, and be more consistent about it. + * os.texi (Time of Day, Time Conversion, Time Parsing) + (Processor Run Time, Time Calculations): + Document the new behavior, plus be clearer about the old behavior. + (Idle Timers): Take advantage of new functionality. + +2014-11-16 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * text.texi (Special Properties): Mention `inhibit-read-only'. + +2014-11-14 Paul Eggert <eggert@cs.ucla.edu> + + * os.texi (Time of Day): + Use leading zero with 24-hour times less than 10:00. + 2014-11-09 Glenn Morris <rgm@gnu.org> * Makefile.in (version): Remove variable. (clean): No longer delete dist tarfile. (dist): Remove rule; replace with code in admin.el. +2014-11-07 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Size and Position): Rewrite description of + `frame-inhibit-implied-resize'. + +2014-10-22 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Size Parameters): Replace "frame contents" by + "frame's text area". Add reference to Size and Position + section. + (Size and Position): Major rewrite. Add explanations for + frame's default font, text and display areas. Add descriptions + for `set-frame-font', `frame-text-height', `frame-text-width' + and `frame-inhibit-implied-resize'. + 2014-10-20 Glenn Morris <rgm@gnu.org> - * Version 24.4 released. + * Merge in all changes up to 24.4 release. + +2014-10-20 Tom Tromey <tom@tromey.com> + + * objects.texi (Type Predicates): Don't mention display-table-p. + +2014-10-15 Eli Zaretskii <eliz@gnu.org> + + * nonascii.texi (Character Properties): Document the new + properties 'bracket-type' and 'paired-bracket'. + + * display.texi (Bidirectional Display): Update the version of the + UBA to which we are conforming. 2014-10-13 Glenn Morris <rgm@gnu.org> * Makefile.in (dist): Update for new output variables. -2014-10-09 Glenn Morris <rgm@gnu.org> +2014-10-12 Glenn Morris <rgm@gnu.org> * elisp.texi (DATE): Bump to October 2014. +2014-10-09 Glenn Morris <rgm@gnu.org> + * frames.texi (Multiple Terminals): Copyedits. -2014-10-08 Eli Zaretskii <eliz@gnu.org> +2014-10-09 Eli Zaretskii <eliz@gnu.org> * frames.texi (Multiple Terminals): Improve the description of X display names. Add index entries. @@ -155,6 +336,22 @@ frame might be positioned differently than specified by the frame parameters alist. +2014-10-08 Leo Liu <sdl.web@gmail.com> + + * streams.texi (Output Functions): Document new argument ENSURE to + terpri. (Bug#18652) + +2014-10-04 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Scroll Bars): Add description of horizontal scroll + bars and associated functions. + * frames.texi (Layout Parameters): Add horizontal scroll bar + entries. Remove paragraph on "combined fringe widths". + * windows.texi (Window Sizes): Describe affects of horizontal + scroll bars on window layout and sizes. Fix description of + window-full-height-p. + (Resizing Windows): Mention horizontal scroll bar. + 2014-10-04 Glenn Morris <rgm@gnu.org> * commands.texi (Generic Commands): Copyedits. @@ -173,45 +370,141 @@ 2014-10-03 Martin Rudalics <rudalics@gmx.at> * frames.texi (Size Parameters, Size and Position): Mention that - with some window managers you have to set - `frame-resize-pixelwise' in order make a frame truly fullscreen - or maximized. + with some window managers you have to set `frame-resize-pixelwise' + in order make a frame truly fullscreen or maximized. + +2014-10-01 Paul Eggert <eggert@cs.ucla.edu> + + Improve doc for use of 'int', and discuss 'ssize_t'. + * internals.texi (C Integer Types): Mention 'int' for other + randomish values that lie in 'int' range. Mention 'ssize_t'. See: + http://lists.gnu.org/archive/html/emacs-devel/2014-10/msg00019.html + + Use AUTO_CONS instead of SCOPED_CONS, etc. + * internals.texi (Stack-allocated Objects): + Adjust to match the revised, less error-prone macros. + +2014-09-30 Paul Eggert <eggert@cs.ucla.edu> + + * internals.texi (Stack-allocated Objects): Further improvements. + Give an example of misuse. + +2014-09-30 Eli Zaretskii <eliz@gnu.org> + + * internals.texi (Stack-allocated Objects): Minor improvements of + the wording and the indexing. + +2014-09-30 Dmitry Antipov <dmantipov@yandex.ru> -2014-09-04 Stefan Monnier <monnier@iro.umontreal.ca> + * internals.texi (Stack-allocated Objects): Describe this feature. + +2014-09-15 Daniel Colascione <dancol@dancol.org> + + * text.texi (Registers): Make `insert-register' documentation + reflect interface change. + +2014-09-08 Stefan Monnier <monnier@iro.umontreal.ca> * functions.texi (Core Advising Primitives): Add a note about the confusing treatment of `interactive' for :filter-args (bug#18399). -2014-08-19 Eli Zaretskii <eliz@gnu.org> +2014-09-07 Michael Albinus <michael.albinus@gmx.de> + + * strings.texi (Text Comparison): Describe `string-collate-equalp' + and `string-collate-lessp'. + +2014-09-06 Leo Liu <sdl.web@gmail.com> + + * control.texi (Pattern matching case statement): Document vector + qpattern. (Bug#18327) + +2014-08-29 Dmitry Antipov <dmantipov@yandex.ru> + + * lists.texi (Functions that Rearrange Lists): + Remove description of sort ... + * sequences.texi (Sequence Functions): ... and generalize + it for sequences. Add an example. + +2014-08-28 Eli Zaretskii <eliz@gnu.org> * display.texi (Bidirectional Display): Update the Emacs's class of bidirectional conformance. -2014-07-08 Stefan Monnier <monnier@iro.umontreal.ca> +2014-08-27 Dmitry Antipov <dmantipov@yandex.ru> + + * eval.texi (Eval): Mention possible recovery from stack overflow. + +2014-07-11 Eli Zaretskii <eliz@gnu.org> + + * internals.texi (Garbage Collection): Fix last change. + +2014-07-11 Dmitry Antipov <dmantipov@yandex.ru> + + * internals.texi (Garbage Collection): Mention memory-info. + +2014-07-11 Michael Albinus <michael.albinus@gmx.de> + + * minibuf.texi (Intro to Minibuffers, Reading a Password): + Password hiding is available in batch mode, do not mention it in + the exclusion list. Mention `read-hide-char'. (Bug#17839) + +2014-07-09 Stefan Monnier <monnier@iro.umontreal.ca> * debugging.texi (Function Debugging, Debugger Commands): Update debug-on-entry w.r.t behavior after redefinitions (bug#17902). -2014-06-29 Glenn Morris <rgm@gnu.org> +2014-07-03 Glenn Morris <rgm@gnu.org> * help.texi (Help Functions): "Online" help doesn't mean what it used to any more. -2014-06-26 Glenn Morris <rgm@gnu.org> +2014-07-02 Stefan Monnier <monnier@iro.umontreal.ca> + + * keymaps.texi (Key Lookup): Remove mention of indirect entries. + (Scanning Keymaps): Reword the `noindirect' argument. + +2014-06-28 Glenn Morris <rgm@gnu.org> * minibuf.texi (Intro to Minibuffers): Batch mode is basic. (Reading a Password): Mention batch mode. (Bug#17839) +2014-06-23 Glenn Morris <rgm@gnu.org> + + * Makefile.in (%.texi): Disable implicit rules. + (mkinfodir): Remove. + (.dvi.ps): Replace with explicit rule. + (html): Declare as PHONY. + (${buildinfodir}): New rule. + ($(buildinfodir)/elisp.info): Use order-only prereq for output dir. + Use $<. + (elisp.dvi, elisp.html, elisp.pdf): Use $<. + (elisp.ps): New rule. + 2014-06-21 Eli Zaretskii <eliz@gnu.org> * positions.texi (Screen Lines): Clarify how columns are counted by vertical-motion. -2014-06-14 Eli Zaretskii <eliz@gnu.org> +2014-06-15 Glenn Morris <rgm@gnu.org> + + * Makefile.in (bootstrap-clean): New. + +2014-06-15 Eli Zaretskii <eliz@gnu.org> * commands.texi (Accessing Mouse): Improve the wording of the posn-col-row documentation. (Bug#17768) +2014-06-10 Glenn Morris <rgm@gnu.org> + + * Makefile.in (INFO_EXT): Remove and replace by ".info" throughout. + (INFO_OPTS): Set directly rather than with configure. + +2014-06-09 Paul Eggert <eggert@cs.ucla.edu> + + Say (accept-process-output P)'s result pertains to P if P is non-nil. + * processes.texi (Accepting Output): Mention that if PROCESS is non-nil, + the return value is about PROCESS, not about other processes. + 2014-06-08 Glenn Morris <rgm@gnu.org> * os.texi (Startup Summary): Small fix for initial-buffer-choice. @@ -220,7 +513,7 @@ * numbers.texi (Comparison of Numbers): Copyedits. -2014-06-06 Glenn Morris <rgm@gnu.org> +2014-06-08 Glenn Morris <rgm@gnu.org> * display.texi (Window Systems): Remove window-setup-hook. * os.texi (Startup Summary, Init File): @@ -230,11 +523,14 @@ * display.texi (Overlay Properties): Update re priority. (Bug#17234) -2014-06-05 Glenn Morris <rgm@gnu.org> - * package.texi (Package Archives): Mention signing packages. -2014-05-27 Glenn Morris <rgm@gnu.org> +2014-06-07 Eli Zaretskii <eliz@gnu.org> + + * commands.texi (Click Events): Update contents of click event's + position list due to last changes in make_lispy_position. + +2014-06-02 Glenn Morris <rgm@gnu.org> * text.texi (Buffer Contents): Update for filter-buffer-substring changes. @@ -242,53 +538,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> -2014-04-04 Glenn Morris <rgm@gnu.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-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 @@ -296,8 +656,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> @@ -305,7 +675,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. @@ -13342,7 +13712,7 @@ 1998-01-30 Richard Stallman <rms@psilocin.gnu.org> - * Makefile (SHELL): Defined. + * Makefile (SHELL): Define. 1998-01-27 Richard Stallman <rms@psilocin.gnu.org> diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in index 075d4a7d5e6..4c62c703462 100644 --- a/doc/lispref/Makefile.in +++ b/doc/lispref/Makefile.in @@ -47,9 +47,8 @@ GZIP_PROG = @GZIP_PROG@ HTML_OPTS = --no-split --html -INFO_EXT=@INFO_EXT@ # Options used only when making info output. -INFO_OPTS=@INFO_OPTS@ +INFO_OPTS= --no-split INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ @@ -60,8 +59,17 @@ TEXI2DVI = texi2dvi TEXI2PDF = texi2pdf DVIPS = dvips -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ - MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" +# 'make' verbosity. +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ + +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = + +ENVADD = \ + $(AM_V_GEN)TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ + MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" DVI_TARGETS = elisp.dvi HTML_TARGETS = elisp.html @@ -123,36 +131,36 @@ srcs = \ $(srcdir)/gpl.texi \ $(srcdir)/doclicense.texi -mkinfodir = @${MKDIR_P} ${buildinfodir} - -.PHONY: info dvi pdf ps - -.SUFFIXES: .ps .dvi +## Disable implicit rules. +%.texi: ; -.dvi.ps: - $(DVIPS) -o $@ $< +.PHONY: info dvi html pdf ps -info: $(buildinfodir)/elisp$(INFO_EXT) +info: $(buildinfodir)/elisp.info dvi: $(DVI_TARGETS) html: $(HTML_TARGETS) pdf: $(PDF_TARGETS) ps: $(PS_TARGETS) -## Note: "<" is not portable in ordinary make rules. -$(buildinfodir)/elisp$(INFO_EXT): $(srcs) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $(srcdir)/elisp.texi +${buildinfodir}: + ${MKDIR_P} $@ + +$(buildinfodir)/elisp.info: $(srcs) | ${buildinfodir} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $< elisp.dvi: $(srcs) - $(ENVADD) $(TEXI2DVI) $(srcdir)/elisp.texi + $(ENVADD) $(TEXI2DVI) $< elisp.html: $(srcs) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $(srcdir)/elisp.texi + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $< elisp.pdf: $(srcs) - $(ENVADD) $(TEXI2PDF) $(srcdir)/elisp.texi + $(ENVADD) $(TEXI2PDF) $< + +elisp.ps: elisp.dvi + $(DVIPS) -o $@ $< -.PHONY: mostlyclean clean distclean maintainer-clean infoclean +.PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean infoclean ## [12] stuff is from two-volume.make. mostlyclean: @@ -168,9 +176,12 @@ 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 \ + $(buildinfodir)/elisp.info-[1-9] \ + $(buildinfodir)/elisp.info-[1-9][0-9] -maintainer-clean: distclean infoclean +bootstrap-clean maintainer-clean: distclean infoclean .PHONY: install-dvi install-html install-pdf install-ps install-doc diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index a503e3f117b..36c74450ed4 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}. @@ -1392,8 +1395,9 @@ The position in the string where the click occurred. @item @var{text-pos} For clicks on a marginal area or on a fringe, this is the buffer position of the first visible character in the corresponding line in -the window. For other events, it is the current buffer position in -the window. +the window. For clicks on the mode line or the header line, this is +@code{nil}. For other events, it is the buffer position closest to +the click. @item @var{col}, @var{row} These are the actual column and row coordinate numbers of the glyph diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 9a9c575c251..d21292348a4 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -372,6 +372,10 @@ More specifically, a Q-pattern can take the following forms: @item (@var{qpattern1} . @var{qpattern2}) This pattern matches any cons cell whose @code{car} matches @var{qpattern1} and whose @code{cdr} matches @var{pattern2}. +@item [@var{qpattern1} @var{qpattern2} @dots{} @var{qpatternm}] +This pattern matches a vector of length @var{M} whose 0..(@var{M}-1)th +elements match @var{qpattern1}, @var{qpattern2} @dots{} @var{qpatternm}, +respectively. @item @var{atom} This pattern matches any atom @code{equal} to @var{atom}. @item ,@var{upattern} diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 0128e469db2..1b7f21da282 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -23,7 +23,7 @@ that Emacs presents to the user. * Faces:: A face defines a graphics style for text characters: font, colors, etc. * Fringes:: Controlling window fringes. -* Scroll Bars:: Controlling vertical scroll bars. +* Scroll Bars:: Controlling scroll bars. * Window Dividers:: Separating windows visually. * Display Property:: Enabling special display features. * Images:: Displaying images in Emacs buffers. @@ -1169,12 +1169,6 @@ it prints into the buffer named @var{buffer-or-name} and displays that buffer in some window. Unlike @code{with-output-to-temp-buffer}, however, it does not automatically switch that buffer to Help mode. -Like @code{with-output-to-temp-buffer} it neither makes the buffer -specified by @var{buffer-or-name} current when executing @var{body}. -@findex with-current-buffer-window -The otherwise identical macro @code{with-current-buffer-window} can be -used to execute @var{body} with that buffer current. - The argument @var{buffer-or-name} specifies the temporary buffer. It can be either a buffer, which must already exist, or a string, in which case a buffer of that name is created, if necessary. The buffer is @@ -1182,14 +1176,14 @@ marked as unmodified and read-only when @code{with-temp-buffer-window} exits. This macro does not call @code{temp-buffer-show-function}. Rather, it -passes the @var{action} argument to @code{display-buffer} in order to -display the buffer. +passes the @var{action} argument to @code{display-buffer} +(@pxref{Choosing Window}) in order to display the buffer. The value of the last form in @var{body} is returned, unless the argument @var{quit-function} is specified. In that case, it is called with two arguments: the window showing the buffer and the result of -@var{body}. The final return value is then whatever -@var{quit-function} returns. +@var{body}. The final return value is then whatever @var{quit-function} +returns. @vindex temp-buffer-window-setup-hook @vindex temp-buffer-window-show-hook @@ -1198,6 +1192,56 @@ and @code{temp-buffer-window-show-hook} in place of the analogous hooks run by @code{with-output-to-temp-buffer}. @end defmac +The two constructs described next are mostly identical to +@code{with-temp-buffer-window} but differ from it as specified: + +@defmac with-current-buffer-window buffer-or-name action quit-function &rest body +This macro is like @code{with-temp-buffer-window} but unlike that makes +the buffer specified by @var{buffer-or-name} current for running +@var{body}. +@end defmac + +@defmac with-displayed-buffer-window buffer-or-name action quit-function &rest body +This macro is like @code{with-current-buffer-window} but unlike that +displays the buffer specified by @var{buffer-or-name} @emph{before} +running @var{body}. +@end defmac + +A window showing a temporary buffer can be fit to the size of that +buffer using the following mode: + +@defopt temp-buffer-resize-mode +When this minor mode is enabled, windows showing a temporary buffer are +automatically resized to fit their buffer's contents. + +A window is resized if and only if it has been specially created for the +buffer. In particular, windows that have shown another buffer before +are not resized. By default, this mode uses @code{fit-window-to-buffer} +(@pxref{Resizing Windows}) for resizing. You can specify a different +function by customizing the options @code{temp-buffer-max-height} and +@code{temp-buffer-max-width} below. +@end defopt + +@defopt temp-buffer-max-height +This option specifies the maximum height (in lines) of a window +displaying a temporary buffer when @code{temp-buffer-resize-mode} is +enabled. It can also be a function to be called to choose the height +for such a buffer. It gets one argument, the buffer, and should return +a positive integer. At the time the function is called, the window to +be resized is selected. +@end defopt + +@defopt temp-buffer-max-width +This option specifies the maximum width of a window (in columns) +displaying a temporary buffer when @code{temp-buffer-resize-mode} is +enabled. It can also be a function to be called to choose the width for +such a buffer. It gets one argument, the buffer, and should return a +positive integer. At the time the function is called, the window to be +resized is selected. +@end defopt + +The following function uses the current buffer for temporal display: + @defun momentary-string-display string position &optional char message This function momentarily displays @var{string} in the current buffer at @var{position}. It has no effect on the undo list or on the buffer's @@ -3348,9 +3392,9 @@ The script that the font must support (a symbol). @item :otf @cindex OpenType font The font must be an OpenType font that supports these OpenType -features, provided Emacs is compiled with support for @samp{libotf} (a -library for performing complex text layout in certain scripts). The -value must be a list of the form +features, provided Emacs is compiled with a library, such as +@samp{libotf} on GNU/Linux, that supports complex text layout for +scripts which need that. The value must be a list of the form @smallexample @code{(@var{script-tag} @var{langsys-tag} @var{gsub} @var{gpos})} @@ -3449,6 +3493,124 @@ If the optional argument @var{fold-wildcards} is non-@code{nil}, consecutive wildcards in the XLFD are folded into one. @end defun +The following two functions return important information about a font. + +@defun font-info name &optional frame +This function returns information about a font specified by its +@var{name}, a string, as it is used on @var{frame}. If @var{frame} is +omitted or @code{nil}, it defaults to the selected frame. + +The value returned by the function is a vector of the form +@code{[@var{opened-name} @var{full-name} @var{size} @var{height} +@var{baseline-offset} @var{relative-compose} @var{default-ascent} +@var{max-width} @var{ascent} @var{descent} @var{space-width} +@var{average-width} @var{filename} @var{capability}]}. Here's the +description of each components of this vector: + +@table @var +@item opened-name +The name used to open the font, a string. + +@item full-name +The full name of the font, a string. + +@item size +The pixel size of the font. + +@item height +The height of the font in pixels. + +@item baseline-offset +The offset in pixels from the @acronym{ASCII} baseline, positive +upward. + +@item relative-compose +@itemx default-ascent +Numbers controlling how to compose characters. + +@item ascent +@itemx descent +The ascent and descent of this font. The sum of these two numbers +should be equal to the value of @var{height} above. + +@item space-width +The width, in pixels, of the font's space character. + +@item average-width +The average width of the font characters. If this is zero, Emacs uses +the value of @var{space-width} instead, when it calculates text layout +on display. + +@item filename +The file name of the font as a string. This can be @code{nil} if the +font back-end does not provide a way to find out the font's file name. + +@item capability +A list whose first element is a symbol representing the font type, one +of @code{x}, @code{opentype}, @code{truetype}, @code{type1}, +@code{pcf}, or @code{bdf}. For OpenType fonts, the list includes 2 +additional elements describing the @sc{gsub} and @sc{gpos} features +supported by the font. Each of these elements is a list of the form +@code{((@var{script} (@var{langsys} @var{feature} @dots{}) @dots{}) +@dots{})}, where @var{script} is a symbol representing an OpenType +script tag, @var{langsys} is a symbol representing an OpenType langsys +tag (or @code{nil}, which stands for the default langsys), and each +@var{feature} is a symbol representing an OpenType feature tag. +@end table +@end defun + +@defun query-font font-object +This function returns information about a @var{font-object}. (This is +in contrast to @code{font-info}, which takes the font name, a string, +as its argument.) + +The value returned by the function is a vector of the form +@code{[@var{name} @var{filename} @var{pixel-size} @var{max-width} +@var{ascent} @var{descent} @var{space-width} @var{average-width} +@var{capability}]}. Here's the description of each components of this +vector: + +@table @var +@item name +The font name, a string. + +@item filename +The file name of the font as a string. This can be @code{nil} if the +font back-end does not provide a way to find out the font's file name. + +@item pixel-size +The pixel size of the font used to open the font. + +@item max-width +The maximum advance width of the font. + +@item ascent +@itemx descent +The ascent and descent of this font. The sum of these two numbers +gives the font height. + +@item space-width +The width, in pixels, of the font's space character. + +@item average-width +The average width of the font characters. If this is zero, Emacs uses +the value of @var{space-width} instead, when it calculates text layout +on display. + +@item capability +A list whose first element is a symbol representing the font type, one +of @code{x}, @code{opentype}, @code{truetype}, @code{type1}, +@code{pcf}, or @code{bdf}. For OpenType fonts, the list includes 2 +additional elements describing the @sc{gsub} and @sc{gpos} features +supported by the font. Each of these elements is a list of the form +@code{((@var{script} (@var{langsys} @var{feature} @dots{}) @dots{}) +@dots{})}, where @var{script} is a symbol representing an OpenType +script tag, @var{langsys} is a symbol representing an OpenType langsys +tag (or @code{nil}, which stands for the default langsys), and each +@var{feature} is a symbol representing an OpenType feature tag. +@end table +@end defun + @node Fringes @section Fringes @cindex fringes @@ -3865,102 +4027,164 @@ arrow position. If either property is not set, the default @code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator is used. + @node Scroll Bars @section Scroll Bars @cindex scroll bars Normally the frame parameter @code{vertical-scroll-bars} controls -whether the windows in the frame have vertical scroll bars, and -whether they are on the left or right. The frame parameter -@code{scroll-bar-width} specifies how wide they are (@code{nil} -meaning the default). @xref{Layout Parameters}. +whether the windows in the frame have vertical scroll bars, and whether +they are on the left or right. The frame parameter +@code{scroll-bar-width} specifies how wide they are (@code{nil} meaning +the default). + + The frame parameter @code{horizontal-scroll-bars} controls whether +the windows in the frame have horizontal scroll bars. The frame +parameter @code{scroll-bar-height} specifies how high they are +(@code{nil} meaning the default). @xref{Layout Parameters}. + +@vindex horizontal-scroll-bars-available-p + Horizontal scroll bars are not available on all platforms. The +function @code{horizontal-scroll-bars-available-p} which takes no +argument returns non-@code{nil} if they are available on your system. + + The following three functions take as argument a live frame which +defaults to the selected one. @defun frame-current-scroll-bars &optional frame -This function reports the scroll bar type settings for frame -@var{frame}. The value is a cons cell -@code{(@var{vertical-type} .@: @var{horizontal-type})}, where -@var{vertical-type} is either @code{left}, @code{right}, or @code{nil} -(which means no scroll bar.) @var{horizontal-type} is meant to -specify the horizontal scroll bar type, but since they are not -implemented, it is always @code{nil}. -@end defun - -@vindex vertical-scroll-bar - You can enable or disable scroll bars for a particular buffer, -by setting the variable @code{vertical-scroll-bar}. This variable -automatically becomes buffer-local when set. The possible values are -@code{left}, @code{right}, @code{t}, which means to use the -frame's default, and @code{nil} for no scroll bar. +This function reports the scroll bar types for frame @var{frame}. The +value is a cons cell @code{(@var{vertical-type} .@: +@var{horizontal-type})}, where @var{vertical-type} is either +@code{left}, @code{right}, or @code{nil} (which means no vertical scroll +bar.) @var{horizontal-type} is either @code{bottom} or @code{nil} +(which means no horizontal scroll bar). +@end defun - You can also control this for individual windows. Call the function -@code{set-window-scroll-bars} to specify what to do for a specific window: +@defun frame-scroll-bar-width &optional Lisp_Object &optional frame +This function returns the width of vertical scroll bars of @var{frame} +in pixels. +@end defun -@defun set-window-scroll-bars window width &optional vertical-type horizontal-type -This function sets the width and type of scroll bars for window -@var{window}. +@defun frame-scroll-bar-height &optional Lisp_Object &optional frame +This function returns the height of horizontal scroll bars of +@var{frame} in pixels. +@end defun -@var{width} specifies the scroll bar width in pixels (@code{nil} means -use the width specified for the frame). @var{vertical-type} specifies -whether to have a vertical scroll bar and, if so, where. The possible -values are @code{left}, @code{right} and @code{nil}, just like the -values of the @code{vertical-scroll-bars} frame parameter. +You can override the frame specific settings for individual windows by +using the following function: -The argument @var{horizontal-type} is meant to specify whether and -where to have horizontal scroll bars, but since they are not -implemented, it has no effect. If @var{window} is @code{nil}, the -selected window is used. +@defun set-window-scroll-bars window &optional width vertical-type height horizontal-type +This function sets the width and/or height and the types of scroll bars +for window @var{window}. + +@var{width} specifies the width of the vertical scroll bar in pixels +(@code{nil} means use the width specified for the frame). +@var{vertical-type} specifies whether to have a vertical scroll bar and, +if so, where. The possible values are @code{left}, @code{right}, +@code{t}, which means to use the frame's default, and @code{nil} for no +vertical scroll bar. + +@var{height} specifies the height of the horizontal scroll bar in pixels +(@code{nil} means use the height specified for the frame). +@var{horizontal-type} specifies whether to have a horizontal scroll bar. +The possible values are @code{bottom}, @code{t}, which means to use the +frame's default, and @code{nil} for no horizontal scroll bar. + +If @var{window} is @code{nil}, the selected window is used. @end defun +The following four functions take as argument a live window which +defaults to the selected one. + @defun window-scroll-bars &optional window -Report the width and type of scroll bars specified for @var{window}. -If @var{window} is omitted or @code{nil}, the selected window is used. -The value is a list of the form @code{(@var{width} -@var{cols} @var{vertical-type} @var{horizontal-type})}. The value -@var{width} is the value that was specified for the width (which may -be @code{nil}); @var{cols} is the number of columns that the scroll -bar actually occupies. +This function returns a list of the form @code{(@var{width} +@var{columns} @var{vertical-type} @var{height} @var{lines} +@var{horizontal-type})}. + +The value @var{width} is the value that was specified for the width of +the vertical scroll bar (which may be @code{nil}); @var{columns} is the +(possibly rounded) number of columns that the vertical scroll bar +actually occupies. -@var{horizontal-type} is not actually meaningful. +The value @var{height} is the value that was specified for the height of +the horizontal scroll bar (which may be @code{nil}); @var{lines} is the +(possibly rounded) number of lines that the horizontally scroll bar +actually occupies. +@end defun + +@defun window-current-scroll-bars &optional window +This function reports the scroll bar type for window @var{window}. The +value is a cons cell @code{(@var{vertical-type} .@: +@var{horizontal-type})}. Unlike @code{window-scroll-bars}, this reports +the scroll bar type actually used, once frame defaults and +@code{scroll-bar-mode} are taken into account. @end defun @defun window-scroll-bar-width &optional window This function returns the width in pixels of @var{window}'s vertical -scrollbar. @var{window} must be a live window, and defaults to the -selected window. +scrollbar. +@end defun + +@defun window-scroll-bar-height &optional window +This function returns the height in pixels of @var{window}'s horizontal +scrollbar. @end defun If you don't specify these values for a window with @code{set-window-scroll-bars}, the buffer-local variables -@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being -displayed control the window's vertical scroll bars. The function +@code{vertical-scroll-bar}, @code{horizontal-scroll-bar}, +@code{scroll-bar-width} and @code{scroll-bar-height} in the buffer being +displayed control the window's scroll bars. The function @code{set-window-buffer} examines these variables. If you change them -in a buffer that is already visible in a window, you can make the -window take note of the new values by calling @code{set-window-buffer} +in a buffer that is already visible in a window, you can make the window +take note of the new values by calling @code{set-window-buffer} specifying the same buffer that is already displayed. -@defopt scroll-bar-mode -This variable, always local in all buffers, controls whether and where -to put scroll bars in windows displaying the buffer. The possible values -are @code{nil} for no scroll bar, @code{left} to put a scroll bar on -the left, and @code{right} to put a scroll bar on the right. -@end defopt +You can control the appearance of scroll bars for a particular buffer by +setting the following variables which automatically become buffer-local +when set. -@defun window-current-scroll-bars &optional window -This function reports the scroll bar type for window @var{window}. -If @var{window} is omitted or @code{nil}, the selected window is used. -The value is a cons cell -@code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike -@code{window-scroll-bars}, this reports the scroll bar type actually -used, once frame defaults and @code{scroll-bar-mode} are taken into -account. -@end defun +@defvar vertical-scroll-bar +This variable specifies the location of the vertical scroll bar. The +possible values are @code{left}, @code{right}, @code{t}, which means to +use the frame's default, and @code{nil} for no scroll bar. +@end defvar + +@defvar horizontal-scroll-bar +This variable specifies the location of the horizontal scroll bar. The +possible values are @code{bottom}, @code{t}, which means to use the +frame's default, and @code{nil} for no scroll bar. +@end defvar @defvar scroll-bar-width -This variable, always local in all buffers, specifies the width of the -buffer's scroll bars, measured in pixels. A value of @code{nil} means -to use the value specified by the frame. +This variable specifies the width of the buffer's vertical scroll bars, +measured in pixels. A value of @code{nil} means to use the value +specified by the frame. @end defvar +@defvar scroll-bar-height +This variable specifies the height of the buffer's horizontal scroll +bar, measured in pixels. A value of @code{nil} means to use the value +specified by the frame. +@end defvar + +Finally you can toggle the display of scroll bars on all frames by +customizing the variables @code{scroll-bar-mode} and +@code{horizontal-scroll-bar-mode}. + +@defopt scroll-bar-mode +This variable controls whether and where to put vertical scroll bars in +all frames. The possible values are @code{nil} for no scroll bars, +@code{left} to put scroll bars on the left and @code{right} to put +scroll bars on the right. +@end defopt + +@defopt horizontal-scroll-bar-mode +This variable controls whether to display horizontal scroll bars on all +frames. +@end defopt + + @node Window Dividers @section Window Dividers @cindex window dividers @@ -6553,10 +6777,9 @@ positions do not increase monotonically with string or buffer position. In performing this @dfn{bidirectional reordering}, Emacs follows the Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}), which is described in Annex #9 of the Unicode standard -(@url{http://www.unicode.org/reports/tr9/}). Emacs currently provides -a ``Non-isolate Bidirectionality'' class implementation of the -@acronym{UBA}: it does not yet support the isolate directional -formatting characters introduced with Unicode Standard v6.3.0. +(@url{http://www.unicode.org/reports/tr9/}). Emacs provides a ``Full +Bidirectionality'' class implementation of the @acronym{UBA}, +consistent with the requirements of the Unicode Standard v7.0. @defvar bidi-display-reordering If the value of this buffer-local variable is non-@code{nil} (the @@ -6741,3 +6964,81 @@ affect all Emacs frames and windows. appropriate mirrored character in the reordered text. Lisp programs can affect the mirrored display by changing this property. Again, any such changes affect all of Emacs display. + +@cindex overriding bidirectional properties +@cindex directional overrides +@cindex LRO +@cindex RLO + The bidirectional properties of characters can be overridden by +inserting into the text special directional control characters, +LEFT-TO-RIGHT OVERRIDE (@acronym{LRO}) and RIGHT-TO-LEFT OVERRIDE +(@acronym{RLO}). Any characters between a @acronym{RLO} and the +following newline or POP DIRECTIONAL FORMATTING (@acronym{PDF}) +control character, whichever comes first, will be displayed as if they +were strong right-to-left characters, i.e.@: they will be reversed on +display. Similarly, any characters between @acronym{LRO} and +@acronym{PDF} or newline will display as if they were strong +left-to-right, and will @emph{not} be reversed even if they are strong +right-to-left characters. + +@cindex phishing using directional overrides +@cindex malicious use of directional overrides + These overrides are useful when you want to make some text +unaffected by the reordering algorithm, and instead directly control +the display order. But they can also be used for malicious purposes, +known as @dfn{phishing}. Specifically, a URL on a Web page or a link +in an email message can be manipulated to make its visual appearance +unrecognizable, or similar to some popular benign location, while the +real location, interpreted by a browser in the logical order, is very +different. + + Emacs provides a primitive that applications can use to detect +instances of text whose bidirectional properties were overridden so as +to make a left-to-right character display as if it were a +right-to-left character, or vise versa. + +@defun bidi-find-overridden-directionality from to &optional object +This function looks at the text of the specified @var{object} between +positions @var{from} (inclusive) and @var{to} (exclusive), and returns +the first position where it finds a strong left-to-right character +whose directional properties were forced to display the character as +right-to-left, or for a strong right-to-left character that was forced +to display as left-to-right. If it finds no such characters in the +specified region of text, it returns @code{nil}. + +The optional argument @var{object} specifies which text to search, and +defaults to the current buffer. If @var{object} is non-@code{nil}, it +can be some other buffer, or it can be a string or a window. If it is +a string, the function searches that string. If it is a window, the +function searches the buffer displayed in that window. If a buffer +whose text you want to examine is displayed in some window, we +recommend to specify it by that window, rather than pass the buffer to +the function. This is because telling the function about the window +allows it to correctly account for window-specific overlays, which +might change the result of the function if some text in the buffer is +covered by overlays. +@end defun + +@cindex copying bidirectional text, preserve visual order +@cindex visual order, preserve when copying bidirectional text + When text that includes mixed right-to-left and left-to-right +characters and bidirectional controls is copied into a different +location, it can change its visual appearance, and also can affect the +visual appearance of the surrounding text at destination. This is +because reordering of bidirectional text specified by the +@acronym{UBA} has non-trivial context-dependent effects both on the +copied text and on the text at copy destination that will surround it. + + Sometimes, a Lisp program may need to preserve the exact visual +appearance of the copied text at destination, and of the text that +surrounds the copy. Lisp programs can use the following function to +achieve that effect. + +@defun buffer-substring-with-bidi-context start end &optional no-properties +This function works similar to @code{buffer-substring} (@pxref{Buffer +Contents}), but it prepends and appends to the copied text bidi +directional control characters necessary to preserve the visual +appearance of the text when it is inserted at another place. Optional +argument @var{no-properties}, if non-@code{nil}, means remove the text +properties from the copy of the text. +@end defun diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 865ac4c3173..cdc443f07d5 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename elisp +@setfilename ../../info/elisp.info @ifset VOL1 @set volflag @@ -1006,6 +1006,7 @@ Windows * Windows and Frames:: Relating windows to the frame they appear on. * Window Sizes:: Accessing a window's size. * Resizing Windows:: Changing the sizes of windows. +* Preserving Window Sizes:: Preserving the size of windows. * Splitting Windows:: Splitting one window into two windows. * Deleting Windows:: Deleting a window gives its space to other windows. * Recombining Windows:: Preserving the frame layout when splitting and @@ -1343,7 +1344,7 @@ Emacs Display * Faces:: A face defines a graphics style for text characters: font, colors, etc. * Fringes:: Controlling window fringes. -* Scroll Bars:: Controlling vertical scroll bars. +* Scroll Bars:: Controlling scroll bars. * Window Dividers:: Separating windows visually. * Display Property:: Enabling special display features. * Images:: Displaying images in Emacs buffers. diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index 818e80b3bbb..d485b3b6f15 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/eval.texi b/doc/lispref/eval.texi index 5af67f6fa05..a185da7086f 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -805,7 +805,12 @@ message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). This limit, with the associated error when it is exceeded, is one way Emacs Lisp avoids infinite recursion on an ill-defined function. If you increase the value of @code{max-lisp-eval-depth} too much, such -code can cause stack overflow instead. +code can cause stack overflow instead. On some systems, this overflow +can be handled. In that case, normal Lisp evaluation is interrupted +and control is transferred back to the top level command loop +(@code{top-level}). Note that there is no way to enter Emacs Lisp +debugger in this situation. @xref{Error Debugging}. + @cindex Lisp nesting error The depth limit counts internal uses of @code{eval}, @code{apply}, and diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 3e1fba3acab..2739e3e509d 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -653,8 +653,9 @@ and also calls the functions in the list @xref{Format Conversion}. Normally, @code{write-region} displays the message @samp{Wrote -@var{filename}} in the echo area. If @var{visit} is neither @code{t} -nor @code{nil} nor a string, then this message is inhibited. This +@var{filename}} in the echo area. This message is inhibited if +@var{visit} is neither @code{t} nor @code{nil} nor a string, or if +Emacs is operating in batch mode (@pxref{Batch Mode}). This feature is useful for programs that use files for internal purposes, files that the user does not need to know about. @end deffn @@ -716,15 +717,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 @@ -1697,6 +1698,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 @@ -2014,6 +2025,11 @@ form. @end example @end defun +@defun directory-name-p filename +This function returns non-@code{nil} if @var{filename} ends with a +forward slash (@samp{/}) character. +@end defun + @node Directory Names @subsection Directory Names @cindex directory name @@ -2601,6 +2617,14 @@ An error is signaled if @var{directory} is not the name of a directory that can be read. @end defun +@defun directory-files-recursively directory match &optional include-directories +Return all files under @var{directory} whose file names match +@var{match} recursively. The file names are returned ``depth first'', +meaning that contents of sub-directories are returned before contents +of the directories. If @var{include-directories} is non-@code{nil}, +also return directory names that have matching names. +@end defun + @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format This is similar to @code{directory-files} in deciding which files to report on and how to report their names. However, instead diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 2d5922732c6..663207c5253 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -712,13 +712,13 @@ pixel sizes of these character units (@pxref{Face Attributes}). @table @code @vindex height, a frame parameter @item height -The height of the frame contents, in characters. (To get the height in -pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.) +The height of the frame's text area (@pxref{Size and Position}), in +characters. @vindex width, a frame parameter @item width -The width of the frame contents, in characters. (To get the width in -pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.) +The width of the frame's text area (@pxref{Size and Position}), in +characters. @vindex user-size, a frame parameter @item user-size @@ -742,9 +742,9 @@ with the mouse, while the latter really covers the whole screen and does not allow resizing by mouse dragging. With some window managers you may have to customize the variable -@code{frame-resize-pixelwise} to a non-@code{nil} value in order to make -a frame appear ``maximized'' or ``fullscreen''. - +@code{frame-resize-pixelwise} (@pxref{Size and Position}) to a +non-@code{nil} value in order to make a frame appear ``maximized'' or +``fullscreen''. @end table @node Layout Parameters @@ -770,19 +770,21 @@ Whether the frame has scroll bars for vertical scrolling, and which side of the frame they should be on. The possible values are @code{left}, @code{right}, and @code{nil} for no scroll bars. -@ignore @vindex horizontal-scroll-bars, a frame parameter @item horizontal-scroll-bars -Whether the frame has scroll bars for horizontal scrolling -(non-@code{nil} means yes). Horizontal scroll bars are not currently -implemented. -@end ignore +Whether the frame has scroll bars for horizontal scrolling (@code{t} and +@code{bottom} mean yes, @code{nil} means no). @vindex scroll-bar-width, a frame parameter @item scroll-bar-width The width of vertical scroll bars, in pixels, or @code{nil} meaning to use the default width. +@vindex scroll-bar-height, a frame parameter +@item scroll-bar-height +The height of horizontal scroll bars, in pixels, or @code{nil} meaning +to use the default height. + @vindex left-fringe, a frame parameter @vindex right-fringe, a frame parameter @item left-fringe @@ -796,14 +798,6 @@ these two frame parameters, the return value is always an integer. When using @code{set-frame-parameter}, passing a @code{nil} value imposes an actual default value of 8 pixels. -The combined fringe widths must add up to an integral number of -columns, so the actual default fringe widths for the frame, as -reported by @code{frame-parameter}, may be larger than what you -specify. Any extra width is distributed evenly between the left and -right fringe. However, you can force one fringe or the other to a -precise width by specifying that width as a negative integer. If both -widths are negative, only the left fringe gets the specified width. - @vindex right-divider-width, a frame parameter @item right-divider-width The width (thickness) reserved for the right divider (@pxref{Window @@ -1147,65 +1141,137 @@ equivalent to the @code{:background} attribute of the @code{scroll-bar} face. @end table + @node Size and Position -@subsection Frame Size And Position +@subsection Frame Size and Position @cindex size of frame @cindex screen size @cindex frame size @cindex resize frame - You can read or change the size and position of a frame using the -frame parameters @code{left}, @code{top}, @code{height}, and -@code{width}. Whatever geometry parameters you don't specify are chosen -by the window manager in its usual fashion. +You can read or change the size and position of a frame using the frame +parameters @code{left}, @code{top}, @code{height}, and @code{width}. +Whatever geometry parameters you don't specify are chosen by the window +manager in its usual fashion. Here are some special features for working with sizes and positions. -(For the precise meaning of ``selected frame'' used by these functions, -see @ref{Input Focus}.) +Most of the functions described below use a @var{frame} argument which +has to specify a live frame. If omitted or @code{nil}, it specifies the +selected frame, see @ref{Input Focus}. @defun set-frame-position frame left top This function sets the position of the top left corner of @var{frame} to @var{left} and @var{top}. These arguments are measured in pixels, and -normally count from the top left corner of the screen. +normally count from the top left corner of the screen to the top left +corner of the rectangle allotted to the frame by the window manager. -Negative parameter values position the bottom edge of the window up from -the bottom edge of the screen, or the right window edge to the left of -the right edge of the screen. It would probably be better if the values -were always counted from the left and top, so that negative arguments -would position the frame partly off the top or left edge of the screen, -but it seems inadvisable to change that now. +Negative parameter values position the bottom edge of that rectangle up +from the bottom edge of the screen, or the right rectangle edge to the +left of the right edge of the screen. It would probably be better if +the values were always counted from the left and top, so that negative +arguments would position the frame partly off the top or left edge of +the screen, but it seems inadvisable to change that now. @end defun -@defun frame-height &optional frame -@defunx frame-width &optional frame -These functions return the height and width of @var{frame}, measured in -lines and columns. If you don't supply @var{frame}, they use the -selected frame. -@end defun +@cindex frame default font +@cindex default font of a frame +Each frame has a @dfn{default font} which specifies the canonical height +and width of a character on that frame. The default font is used when +retrieving or changing the size of a frame in terms of columns or lines. +It is also used when resizing (@pxref{Window Sizes}) or splitting +(@pxref{Splitting Windows}) windows. + +@defun frame-char-height &optional frame +@defunx frame-char-width &optional frame +These functions return the canonical height and width of a character in +@var{frame}, measured in pixels. Together, these values establish the +size of the default font on @var{frame}. The values depend on the +choice of font for @var{frame}, see @ref{Font and Color Parameters}. +@end defun + +The default font can be also set directly with the following function: + +@deffn Command set-frame-font font &optional keep-size frames +This sets the default font to @var{font}. When called interactively, it +prompts for the name of a font, and uses that font on the selected +frame. When called from Lisp, @var{font} should be a font name (a +string), a font object, font entity, or a font spec. + +If the optional argument @var{keep-size} is @code{nil}, this keeps the +number of frame lines and columns fixed. (If non-@code{nil}, the option +@code{frame-inhibit-implied-resize} described below will override this.) +If @var{keep-size} is non-@code{nil} (or with a prefix argument), it +tries to keep the size of the display area of the current frame fixed by +adjusting the number of lines and columns. + +If the optional argument @var{frames} is @code{nil}, this applies the +font to the selected frame only. If @var{frames} is non-@code{nil}, it +should be a list of frames to act upon, or @code{t} meaning all existing +graphical frames. +@end deffn + +@cindex frame display area +@cindex display area of a frame +The @dfn{display area} of a frame is a rectangular area within the area +allotted to the frame by the window manager. The display area neither +includes the title bar (@pxref{Frame Titles}) nor any other decorations +provided by the window manager (like an external border used for +resizing frames via mouse dragging). + + The actual height of the display area depends on the window-system +and toolkit in use. With GTK+, the display area does not include any +tool bar or menu bar. With the Motif or Lucid toolkits and with +Windows, the display area includes the tool bar but not the menu bar. +In a graphical version with no toolkit, it includes both the tool bar +and menu bar. On a text terminal, the display area includes the menu +bar. @defun frame-pixel-height &optional frame @defunx frame-pixel-width &optional frame -These functions return the height and width of the main display area -of @var{frame}, measured in pixels. If you don't supply @var{frame}, -they use the selected frame. For a text terminal, the results are in -characters rather than pixels. - -These values include the internal borders, and windows' scroll bars -and fringes (which belong to individual windows, not to the frame -itself). The exact value of the heights depends on the window-system -and toolkit in use. With GTK+, the height does not include any tool -bar or menu bar. With the Motif or Lucid toolkits, it includes the -tool bar but not the menu bar. In a graphical version with no -toolkit, it includes both the tool bar and menu bar. For a text -terminal, the result includes the menu bar. + These functions return the height and width of the display area of +@var{frame}, measured in pixels. For a text terminal, the results are +in characters rather than pixels. +@end defun + +@cindex frame text area +@cindex text area of a frame + The @dfn{text area} of a frame is a concept implicitly used by all +functions that change a frame's height or width. It is a rectangle +located within the display area. Its size is obtained from that of the +display area by subtracting the sizes of any tool or menu bars that are +part of the display area, any internal borders, one vertical and one +horizontal scroll bar, and one left and one right fringe as specified +for this frame, see @ref{Layout Parameters}. + +@defun frame-text-height &optional frame +@defunx frame-text-width &optional frame +These functions return the height and width of the text area of +@var{frame}, measured in pixels. For a text terminal, the results are +in characters rather than pixels. + +The value returned by @code{frame-text-height} differs from that +returned by @code{frame-pixel-height} by not including the heights of +any tool bar or menu bar, the height of one horizontal scroll bar and +the widths of the internal border. + +The value returned by @code{frame-text-width} differs from that returned +by @code{frame-pixel-width} by not including the width of one vertical +scroll bar, the widths of one left and one right fringe and the widths +of the internal border. @end defun -@defun frame-char-height &optional frame -@defunx frame-char-width &optional frame -These functions return the height and width of a character in -@var{frame}, measured in pixels. The values depend on the choice of -font. If you don't supply @var{frame}, these functions use the selected -frame. +@defun frame-height &optional frame +@defunx frame-width &optional frame +These functions return the height and width of the text area of +@var{frame}, measured in units of the default font height and width of +@var{frame}. These functions are plain shorthands for writing +@code{(frame-parameter frame 'height)} and @code{(frame-parameter frame +'width)}. + +If the text area of @var{frame} measured in pixles is not a multiple of +its default font size, the values returned by this functions are rounded +down to the number of characters of the default font that fully fit into +the text area. @end defun @defopt frame-resize-pixelwise @@ -1231,9 +1297,9 @@ order to make a frame appear truly ``maximized'' or ``fullscreen''. @end defopt @defun set-frame-size frame width height pixelwise -This function sets the size of @var{frame}, measured in characters; -@var{width} and @var{height} specify the new width in columns and the -new height in lines. +This function sets the size of the text area of @var{frame}, measured in +characters; @var{width} and @var{height} specify the new width in +columns and the new height in lines. The optional argument @var{pixelwise} non-@code{nil} means to measure the new width and height in units of pixels instead. Note that if @@ -1243,9 +1309,9 @@ to a multiple of its character size. @end defun @defun set-frame-height frame height &optional pretend pixelwise -This function resizes @var{frame} to a height of @var{height} lines. The -sizes of existing windows in @var{frame} are altered proportionally to -fit. +This function resizes the text area of @var{frame} to a height of +@var{height} lines. The sizes of existing windows in @var{frame} are +altered proportionally to fit. If @var{pretend} is non-@code{nil}, then Emacs displays @var{height} lines of output in @var{frame}, but does not change its value for the @@ -1265,8 +1331,8 @@ height to a multiple of its character height. @end defun @defun set-frame-width frame width &optional pretend pixelwise -This function sets the width of @var{frame}, measured in characters. -The argument @var{pretend} has the same meaning as in +This function sets the width of the text area of @var{frame}, measured +in characters. The argument @var{pretend} has the same meaning as in @code{set-frame-height}. The optional fourth argument @var{pixelwise} non-@code{nil} means that @@ -1276,6 +1342,65 @@ fully honor the request if it does not increase/decrease the frame width to a multiple of its character width. @end defun +None of these three functions will make a frame smaller than needed to +display all of its windows together with their scroll bars, fringes, +margins, dividers, mode and header lines. This contrasts with requests +by the window manager triggered, for example, by dragging the external +border of a frame with the mouse. Such requests are always honored by +clipping, if necessary, portions that cannot be displayed at the right, +bottom corner of the frame. + + By default, Emacs tries to keep the number of lines and columns of a +frame's text area unaltered when, for example, adding or removing a menu +bar, changing the default font or setting the width of the frame's +scroll bars. This means, however, that in such case Emacs must ask the +window manager to resize the display area of the frame in order to +accommodate the size change. Note that wrapping a menu or tool bar +usually does not resize the frame's display area, hence this will alter +the number of displayed lines. + + Occasionally, such implied resizing of the display area may be +unwanted, for example, when the frame is maximized or made fullscreen +where it's turned off by default. In other cases you can disable +implied resizing with the following option: + +@defopt frame-inhibit-implied-resize +If this option is @code{nil}, changing font, menu bar, tool bar, +internal borders, fringes or scroll bars of a specific frame may +implicitly resize the frame's display area in order to preserve the +number of columns or lines the frame displays. If this option is +non-@code{nil}, no implied resizing is done. + +The value of this option can be also be a list of frame parameters. In +that case, implied resizing is inhibited when changing a parameter that +appears in this list. The frame parameters currently handled by this +option are: @code{font}, @code{font-backend}, +@code{internal-border-width}, @code{menu-bar-lines} and +@code{tool-bar-lines}. + +Changing any of the @code{scroll-bar-width}, @code{scroll-bar-height}, +@code{vertical-scroll-bars}, @code{horizontal-scroll-bars}, +@code{left-fringe} and @code{right-fringe} frame parameters is handled +as if the frame contained just one live window. This means, for +example, that removing vertical scroll bars on a frame containing +several side by side windows will shrink the frame width by the width of +one scroll bar provided this option is @code{nil} and keep it unchanged +if this option is either @code{t} or a list containing +@code{vertical-scroll-bars}. + +The default value is @code{'(tool-bar-lines)} for Lucid, Motif and +Windows (which means that adding/removing a tool bar there does not +change the frame height), @code{nil} on all other window systems +including GTK+ (which means that changing any of the parameters listed +above may change the size of the frame), and @code{t} otherwise (which +means the frame size never changes implicitly when there's no window +system support). + +Note that when a frame is not large enough to accommodate a change of +any of the parameters listed above, Emacs may try to enlarge the frame +even if this option is non-@code{nil}. +@end defopt + @c FIXME? Belongs more in Emacs manual than here? @c But, e.g., fit-window-to-buffer is in this manual. If you have a frame that displays only one window, you can fit that @@ -1398,6 +1523,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 a92c29d6179..40b8322c73e 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1204,13 +1204,13 @@ behavior with: The arguments @code{:before} and @code{:around} used in the above examples specify how the two functions are composed, since there are many different -ways to do it. The added function is also called an @emph{advice}. +ways to do it. The added function is also called a piece of @emph{advice}. @menu * Core Advising Primitives:: Primitives to manipulate advice. * Advising Named Functions:: Advising named functions. -* Advice combinators:: Ways to compose advices. -* Porting old advices:: Adapting code using the old defadvice. +* Advice combinators:: Ways to compose advice. +* Porting old advice:: Adapting code using the old defadvice. @end menu @node Core Advising Primitives @@ -1246,22 +1246,25 @@ identify which function to remove. Typically used when @var{function} is an anonymous function. @item depth -This specifies how to order the advices, in case several advices are present. -By default, the depth is 0. A depth of 100 indicates that this advice should -be kept as deep as possible, whereas a depth of -100 indicates that it -should stay as the outermost advice. When two advices specify the same depth, -the most recently added advice will be outermost. - -For a @code{:before} advice, being outermost means that this advice will be run -first, before any other advice, whereas being innermost means that it will run -right before the original function, with no other advice run between itself and -the original function. Similarly, for an @code{:after} advice innermost means -that it will run right after the original function, with no other advice run in -between, whereas outermost means that it will be run very last after all -other advices. An innermost @code{:override} advice will only override the -original function and other advices will apply to it, whereas an outermost -@code{:override} advice will override not only the original function but all -other advices applied to it as well. +This specifies how to order the advice, should several pieces of +advice be present. By default, the depth is 0. A depth of 100 +indicates that this piece of advice should be kept as deep as +possible, whereas a depth of -100 indicates that it should stay as the +outermost piece. When two pieces of advice specify the same depth, +the most recently added one will be outermost. + +For @code{:before} advice, being outermost means that this advice will +be run first, before any other advice, whereas being innermost means +that it will run right before the original function, with no other +advice run between itself and the original function. Similarly, for +@code{:after} advice innermost means that it will run right after the +original function, with no other advice run in between, whereas +outermost means that it will be run right at the end after all other +advice. An innermost @code{:override} piece of advice will only +override the original function and other pieces of advice will apply +to it, whereas an outermost @code{:override} piece of advice will +override not only the original function but all other advice applied +to it as well. @end table If @var{function} is not interactive, then the combined function will inherit @@ -1299,7 +1302,7 @@ function, it can also be the @code{name} of the piece of advice. @end defun @defun advice-function-mapc f function-def -Call the function @var{f} for every advice that was added to +Call the function @var{f} for every piece of advice that was added to @var{function-def}. @var{f} is called with two arguments: the advice function and its properties. @end defun @@ -1328,7 +1331,7 @@ instead. This separate set of functions to manipulate pieces of advice applied to named functions, offers the following extra features compared to @code{add-function}: they know how to deal with macros and autoloaded functions, they let @code{describe-function} preserve the original docstring as -well as document the added advice, and they let you add and remove advices +well as document the added advice, and they let you add and remove advice before a function is even defined. @code{advice-add} can be useful for altering the behavior of existing calls @@ -1362,6 +1365,13 @@ called directly from C, and such calls ignore advice; hence, one ends up in a confusing situation where some calls (occurring from Lisp code) obey the advice and other calls (from C code) do not. +@defmac define-advice symbol (where lambda-list &optional name depth) &rest body +This macro defines a piece of advice and adds it to the function named +@var{symbol}. The advice is an anonymous function if @var{name} is +nil or a function named @code{symbol@@name}. See @code{advice-add} +for explanation of other arguments. +@end defmac + @defun advice-add symbol where function &optional props Add the advice @var{function} to the named function @var{symbol}. @var{where} and @var{props} have the same meaning as for @code{add-function} @@ -1370,23 +1380,23 @@ Add the advice @var{function} to the named function @var{symbol}. @defun advice-remove symbol function Remove the advice @var{function} from the named function @var{symbol}. -@var{function} can also be the @code{name} of an advice. +@var{function} can also be the @code{name} of a piece of advice. @end defun @defun advice-member-p function symbol Return non-@code{nil} if the advice @var{function} is already in the named function @var{symbol}. @var{function} can also be the @code{name} of -an advice. +a piece of advice. @end defun @defun advice-mapc function symbol -Call @var{function} for every advice that was added to the named function -@var{symbol}. @var{function} is called with two arguments: the advice function -and its properties. +Call @var{function} for every piece of advice that was added to the +named function @var{symbol}. @var{function} is called with two +arguments: the advice function and its properties. @end defun @node Advice combinators -@subsection Ways to compose advices +@subsection Ways to compose advice Here are the different possible values for the @var{where} argument of @code{add-function} and @code{advice-add}, specifying how the advice @@ -1498,7 +1508,7 @@ More specifically, the composition of the two functions behaves like: @end table -@node Porting old advices +@node Porting old advice @subsection Adapting code using the old defadvice @cindex old advices, porting @@ -1506,7 +1516,7 @@ A lot of code uses the old @code{defadvice} mechanism, which is largely made obsolete by the new @code{advice-add}, whose implementation and semantics is significantly simpler. -An old advice such as: +An old piece of advice such as: @example (defadvice previous-line (before next-line-at-end @@ -1543,11 +1553,11 @@ whereas the new advice mechanism needs: Note that @code{ad-activate} had a global effect: it activated all pieces of advice enabled for that specified function. If you wanted to only activate or -deactivate a particular advice, you needed to @emph{enable} or @emph{disable} -that advice with @code{ad-enable-advice} and @code{ad-disable-advice}. +deactivate a particular piece, you needed to @emph{enable} or @emph{disable} +it with @code{ad-enable-advice} and @code{ad-disable-advice}. The new mechanism does away with this distinction. -An around advice such as: +Around advice such as: @example (defadvice foo (around foo-around) @@ -1573,12 +1583,12 @@ modify the function's arguments (e.g., with @code{ad-set-arg}), and that would affect the argument values seen by the original function, whereas in the new @code{:before}, modifying an argument via @code{setq} in the advice has no effect on the arguments seen by the original function. -When porting a @code{before} advice which relied on this behavior, you'll need -to turn it into a new @code{:around} or @code{:filter-args} advice instead. +When porting @code{before} advice which relied on this behavior, you'll need +to turn it into new @code{:around} or @code{:filter-args} advice instead. -Similarly an old @code{after} advice could modify the returned value by -changing @code{ad-return-value}, whereas a new @code{:after} advice cannot, so -when porting such an old @code{after} advice, you'll need to turn it into a new +Similarly old @code{after} advice could modify the returned value by +changing @code{ad-return-value}, whereas new @code{:after} advice cannot, so +when porting such old @code{after} advice, you'll need to turn it into new @code{:around} or @code{:filter-return} advice instead. @node Obsolete Functions @@ -1752,6 +1762,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 9bab636d654..2627ab74623 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -14,6 +14,7 @@ internal aspects of GNU Emacs that may be of interest to C programmers. * Building Emacs:: How the dumped Emacs is made. * Pure Storage:: Kludge to make preloaded Lisp functions shareable. * Garbage Collection:: Reclaiming space for Lisp objects no longer used. +* Stack-allocated Objects:: Temporary conses and strings on C stack. * Memory Usage:: Info about total size of Lisp objects made so far. * C Dialect:: What C variant Emacs is written in. * Writing Emacs Primitives:: Writing C code for Emacs. @@ -513,6 +514,11 @@ created in this Emacs session. Each of these counters increments for a certain kind of object. See the documentation string for details. @end defun +@defun memory-info +This functions returns an amount of total system memory and how much +of it is free. On an unsupported system, the value may be @code{nil}. +@end defun + @defvar gcs-done This variable contains the total number of garbage collections done so far in this Emacs session. @@ -524,6 +530,35 @@ during garbage collection so far in this Emacs session, as a floating-point number. @end defvar +@node Stack-allocated Objects +@section Stack-allocated Objects + +@cindex stack allocated Lisp objects +@cindex Lisp objects, stack-allocated + The garbage collector described above is used to manage data visible +from Lisp programs, as well as most of the data internally used by the +Lisp interpreter. Sometimes it may be useful to allocate temporary +internal objects using the C stack of the interpreter. This can help +performance, as stack allocation is typically faster than using heap +memory to allocate and the garbage collector to free. The downside is +that using such objects after they are freed results in undefined +behavior, so uses should be well thought out and carefully debugged by +using the @code{GC_CHECK_MARKED_OBJECTS} feature (see +@file{src/alloc.c}). In particular, stack-allocated objects should +never be made visible to user Lisp code. + + Currently, cons cells and strings can be allocated this way. This +is implemented by C macros like @code{AUTO_CONS} and +@code{AUTO_STRING} that define a named @code{Lisp_Object} with block +lifetime. These objects are not freed by the garbage collector; +instead, they have automatic storage duration, i.e., they are +allocated like local variables and are automatically freed at the end +of execution of the C block that defined the object. + + For performance reasons, stack-allocated strings are limited to +@acronym{ASCII} characters, and many of these strings are immutable, +i.e., calling @code{ASET} on them produces undefined behavior. + @node Memory Usage @section Memory Usage @cindex memory usage @@ -580,15 +615,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 @@ -1591,6 +1625,8 @@ of @code{intptr_t}). @item Prefer @code{int} for Emacs character codes, in the range 0 ..@: 0x3FFFFF. +More generally, prefer @code{int} for integers known to be in +@code{int} range, e.g., screen column counts. @item Prefer @code{ptrdiff_t} for sizes, i.e., for integers bounded by the @@ -1602,6 +1638,17 @@ anyway since they would break pointer subtraction, so this does not impose an arbitrary limit. @item +Avoid @code{ssize_t} except when communicating to low-level APIs that +have @code{ssize_t}-related limitations. Although it's equivalent to +@code{ptrdiff_t} on typical platforms, @code{ssize_t} is occasionally +narrower, so using it for size-related calculations could overflow. +Also, @code{ptrdiff_t} is more ubiquitous and better-standardized, has +standard @code{printf} formats, and is the basis for Emacs's internal +size-overflow checking. When using @code{ssize_t}, please note that +POSIX requires support only for values in the range @minus{}1 ..@: +@code{SSIZE_MAX}. + +@item Prefer @code{intptr_t} for internal representations of pointers, or for integers bounded only by the number of objects that can exist at any given time or by the total number of bytes that can be allocated. @@ -1637,8 +1684,7 @@ using @code{int}. Although it is also OK to use @code{int}, @code{0} and @code{1}, this older style is gradually being phased out. When using @code{bool}, respect the limitations of the replacement implementation of @code{bool}, as documented in the source file -@file{lib/stdbool.in.h}, so that Emacs remains portable to pre-C99 -platforms. In particular, boolean bitfields should be of type +@file{lib/stdbool.in.h}. In particular, boolean bitfields should be of type @code{bool_bf}, not @code{bool}, so that they work correctly even when compiling Objective C with standard GCC. diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index ffcffad691d..7ba45a6023f 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -1044,22 +1044,6 @@ lambda expression. This is presumed to be a function, and is treated as such (see above). In order to execute properly as a key binding, this function must be a command---it must have an @code{interactive} specification. @xref{Defining Commands}. - -@item -If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event -type, then this is an @dfn{indirect entry}: - -@example -(@var{othermap} . @var{othertype}) -@end example - -When key lookup encounters an indirect entry, it looks up instead the -binding of @var{othertype} in @var{othermap} and uses that. - -This feature permits you to define one key as an alias for another key. -For example, an entry whose @sc{car} is the keymap called @code{esc-map} -and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global -binding of @kbd{Meta-@key{SPC}}, whatever that may be''. @end itemize @item @var{symbol} @@ -1067,9 +1051,7 @@ binding of @kbd{Meta-@key{SPC}}, whatever that may be''. The function definition of @var{symbol} is used in place of @var{symbol}. If that too is a symbol, then this process is repeated, any number of times. Ultimately this should lead to an object that is -a keymap, a command, or a keyboard macro. A list is allowed if it is a -keymap or a command, but indirect entries are not understood when found -via symbols. +a keymap, a command, or a keyboard macro. Note that keymaps and keyboard macros (strings and vectors) are not valid functions, so a symbol with a keymap, string, or vector as its @@ -1098,8 +1080,7 @@ binding is not executable as a command. @end table In short, a keymap entry may be a keymap, a command, a keyboard -macro, a symbol that leads to one of them, or an indirection or -@code{nil}. +macro, a symbol that leads to one of them, or @code{nil}. @node Functions for Key Lookup @section Functions for Key Lookup @@ -1948,9 +1929,9 @@ entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII} characters) are preferred to all other key sequences and that the return value can never be a menu binding. -If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't -follow indirect keymap bindings. This makes it possible to search for -an indirect definition itself. +If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't look +inside menu-items to find their commands. This makes it possible to search for +a menu-item itself. The fifth argument, @var{no-remap}, determines how this function treats command remappings (@pxref{Remapping Commands}). There are two diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 5c1755dfae1..a2e70a680ea 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -603,25 +603,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 @@ -1150,126 +1131,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 -This function sorts @var{list} stably, though destructively, and -returns the sorted list. It compares elements using @var{predicate}. A -stable sort is one in which elements with equal sort keys maintain their -relative order before and after the sort. Stability is important when -successive sorts are used to order elements according to different -criteria. - -The argument @var{predicate} must be a function that accepts two -arguments. It is called with two elements of @var{list}. To get an -increasing order sort, the @var{predicate} should return non-@code{nil} if the -first element is ``less than'' the second, or @code{nil} if not. - -The comparison function @var{predicate} must give reliable results for -any given pair of arguments, at least within a single call to -@code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is -less than @var{b}, @var{b} must not be less than @var{a}. It must be -@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b} -is less than @var{c}, then @var{a} must be less than @var{c}. If you -use a comparison function which does not meet these requirements, the -result of @code{sort} is unpredictable. - -The destructive aspect of @code{sort} is that it rearranges the cons -cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort -function would create new cons cells to store the elements in their -sorted order. If you wish to make a sorted copy without destroying the -original, copy it first with @code{copy-sequence} and then sort. - -Sorting does not change the @sc{car}s of the cons cells in @var{list}; -the cons cell that originally contained the element @code{a} in -@var{list} still has @code{a} in its @sc{car} after sorting, but it now -appears in a different position in the list due to the change of -@sc{cdr}s. For example: - -@example -@group -(setq nums '(1 3 2 6 5 4 0)) - @result{} (1 3 2 6 5 4 0) -@end group -@group -(sort nums '<) - @result{} (0 1 2 3 4 5 6) -@end group -@group -nums - @result{} (1 2 3 4 5 6) -@end group -@end example - -@noindent -@strong{Warning}: Note that the list in @code{nums} no longer contains -0; this is the same cons cell that it was before, but it is no longer -the first one in the list. Don't assume a variable that formerly held -the argument now holds the entire sorted list! Instead, save the result -of @code{sort} and use that. Most often we store the result back into -the variable that held the original list: - -@example -(setq nums (sort nums '<)) -@end example - -@xref{Sorting}, for more functions that perform sorting. -See @code{documentation} in @ref{Accessing Documentation}, for a -useful example of @code{sort}. -@end defun - @node Sets And Lists @section Using Lists as Sets @cindex lists as sets diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 14ac893f292..82039ba450f 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -102,8 +102,8 @@ the minibuffer is in a separate frame. @xref{Minibuffers and Frames}. When Emacs is running in batch mode, any request to read from the minibuffer actually reads a line from the standard input descriptor that was supplied when Emacs was started. This supports only basic input: -none of the special minibuffer features (history, completion, -password hiding, etc.) are available in batch mode. +none of the special minibuffer features (history, completion, etc.) +are available in batch mode. @node Text from Minibuffer @section Reading Text Strings with the Minibuffer @@ -1738,7 +1738,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 @@ -1877,11 +1877,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 @@ -2127,9 +2150,10 @@ function @code{read-passwd}. @defun read-passwd prompt &optional confirm default This function reads a password, prompting with @var{prompt}. It does -not echo the password as the user types it; instead, it echoes @samp{.} -for each character in the password. (Note that in batch mode, the -input is not hidden.) +not echo the password as the user types it; instead, it echoes +@samp{.} for each character in the password. If you want to apply +another character to hide the password, let-bind the variable +@code{read-hide-char} with that character. The optional argument @var{confirm}, if non-@code{nil}, says to read the password twice and insist it must be the same both times. If it isn't @@ -2197,8 +2221,8 @@ contents of the minibuffer before the point. @section Minibuffer Windows @cindex minibuffer windows - These functions access and select minibuffer windows -and test whether they are active. +These functions access and select minibuffer windows, test whether they +are active and control how they get resized. @defun active-minibuffer-window This function returns the currently active minibuffer window, or @@ -2239,6 +2263,29 @@ This function returns non-@code{nil} if @var{window} is the currently active minibuffer window. @end defun +The following two options control whether minibuffer windows are resized +automatically and how large they can get in the process. + +@defopt resize-mini-windows +This option specifies whether minibuffer windows are resized +automatically. The default value is @code{grow-only}, which means that +a minibuffer window by default expands automatically to accommodate the +text it displays and shrinks back to one line as soon as the minibuffer +gets empty. If the value is @code{t}, Emacs will always try to fit the +height of a minibuffer window to the text it displays (with a minimum of +one line). If the value is @code{nil}, a minibuffer window never +changes size automatically. In that case the window resizing commands +(@pxref{Resizing Windows}) can be used to adjust its height. +@end defopt + +@defopt max-mini-window-height +This option provides a maximum height for resizing minibuffer windows +automatically. A floating-point number specifies a fraction of the +frame's height; an integer specifies the maximum number of lines. The +default value is 0.25. +@end defopt + + @node Minibuffer Contents @section Minibuffer Contents @cindex access minibuffer contents diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index b52ac732c29..50e50ff39a6 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -520,6 +520,24 @@ property to display mirror images of characters when appropriate (@pxref{Bidirectional Display}). For unassigned codepoints, the value is @code{nil}. +@item paired-bracket +Corresponds to the Unicode @code{Bidi_Paired_Bracket} property. The +value of this property is the codepoint of a character's @dfn{paired +bracket}, or @code{nil} if the character is not a bracket character. +This establishes a mapping between characters that are treated as +bracket pairs by the Unicode Bidirectional Algorithm; Emacs uses this +property when it decides how to reorder for display parentheses, +braces, and other similar characters (@pxref{Bidirectional Display}). + +@item bracket-type +Corresponds to the Unicode @code{Bidi_Paired_Bracket_Type} property. +For characters whose @code{paired-bracket} property is non-@code{nil}, +the value of this property is a symbol, either @code{o} (for opening +bracket characters) or @code{c} (for closing bracket characters). For +characters whose @code{paired-bracket} property is @code{nil}, the +value is the symbol @code{n} (None). Like @code{paired-bracket}, this +property is used for bidirectional display. + @item old-name Corresponds to the Unicode @code{Unicode_1_Name} property. The value is a string. Unassigned codepoints, and characters that have no value @@ -574,6 +592,14 @@ This function returns the value of @var{char}'s @var{propname} property. (get-char-code-property ?\u2163 'numeric-value) @result{} 4 @end group +@group +(get-char-code-property ?\( 'paired-bracket) + @result{} 41 ;; closing parenthesis +@end group +@group +(get-char-code-property ?\) 'bracket-type) + @result{} c +@end group @end example @end defun diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 739477bf372..ba28b63f0de 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -1805,9 +1805,6 @@ with references to further information. @item custom-variable-p @xref{Variable Definitions, custom-variable-p}. -@item display-table-p -@xref{Display Tables, display-table-p}. - @item floatp @xref{Predicates on Numbers, floatp}. diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index bf796d6057e..46df0e78928 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -443,10 +443,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 @@ -475,7 +478,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: @@ -490,7 +493,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 @@ -907,13 +917,6 @@ This function returns the name of the machine you are running on, as a string. @end defun - The symbol @code{system-name} is a variable as well as a function. In -fact, the function returns whatever value the variable -@code{system-name} currently holds. Thus, you can set the variable -@code{system-name} in case Emacs is confused about the name of your -system. The variable is also useful for constructing frame titles -(@pxref{Frame Titles}). - @c FIXME seems like this section is not the best place for this option? @defopt mail-host-address If this variable is non-@code{nil}, it is used instead of @@ -1204,37 +1207,34 @@ return value is @code{nil}. zone. @cindex epoch - Most of these functions represent time as a list of either four -integers, @code{(@var{sec-high} @var{sec-low} @var{microsec} -@var{picosec})}, or of three -integers, @code{(@var{sec-high} @var{sec-low} @var{microsec})}, or of -two integers, @code{(@var{sec-high} @var{sec-low})}. The integers -@var{sec-high} and @var{sec-low} give the high and low bits of an -integer number of seconds. This integer, + Most of these functions represent time as a list of four integers +@code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}. +This represents the number of seconds from the @dfn{epoch} (January +1, 1970 at 00:00 UTC), using the formula: @ifnottex -@var{high} * 2**16 + @var{low}, +@var{high} * 2**16 + @var{low} + @var{micro} * 10**@minus{}6 + +@var{pico} * 10**@minus{}12. @end ifnottex @tex -$high*2^{16}+low$, +$high*2^{16} + low + micro*10^{-6} + pico*10^{-12}$. @end tex -is the number of seconds from the @dfn{epoch} (0:00 January 1, 1970 -UTC) to the specified time. The third list element @var{microsec}, if -present, gives the number of microseconds from the start of that -second to the specified time. -Similarly, the fourth list element @var{picosec}, if present, gives -the number of picoseconds from the start of that microsecond to the -specified time. - - The return value of @code{current-time} represents time using four -integers, as do the timestamps in the return value of -@code{file-attributes} (@pxref{Definition of -file-attributes}). In function arguments, e.g., the @var{time-value} -argument to @code{current-time-string}, two-, three-, and four-integer -lists are accepted. You can convert times from the list -representation into standard human-readable strings using -@code{current-time-string}, or to other forms using the -@code{decode-time} and @code{format-time-string} functions documented -in the following sections. +The return value of @code{current-time} represents time using this +form, as do the timestamps in the return values of other functions +such as @code{file-attributes} (@pxref{Definition of +file-attributes}). In some cases, functions may return two- or +three-element lists, with omitted @var{microsec} and @var{picosec} +components defaulting to zero. + +@cindex time value + Function arguments, e.g., the @var{time-value} argument to +@code{current-time-string}, accept a more-general @dfn{time value} +format, which can be a list of integers as above, or a single number +for seconds since the epoch, or @code{nil} for the current time. You +can convert a time value into a human-readable string using +@code{current-time-string} and @code{format-time-string}, into a list +of integers using @code{seconds-to-time}, and into other forms using +@code{decode-time} and @code{float-time}. These functions are +described in the following sections. @defun current-time-string &optional time-value This function returns the current time and date as a human-readable @@ -1247,8 +1247,8 @@ characters from the beginning of the string rather than from the end, as the year might not have exactly four digits, and additional information may some day be added at the end. -The argument @var{time-value}, if given, specifies a time to format -(represented as a list of integers), instead of the current time. +The argument @var{time-value}, if given, specifies a time to format, +instead of the current time. @example @group @@ -1270,11 +1270,19 @@ become available. @defun float-time &optional time-value This function returns the current time as a floating-point number of seconds since the epoch. The optional argument @var{time-value}, if -given, specifies a time (represented as a list of integers) to convert -instead of the current time. +given, specifies a time to convert instead of the current time. @emph{Warning}: Since the result is floating point, it may not be exact. Do not use this function if precise time stamps are required. + +@code{time-to-seconds} is an alias for this function. +@end defun + +@defun seconds-to-time time-value +This function converts a time value to list-of-integer form. +For example, if @var{time-value} is a number, @code{(time-to-seconds +(seconds-to-time @var{time-value}))} equals the number unless overflow +or rounding errors occur. @end defun @defun current-time-zone &optional time-value @@ -1293,8 +1301,8 @@ adjustment, then the value is constant through time. If the operating system doesn't supply all the information necessary to compute the value, the unknown elements of the list are @code{nil}. -The argument @var{time-value}, if given, specifies a time (represented -as a list of integers) to analyze instead of the current time. +The argument @var{time-value}, if given, specifies a time value to +analyze instead of the current time. @end defun The current time zone is determined by the @env{TZ} environment @@ -1308,15 +1316,15 @@ time zone. @cindex calendrical information @cindex time conversion - These functions convert time values (lists of two to four integers, -as explained in the previous section) into calendrical information and -vice versa. + These functions convert time values (@pxref{Time of Day}) into +calendrical information and vice versa. - Many 32-bit operating systems are limited to time values containing -32 bits of information; these systems typically handle only the times -from 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC@. -However, 64-bit and some 32-bit operating systems have larger time -values, and can represent times far in the past or future. + Many 32-bit operating systems are limited to system times containing +32 bits of information in their seconds component; these systems +typically handle only the times from 1901-12-13 20:45:52 UTC through +2038-01-19 03:14:07 UTC@. However, 64-bit and some 32-bit operating +systems have larger seconds components, and can represent times far in +the past or future. Time conversion functions always use the Gregorian calendar, even for dates before the Gregorian calendar was introduced. Year numbers @@ -1324,9 +1332,9 @@ count the number of years since the year 1 B.C., and do not skip zero as traditional Gregorian years do; for example, the year number @minus{}37 represents the Gregorian year 38 B.C@. -@defun decode-time &optional time +@defun decode-time &optional time-value This function converts a time value into calendrical information. If -you don't specify @var{time}, it decodes the current time. The return +you don't specify @var{time-value}, it decodes the current time. The return value is a list of nine elements, as follows: @example @@ -1365,8 +1373,9 @@ Greenwich. @defun encode-time seconds minutes hour day month year &optional zone This function is the inverse of @code{decode-time}. It converts seven -items of calendrical data into a time value. For the meanings of the -arguments, see the table above under @code{decode-time}. +items of calendrical data into a list-of-integer time value. For the +meanings of the arguments, see the table above under +@code{decode-time}. Year numbers less than 100 are not treated specially. If you want them to stand for years above 1900, or years above 2000, you must alter them @@ -1413,9 +1422,11 @@ This function parses the time-string @var{string} and returns the corresponding time value. @end defun -@defun format-time-string format-string &optional time universal -This function converts @var{time} (or the current time, if @var{time} is -omitted) to a string according to @var{format-string}. The argument +@defun format-time-string format-string &optional time-value universal + +This function converts @var{time-value} (or the current time, if +@var{time-value} is omitted) to a string according to +@var{format-string}. The argument @var{format-string} may contain @samp{%}-sequences which say to substitute parts of the time. Here is a table of what the @samp{%}-sequences mean: @@ -1535,12 +1546,6 @@ specified by @code{locale-coding-system} (@pxref{Locales}); after system. @end defun -@defun seconds-to-time seconds -This function converts @var{seconds}, the number of seconds since the -epoch, to a time value and returns that. To convert back, use -@code{float-time} (@pxref{Time of Day}). -@end defun - @defun format-seconds format-string seconds This function converts its argument @var{seconds} into a string of years, days, hours, etc., according to @var{format-string}. The @@ -1614,7 +1619,7 @@ When called interactively, it prints the uptime in the echo area. @defun get-internal-run-time This function returns the processor run time used by Emacs as a list -of four integers: @code{(@var{high} @var{low} @var{microsec} +of four integers: @code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}, using the same format as @code{current-time} (@pxref{Time of Day}). @@ -1641,7 +1646,7 @@ interactively, it prints the duration in the echo area. @cindex calendrical computations These functions perform calendrical computations using time values -(the kind of list that @code{current-time} returns). +(@pxref{Time of Day}). @defun time-less-p t1 t2 This returns @code{t} if time value @var{t1} is less than time value @@ -1650,26 +1655,26 @@ This returns @code{t} if time value @var{t1} is less than time value @defun time-subtract t1 t2 This returns the time difference @var{t1} @minus{} @var{t2} between -two time values, in the same format as a time value. +two time values, as a time value. @end defun @defun time-add t1 t2 -This returns the sum of two time values, one of which ought to -represent a time difference rather than a point in time. +This returns the sum of two time values, as a time value. +One argument should represent a time difference rather than a point in time. Here is how to add a number of seconds to a time value: @example -(time-add @var{time} (seconds-to-time @var{seconds})) +(time-add @var{time} @var{seconds}) @end example @end defun -@defun time-to-days time +@defun time-to-days time-value This function returns the number of days between the beginning of year -1 and @var{time}. +1 and @var{time-value}. @end defun -@defun time-to-day-in-year time -This returns the day number within the year corresponding to @var{time}. +@defun time-to-day-in-year time-value +This returns the day number within the year corresponding to @var{time-value}. @end defun @defun date-leap-year-p year @@ -1914,8 +1919,7 @@ idleness. Here's an example: (run-with-idle-timer ;; Compute an idle time @var{break-length} ;; more than the current value. - (time-add (current-idle-time) - (seconds-to-time @var{break-length})) + (time-add (current-idle-time) @var{break-length}) nil 'my-timer-function)))) @end example diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index 854a5ee7f6d..317b9d64a5c 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -652,9 +652,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-@code{nil} (as it is +interactively), move out of enclosing strings as well. If +@var{no-syntax-crossing} is non-@code{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/processes.texi b/doc/lispref/processes.texi index 621e8a1bfba..99411af3d46 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -1487,7 +1487,7 @@ The arguments @var{seconds} and @var{millisec} let you specify timeout periods. The former specifies a period measured in seconds and the latter specifies one measured in milliseconds. The two time periods thus specified are added together, and @code{accept-process-output} -returns after that much time, whether or not there has been any +returns after that much time, even if there is no subprocess output. The argument @var{millisec} is obsolete (and should not be used), @@ -1505,7 +1505,8 @@ recommended, but may be necessary for specific applications, such as speech synthesis. The function @code{accept-process-output} returns non-@code{nil} if it -did get some output, or @code{nil} if the timeout expired before output +got output from @var{process}, or from any process if @var{process} is +@code{nil}. It returns @code{nil} if the timeout expired before output arrived. @end defun @@ -2043,6 +2044,12 @@ Regular expression matching a successful @acronym{STARTTLS} negotiation. If non-@code{nil}, do opportunistic @acronym{STARTTLS} upgrades even if Emacs doesn't have built-in @acronym{TLS} support. +@item :warn-unless-encrypted @var{boolean} +If non-@code{nil}, and @code{:return-value} is also non-@code{nil}, +Emacs will warn if the connection isn't encrypted. This is useful for +protocols like @acronym{IMAP} and the like, where most users would +expect the network traffic to be encrypted. + @item :client-certificate @var{list-or-t} Either a list of the form @code{(@var{key-file} @var{cert-file})}, naming the certificate key file and certificate file itself, or @@ -2068,6 +2075,7 @@ The connection type: @samp{plain} or @samp{tls}. @end defun + @node Network Servers @section Network Servers @cindex network servers diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 71160a91931..f82c4962759 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -217,6 +217,491 @@ y @result{} [foo (69 2)] @end example @end defun +@defun reverse sequence +@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{sequence}, but in reverse order. The original argument @var{sequence} +is @emph{not} altered. Note that char-tables 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 sequence +@cindex reversing a string +@cindex reversing a list +@cindex reversing a vector + This function reverses the order of the elements of @var{sequence}. +Unlike @code{reverse} the original @var{sequence} 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 + +@defun sort sequence predicate +@cindex stable sort +@cindex sorting lists +@cindex sorting vectors +This function sorts @var{sequence} stably. Note that this function doesn't work +for all sequences; it may be used only for lists and vectors. If @var{sequence} +is a list, it is modified destructively. This functions returns the sorted +@var{sequence} and compares elements using @var{predicate}. A stable sort is +one in which elements with equal sort keys maintain their relative order before +and after the sort. Stability is important when successive sorts are used to +order elements according to different criteria. + +The argument @var{predicate} must be a function that accepts two +arguments. It is called with two elements of @var{sequence}. To get an +increasing order sort, the @var{predicate} should return non-@code{nil} if the +first element is ``less than'' the second, or @code{nil} if not. + +The comparison function @var{predicate} must give reliable results for +any given pair of arguments, at least within a single call to +@code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is +less than @var{b}, @var{b} must not be less than @var{a}. It must be +@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b} +is less than @var{c}, then @var{a} must be less than @var{c}. If you +use a comparison function which does not meet these requirements, the +result of @code{sort} is unpredictable. + +The destructive aspect of @code{sort} for lists is that it rearranges the +cons cells forming @var{sequence} by changing @sc{cdr}s. A nondestructive +sort function would create new cons cells to store the elements in their +sorted order. If you wish to make a sorted copy without destroying the +original, copy it first with @code{copy-sequence} and then sort. + +Sorting does not change the @sc{car}s of the cons cells in @var{sequence}; +the cons cell that originally contained the element @code{a} in +@var{sequence} still has @code{a} in its @sc{car} after sorting, but it now +appears in a different position in the list due to the change of +@sc{cdr}s. For example: + +@example +@group +(setq nums '(1 3 2 6 5 4 0)) + @result{} (1 3 2 6 5 4 0) +@end group +@group +(sort nums '<) + @result{} (0 1 2 3 4 5 6) +@end group +@group +nums + @result{} (1 2 3 4 5 6) +@end group +@end example + +@noindent +@strong{Warning}: Note that the list in @code{nums} no longer contains +0; this is the same cons cell that it was before, but it is no longer +the first one in the list. Don't assume a variable that formerly held +the argument now holds the entire sorted list! Instead, save the result +of @code{sort} and use that. Most often we store the result back into +the variable that held the original list: + +@example +(setq nums (sort nums '<)) +@end example + +For the better understanding of what stable sort is, consider the following +vector example. After sorting, all items whose @code{car} is 8 are grouped +at the beginning of @code{vector}, but their relative order is preserved. +All items whose @code{car} is 9 are grouped at the end of @code{vector}, +but their relative order is also preserved: + +@example +@group +(setq + vector + (vector '(8 . "xxx") '(9 . "aaa") '(8 . "bbb") '(9 . "zzz") + '(9 . "ppp") '(8 . "ttt") '(8 . "eee") '(9 . "fff"))) + @result{} [(8 . "xxx") (9 . "aaa") (8 . "bbb") (9 . "zzz") + (9 . "ppp") (8 . "ttt") (8 . "eee") (9 . "fff")] +@end group +@group +(sort vector (lambda (x y) (< (car x) (car y)))) + @result{} [(8 . "xxx") (8 . "bbb") (8 . "ttt") (8 . "eee") + (9 . "aaa") (9 . "zzz") (9 . "ppp") (9 . "fff")] +@end group +@end example + +@xref{Sorting}, for more functions that perform sorting. +See @code{documentation} in @ref{Accessing Documentation}, for a +useful example of @code{sort}. +@end defun + +@cindex sequence functions in seq +@cindex seq library + The @file{seq.el} library provides the following additional sequence +manipulation macros and functions, prefixed with @code{seq-}. To use +them, you must first load the @file{seq} library. + + All functions defined in this library are free of side-effects; +i.e., they do not modify any sequence (list, vector, or string) that +you pass as an argument. Unless otherwise stated, the result is a +sequence of the same type as the input. For those functions that take +a predicate, this should be a function of one argument. + +@defun seq-drop sequence n + This function returns all but the first @var{n} (an integer) +elements of @var{sequence}. If @var{n} is negative or zero, +the result is @var{sequence}. + +@example +@group +(seq-drop [1 2 3 4 5 6] 3) +@result{} [4 5 6] +@end group +@group +(seq-drop "hello world" -4) +@result{} "hello world" +@end group +@end example +@end defun + +@defun seq-take sequence n + This function returns the first @var{n} (an integer) elements of +@var{sequence}. If @var{n} is negative or zero, the result +is @code{nil}. + +@example +@group +(seq-take '(1 2 3 4) 3) +@result{} (1 2 3) +@end group +@group +(seq-take [1 2 3 4] 0) +@result{} [] +@end group +@end example +@end defun + +@defun seq-take-while predicate sequence + This function returns the members of @var{sequence} in order, +stopping before the first one for which @var{predicate} returns @code{nil}. + +@example +@group +(seq-take-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2)) +@result{} (1 2 3) +@end group +@group +(seq-take-while (lambda (elt) (> elt 0)) [-1 4 6]) +@result{} [] +@end group +@end example +@end defun + +@defun seq-drop-while predicate sequence + This function returns the members of @var{sequence} in order, +starting from the first one for which @var{predicate} returns @code{nil}. + +@example +@group +(seq-drop-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2)) +@result{} (-1 -2) +@end group +@group +(seq-drop-while (lambda (elt) (< elt 0)) [1 4 6]) +@result{} [1 4 6] +@end group +@end example +@end defun + +@defun seq-filter predicate sequence +@cindex filtering sequences + This function returns a list of all the elements in @var{sequence} +for which @var{predicate} returns non-@code{nil}. + +@example +@group +(seq-filter (lambda (elt) (> elt 0)) [1 -1 3 -3 5]) +@result{} (1 3 5) +@end group +@group +(seq-filter (lambda (elt) (> elt 0)) '(-1 -3 -5)) +@result{} nil +@end group +@end example +@end defun + +@defun seq-remove predicate sequence +@cindex removing from sequences + This function returns a list of all the elements in @var{sequence} +for which @var{predicate} returns @code{nil}. + +@example +@group +(seq-remove (lambda (elt) (> elt 0)) [1 -1 3 -3 5]) +@result{} (-1 -3) +@end group +@group +(seq-remove (lambda (elt) (< elt 0)) '(-1 -3 -5)) +@result{} nil +@end group +@end example +@end defun + +@defun seq-reduce function sequence initial-value +@cindex reducing sequences + This function returns the result of calling @var{function} with +@var{initial-value} and the first element of @var{sequence}, then calling +@var{function} with that result and the second element of @var{sequence}, +then with that result and the third element of @var{sequence}, etc. +@var{function} should be a function of two arguments. If +@var{sequence} is empty, this returns @var{initial-value} without +calling @var{function}. + +@example +@group +(seq-reduce #'+ [1 2 3 4] 0) +@result{} 10 +@end group +@group +(seq-reduce #'+ '(1 2 3 4) 5) +@result{} 15 +@end group +@group +(seq-reduce #'+ '() 3) +@result{} 3 +@end group +@end example +@end defun + +@defun seq-some-p predicate sequence + This function returns the first member of sequence for which @var{predicate} +returns non-@code{nil}. + +@example +@group +(seq-some-p #'numberp ["abc" 1 nil]) +@result{} 1 +@end group +@group +(seq-some-p #'numberp ["abc" "def"]) +@result{} nil +@end group +@end example +@end defun + +@defun seq-every-p predicate sequence + This function returns non-@code{nil} if applying @var{predicate} +to every element of @var{sequence} returns non-@code{nil}. + +@example +@group +(seq-every-p #'numberp [2 4 6]) +@result{} t +@end group +@group +(seq-some-p #'numberp [2 4 "6"]) +@result{} nil +@end group +@end example +@end defun + +@defun seq-empty-p sequence + This function returns non-@code{nil} if @var{sequence} is empty. + +@example +@group +(seq-empty-p "not empty") +@result{} nil +@end group +@group +(seq-empty-p "") +@result{} t +@end group +@end example +@end defun + +@defun seq-count predicate sequence + This function returns the number of elements in @var{sequence} for which +@var{predicate} returns non-@code{nil}. + +@example +(seq-count (lambda (elt) (> elt 0)) [-1 2 0 3 -2]) +@result{} 2 +@end example +@end defun + +@cindex sorting sequences +@defun seq-sort function sequence + This function returns a copy of @var{sequence} that is sorted +according to @var{function}, a function of two arguments that returns +non-@code{nil} if the first argument should sort before the second. +@end defun + +@defun seq-contains-p sequence elt &optional function + This function returns the first element in @var{sequence} that is equal to +@var{elt}. If the optional argument @var{function} is non-@code{nil}, +it is a function of two arguments to use instead of the default @code{equal}. + +@example +@group +(seq-contains-p '(symbol1 symbol2) 'symbol1) +@result{} symbol1 +@end group +@group +(seq-contains-p '(symbol1 symbol2) 'symbol3) +@result{} nil +@end group +@end example + +@end defun + +@defun seq-uniq sequence &optional function + This function returns a list of the elements of @var{sequence} with +duplicates removed. If the optional argument @var{function} is non-@code{nil}, +it is a function of two arguments to use instead of the default @code{equal}. + +@example +@group +(seq-uniq '(1 2 2 1 3)) +@result{} (1 2 3) +@end group +@group +(seq-uniq '(1 2 2.0 1.0) #'=) +@result{} [3 4] +@end group +@end example +@end defun + +@defun seq-subseq sequence start &optional end + This function returns a subset of @var{sequence} from @var{start} +to @var{end}, both integers (@var{end} defaults to the last element). +If @var{start} or @var{end} is negative, it counts from the end of +@var{sequence}. + +@example +@group +(seq-subseq '(1 2 3 4 5) 1) +@result{} (2 3 4 5) +@end group +@group +(seq-subseq '[1 2 3 4 5] 1 3) +@result{} [2 3] +@end group +@group +(seq-subseq '[1 2 3 4 5] -3 -1) +@result{} [3 4] +@end group +@end example +@end defun + +@defun seq-concatenate type &rest sequences + This function returns a sequence of type @var{type} made of the +concatenation of @var{sequences}. @var{type} may be: @code{vector}, +@code{list} or @code{string}. + +@example +@group +(seq-concatenate 'list '(1 2) '(3 4) [5 6]) +@result{} (1 2 3 5 6) +@end group +@group +(seq-concatenate 'string "Hello " "world") +@result{} "Hello world" +@end group +@end example +@end defun + +@defmac seq-doseq (var sequence [result]) body@dots{} +@cindex sequence iteration +This macro is like @code{dolist}, except that @var{sequence} can be a list, +vector or string (@pxref{Iteration} for more information about the +@code{dolist} macro). This is primarily useful for side-effects. +@end defmac + @node Arrays @section Arrays @cindex array @@ -699,7 +1184,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 +1193,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 +1251,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/streams.texi b/doc/lispref/streams.texi index 6cddba86a12..e52a543110b 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -339,6 +339,25 @@ shared structures. @xref{Circular Objects}. Its default value is @code{t}. @end defvar +@cindex binary I/O in batch mode +When reading or writing from the standard input/output streams of the +Emacs process in batch mode, it is sometimes required to make sure any +arbitrary binary data will be read/written verbatim, and/or that no +translation of newlines to or from CR-LF pairs are performed. This +issue does not exist on Posix hosts, only on MS-Windows and MS-DOS. +The following function allows to control the I/O mode of any standard +stream of the Emacs process. + +@defun set-binary-mode stream mode +Switch @var{stream} into binary or text I/O mode. If @var{mode} is +non-@code{nil}, switch to binary mode, otherwise switch to text mode. +The value of @var{stream} can be one of @code{stdin}, @code{stdout}, +or @code{stderr}. This function flushes any pending output data of +@var{stream} as a side effect, and returns the previous value of I/O +mode for @var{stream}. On Posix hosts, it always returns a +non-@code{nil} value and does nothing except flushing pending output. +@end defun + @node Output Streams @section Output Streams @cindex stream (for printing) @@ -615,10 +634,13 @@ spacing between calls. @end example @end defun -@defun terpri &optional stream +@defun terpri &optional stream ensure @cindex newline in print -This function outputs a newline to @var{stream}. The name stands -for ``terminate print''. +This function outputs a newline to @var{stream}. The name stands for +``terminate print''. If @var{ensure} is non-@code{nil} no newline is printed +if @var{stream} is already at the beginning of a line. Note in this +case @var{stream} can not be a function and an error is signalled if +it is. This function returns @code{t} if a newline is printed. @end defun @defun write-char character &optional stream @@ -683,6 +705,11 @@ This function outputs @var{object} to @var{stream}, just like indent and fill the object to make it more readable for humans. @end defun +If you need to use binary I/O in batch mode, e.g., use the functions +described in this section to write out arbitrary binary data or avoid +conversion of newlines on non-Posix hosts, see @ref{Input Functions, +set-binary-mode}. + @node Output Variables @section Variables Affecting Output @cindex output-controlling variables diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 5f34be4a503..aca6189d7bf 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -465,6 +465,59 @@ Representations}. @code{string-equal} is another name for @code{string=}. @end defun +@defun string-collate-equalp string1 string2 &optional locale ignore-case +This function returns @code{t} if @var{string1} and @var{string2} are +equal with respect to collation rules. A collation rule is not only +determined by the lexicographic order of the characters contained in +@var{string1} and @var{string2}, but also further rules about +relations between these characters. Usually, it is defined by the +@var{locale} environment Emacs is running with. + +For example, characters with different coding points but +the same meaning might be considered as equal, like different grave +accent Unicode characters: + +@example +@group +(string-collate-equalp (string ?\uFF40) (string ?\u1FEF)) + @result{} t +@end group +@end example + +The optional argument @var{locale}, a string, overrides the setting of +your current locale identifier for collation. The value is system +dependent; a @var{locale} "en_US.UTF-8" is applicable on POSIX +systems, while it would be, e.g., "enu_USA.1252" on MS-Windows +systems. + +If @var{ignore-case} is non-@code{nil}, characters are converted to lower-case +before comparing them. + +To emulate Unicode-compliant collation on MS-Windows systems, +bind @code{w32-collate-ignore-punctuation} to a non-@code{nil} value, since +the codeset part of the locale cannot be "UTF-8" on MS-Windows. + +If your system does not support a locale environment, this function +behaves like @code{string-equal}. + +Do @emph{not} use this function to compare file names for equality, only +for sorting them. +@end defun + +@defun string-prefix-p string1 string2 &optional ignore-case +This function returns non-@code{nil} if @var{string1} is a prefix of +@var{string2}; i.e., if @var{string2} starts with @var{string1}. If +the optional argument @var{ignore-case} is non-@code{nil}, the +comparison ignores case differences. +@end defun + +@defun string-suffix-p suffix string &optional ignore-case +This function returns non-@code{nil} if @var{suffix} is a suffix of +@var{string}; i.e., if @var{string} ends with @var{suffix}. If the +optional argument @var{ignore-case} is non-@code{nil}, the comparison +ignores case differences. +@end defun + @cindex lexical comparison @defun string< string1 string2 @c (findex string< causes problems for permuted index!!) @@ -523,6 +576,50 @@ are used. @code{string-lessp} is another name for @code{string<}. @end defun +@defun string-collate-lessp string1 string2 &optional locale ignore-case +This function returns @code{t} if @var{string1} is less than +@var{string2} in collation order. A collation order is not only +determined by the lexicographic order of the characters contained in +@var{string1} and @var{string2}, but also further rules about +relations between these characters. Usually, it is defined by the +@var{locale} environment Emacs is running with. + +For example, punctuation and whitespace characters might be considered +less significant for @ref{Sorting,,sorting}. + +@example +@group +(sort '("11" "12" "1 1" "1 2" "1.1" "1.2") 'string-collate-lessp) + @result{} ("11" "1 1" "1.1" "12" "1 2" "1.2") +@end group +@end example + +The optional argument @var{locale}, a string, overrides the setting of +your current locale identifier for collation. The value is system +dependent; a @var{locale} "en_US.UTF-8" is applicable on POSIX +systems, while it would be, e.g., "enu_USA.1252" on MS-Windows +systems. The @var{locale} "POSIX" lets @code{string-collate-lessp} +behave like @code{string-lessp}: + +@example +@group +(sort '("11" "12" "1 1" "1 2" "1.1" "1.2") + (lambda (s1 s2) (string-collate-lessp s1 s2 "POSIX"))) + @result{} ("1 1" "1 2" "1.1" "1.2" "11" "12") +@end group +@end example + +If @var{ignore-case} is non-@code{nil}, characters are converted to lower-case +before comparing them. + +To emulate Unicode-compliant collation on MS-Windows systems, +bind @code{w32-collate-ignore-punctuation} to a non-@code{nil} value, since +the codeset part of the locale cannot be "UTF-8" on MS-Windows. + +If your system does not support a locale environment, this function +behaves like @code{string-lessp}. +@end defun + @defun string-prefix-p string1 string2 &optional ignore-case This function returns non-@code{nil} if @var{string1} is a prefix of @var{string2}; i.e., if @var{string2} starts with @var{string1}. If diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index a611850c35f..1b8897f59e7 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -220,6 +220,12 @@ This function returns the contents of the entire accessible portion of the current buffer, as a string. @end defun + If you need to make sure the resulting string, when copied to a +different location, will not change its visual appearance due to +reordering of bidirectional text, use the +@code{buffer-substring-with-bidi-context} function +(@pxref{Bidirectional Display, buffer-substring-with-bidi-context}). + @defun filter-buffer-substring start end &optional delete This function filters the buffer text between @var{start} and @var{end} using a function specified by the variable @@ -3248,6 +3254,11 @@ possible to remove a @code{read-only} property unless you know the special trick: bind @code{inhibit-read-only} to a non-@code{nil} value and then remove the property. @xref{Read Only Buffers}. +@item inhibit-read-only +@kindex inhibit-read-only @r{(text property)} +If a character has the property @code{inhibit-read-only}, and the +buffer is read-only, editing the character in question is allowed. + @item invisible @kindex invisible @r{(text property)} A non-@code{nil} @code{invisible} property can make a character invisible @@ -4123,8 +4134,9 @@ buffer. Normally, this command puts point before the inserted text, and the mark after it. However, if the optional second argument @var{beforep} is non-@code{nil}, it puts the mark before and point after. -You can pass a non-@code{nil} second argument @var{beforep} to this -function interactively by supplying any prefix argument. + +When called interactively, the command defaults to putting point after +text, and a prefix argument inverts this behavior. If the register contains a rectangle, then the rectangle is inserted with its upper left corner at point. This means that text is inserted @@ -4327,7 +4339,7 @@ coding instead. When Emacs is compiled with libxml2 support, the following functions are available to parse HTML or XML text into Lisp object trees. -@defun libxml-parse-html-region start end &optional base-url +@defun libxml-parse-html-region start end &optional base-url discard-comments This function parses the text between @var{start} and @var{end} as HTML, and returns a list representing the HTML @dfn{parse tree}. It attempts to handle ``real world'' HTML by robustly coping with syntax @@ -4336,6 +4348,9 @@ mistakes. The optional argument @var{base-url}, if non-@code{nil}, should be a string specifying the base URL for relative URLs occurring in links. +If the optional argument @var{discard-comments} is non-@code{nil}, +then the parse tree is created without any comments. + In the parse tree, each HTML node is represented by a list in which the first element is a symbol representing the node name, the second element is an alist of node attributes, and the remaining elements are @@ -4349,16 +4364,17 @@ document: @end example @noindent -A call to @code{libxml-parse-html-region} returns this: +A call to @code{libxml-parse-html-region} returns this @acronym{DOM} +(document object model): @example -(html () - (head ()) - (body ((width . "101")) - (div ((class . "thing")) - "Foo" - (div () - "Yes")))) +(html nil + (head nil) + (body ((width . "101")) + (div ((class . "thing")) + "Foo" + (div nil + "Yes")))) @end example @end defun @@ -4371,12 +4387,140 @@ buffer. The argument @var{dom} should be a list as generated by @end defun @cindex parsing xml -@defun libxml-parse-xml-region start end &optional base-url +@defun libxml-parse-xml-region start end &optional base-url discard-comments This function is the same as @code{libxml-parse-html-region}, except that it parses the text as XML rather than HTML (so it is stricter about syntax). @end defun +@menu +* Document Object Model:: Access, manipulate and search the @acronym{DOM}. +@end menu + +@node Document Object Model +@subsection Document Object Model +@cindex HTML DOM +@cindex XML DOM +@cindex DOM +@cindex Document Object Model + +The @acronym{DOM} returned by @code{libxml-parse-html-region} (and the +other @acronym{XML} parsing functions) is a tree structure where each +node has a node name (called a @dfn{tag}), and optional key/value +@dfn{attribute} list, and then a list of @dfn{child nodes}. The child +nodes are either strings or @acronym{DOM} objects. + +@example +(body ((width . "101")) + (div ((class . "thing")) + "Foo" + (div nil + "Yes"))) +@end example + +@defun dom-node tag &optional attributes &rest children +This function creates a @acronym{DOM} node of type @var{tag}. If +given, @var{attributes} should be a key/value pair list. +If given, @var{children} should be @acronym{DOM} nodes. +@end defun + +The following functions can be used to work with this structure. Each +function takes a @acronym{DOM} node, or a list of nodes. In the +latter case, only the first node in the list is used. + +Simple accessors: + +@table @code +@item dom-tag @var{node} +Return the @dfn{tag} (also called ``node name'') of the node. + +@item dom-attr @var{node} @var{attribute} +Return the value of @var{attribute} in the node. A common usage +would be: + +@lisp +(dom-attr img 'href) +=> "http://fsf.org/logo.png" +@end lisp + +@item dom-children @var{node} +Return all the children of the node. + +@item dom-non-text-children @var{node} +Return all the non-string children of the node. + +@item dom-attributes @var{node} +Return the key/value pair list of attributes of the node. + +@item dom-text @var{node} +Return all the textual elements of the node as a concatenated string. + +@item dom-texts @var{node} +Return all the textual elements of the node, as well as the textual +elements of all the children of the node, recursively, as a +concatenated string. This function also takes an optional separator +to be inserted between the textual elements. + +@item dom-parent @var{dom} @var{node} +Return the parent of @var{node} in @var{dom}. +@end table + +The following are functions for altering the @acronym{DOM}. + +@table @code +@item dom-set-attribute @var{node} @var{attribute} @var{value} +Set the @var{attribute} of the node to @var{value}. + +@item dom-append-child @var{node} @var{child} +Append @var{child} as the last child of @var{node}. + +@item dom-add-child-before @var{node} @var{child} @var{before} +Add @var{child} to @var{node}'s child list before the @var{before} +node. If @var{before} is @code{nil}, make @var{child} the first child. + +@item dom-set-attributes @var{node} @var{attributes} +Replace all the attributes of the node with a new key/value list. +@end table + +The following are functions for searching for elements in the +@acronym{DOM}. They all return lists of matching nodes. + +@table @code +@item dom-by-tag @var{dom} @var{tag} +Return all nodes in @var{dom} that are of type @var{tag}. A typical +use would be: + +@lisp +(dom-by-tag dom 'td) +=> '((td ...) (td ...) (td ...)) +@end lisp + +@item dom-by-class @var{dom} @var{match} +Return all nodes in @var{dom} that have class names that match +@var{match}, which is a regular expression. + +@item dom-by-style @var{dom} @var{style} +Return all nodes in @var{dom} that have styles that match @var{match}, +which is a regular expression. + +@item dom-by-id @var{dom} @var{style} +Return all nodes in @var{dom} that have IDs that match @var{match}, +which is a regular expression. + +@item dom-strings @var{dom} +Return all strings in @var{DOM}. + +@end table + +Utility functions: + +@table @code +@item dom-pp @var{dom} &optional @var{remove-empty} +Pretty-print @var{dom} at point. If @var{remove-empty}, don't print +textual nodes that just contain white-space. +@end table + + @node Atomic Changes @section Atomic Change Groups @cindex atomic changes diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index c40686a91c7..8d6e1249478 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -16,6 +16,7 @@ is displayed in windows. * Windows and Frames:: Relating windows to the frame they appear on. * Window Sizes:: Accessing a window's size. * Resizing Windows:: Changing the sizes of windows. +* Preserving Window Sizes:: Preserving the size of windows. * Splitting Windows:: Creating a new window. * Deleting Windows:: Removing a window from its frame. * Recombining Windows:: Preserving the frame layout when splitting and @@ -394,13 +395,14 @@ internal window). The @var{edges} element is a list @code{(@var{left} @group ____________________________________________ |______________ Header Line ______________|RD| ^ - ^ |LS|LF|LM| |RM|RF|RS| | | + ^ |LS|LM|LF| |RF|RM|RS| | | | | | | | | | | | | | Window | | | | Text Area | | | | | Window Body | | | | | (Window Body) | | | | | Total Height | | | | | | | | | Height | | | | |<- Window Body Width ->| | | | | | v |__|__|__|_______________________|__|__|__| | | + |_________ Horizontal Scroll Bar _________| | | |_______________ Mode Line _______________|__| | |_____________ Bottom Divider _______________| v <---------- Window Total Width ------------> @@ -414,15 +416,15 @@ Height | | | | | | | | | Height At the center of the window is the @dfn{text area}, or @dfn{body}, where the buffer text is displayed. The text area can be surrounded by a series of optional areas. On the left and right, from innermost to -outermost, these are the left and right margins, denoted by LM and RM in -the schematic (@pxref{Display Margins}); the left and right fringes, -denoted by LF and RF (@pxref{Fringes}); the left or right scroll bar, -only one of which is present at any time, denoted by LS and RS -(@pxref{Scroll Bars}); and the right divider, denoted by RD +outermost, these are the left and right fringes, denoted by LF and RF +(@pxref{Fringes}); the left and right margins, denoted by LM and RM in +the schematic (@pxref{Display Margins}); the left or right vertical +scroll bar, only one of which is present at any time, denoted by LS and +RS (@pxref{Scroll Bars}); and the right divider, denoted by RD (@pxref{Window Dividers}). At the top of the window is the header line -(@pxref{Header Lines}); at the bottom of the window is the mode line -(@pxref{Mode Line Format}) followed by the bottom divider (@pxref{Window -Dividers}). +(@pxref{Header Lines}). At the bottom of the window are the horizontal +scroll bar (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line +Format}); and the bottom divider (@pxref{Window Dividers}). Emacs provides miscellaneous functions for finding the height and width of a window. The return value of many of these functions can be @@ -439,11 +441,8 @@ displayed within it. @cindex height of a window @cindex total height of a window The @dfn{total height} of a window is the number of lines comprising -the window's body, the header line, the mode line and the bottom divider -(if any). Note that the height of a frame is not the same as the height -of its root window (@pxref{Windows and Frames}), since a frame may also -contain an echo area, a menu bar, and a tool bar (@pxref{Size and -Position}). +the window's body, the header line, the horizontal scroll bar, the mode +line and the bottom divider (if any). @defun window-total-height &optional window round This function returns the total height, in lines, of the window @@ -457,8 +456,8 @@ rounded internally. This is done in a way such that, if the window is a parent window, the sum of the total heights of all its child windows internally equals the total height of their parent. This means that although two windows have the same pixel height, their internal total -heights may differ by one line. This means also, that if this window is -vertically combined and has a right sibling, the topmost row of that +heights may differ by one line. This means also, that if window is +vertically combined and has a next sibling, the topmost row of that sibling can be calculated as the sum of this window's topmost row and total height (@pxref{Coordinates and Windows}) @@ -490,11 +489,10 @@ window, the sum of the total widths of all its children internally equals the total width of their parent. This means that although two windows have the same pixel width, their internal total widths may differ by one column. This means also, that if this window is -horizontally combined and has a right sibling, the leftmost column of +horizontally combined and has a next sibling, the leftmost column of that sibling can be calculated as the sum of this window's leftmost -column and total width (@pxref{Coordinates and Windows}). The -optional argument @var{round} behaves as it does for -@code{window-total-height}. +column and total width (@pxref{Coordinates and Windows}). The optional +argument @var{round} behaves as it does for @code{window-total-height}. @end defun @defun window-total-size &optional window horizontal round @@ -517,9 +515,10 @@ window in units of pixels. This function returns the total height of window @var{window} in pixels. @var{window} must be a valid window and defaults to the selected one. -The return value includes mode and header line and a bottom divider, if -any. If @var{window} is an internal window, its pixel height is the -pixel height of the screen areas spanned by its children. +The return value includes mode and header line, a horizontal scroll bar +and a bottom divider, if any. If @var{window} is an internal window, +its pixel height is the pixel height of the screen areas spanned by its +children. @end defun @cindex window pixel height @@ -542,10 +541,12 @@ the screen areas spanned by its children. window has any adjacent windows. @defun window-full-height-p &optional window -This function returns non-@code{nil} if @var{window} has no other -window above or below it in its frame, i.e., its total height equals -the total height of the root window on that frame. If @var{window} is -omitted or @code{nil}, it defaults to the selected window. +This function returns non-@code{nil} if @var{window} has no other window +above or below it in its frame. More precisely, this means that the +total height of @var{window} equals the total height of the root window +on that frame. The minibuffer window does not count in this regard. If +@var{window} is omitted or @code{nil}, it defaults to the selected +window. @end defun @defun window-full-width-p &optional window @@ -559,7 +560,8 @@ that of the root window on that frame. If @var{window} is omitted or @cindex body height of a window @cindex window body width The @dfn{body height} of a window is the height of its text area, which -does not include a mode or header line or a bottom divider. +does not include a mode or header line, a horizontal scroll bar, or a +bottom divider. @defun window-body-height &optional window pixelwise This function returns the height, in lines, of the body of window @@ -646,7 +648,8 @@ size: @defopt window-min-height This option specifies the minimum total height, in lines, of any window. Its value has to accommodate at least one text line as well as a mode -and header line and a bottom divider, if present. +and header line, a horizontal scroll bar and a bottom divider, if +present. @end defopt @defopt window-min-width @@ -655,22 +658,6 @@ window. Its value has to accommodate two text columns as well as margins, fringes, a scroll bar and a right divider, if present. @end defopt -@defvar window-size-fixed -If this buffer-local variable is non-@code{nil}, the size of any -window displaying the buffer cannot normally be changed. Deleting a -window or changing the frame's size may still change its size, if -there is no choice. - -If the value is @code{height}, then only the window's height is fixed; -if the value is @code{width}, then only the window's width is fixed. -Any other non-@code{nil} value fixes both the width and the height. - -If this variable is @code{nil}, this does not necessarily mean that any -window showing the buffer can be resized in the desired direction. To -determine that, use the function @code{window-resizable}. -@xref{Resizing Windows}. -@end defvar - The following function tells how small a specific window can get taking into account the sizes of its areas and the values of @code{window-min-height}, @code{window-min-width} and @@ -685,10 +672,11 @@ of @var{window}'s lines. The return value makes sure that all components of @var{window} remain fully visible if @var{window}'s size were actually set to it. With -@var{horizontal} @code{nil} it includes the mode and header line and the -bottom divider. With @var{horizontal} non-@code{nil} it includes the -fringes, a scroll bar, and a right divider, if present. It does not, -however, include the space reserved for the margins. +@var{horizontal} @code{nil} it includes the mode and header line, the +horizontal scroll bar and the bottom divider. With @var{horizontal} +non-@code{nil} it includes the fringes, a scroll bar, and a right +divider, if present. It does not, however, include the space reserved +for the margins. The optional argument @var{ignore}, if non-@code{nil}, means ignore restrictions imposed by fixed size windows, @code{window-min-height} or @@ -740,11 +728,11 @@ Normally, the variables @code{window-min-height} and (@pxref{Window Sizes}). However, if the optional argument @var{ignore} is non-@code{nil}, this function ignores @code{window-min-height} and @code{window-min-width}, as well as @code{window-size-fixed}. Instead, -it considers the minimum-height window to be one consisting of a header, -a mode line and a bottom divider (if any), plus a text area one line -tall; and a minimum-width window as one consisting of fringes, margins, -a scroll bar and a right divider (if any), plus a text area two columns -wide. +it considers the minimum-height window to be one consisting of a header +and a mode line, a horizontal scrollbar and a bottom divider (if any), +plus a text area one line tall; and a minimum-width window as one +consisting of fringes, margins, a scroll bar and a right divider (if +any), plus a text area two columns wide. If the optional argument @var{pixelwise} is non-@code{nil}, @var{delta} is interpreted as pixels. @@ -814,7 +802,7 @@ option is @code{nil}. The default value is @code{nil}. The following commands resize windows in more specific ways. When called interactively, they act on the selected window. -@deffn Command fit-window-to-buffer &optional window max-height min-height max-width min-width +@deffn Command fit-window-to-buffer &optional window max-height min-height max-width min-width preserve-size This command adjusts the height or width of @var{window} to fit the text in it. It returns non-@code{nil} if it was able to resize @var{window}, and @code{nil} otherwise. If @var{window} is omitted or @code{nil}, it @@ -842,6 +830,10 @@ defaults to the width of @var{window}'s frame. The optional argument specified in columns and include fringes, margins and scrollbars, if any. +The optional argument @var{preserve-size}, if non-@code{nil}, will +install a parameter to preserve the size of @var{window} during future +resize operations (@pxref{Preserving Window Sizes}). + If the option @code{fit-frame-to-buffer} (see below) is non-@code{nil}, this function will try to resize the frame of @var{window} to fit its contents by calling @code{fit-frame-to-buffer} (@pxref{Size and @@ -915,6 +907,98 @@ window. @end deffn +@node Preserving Window Sizes +@section Preserving Window Sizes +@cindex preserving window sizes + +A window can get resized explicitly by using one of the functions from +the preceding section or implicitly, for example, when resizing an +adjacent window, when splitting or deleting a window (@pxref{Splitting +Windows}, @pxref{Deleting Windows}) or when resizing the window's frame +(@pxref{Size and Position}). + + It is possible to avoid implicit resizing of a specific window when +there are one or more other resizable windows on the same frame. For +this purpose, Emacs must be advised to @dfn{preserve} the size of that +window. There are two basic ways to do that. + +@defvar window-size-fixed +If this buffer-local variable is non-@code{nil}, the size of any window +displaying the buffer cannot normally be changed. Deleting a window or +changing the frame's size may still change the window's size, if there +is no choice. + +If the value is @code{height}, then only the window's height is fixed; +if the value is @code{width}, then only the window's width is fixed. +Any other non-@code{nil} value fixes both the width and the height. + +If this variable is @code{nil}, this does not necessarily mean that any +window showing the buffer can be resized in the desired direction. To +determine that, use the function @code{window-resizable}. +@xref{Resizing Windows}. +@end defvar + +Often @code{window-size-fixed} is overly aggressive because it inhibits +any attempt to explicitly resize or split an affected window as well. +This may even happen after the window has been resized implicitly, for +example, when deleting an adjacent window or resizing the window's +frame. The following function tries hard to never disallow resizing +such a window explicitly: + +@defun window-preserve-size &optional window horizontal preserve +This function (un-)marks the height of window @var{window} as preserved +for future resize operations. @var{window} must be a live window and +defaults to the selected one. If the optional argument @var{horizontal} +is non-@code{nil}, it (un-)marks the width of @var{window} as preserved. + +If the optional argument @var{preserve} is @code{t}, this means to +preserve the current height/width of @var{window}'s body. The +height/width of @var{window} will change only if Emacs has no better +choice. Resizing a window whose height/width is preserved by this +function never throws an error. + +If @var{preserve} is @code{nil}, this means to stop preserving the +height/width of @var{window}, lifting any respective restraint induced +by a previous call of this function for @var{window}. Calling +@code{enlarge-window}, @code{shrink-window} or +@code{fit-window-to-buffer} with @var{window} as argument may also +remove the respective restraint. +@end defun + +@code{window-preserve-size} is currently invoked by the following +functions: + +@table @code +@item fit-window-to-buffer +If the optional argument @var{preserve-size} of that function +(@pxref{Resizing Windows}) is non-@code{nil}, the size established by +that function is preserved. + +@item display-buffer +If the @var{alist} argument of that function (@pxref{Choosing Window}) +contains a @code{preserve-size} entry, the size of the window produced +by that function is preserved. +@end table + + @code{window-preserve-size} installs a window parameter (@pxref{Window +Parameters}) called @code{preserved-size} which is consulted by the +window resizing functions. This parameter will not prevent resizing the +window when the window shows another buffer than the one when +@code{window-preserve-size} was invoked or if its size has changed since +then. + +The following function can be used to check whether the height of a +particular window is preserved: + +@defun window-preserved-size &optional window horizontal +This function returns the preserved height of window @var{window} in +pixels. @var{window} must be a live window and defaults to the selected +one. If the optional argument @var{horizontal} is non-@code{nil}, it +returns the preserved width of @var{window}. It returns @code{nil} if +the size of @var{window} is not preserved. +@end defun + + @node Splitting Windows @section Splitting Windows @cindex splitting windows @@ -1075,6 +1159,7 @@ point was previously on. Note that this only affects function. @end defopt + @node Deleting Windows @section Deleting Windows @cindex deleting windows @@ -2232,6 +2317,13 @@ argument: the new window. The function is supposed to adjust the width of the window; its return value is ignored. @end itemize +If @var{alist} contains a @code{preserve-size} entry, Emacs will try to +preserve the size of the new window during future resize operations +(@pxref{Preserving Window Sizes}). The @sc{cdr} of that entry must be a +cons cell whose @sc{car}, if non-@code{nil}, means to preserve the width +of the window and whose @sc{cdr}, if non-@code{nil}, means to preserve +the height of the window. + This function can fail if no window splitting can be performed for some reason (e.g., if the selected frame has an @code{unsplittable} frame parameter; @pxref{Buffer Parameters}). @@ -3648,7 +3740,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 @@ -3724,13 +3816,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 @@ -3899,6 +3991,15 @@ This parameter specifies the window that this one has been cloned from. It is installed by @code{window-state-get} (@pxref{Window Configurations}). +@item @code{preserved-size} +This parameter specifies a buffer, a direction where @code{nil} means +vertical and @code{t} horizontal, and a size in pixels. If this window +displays the specified buffer and its size in the indicated direction +equals the size specified by this parameter, then Emacs will try to +preserve the size of this window in the indicated direction. This +parameter is installed and updated by the function +@code{window-preserve-size} (@pxref{Preserving Window Sizes}). + @item @code{quit-restore} This parameter is installed by the buffer display functions (@pxref{Choosing Window}) and consulted by @code{quit-restore-window} diff --git a/doc/man/ChangeLog b/doc/man/ChangeLog index 576cc097e62..205e9b900cc 100644 --- a/doc/man/ChangeLog +++ b/doc/man/ChangeLog @@ -1,6 +1,18 @@ +2014-12-14 Glenn Morris <rgm@gnu.org> + + * grep-changelog.1: Remove file. + +2014-11-10 Glenn Morris <rgm@gnu.org> + + * emacs.1.in: Rename from emacs.1. + 2014-10-20 Glenn Morris <rgm@gnu.org> - * Version 24.4 released. + * Merge in all changes up to 24.4 release. + +2014-09-29 Eli Zaretskii <eliz@gnu.org> + + * emacs.1: Bump version to 25.0.50. 2014-01-12 Glenn Morris <rgm@gnu.org> diff --git a/doc/man/emacs.1 b/doc/man/emacs.1.in index e68c89ff83d..259acb9bba8 100644 --- a/doc/man/emacs.1 +++ b/doc/man/emacs.1.in @@ -1,5 +1,5 @@ .\" See section COPYING for copyright and redistribution information. -.TH EMACS 1 "2007 April 13" "GNU Emacs 24.4.51" +.TH EMACS 1 "2007 April 13" "GNU Emacs @version@" . . .SH NAME @@ -579,7 +579,7 @@ They are stored here to reduce the size of Emacs proper. . . .SH BUGS -There is a mailing list, bug-gnu-emacs@gnu.org, for reporting Emacs +There is a mailing list, @PACKAGE_BUGREPORT@, for reporting Emacs bugs and fixes. But before reporting something as a bug, please try to be sure that it really is a bug, not a misunderstanding or a deliberate feature. diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 58b5d1d281c..e75589f92ec 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,16 +1,95 @@ -2014-12-29 Michael Albinus <michael.albinus@gmx.de> +2015-01-23 Thomas Fitzsimmons <fitzsim@fitzsim.org> - Sync with Tramp 2.2.11. + * eudc.texi (LDAP Configuration): Rename from LDAP Requirements + and provide configuration examples. + +2015-01-17 Stefan Monnier <monnier@iro.umontreal.ca> + + * eieio.texi (Slot Options): Document :protection as unsupported. +2015-01-01 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.2.11. * trampver.texi: Update release number. -2014-11-10 Tassilo Horn <tsdh@gnu.org> +2014-12-31 Paul Eggert <eggert@cs.ucla.edu> - * gnus.texi (HTML): Update section so that it mentions shr and w3m. - Also link the full EWW manual that explains more on shr, too. + Less 'make' chatter for Emacs doc + * Makefile.in (AM_DEFAULT_VERBOSITY, AM_V_GEN, am__v_GEN_) + (am__v_GEN_0, am__v_GEN_1): New macros, from ../../src/Makefile.in. + (ENVADD, $(buildinfodir)/%.info, %.html, ${buildinfodir}/ccmode.info) + (${buildinfodir}/efaq%.info, efaq%.html): + Use them. - * gnus-faq.texi (FAQ 4 - Reading messages, FAQ 4-16): Add Q&A on how to - increase contrast when displaying HTML mail with shr. +2014-12-31 Filipp Gunbin <fgunbin@fastmail.fm> + + * info.texi (Create Info buffer): Mention info-display-manual prefix. + +2014-12-29 Paul Eggert <eggert@cs.ucla.edu> + + * efaq.texi (Displaying the current file name in the titlebar): + Prefer (system-name) to system-name. + * smtpmail.texi (Server workarounds): Fix grammar. + +2014-12-18 Eric Abrahamsen <eric@ericabrahamsen.net> + + * gnus.texi (Gnus Registry Setup): Explain pruning changes. + Mention gnus-registry-prune-factor. Explain sorting changes and + gnus-registry-default-sort-function. Correct file extension. + +2014-12-17 Jay Belanger <jay.p.belanger@gmail.com> + + * calc.texi (About This Manual): Update instructions + for building the manual. + +2014-12-15 Alan Mackenzie <acm@muc.de> + + "Advice" is a mass noun. Amend text accordingly. + * cl.texi (Obsolete Macros): Replace "an advice" with "advice". + +2014-12-12 Paul Eggert <eggert@cs.ucla.edu> + + * texinfo.tex: Update from gnulib. + +2014-12-08 Andrey Kotlarski <m00naticus@gmail.com> + + * eww.texi (Basics): Document managing multiple eww buffers. + +2014-12-05 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * eww.texi (Basics): Document eww PDF viewing. + +2014-11-23 Ivan Shmakov <ivan@siamics.net> + + * eww.texi (Advanced): Mention the Desktop stuff (bug#18010). + +2014-11-23 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (Remote processes): Let-bind environment variables to + `process-environment' when running `process-file' or + `start-file-process'. + +2014-11-19 Ivan Shmakov <ivan@siamics.net> + + * eww.texi (Basics): Document `eww-history-limit'. + +2014-11-14 Paul Eggert <eggert@cs.ucla.edu> + + * org.texi (The date/time prompt, Matching tags and properties): + Use leading zero with 24-hour times less than 10:00. + +2014-11-13 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * eww.texi (Variable Index): Mention `eww-after-render-hook'. + +2014-11-10 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * eww.texi (Basics): Document `eww-readable'. + +2014-11-10 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Top): Add missing `HTML' menu. + (HTML): Fix xref to FAQ 4-16. 2014-11-09 Glenn Morris <rgm@gnu.org> @@ -18,123 +97,238 @@ (clean): No longer delete dist tarfile. (dist): Remove rule; replace with code in admin.el. -2014-11-08 Michael Albinus <michael.albinus@gmx.de> +2014-11-08 Glenn Morris <rgm@gnu.org> - Backport Tramp changes from trunk. + * Makefile.in (${buildinfodir}/ccmode.info) + (${buildinfodir}/efaq%.info): Ensure output directory exists. - * tramp.texi (Inline methods): Remove restriction on "telnet". - Recommend sharing ssh connections for "plink". - (External methods): Remove "sftp". Merge "pscp" and "psftp" - descriptions. Recommend sharing ssh connections. Add "nc" method. - (GVFS based methods): Add "sftp". - (Customizing Completion, External packages, Issues): Use @dots{}. - (Remote shell setup): Explain, how to change command line - arguments of remote "nc" listener. +2014-11-07 Tassilo Horn <tsdh@gnu.org> - * trampver.texi: Update release number. + * gnus.texi (HTML): Update section so that it mentions shr and w3m. + Also link the full EWW manual that explains more on shr, too. -2014-11-07 Tassilo Horn <tsdh@gnu.org> + * gnus-faq.texi (FAQ 4 - Reading messages, FAQ 4-16): Add Q&A on how to + increase contrast when displaying HTML mail with shr. * eww.texi (Advanced): Document increasing contrast with shr-color-visible-distance-min and shr-color-visible-luminance-min. -2014-10-31 Eric S. Raymond <esr@thyrsus.com> - - * efaq-w32.texi: Neutralized language specific to a repository type. +2014-11-02 Teodor Zlatanov <tzz@lifelogs.com> - * gnus-coding.txt: Neutralized language specific to a repository type. + * auth.texi (Help for users): Explain quoting rules better. 2014-10-30 Glenn Morris <rgm@gnu.org> * efaq.texi (Gnus does not work with NNTP): Remove; ancient. -2014-10-20 Stefan Monnier <monnier@iro.umontreal.ca> +2014-10-30 Stefan Monnier <monnier@iro.umontreal.ca> * eieio.texi (Accessing Slots, CLOS compatibility): Adjust wording since `setf' is in core rather than in CL nowadays. -2014-10-20 Glenn Morris <rgm@gnu.org> +2014-10-29 Paul Eggert <eggert@cs.ucla.edu> - * efaq.texi (Finding a package with particular functionality): - Update example. - * vip.texi: Mention this is obsolete. + Simplify use of current-time and friends. + * org.texi (Dynamic blocks): Omit unnecessary call to current-time + in example. + +2014-10-28 Christopher Schmidt <ch@ristopher.com> + + * calc.texi (Quick Calculator): Mention prefix argument of + `quick-calc'. + +2014-10-26 Eric S. Raymond <esr@thyrsus.com> + + * efaq-w32.texi: Neutralize language specific to a repository type. + +2014-10-25 Eric S. Raymond <esr@thyrsus.com> + + * gnus-coding.texi: Neutralize language specific to a repository type. 2014-10-20 Glenn Morris <rgm@gnu.org> - * Version 24.4 released. + * Merge in all changes up to 24.4 release. 2014-10-13 Glenn Morris <rgm@gnu.org> * Makefile.in (dist): Update for new output variables. +2014-10-08 Leo Liu <sdl.web@gmail.com> + + * cl.texi (Porting Common Lisp): Remove parse-integer. + +2014-10-06 Ulf Jasper <ulf.jasper@web.de> + + * newsticker.texi (Supported Formats): Fix order of subheading and + itemize. + 2014-10-04 Glenn Morris <rgm@gnu.org> * vip.texi (Other Vi Commands): Markup fix. -2014-10-02 Bastien Guerry <bzg@gnu.org> +2014-10-03 Bastien Guerry <bzg@gnu.org> - * org.texi (Key bindings and useful functions): Fix typo. Use the - correct function's name. + * org.texi (Key bindings and useful functions): Fix typo. + Use the correct function's name. -2014-10-02 Michael Brand <michael.ch.brand@gmail.com> +2014-10-03 Michael Brand <michael.ch.brand@gmail.com> * org.texi (Formula syntax for Calc): Add `f-1' to TBLFM example about `nan'. -2014-10-02 Nicolas Goaziou <mail@nicolasgoaziou.fr> +2014-10-03 Nicolas Goaziou <mail@nicolasgoaziou.fr> * org.texi (Export settings): Be more explicit about how output file name is built. * org.texi (Headings and sectioning structure): Document menus. -2014-10-02 Nicolas Goaziou <n.goaziou@gmail.com> - * org.texi (Include files, Publishing options): Remove reference - to inexistent variable. + to nonexistent variable. + +2014-10-03 Eli Zaretskii <eliz@gnu.org> + + * erc.texi (Connecting): Remove stray "OA" that failed the manual + build. + +2014-10-03 Kelvin White <kwhite@gnu.org> + + * erc.texi (Advanced Usage, Options): Add descriptions and examples + for erc-format-nick-function and erc-rename-buffers options. + +2014-09-26 Leo Liu <sdl.web@gmail.com> + + * cl.texi (Predicates on Numbers): Document cl-digit-char-p. + (Numerical Functions): Document cl-parse-integer. (Bug#18557) + +2014-09-24 Ulf Jasper <ulf.jasper@web.de> + + * newsticker.texi: Reworked. Document new treeview group + commands. Remove VERSION, UPDATED, use EMACSVER instead. + Use term 'feed reader'. + +2014-09-04 Paul Eggert <eggert@cs.ucla.edu> + + Less chatter in 'make' output. + * Makefile.in (clean): Simplify, for shorter command line. + +2014-08-07 Reuben Thomas <rrt@sc3d.org> -2014-07-25 Stephen Berman <stephen.berman@gmx.net> + * ediff.texi (Merging and diff3): Don't mention lack of support + for VMS diff, we no longer support VMS. + +2014-08-07 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (Remote shell setup): Explain, how to change command + line arguments of remote "nc" listener. + +2014-07-31 Tassilo Horn <tsdh@gnu.org> + + * gnus.texi (Group Parameters): Document that `gcc-self' may also be a + list. + +2014-07-28 Stephen Berman <stephen.berman@gmx.net> * todo-mode.texi (Marked Items): Correct omission of item deletion from commands applying to both todo and done items. -2014-07-04 Stephen Berman <stephen.berman@gmx.net> +2014-07-18 Albert Krewinkel <albert+gnus@zeitkraut.de> + + * gnus.texi (Posting Styles): Document the possibility to perform + string replacements when matching against headers. + +2014-07-09 Stephen Berman <stephen.berman@gmx.net> * todo-mode.texi (Levels of Organization): Comment out statement that Emacs recognizes todo files by their extension, since this feature has been removed due to bug#17482. -2014-06-29 Glenn Morris <rgm@gnu.org> +2014-07-03 Michael Albinus <michael.albinus@gmx.de> + + * trampver.texi: Update release number. + +2014-07-03 Glenn Morris <rgm@gnu.org> * info.texi, mh-e.texi: "Online help" doesn't mean what it used to any more. * idlwave.texi (Introduction): Comment out dead http screenshot links. -2014-06-23 Leo Liu <sdl.web@gmail.com> +2014-06-24 Leo Liu <sdl.web@gmail.com> - * dired-x.texi (Omitting Files in Dired, Omitting Variables): Fix - key binding to dired-omit-mode. (Bug#16354) + * dired-x.texi (Omitting Files in Dired, Omitting Variables): + Fix key binding to dired-omit-mode. (Bug#16354) -2014-06-22 Eli Zaretskii <eliz@gnu.org> +2014-06-24 Eli Zaretskii <eliz@gnu.org> - * autotype.texi (Skeleton Language): Document the \n feature - better. + * autotype.texi (Skeleton Language): Document the \n feature better. + +2014-06-23 Glenn Morris <rgm@gnu.org> + + * Makefile.in (%.texi): Disable implicit rules. + +2014-06-22 Mario Lang <mlang@delysid.org> + + * srecode.texi (Base Arguments): The the -> to the. + + * org.texi (Images in ODT export): The the -> the. 2014-06-21 Eli Zaretskii <eliz@gnu.org> * autotype.texi (Skeleton Language): Document the feature of \n when at eol. -2014-06-15 Michael Albinus <michael.albinus@gmx.de> +2014-06-21 Michael Albinus <michael.albinus@gmx.de> * dbus.texi (Type Conversion): Formatting edits in example. -2014-06-10 Glenn Morris <rgm@gnu.org> +2014-06-15 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.2.10. + + * tramp.texi (Inline methods): Remove restriction on "telnet". + Recommend sharing ssh connections for "plink". + (External methods): Remove "sftp". Merge "pscp" and "psftp" + descriptions. Recommend sharing ssh connections. Add "nc" method. + (GVFS based methods): Add "sftp". + (Customizing Completion, External packages, Issues): + Use @dots{}. + + * trampver.texi: Update release number. + +2014-06-15 Glenn Morris <rgm@gnu.org> + + * Makefile.in (bootstrap-clean): New. + +2014-06-12 Vincent Belaïche <vincentb1@users.sourceforge.net> + + * ses.texi: Adding documentation for SES local printer functions. + +2014-06-12 Glenn Morris <rgm@gnu.org> + + * Makefile.in: Use GNU Make features to reduce duplication. + (mkinfodir): Remove. + (${buildinfodir}): Generate using an order-only prerequisite. + (.dvi.ps): Replace with pattern rule. + ($INFO_TARGETS): Mark as PHONY. + (${buildinfodir}): New rule. + (EXTRA_OPTS, need_emacsver, need_emacsver_prefix): New variables. + (${buildinfodir}/%.info, %.dvi, %.pdf, %.html, %.ps): + New pattern rules, replacing numerous previous explicit rules. + (info_template): New definition. + (gnus.dvi, gnus.pdf): Use distinct intermediate files. + (mostlyclean): Adjust for above gnus change. + +2014-06-11 Glenn Morris <rgm@gnu.org> * Makefile.in (INFO_INSTALL): Update for 2013-08-28 DOCMISC_W32 change. +2014-06-10 Glenn Morris <rgm@gnu.org> + + * Makefile.in (INFO_EXT): Remove and replace by ".info" throughout. + (INFO_OPTS): Set directly rather than with configure. + 2014-06-08 Karl Berry <karl@gnu.org> * doc/info.texi (Help-^L): "mode line", "screenful", @@ -156,12 +350,22 @@ * todo-mode.texi (Moving and Deleting Items): * woman.texi (Navigation): Markup fixes re SPC, RET. -2014-05-24 Paul Eggert <eggert@cs.ucla.edu> +2014-06-02 Glenn Morris <rgm@gnu.org> + + * efaq.texi (Finding a package with particular functionality): + Update example. + * vip.texi: Mention this is obsolete. + +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 @@ -169,23 +373,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 @@ -214,14 +431,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): @@ -345,7 +619,6 @@ 2014-02-16 Michael Albinus <michael.albinus@gmx.de> Sync with Tramp 2.2.9. - * trampver.texi: Update release number. * efaq-w32.texi (Tramp ssh): Remove also pscp1 and pscp2. @@ -8733,7 +9006,7 @@ * org.texi (Installation, Activation): Split from Installation and Activation. - (Clocking work time): Documented new features. + (Clocking work time): Document new features. 2006-08-13 Alex Schroeder <alex@gnu.org> @@ -9334,22 +9607,22 @@ * emacs-mime.texi (Flowed text): Add mm-fill-flowed. (Sync 2004-01-27 from the trunk). -2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org> +2006-02-24 Alan Mackenzie <acm@muc.de> * cc-mode.texi: Rename c-hungry-backspace to c-hungry-delete-backwards, at the request of RMS. Leave the old name as an alias. -2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org> +2006-02-24 Alan Mackenzie <acm@muc.de> * cc-mode.texi: Correct the definition of c-beginning-of-defun, to include the function header within the defun. -2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org> +2006-02-24 Alan Mackenzie <acm@muc.de> * cc-mode.texi: Correct two typos. -2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org> +2006-02-24 Alan Mackenzie <acm@muc.de> * cc-mode.texi (Comment Commands): State that C-u M-; kills any existing comment. @@ -9663,7 +9936,7 @@ (MIME with Emacs mail packages): Delete section about the Emacs MIME FAQ (it's not reachable anymore). -2005-12-08 Alan Mackenzie <bug-cc-mode@gnu.org> +2005-12-08 Alan Mackenzie <acm@muc.de> * cc-mode.texi: The manual has been extensively revised: the information about using CC Mode has been separated from the larger @@ -9891,7 +10164,7 @@ 2005-10-10 Carsten Dominik <dominik@science.uva.nl> - * org.texi (Workflow states): Documented that change in keywords + * org.texi (Workflow states): Document that change in keywords becomes active only after restart of Emacs. 2005-10-08 Michael Albinus <michael.albinus@gmx.de> @@ -10766,7 +11039,7 @@ * Makefile.in (../info/tramp, tramp.dvi): Depend on trampver.texi. -2004-08-11 Martin Stjernholm <bug-cc-mode@gnu.org> +2004-08-11 Martin Stjernholm <mast@lysator.liu.se> * cc-mode.texi: Various updates for CC Mode 5.30.9. @@ -11014,7 +11287,7 @@ * eshell.texi (Known Problems): Add doc item. -2003-11-22 Martin Stjernholm <bug-cc-mode@gnu.org> +2003-11-22 Martin Stjernholm <mast@lysator.liu.se> * cc-mode.texi: Update for CC Mode 5.30. diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index 1644833d2b9..e2de06d1636 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -19,13 +19,16 @@ SHELL = @SHELL@ -# Where to find the source code. $(srcdir) will be the man-aux -# subdirectory of the source tree. This is -# set by the configure script's `--srcdir' option. +# Where to find the source code. $(srcdir) will be the doc/misc subdirectory +# of the source tree. This is set by configure's `--srcdir' option. srcdir=@srcdir@ ## Where the output files go. +## Note that all the Info targets build the Info files in srcdir. +## There is no provision for Info files to exist in the build directory. +## In a tarfile of Emacs, the Info files should be up to date. buildinfodir = $(srcdir)/../../info + ## Directory with emacsver.texi. emacsdir = $(srcdir)/../emacs @@ -45,15 +48,16 @@ GZIP_PROG = @GZIP_PROG@ HTML_OPTS = --no-split --html -INFO_EXT=@INFO_EXT@ # Options used only when making info output. -INFO_OPTS=@INFO_OPTS@ +# (Note that idlwave, info used --nosplit even without the .info extension.) +INFO_OPTS= --no-split INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ # The makeinfo program is part of the Texinfo distribution. # Use --force so that it generates output even if there are errors. +# (TODO? Why is this appropriate?) MAKEINFO = @MAKEINFO@ MAKEINFO_OPTS = --force -I$(emacsdir) @@ -68,7 +72,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_W32) @@ -92,21 +96,25 @@ TEXI2DVI = texi2dvi TEXI2PDF = texi2pdf DVIPS = dvips -ENVADD = TEXINPUTS="$(srcdir):$(emacsdir):$(TEXINPUTS)" \ - MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" +# 'make' verbosity. +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ -mkinfodir = @${MKDIR_P} ${buildinfodir} +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = + +ENVADD = $(AM_V_GEN)TEXINPUTS="$(srcdir):$(emacsdir):$(TEXINPUTS)" \ + MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" gfdl = ${srcdir}/doclicense.texi -.PHONY: info dvi html pdf ps echo-info +.PHONY: info dvi html pdf ps echo-info $(INFO_TARGETS) ## Prevent implicit rule triggering for foo.info. .SUFFIXES: -.SUFFIXES: .ps .dvi - -.dvi.ps: - $(DVIPS) -o $@ $< +## Disable implicit rules. +%.texi: ; # Default. info: $(INFO_TARGETS) @@ -115,7 +123,7 @@ info: $(INFO_TARGETS) ## Base file names of output info files. echo-info: @echo "$(INFO_INSTALL) " | \ - sed -e 's|[^ ]*/||g' -e 's/\.info//g' -e "s/ */$(INFO_EXT) /g" + sed -e 's|[^ ]*/||g' -e 's/\.info//g' -e "s/ */.info /g" dvi: $(DVI_TARGETS) @@ -125,754 +133,118 @@ pdf: $(PDF_TARGETS) ps: $(PS_TARGETS) -# Note that all the Info targets build the Info files in srcdir. -# There is no provision for Info files to exist in the build directory. -# In a distribution of Emacs, the Info files should be up to date. - -# Note: "<" is not portable in ordinary make rules. - -ada_mode_deps = ${srcdir}/ada-mode.texi ${gfdl} -ada-mode : $(buildinfodir)/ada-mode$(INFO_EXT) -$(buildinfodir)/ada-mode$(INFO_EXT): $(ada_mode_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/ada-mode.texi -ada-mode.dvi: $(ada_mode_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/ada-mode.texi -ada-mode.pdf: $(ada_mode_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/ada-mode.texi -ada-mode.html: $(ada_mode_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/ada-mode.texi - -auth_deps = ${srcdir}/auth.texi ${gfdl} -auth : $(buildinfodir)/auth$(INFO_EXT) -$(buildinfodir)/auth$(INFO_EXT): $(auth_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/auth.texi -auth.dvi: $(auth_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/auth.texi -auth.pdf: $(auth_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/auth.texi -auth.html: $(auth_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/auth.texi - -autotype_deps = ${srcdir}/autotype.texi ${gfdl} -autotype : $(buildinfodir)/autotype$(INFO_EXT) -$(buildinfodir)/autotype$(INFO_EXT): $(autotype_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/autotype.texi -autotype.dvi: $(autotype_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/autotype.texi -autotype.pdf: $(autotype_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/autotype.texi -autotype.html: $(autotype_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/autotype.texi - -bovine_deps = ${srcdir}/bovine.texi ${gfdl} -bovine : $(buildinfodir)/bovine$(INFO_EXT) -$(buildinfodir)/bovine$(INFO_EXT): $(bovine_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/bovine.texi -bovine.dvi: $(bovine_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/bovine.texi -bovine.pdf: $(bovine_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/bovine.texi -bovine.html: $(bovine_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/bovine.texi - -calc_deps = ${srcdir}/calc.texi $(emacsdir)/emacsver.texi ${gfdl} -calc : $(buildinfodir)/calc$(INFO_EXT) -$(buildinfodir)/calc$(INFO_EXT): $(calc_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/calc.texi -calc.dvi: $(calc_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/calc.texi -calc.pdf: $(calc_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/calc.texi -calc.html: $(calc_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/calc.texi - -cc_mode_deps = ${srcdir}/cc-mode.texi ${gfdl} -ccmode : $(buildinfodir)/ccmode$(INFO_EXT) -$(buildinfodir)/ccmode$(INFO_EXT): $(cc_mode_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/cc-mode.texi -cc-mode.dvi: $(cc_mode_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/cc-mode.texi -cc-mode.pdf: $(cc_mode_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/cc-mode.texi -cc-mode.html: $(cc_mode_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/cc-mode.texi - -cl_deps = ${srcdir}/cl.texi $(emacsdir)/emacsver.texi ${gfdl} -cl : $(buildinfodir)/cl$(INFO_EXT) -$(buildinfodir)/cl$(INFO_EXT): $(cl_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/cl.texi -cl.dvi: $(cl_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/cl.texi -cl.pdf: $(cl_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/cl.texi -cl.html: $(cl_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/cl.texi - -dbus_deps = ${srcdir}/dbus.texi ${gfdl} -dbus : $(buildinfodir)/dbus$(INFO_EXT) -$(buildinfodir)/dbus$(INFO_EXT): $(dbus_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/dbus.texi -dbus.dvi: $(dbus_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/dbus.texi -dbus.pdf: $(dbus_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/dbus.texi -dbus.html: $(dbus_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/dbus.texi - -dired_x_deps = ${srcdir}/dired-x.texi $(emacsdir)/emacsver.texi ${gfdl} -dired-x : $(buildinfodir)/dired-x$(INFO_EXT) -$(buildinfodir)/dired-x$(INFO_EXT): $(dired_x_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/dired-x.texi -dired-x.dvi: $(dired_x_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/dired-x.texi -dired-x.pdf: $(dired_x_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/dired-x.texi -dired-x.html: $(dired_x_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/dired-x.texi - -ebrowse_deps = ${srcdir}/ebrowse.texi ${gfdl} -ebrowse : $(buildinfodir)/ebrowse$(INFO_EXT) -$(buildinfodir)/ebrowse$(INFO_EXT): $(ebrowse_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/ebrowse.texi -ebrowse.dvi: $(ebrowse_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/ebrowse.texi -ebrowse.pdf: $(ebrowse_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/ebrowse.texi -ebrowse.html: $(ebrowse_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/ebrowse.texi - -ede_deps = ${srcdir}/ede.texi ${gfdl} -ede : $(buildinfodir)/ede$(INFO_EXT) -$(buildinfodir)/ede$(INFO_EXT): $(ede_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/ede.texi -ede.dvi: $(ede_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/ede.texi -ede.pdf: $(ede_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/ede.texi -ede.html: $(ede_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/ede.texi - -ediff_deps = ${srcdir}/ediff.texi ${gfdl} -ediff : $(buildinfodir)/ediff$(INFO_EXT) -$(buildinfodir)/ediff$(INFO_EXT): $(ediff_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/ediff.texi -ediff.dvi: $(ediff_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/ediff.texi -ediff.pdf: $(ediff_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/ediff.texi -ediff.html: $(ediff_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/ediff.texi - -edt_deps = ${srcdir}/edt.texi ${gfdl} -edt : $(buildinfodir)/edt$(INFO_EXT) -$(buildinfodir)/edt$(INFO_EXT): $(edt_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/edt.texi -edt.dvi: $(edt_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/edt.texi -edt.pdf: $(edt_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/edt.texi -edt.html: $(edt_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/edt.texi - -## No gfdl dependency. -efaq_deps = ${srcdir}/efaq.texi $(emacsdir)/emacsver.texi -efaq : $(buildinfodir)/efaq$(INFO_EXT) -$(buildinfodir)/efaq$(INFO_EXT): $(efaq_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/efaq.texi -efaq.dvi: $(efaq_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/efaq.texi -efaq.pdf: $(efaq_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/efaq.texi -efaq.html: $(efaq_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/efaq.texi - -efaq_w32_deps = ${srcdir}/efaq-w32.texi $(emacsdir)/emacsver.texi -efaq-w32 : $(buildinfodir)/efaq-w32$(INFO_EXT) -$(buildinfodir)/efaq-w32$(INFO_EXT): $(efaq_w32_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/efaq-w32.texi -efaq-w32.dvi: $(efaq_w32_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/efaq-w32.texi -efaq-w32.pdf: $(efaq_w32_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/efaq-w32.texi -efaq-w32.html: $(efaq_w32_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/efaq-w32.texi - -eieio_deps = ${srcdir}/eieio.texi ${gfdl} -eieio : $(buildinfodir)/eieio$(INFO_EXT) -$(buildinfodir)/eieio$(INFO_EXT): $(eieio_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/eieio.texi -eieio.dvi: $(eieio_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/eieio.texi -eieio.pdf: $(eieio_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/eieio.texi -eieio.html: $(eieio_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/eieio.texi - -emacs_gnutls_deps = ${srcdir}/emacs-gnutls.texi ${gfdl} -emacs-gnutls : $(buildinfodir)/emacs-gnutls$(INFO_EXT) -$(buildinfodir)/emacs-gnutls$(INFO_EXT): $(emacs_gnutls_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/emacs-gnutls.texi -emacs-gnutls.dvi: $(emacs_gnutls_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-gnutls.texi -emacs-gnutls.pdf: $(emacs_gnutls_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs-gnutls.texi -emacs-gnutls.html: $(emacs_gnutls_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/emacs-gnutls.texi - -emacs_mime_deps = ${srcdir}/emacs-mime.texi ${gfdl} -emacs-mime : $(buildinfodir)/emacs-mime$(INFO_EXT) -$(buildinfodir)/emacs-mime$(INFO_EXT): $(emacs_mime_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) --enable-encoding -o $@ ${srcdir}/emacs-mime.texi -emacs-mime.dvi: $(emacs_mime_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-mime.texi -emacs-mime.pdf: $(emacs_mime_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs-mime.texi -emacs-mime.html: $(emacs_mime_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) --enable-encoding -o $@ ${srcdir}/emacs-mime.texi - -epa_deps = ${srcdir}/epa.texi ${gfdl} -epa : $(buildinfodir)/epa$(INFO_EXT) -$(buildinfodir)/epa$(INFO_EXT): $(epa_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/epa.texi -epa.dvi: $(epa_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/epa.texi -epa.pdf: $(epa_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/epa.texi -epa.html: $(epa_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/epa.texi - -erc_deps = ${srcdir}/erc.texi $(emacsdir)/emacsver.texi ${gfdl} -erc : $(buildinfodir)/erc$(INFO_EXT) -$(buildinfodir)/erc$(INFO_EXT): $(erc_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/erc.texi -erc.dvi: $(erc_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/erc.texi -erc.pdf: $(erc_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/erc.texi -erc.html: $(erc_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/erc.texi - -ert_deps = ${srcdir}/ert.texi ${gfdl} -ert : $(buildinfodir)/ert$(INFO_EXT) -$(buildinfodir)/ert$(INFO_EXT): $(ert_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/ert.texi -ert.dvi: $(ert_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/ert.texi -ert.pdf: $(ert_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/ert.texi -ert.html: $(ert_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/ert.texi - -eshell_deps = ${srcdir}/eshell.texi ${gfdl} -eshell : $(buildinfodir)/eshell$(INFO_EXT) -$(buildinfodir)/eshell$(INFO_EXT): $(eshell_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/eshell.texi -eshell.dvi: $(eshell_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/eshell.texi -eshell.pdf: $(eshell_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/eshell.texi -eshell.html: $(eshell_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/eshell.texi - -eudc_deps = ${srcdir}/eudc.texi ${gfdl} -eudc : $(buildinfodir)/eudc$(INFO_EXT) -$(buildinfodir)/eudc$(INFO_EXT): $(eudc_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/eudc.texi -eudc.dvi: $(eudc_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/eudc.texi -eudc.pdf: $(eudc_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/eudc.texi -eudc.html: $(eudc_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/eudc.texi - -eww_deps = ${srcdir}/eww.texi ${gfdl} -eww : $(buildinfodir)/eww$(INFO_EXT) -$(buildinfodir)/eww$(INFO_EXT): $(eww_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/eww.texi -eww.dvi: $(eww_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/eww.texi -eww.pdf: $(eww_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/eww.texi -eww.html: $(eww_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/eww.texi - -flymake_deps = ${srcdir}/flymake.texi ${gfdl} -flymake : $(buildinfodir)/flymake$(INFO_EXT) -$(buildinfodir)/flymake$(INFO_EXT): $(flymake_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/flymake.texi -flymake.dvi: $(flymake_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/flymake.texi -flymake.pdf: $(flymake_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/flymake.texi -flymake.html: $(flymake_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/flymake.texi - -forms_deps = ${srcdir}/forms.texi ${gfdl} -forms : $(buildinfodir)/forms$(INFO_EXT) -$(buildinfodir)/forms$(INFO_EXT): $(forms_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/forms.texi -forms.dvi: $(forms_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/forms.texi -forms.pdf: $(forms_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/forms.texi -forms.html: $(forms_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/forms.texi - -## gnus/message/emacs-mime/sieve/pgg are part of Gnus. +${buildinfodir}: + ${MKDIR_P} $@ + +### The general case. + +EXTRA_OPTS = + +${buildinfodir}/%.info: ${srcdir}/%.texi ${gfdl} | ${buildinfodir} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) $(EXTRA_OPTS) \ + -o $@ $< + +## The short aliases, eg efaq = $(buildinfodir)/efaq.info. +define info_template + $(1): $$(buildinfodir)/$(1).info +endef + +## "info" is already taken. +info.info: $(buildinfodir)/info.info + +$(foreach ifile,$(filter-out info.info,$(INFO_TARGETS)),$(eval $(call info_template,$(ifile)))) + + +%.dvi: ${srcdir}/%.texi ${gfdl} + $(ENVADD) $(TEXI2DVI) $< + +%.pdf: ${srcdir}/%.texi ${gfdl} + $(ENVADD) $(TEXI2PDF) $< + +%.html: ${srcdir}/%.texi ${gfdl} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) $(EXTRA_OPTS) \ + -o $@ $< + +%.ps: %.dvi + $(DVIPS) -o $@ $< + + +### The exceptions. + +## Extra dependencies. + +need_emacsver = calc cl dired-x efaq efaq-w32 erc ido reftex woman +need_emacsver_prefix = $(addprefix ${buildinfodir}/,${need_emacsver}) + +$(need_emacsver_prefix:=.info) $(need_emacsver:=.dvi) $(need_emacsver:=.pdf) $(need_emacsver:=.html) : ${emacsdir}/emacsver.texi + +$(buildinfodir)/gnus.info gnus.html: ${srcdir}/gnus-faq.texi + +$(buildinfodir)/semantic.info semantic.dvi semantic.pdf semantic.html: ${srcdir}/sem-user.texi + + +## Please can we just rename cc-mode.texi to ccmode.texi... +${buildinfodir}/ccmode.info: ${srcdir}/cc-mode.texi ${gfdl} | ${buildinfodir} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $< + +## efaq, efaq_w32 do not depend on gfdl. +## Maybe we can use .SECONDEXPANSION for this. +${buildinfodir}/efaq%.info: ${srcdir}/efaq%.texi | ${buildinfodir} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $< + +efaq%.dvi: ${srcdir}/efaq%.texi + $(ENVADD) $(TEXI2DVI) $< + +efaq%.pdf: ${srcdir}/efaq%.texi + $(ENVADD) $(TEXI2PDF) $< + +efaq%.html: ${srcdir}/efaq%.texi + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $< + +${buildinfodir}/emacs-mime.info emacs-mime.html: EXTRA_OPTS = --enable-encoding + gnus_deps = ${srcdir}/gnus.texi ${srcdir}/gnus-faq.texi ${gfdl} -gnus : $(buildinfodir)/gnus$(INFO_EXT) -$(buildinfodir)/gnus$(INFO_EXT): $(gnus_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/gnus.texi gnus.dvi: $(gnus_deps) - sed -e '/@iflatex/,/@end iflatex/d' ${srcdir}/gnus.texi > gnustmp.texi - $(ENVADD) $(TEXI2DVI) gnustmp.texi - cp gnustmp.dvi $@ - rm gnustmp.* + sed -e '/@iflatex/,/@end iflatex/d' $< > gnustmpdvi.texi + $(ENVADD) $(TEXI2DVI) gnustmpdvi.texi + cp gnustmpdvi.dvi $@ + rm gnustmpdvi.* + gnus.pdf: $(gnus_deps) - sed -e '/@iflatex/,/@end iflatex/d' ${srcdir}/gnus.texi > gnustmp.texi - $(ENVADD) $(TEXI2PDF) gnustmp.texi - cp gnustmp.pdf $@ - rm gnustmp.* -gnus.html: $(gnus_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/gnus.texi - -htmlfontify_deps = ${srcdir}/htmlfontify.texi ${gfdl} -htmlfontify : $(buildinfodir)/htmlfontify$(INFO_EXT) -$(buildinfodir)/htmlfontify$(INFO_EXT): $(htmlfontify_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/htmlfontify.texi -htmlfontify.dvi: $(htmlfontify_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/htmlfontify.texi -htmlfontify.pdf: $(htmlfontify_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/htmlfontify.texi -htmlfontify.html: $(htmlfontify_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/htmlfontify.texi - -idlwave_deps = ${srcdir}/idlwave.texi ${gfdl} -idlwave : $(buildinfodir)/idlwave$(INFO_EXT) -# NB this one needs --no-split even without a .info extension. -$(buildinfodir)/idlwave$(INFO_EXT): $(idlwave_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/idlwave.texi -idlwave.dvi: $(idlwave_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/idlwave.texi -idlwave.pdf: $(idlwave_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/idlwave.texi -idlwave.html: $(idlwave_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/idlwave.texi - -ido_deps = ${srcdir}/ido.texi $(emacsdir)/emacsver.texi ${gfdl} -ido : $(buildinfodir)/ido$(INFO_EXT) -$(buildinfodir)/ido$(INFO_EXT): $(ido_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/ido.texi -ido.dvi: $(ido_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/ido.texi -ido.pdf: $(ido_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/ido.texi -ido.html: $(ido_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/ido.texi - -info_deps = ${srcdir}/info.texi ${gfdl} -# Avoid name clash with overall "info" target. -info.info : $(buildinfodir)/info$(INFO_EXT) -# NB this one needs --no-split even without a .info extension. -$(buildinfodir)/info$(INFO_EXT): $(info_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/info.texi -info.dvi: $(info_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/info.texi -info.pdf: $(info_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/info.texi -info.html: $(info_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/info.texi - -mairix_el_deps = ${srcdir}/mairix-el.texi ${gfdl} -mairix-el : $(buildinfodir)/mairix-el$(INFO_EXT) -$(buildinfodir)/mairix-el$(INFO_EXT): $(mairix_el_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/mairix-el.texi -mairix-el.dvi: $(mairix_el_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/mairix-el.texi -mairix-el.pdf: $(mairix_el_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/mairix-el.texi -mairix-el.html: $(mairix_el_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/mairix-el.texi - -message_deps = ${srcdir}/message.texi ${gfdl} -message : $(buildinfodir)/message$(INFO_EXT) -$(buildinfodir)/message$(INFO_EXT): $(message_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/message.texi -message.dvi: $(message_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/message.texi -message.pdf: $(message_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/message.texi -message.html: $(message_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/message.texi - -mh_e_deps = ${srcdir}/mh-e.texi ${gfdl} -mh-e : $(buildinfodir)/mh-e$(INFO_EXT) -$(buildinfodir)/mh-e$(INFO_EXT): $(mh_e_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/mh-e.texi -mh-e.dvi: $(mh_e_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/mh-e.texi -mh-e.pdf: $(mh_e_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/mh-e.texi -mh-e.html: $(mh_e_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/mh-e.texi - -newsticker_deps = ${srcdir}/newsticker.texi ${gfdl} -newsticker : $(buildinfodir)/newsticker$(INFO_EXT) -$(buildinfodir)/newsticker$(INFO_EXT): $(newsticker_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/newsticker.texi -newsticker.dvi: $(newsticker_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/newsticker.texi -newsticker.pdf: $(newsticker_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/newsticker.texi -newsticker.html: $(newsticker_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/newsticker.texi - -nxml_mode_deps = ${srcdir}/nxml-mode.texi ${gfdl} -nxml-mode : $(buildinfodir)/nxml-mode$(INFO_EXT) -$(buildinfodir)/nxml-mode$(INFO_EXT): $(nxml_mode_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/nxml-mode.texi -nxml-mode.dvi: $(nxml_mode_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/nxml-mode.texi -nxml-mode.pdf: $(nxml_mode_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/nxml-mode.texi -nxml-mode.html: $(nxml_mode_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/nxml-mode.texi - -octave_mode_deps = ${srcdir}/octave-mode.texi ${gfdl} -octave-mode : $(buildinfodir)/octave-mode$(INFO_EXT) -$(buildinfodir)/octave-mode$(INFO_EXT): $(octave_mode_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/octave-mode.texi -octave-mode.dvi: $(octave_mode_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/octave-mode.texi -octave-mode.pdf: $(octave_mode_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/octave-mode.texi -octave-mode.html: $(octave_mode_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/octave-mode.texi - -org_deps = ${srcdir}/org.texi ${gfdl} -org : $(buildinfodir)/org$(INFO_EXT) -$(buildinfodir)/org$(INFO_EXT): $(org_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/org.texi -org.dvi: $(org_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/org.texi -org.pdf: $(org_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/org.texi -org.html: $(org_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/org.texi - -pcl_cvs_deps = ${srcdir}/pcl-cvs.texi ${gfdl} -pcl-cvs : $(buildinfodir)/pcl-cvs$(INFO_EXT) -$(buildinfodir)/pcl-cvs$(INFO_EXT): $(pcl_cvs_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/pcl-cvs.texi -pcl-cvs.dvi: $(pcl_cvs_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/pcl-cvs.texi -pcl-cvs.pdf: $(pcl_cvs_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/pcl-cvs.texi -pcl-cvs.html: $(pcl_cvs_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/pcl-cvs.texi - -pgg_deps = ${srcdir}/pgg.texi ${gfdl} -pgg : $(buildinfodir)/pgg$(INFO_EXT) -$(buildinfodir)/pgg$(INFO_EXT): $(pgg_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/pgg.texi -pgg.dvi: $(pgg_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/pgg.texi -pgg.pdf: $(pgg_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/pgg.texi -pgg.html: $(pgg_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/pgg.texi - -rcirc_deps = ${srcdir}/rcirc.texi ${gfdl} -rcirc : $(buildinfodir)/rcirc$(INFO_EXT) -$(buildinfodir)/rcirc$(INFO_EXT): $(rcirc_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/rcirc.texi -rcirc.dvi: $(rcirc_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/rcirc.texi -rcirc.pdf: $(rcirc_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/rcirc.texi -rcirc.html: $(rcirc_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/rcirc.texi - -reftex_deps = ${srcdir}/reftex.texi $(emacsdir)/emacsver.texi ${gfdl} -reftex : $(buildinfodir)/reftex$(INFO_EXT) -$(buildinfodir)/reftex$(INFO_EXT): $(reftex_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/reftex.texi -reftex.dvi: $(reftex_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/reftex.texi -reftex.pdf: $(reftex_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/reftex.texi -reftex.html: $(reftex_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/reftex.texi - -remember_deps = ${srcdir}/remember.texi ${gfdl} -remember : $(buildinfodir)/remember$(INFO_EXT) -$(buildinfodir)/remember$(INFO_EXT): $(remember_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/remember.texi -remember.dvi: $(remember_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/remember.texi -remember.pdf: $(remember_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/remember.texi -remember.html: $(remember_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/remember.texi - -sasl_deps = ${srcdir}/sasl.texi ${gfdl} -sasl : $(buildinfodir)/sasl$(INFO_EXT) -$(buildinfodir)/sasl$(INFO_EXT): $(sasl_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/sasl.texi -sasl.dvi: $(sasl_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/sasl.texi -sasl.pdf: $(sasl_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/sasl.texi -sasl.html: $(sasl_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/sasl.texi - -sc_deps = ${srcdir}/sc.texi ${gfdl} -sc : $(buildinfodir)/sc$(INFO_EXT) -$(buildinfodir)/sc$(INFO_EXT): $(sc_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/sc.texi -sc.dvi: $(sc_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/sc.texi -sc.pdf: $(sc_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/sc.texi -sc.html: $(sc_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/sc.texi - -semantic_deps = ${srcdir}/semantic.texi ${srcdir}/sem-user.texi ${gfdl} -semantic : $(buildinfodir)/semantic$(INFO_EXT) -$(buildinfodir)/semantic$(INFO_EXT): $(semantic_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/semantic.texi -semantic.dvi: $(semantic_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/semantic.texi -semantic.pdf: $(semantic_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/semantic.texi -semantic.html: $(semantic_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/semantic.texi - -ses_deps = ${srcdir}/ses.texi ${gfdl} -ses : $(buildinfodir)/ses$(INFO_EXT) -$(buildinfodir)/ses$(INFO_EXT): $(ses_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/ses.texi -ses.dvi: $(ses_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/ses.texi -ses.pdf: $(ses_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/ses.texi -ses.html: $(ses_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/ses.texi - -sieve_deps = ${srcdir}/sieve.texi ${gfdl} -sieve : $(buildinfodir)/sieve$(INFO_EXT) -$(buildinfodir)/sieve$(INFO_EXT): $(sieve_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/sieve.texi -sieve.dvi: $(sieve_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/sieve.texi -sieve.pdf: $(sieve_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/sieve.texi -sieve.html: $(sieve_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/sieve.texi - -smtpmail_deps = ${srcdir}/smtpmail.texi ${gfdl} -smtpmail : $(buildinfodir)/smtpmail$(INFO_EXT) -$(buildinfodir)/smtpmail$(INFO_EXT): $(smtpmail_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/smtpmail.texi -smtpmail.dvi: $(smtpmail_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/smtpmail.texi -smtpmail.pdf: $(smtpmail_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/smtpmail.texi -smtpmail.html: $(smtpmail_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/smtpmail.texi - -speedbar_deps = ${srcdir}/speedbar.texi ${gfdl} -speedbar : $(buildinfodir)/speedbar$(INFO_EXT) -$(buildinfodir)/speedbar$(INFO_EXT): $(speedbar_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/speedbar.texi -speedbar.dvi: $(speedbar_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/speedbar.texi -speedbar.pdf: $(speedbar_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/speedbar.texi -speedbar.html: $(speedbar_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/speedbar.texi - -srecode_deps = ${srcdir}/srecode.texi ${gfdl} -srecode : $(buildinfodir)/srecode$(INFO_EXT) -$(buildinfodir)/srecode$(INFO_EXT): $(srecode_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/srecode.texi -srecode.dvi: $(srecode_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/srecode.texi -srecode.pdf: $(srecode_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/srecode.texi -srecode.html: $(srecode_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/srecode.texi - -todo_mode_deps = ${srcdir}/todo-mode.texi ${gfdl} -todo-mode : $(buildinfodir)/todo-mode$(INFO_EXT) -$(buildinfodir)/todo-mode$(INFO_EXT): $(todo_mode_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/todo-mode.texi -todo-mode.dvi: $(todo_mode_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/todo-mode.texi -todo-mode.pdf: $(todo_mode_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/todo-mode.texi -todo-mode.html: $(todo_mode_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/todo-mode.texi - -tramp_deps = ${srcdir}/tramp.texi ${srcdir}/trampver.texi ${gfdl} -tramp : $(buildinfodir)/tramp$(INFO_EXT) -$(buildinfodir)/tramp$(INFO_EXT): $(tramp_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ -D emacs ${srcdir}/tramp.texi -tramp.dvi: $(tramp_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/tramp.texi -tramp.pdf: $(tramp_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/tramp.texi -tramp.html: $(tramp_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ -D emacs ${srcdir}/tramp.texi - -url_deps = ${srcdir}/url.texi ${gfdl} -url : $(buildinfodir)/url$(INFO_EXT) -$(buildinfodir)/url$(INFO_EXT): $(url_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/url.texi -url.dvi: $(url_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/url.texi -url.pdf: $(url_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/url.texi -url.html: $(url_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/url.texi - -vip_deps = ${srcdir}/vip.texi ${gfdl} -vip : $(buildinfodir)/vip$(INFO_EXT) -$(buildinfodir)/vip$(INFO_EXT): $(vip_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/vip.texi -vip.dvi: $(vip_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/vip.texi -vip.pdf: $(vip_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/vip.texi -vip.html: $(vip_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/vip.texi - -viper_deps = ${srcdir}/viper.texi ${gfdl} -viper : $(buildinfodir)/viper$(INFO_EXT) -$(buildinfodir)/viper$(INFO_EXT): $(viper_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/viper.texi -viper.dvi: $(viper_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/viper.texi -viper.pdf: $(viper_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/viper.texi -viper.html: $(viper_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/viper.texi - -widget_deps = ${srcdir}/wisent.texi ${gfdl} -widget : $(buildinfodir)/widget$(INFO_EXT) -$(buildinfodir)/widget$(INFO_EXT): $(widget_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/widget.texi -widget.dvi: $(widget_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/widget.texi -widget.pdf: $(widget_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/widget.texi -widget.html: $(widget_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/widget.texi - -wisent_deps = ${srcdir}/wisent.texi ${gfdl} -wisent : $(buildinfodir)/wisent$(INFO_EXT) -$(buildinfodir)/wisent$(INFO_EXT): $(wisent_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/wisent.texi -wisent.dvi: $(wisent_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/wisent.texi -wisent.pdf: $(wisent_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/wisent.texi -wisent.html: $(wisent_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/wisent.texi - -woman_deps = ${srcdir}/woman.texi $(emacsdir)/emacsver.texi ${gfdl} -woman : $(buildinfodir)/woman$(INFO_EXT) -$(buildinfodir)/woman$(INFO_EXT): $(woman_deps) - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/woman.texi -woman.dvi: $(woman_deps) - $(ENVADD) $(TEXI2DVI) ${srcdir}/woman.texi -woman.pdf: $(woman_deps) - $(ENVADD) $(TEXI2PDF) ${srcdir}/woman.texi -woman.html: $(woman_deps) - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/woman.texi - -.PHONY: mostlyclean clean distclean maintainer-clean + sed -e '/@iflatex/,/@end iflatex/d' $< > gnustmppdf.texi + $(ENVADD) $(TEXI2PDF) gnustmppdf.texi + cp gnustmppdf.pdf $@ + rm gnustmppdf.* + +${buildinfodir}/tramp.info tramp.html: EXTRA_OPTS = -D emacs +${buildinfodir}/tramp.info tramp.html: ${srcdir}/trampver.texi + + +.PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean mostlyclean: rm -f *.aux *.log *.toc *.c[mp] *.c[mp]s *.fn *.fns \ *.ky *.kys *.op *.ops *.p[gj] *.p[gj]s *.sc *.scs *.ss \ *.t[gp] *.t[gp]s *.vr *.vrs - rm -f gnustmp.* + rm -f gnustmp* clean: mostlyclean - rm -f $(DVI_TARGETS) $(HTML_TARGETS) $(PDF_TARGETS) $(PS_TARGETS) - rm -f efaq-w32.dvi efaq-w32.html efaq-w32.pdf efaq-w32.ps + rm -f *.dvi *.html *.pdf *.ps distclean: clean rm -f Makefile ## buildinfodir is relative to srcdir. infoclean: - cd $(buildinfodir); 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]; \ + for file in $(INFO_TARGETS); do \ + file=`echo $${file} | sed 's/\.info$$//'`.info; \ + rm -f \ + $(buildinfodir)/$${file} \ + $(buildinfodir)/$${file}-[1-9] \ + $(buildinfodir)/$${file}-[1-9][0-9]; \ done -maintainer-clean: distclean infoclean +bootstrap-clean maintainer-clean: distclean infoclean .PHONY: install-dvi install-html install-pdf install-ps install-doc diff --git a/doc/misc/ada-mode.texi b/doc/misc/ada-mode.texi index 8bab2512f0a..539e2b23fcb 100644 --- a/doc/misc/ada-mode.texi +++ b/doc/misc/ada-mode.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@setfilename ../../info/ada-mode +@setfilename ../../info/ada-mode.info @settitle Ada Mode @documentencoding UTF-8 diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi index 36d2741fee8..44fcad8d493 100644 --- a/doc/misc/auth.texi +++ b/doc/misc/auth.texi @@ -4,7 +4,7 @@ @set VERSION 0.3 -@setfilename ../../info/auth +@setfilename ../../info/auth.info @settitle Emacs auth-source Library @value{VERSION} @documentencoding UTF-8 @@ -106,12 +106,17 @@ The @code{user} is the user name. It's known as @var{:user} in @code{auth-source-search} queries. You can also use @code{login} and @code{account}. -Spaces are always OK as far as auth-source is concerned (but other -programs may not like them). Just put the data in quotes, escaping -quotes as you'd expect with @samp{\}. +You can use spaces inside a password or other token by surrounding the +token with either single or double quotes. -All these are optional. You could just say (but we don't recommend -it, we're just showing that it's possible) +You can use single quotes inside a password or other token by +surrounding it with double quotes, e.g. @code{"he'llo"}. Similarly you +can use double quotes inside a password or other token by surrounding +it with single quotes, e.g. @code{'he"llo'}. You can't mix both (so a +password or other token can't have both single and double quotes). + +All this is optional. You could just say (but we don't recommend it, +we're just showing that it's possible) @example password @var{mypassword} diff --git a/doc/misc/autotype.texi b/doc/misc/autotype.texi index 6fed71332df..65cbae523ff 100644 --- a/doc/misc/autotype.texi +++ b/doc/misc/autotype.texi @@ -1,7 +1,7 @@ \input texinfo @c This is an annex of the Emacs manual. @c Author: Daniel Pfeiffer <Daniel.Pfeiffer@Informatik.START.dbp.de> -@setfilename ../../info/autotype +@setfilename ../../info/autotype.info @c @node Autotypist, Picture, Abbrevs, Top @c @chapter Features for Automatic Typing @settitle Features for Automatic Typing diff --git a/doc/misc/bovine.texi b/doc/misc/bovine.texi index b390b60c292..cd2e7365f25 100644 --- a/doc/misc/bovine.texi +++ b/doc/misc/bovine.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/bovine +@setfilename ../../info/bovine.info @set TITLE Bovine parser development @set AUTHOR Eric M. Ludlam, David Ponce, and Richard Y. Kim @settitle @value{TITLE} diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index b54f8af7ae2..30e39c43112 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -1,7 +1,7 @@ \input texinfo @c -*-texinfo-*- @comment %**start of header (This is for running Texinfo on a region.) @c smallbook -@setfilename ../../info/calc +@setfilename ../../info/calc.info @c [title] @settitle GNU Emacs Calc Manual @documentencoding UTF-8 @@ -349,25 +349,12 @@ program by Donald Knuth at Stanford University) as well as the @file{texindex} program and @file{texinfo.tex} file, both of which can be obtained from the FSF as part of the @code{texinfo} package. To print the Calc manual in one huge tome, you will need the -source code to this manual, @file{calc.texi}, available as part of the -Emacs source. Once you have this file, type @kbd{texi2dvi calc.texi}. -Alternatively, change to the @file{man} subdirectory of the Emacs -source distribution, and type @kbd{make calc.dvi}. (Don't worry if you -get some ``overfull box'' warnings while @TeX{} runs.) -The result will be a device-independent output file called -@file{calc.dvi}, which you must print in whatever way is right -for your system. On many systems, the command is - -@example -lpr -d calc.dvi -@end example - -@noindent -or - -@example -dvips calc.dvi -@end example +Emacs source, which contains the source code to this manual, +@file{calc.texi}. Change to the @file{doc/misc} subdirectory of the +Emacs source distribution, which contains source code for this manual, +and type @kbd{make calc.pdf}. (Don't worry if you get some ``overfull +box'' warnings while @TeX{} runs.) The result will be this entire +manual as a pdf file. @end ifnottex @c Printed copies of this manual are also available from the Free Software @c Foundation. @@ -10168,9 +10155,10 @@ to yank the result into the next @kbd{C-x * q} input line as a more explicit alternative to @kbd{$} notation, or to yank the result into the Calculator stack after typing @kbd{C-x * c}. -If you finish your formula by typing @key{LFD} (or @kbd{C-j}) instead -of @key{RET}, the result is inserted immediately into the current -buffer rather than going into the kill ring. +If you give a prefix argument to @kbd{C-x * q} or finish your formula +by typing @key{LFD} (or @kbd{C-j}) instead of @key{RET}, the result is +inserted immediately into the current buffer rather than going into +the kill ring. Quick Calculator results are actually evaluated as if by the @kbd{=} key (which replaces variable names by their stored values, if any). diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index 471f507fe5f..1b79640d77a 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -81,7 +81,7 @@ the second with them pointing to the XEmacs manuals. @comment No overfull hbox marks in the dvi file. @finalout -@setfilename ../../info/ccmode +@setfilename ../../info/ccmode.info @settitle CC Mode Manual @documentencoding UTF-8 @footnotestyle end diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 3a5c7c8f476..66776029353 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@setfilename ../../info/cl +@setfilename ../../info/cl.info @settitle Common Lisp Extensions @documentencoding UTF-8 @include emacsver.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 @@ -2929,6 +2929,12 @@ This predicate tests whether @var{integer} is even. It is an error if the argument is not an integer. @end defun +@defun cl-digit-char-p char radix +Test if @var{char} is a digit in the specified @var{radix} (default is +10). If true return the decimal value of digit @var{char} in +@var{radix}. +@end defun + @node Numerical Functions @section Numerical Functions @@ -3011,6 +3017,15 @@ This function returns the same value as the second return value of @code{cl-truncate}. @end defun +@defun cl-parse-integer string &key start end radix junk-allowed +This function implements the Common Lisp @code{parse-integer} +function. It parses an integer in the specified @var{radix} from the +substring of @var{string} between @var{start} and @var{end}. Any +leading and trailing whitespace chars are ignored. It signals an error +if the substring between @var{start} and @var{end} cannot be parsed as +an integer unless @var{junk-allowed} is non-nil. +@end defun + @node Random Numbers @section Random Numbers @@ -3679,10 +3694,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 +4260,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 +4462,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 @@ -4661,9 +4707,8 @@ exactly the same thing, so this package has not bothered to implement a Common Lisp-style @code{make-list}. @item -A few more notable Common Lisp features not included in this -package: @code{compiler-let}, @code{tagbody}, @code{prog}, -@code{ldb/dpb}, @code{parse-integer}, @code{cerror}. +A few more notable Common Lisp features not included in this package: +@code{compiler-let}, @code{prog}, @code{ldb/dpb}, @code{cerror}. @item Recursion. While recursion works in Emacs Lisp just like it @@ -4869,7 +4914,7 @@ through the Lisp @code{message} function. For those cases where the dynamic scoping of @code{flet} is desired, @code{cl-flet} is clearly not a substitute. The most direct replacement would be instead to use @code{cl-letf} to temporarily rebind @code{(symbol-function -'@var{fun})}. But in most cases, a better substitute is to use an advice, such +'@var{fun})}. But in most cases, a better substitute is to use advice, such as: @example @@ -4885,7 +4930,7 @@ binding of @code{my-fun-advice-enable}. @c Bug#411. Note that many primitives (e.g., @code{+}) have special byte-compile handling. -Attempts to redefine such functions using @code{flet}, @code{cl-letf}, or an +Attempts to redefine such functions using @code{flet}, @code{cl-letf}, or advice will fail when byte-compiled. @c Or cl-flet. @c In such cases, use @code{labels} instead. diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi index 773ef6f6b55..2eef4f4e7e7 100644 --- a/doc/misc/dbus.texi +++ b/doc/misc/dbus.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@setfilename ../../info/dbus +@setfilename ../../info/dbus.info @c %**start of header @settitle Using of D-Bus @documentencoding UTF-8 diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi index b175c63932e..90fb5119511 100644 --- a/doc/misc/dired-x.texi +++ b/doc/misc/dired-x.texi @@ -7,7 +7,7 @@ @c [Dodd's address no longer valid.] @comment %**start of header (This is for running Texinfo on a region.) -@setfilename ../../info/dired-x +@setfilename ../../info/dired-x.info @settitle Dired Extra User's Manual @documentencoding UTF-8 diff --git a/doc/misc/ebrowse.texi b/doc/misc/ebrowse.texi index 88679596f40..943b98df96f 100644 --- a/doc/misc/ebrowse.texi +++ b/doc/misc/ebrowse.texi @@ -1,7 +1,7 @@ \input texinfo @c -*-texinfo-*- @comment %**start of header -@setfilename ../../info/ebrowse +@setfilename ../../info/ebrowse.info @settitle A Class Browser for C++ @documentencoding UTF-8 @setchapternewpage odd diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi index 5529b9b4466..ecf1d0380c8 100644 --- a/doc/misc/ede.texi +++ b/doc/misc/ede.texi @@ -1,5 +1,5 @@ \input texinfo -@setfilename ../../info/ede +@setfilename ../../info/ede.info @settitle Emacs Development Environment @documentencoding UTF-8 diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi index 0fa88a55c64..36c6ae24b12 100644 --- a/doc/misc/ediff.texi +++ b/doc/misc/ediff.texi @@ -7,7 +7,7 @@ @comment Using ediff.info instead of ediff in setfilename breaks DOS. @comment @setfilename ediff @comment @setfilename ediff.info -@setfilename ../../info/ediff +@setfilename ../../info/ediff.info @settitle Ediff User's Manual @documentencoding UTF-8 @@ -350,8 +350,7 @@ All the above functions use the POSIX @code{diff} or @code{diff3} programs to find differences between two files. They process the @code{diff} output and display it in a convenient form. At present, Ediff understands only the plain output from diff. Options such as @samp{-c} are not supported, -nor is the format produced by incompatible file comparison programs such as -the VMS version of @code{diff}. +nor is the format produced by incompatible file comparison programs. The functions @code{ediff-files}, @code{ediff-buffers}, @code{ediff-files3}, @code{ediff-buffers3} first display the coarse, @@ -1945,11 +1944,6 @@ Specifies the default directory to look for patches. @end table -@noindent -@strong{Warning:} Ediff does not support the output format of VMS -@code{diff}. Instead, make sure you are using some implementation of POSIX -@code{diff}, such as @code{gnudiff}. - @node Merging and diff3 @section Merging and diff3 diff --git a/doc/misc/edt.texi b/doc/misc/edt.texi index 68324b14166..aa0ef63e1d7 100644 --- a/doc/misc/edt.texi +++ b/doc/misc/edt.texi @@ -1,5 +1,5 @@ \input texinfo -@setfilename ../../info/edt +@setfilename ../../info/edt.info @settitle EDT Emulation for Emacs @documentencoding UTF-8 diff --git a/doc/misc/efaq-w32.texi b/doc/misc/efaq-w32.texi index 8332ad98f4c..9691a731123 100644 --- a/doc/misc/efaq-w32.texi +++ b/doc/misc/efaq-w32.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-coding:utf-8 -*- -@setfilename efaq-w32 +@setfilename ../../info/efaq-w32.info @settitle GNU Emacs FAQ For MS Windows @setchapternewpage odd @syncodeindex pg cp diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi index 8f6515ae3d0..84178277aab 100644 --- a/doc/misc/efaq.texi +++ b/doc/misc/efaq.texi @@ -1,6 +1,6 @@ \input texinfo @c -*- mode: texinfo; -*- @c %**start of header -@setfilename ../../info/efaq +@setfilename ../../info/efaq.info @settitle GNU Emacs FAQ @documentencoding UTF-8 @c %**end of header @@ -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 @@ -1473,7 +1469,7 @@ machine at which Emacs was invoked. This is done by setting @code{frame-title-format} to the default value of @lisp -(multiple-frames "%b" ("" invocation-name "@@" system-name)) +(multiple-frames "%b" ("" invocation-name "@@" (system-name))) @end lisp To modify the behavior such that frame titlebars contain the buffer's diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi index f64cf27c5e6..3f42862f07a 100644 --- a/doc/misc/eieio.texi +++ b/doc/misc/eieio.texi @@ -1,5 +1,5 @@ \input texinfo -@setfilename ../../info/eieio +@setfilename ../../info/eieio.info @set TITLE Enhanced Implementation of Emacs Interpreted Objects @set AUTHOR Eric M. Ludlam @settitle @value{TITLE} @@ -538,10 +538,15 @@ to quote the symbol. If you wanted to run a function on load, you can output the code to do the construction of the value. @item :protection +This is an old option that is not supported any more. + When using a slot referencing function such as @code{slot-value}, and the value behind @var{slot} is private or protected, then the current scope of operation must be within a method of the calling object. +This protection is not enforced by the code any more, so it's only useful +as documentation. + Valid values are: @table @code diff --git a/doc/misc/emacs-gnutls.texi b/doc/misc/emacs-gnutls.texi index 284b7f7754d..25bb9d05f3e 100644 --- a/doc/misc/emacs-gnutls.texi +++ b/doc/misc/emacs-gnutls.texi @@ -2,7 +2,7 @@ @set VERSION 0.3 -@setfilename ../../info/emacs-gnutls +@setfilename ../../info/emacs-gnutls.info @settitle Emacs GnuTLS Integration @value{VERSION} @documentencoding UTF-8 diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi index bc09d47752f..0147db34fff 100644 --- a/doc/misc/emacs-mime.texi +++ b/doc/misc/emacs-mime.texi @@ -2,7 +2,7 @@ @include gnus-overrides.texi -@setfilename ../../info/emacs-mime +@setfilename ../../info/emacs-mime.info @settitle Emacs MIME Manual @synindex fn cp @synindex vr cp @@ -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/epa.texi b/doc/misc/epa.texi index 500c629f042..8de8604634a 100644 --- a/doc/misc/epa.texi +++ b/doc/misc/epa.texi @@ -1,6 +1,6 @@ \input texinfo @c -*- mode: texinfo -*- @c %**start of header -@setfilename ../../info/epa +@setfilename ../../info/epa.info @settitle EasyPG Assistant User's Manual @documentencoding UTF-8 @c %**end of header diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index ffb8cd6455c..aaa88ce803b 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -1,6 +1,6 @@ \input texinfo @c %**start of header -@setfilename ../../info/erc +@setfilename ../../info/erc.info @settitle ERC Manual @syncodeindex fn cp @include emacsver.texi @@ -588,6 +588,16 @@ In the latter case, if the first nick in the list is already in use, other nicks are tried in the list order. @end defopt +@defopt erc-format-nick-function +A function to format a nickname for message display + +You can set this to @code{erc-format-@@nick} to display user mode prefix +@end defopt + +@example +(setq erc-format-nick-function 'erc-format-@@nick) +@end example + @defopt erc-nick-uniquifier The string to append to the nick if it is already in use. @end defopt @@ -661,7 +671,8 @@ your Emacs configuration file. Everything after the @code{(require ;; using the version of ERC that comes with Emacs (add-to-list 'load-path "~/elisp/erc") -;; Load ERC +;; Load ERC -- again, you don't need this if you are using the version +;; of ERC that comes with Emacs (require 'erc) ;; Load authentication info from an external source. Put sensitive @@ -712,6 +723,12 @@ stuff, to the current ERC buffer." ;; Join the #emacs and #erc channels whenever connecting to Freenode. (setq erc-autojoin-channels-alist '(("freenode.net" "#emacs" "#erc"))) +;; Rename server buffers to reflect the current network name instead +;; of IP:PORT. (e.g. "freenode" instead of "84.240.3.129:6667"). This +;; is useful when using a bouncer like ZNC where you have multiple +;; connections to the same server. +(setq erc-rename-buffers t) + ;; Interpret mIRC-style color commands in IRC chats (setq erc-interpret-mirc-color t) @@ -750,6 +767,14 @@ lurkers. The function @code{erc-lurker-p} determines whether a given nickname is considered a lurker. @end defopt +@defopt erc-rename-buffers +If non, @code{nil}, this will rename server buffers to reflect the +current network name instead of IP:PORT + +@example +(setq erc-rename-buffers t) +@end example +@end defopt @node Getting Help and Reporting Bugs @chapter Getting Help and Reporting Bugs diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi index e6840b182f8..51e9586991a 100644 --- a/doc/misc/ert.texi +++ b/doc/misc/ert.texi @@ -1,6 +1,6 @@ \input texinfo @c %**start of header -@setfilename ../../info/ert +@setfilename ../../info/ert.info @settitle Emacs Lisp Regression Testing @documentencoding UTF-8 @c %**end of header diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index a7a503f4c55..ca90573f30b 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/eshell +@setfilename ../../info/eshell.info @settitle Eshell: The Emacs Shell @defindex cm @synindex vr fn diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi index 2f7a0199af3..9757c82fe7e 100644 --- a/doc/misc/eudc.texi +++ b/doc/misc/eudc.texi @@ -1,6 +1,6 @@ \input texinfo.tex @c %**start of header -@setfilename ../../info/eudc +@setfilename ../../info/eudc.info @settitle Emacs Unified Directory Client (EUDC) Manual @afourpaper @documentencoding UTF-8 @@ -137,7 +137,7 @@ location, etc@enddots{} More information about LDAP can be found at @url{http://www.openldap.org/}. EUDC requires external support to access LDAP directory servers -(@pxref{LDAP Requirements}) +(@pxref{LDAP Configuration}) @node CCSO PH/QI @@ -213,17 +213,131 @@ email composition buffers (@pxref{Inline Query Expansion}) @end lisp @menu -* LDAP Requirements:: EUDC needs external support for LDAP +* LDAP Configuration:: EUDC needs external support for LDAP @end menu -@node LDAP Requirements -@section LDAP Requirements +@node LDAP Configuration +@section LDAP Configuration -LDAP support is added by means of @file{ldap.el}, which is part of Emacs. -@file{ldap.el} needs an external command line utility named -@file{ldapsearch}, available as part of Open LDAP -(@url{http://www.openldap.org/}). +LDAP support is added by means of @file{ldap.el}, which is part of +Emacs. @file{ldap.el} needs an external command line utility named +@file{ldapsearch}, available as part of OpenLDAP +(@url{http://www.openldap.org/}). The configurations in this section +were tested with OpenLDAP 2.4.23. +The following examples use a base of +@code{ou=people,dc=example,dc=com} and the host name +@code{directory.example.com}, a server that supports LDAP-over-SSL +(the @code{ldaps} protocol, with default port @code{636}) and which +requires authentication by the user @code{emacsuser} with password +@code{s3cr3t}. + +These configurations are meant to be self-contained; that is, each +provides everything required for sensible TAB-completion of email +fields. BBDB lookups are attempted first; if a matching BBDB entry is +found then EUDC will not attempt any LDAP lookups. + +Wildcard LDAP lookups are supported using the @code{*} character. For +example, attempting to TAB-complete the following: + +@example +To: * Smith +@end example + +will return all LDAP entries with surnames that begin with +@code{Smith}. In every LDAP query it makes, EUDC implicitly appends +the wildcard character to the end of the last word. + +@subsection Emacs-only Configuration + +Emacs can pass most required configuration options via the +@file{ldapsearch} command-line. One exception is certificate +configuration for LDAP-over-SSL, which must be specified in +@file{/etc/openldap/ldap.conf}. On systems that provide such +certificates as part of the @code{OpenLDAP} installation, this can be +as simple as one line: + +@example +TLS_CACERTDIR /etc/openldap/certs +@end example + +In @file{.emacs}, these expressions suffice to configure EUDC for +LDAP: + +@lisp +(eval-after-load "message" + '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) +(customize-set-variable 'eudc-server-hotlist + '(("" . bbdb) + ("ldaps://directory.example.com" . ldap))) +(customize-set-variable 'ldap-host-parameters-alist + '(("ldaps://directory.example.com" + base "ou=people,dc=example,dc=com" + binddn "example\\emacsuser" + passwd ldap-password-read))) +@end lisp + +Specifying the function @code{ldap-password-read} for @code{passwd} +will cause Emacs to prompt interactively for the password. The +password will then be validated and cached, unless +@code{password-cache} is nil. You can customize +@code{password-cache-expiry} to control the duration for which the +password is cached. If you want to clear the cache, call +@code{password-reset}. + +@subsection External Configuration + +Your system may already be configured for a default LDAP server. For +example, @file{/etc/openldap/ldap.conf} might contain: + +@example +BASE ou=people,dc=example,dc=com +URI ldaps://directory.example.com +TLS_CACERTDIR /etc/openldap/certs +@end example + +To authenticate, the @dfn{bind distinguished name (binddn)} is +required, in this case, @code{example\emacsuser}, along with the +password. These can be specified in @file{~/.authinfo.gpg} with the +following line: + +@example +machine ldaps://directory.example.com binddn example\emacsuser password s3cr3t +@end example + +Then in the @file{.emacs} init file, these expressions suffice to +configure EUDC for LDAP: + +@lisp +(eval-after-load "message" + '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) +(customize-set-variable 'eudc-server-hotlist + '(("" . bbdb) + ("ldaps://directory.example.com" . ldap))) +(customize-set-variable 'ldap-host-parameters-alist + '(("ldaps://directory.example.com" + auth-source t))) +@end lisp + +For this example where we only care about one server, the server name +can be omitted in @file{~/.authinfo.gpg} and @file{.emacs}, in which +case @file{ldapsearch} defaults to the host name in +@file{/etc/openldap/ldap.conf}. + +The @file{~/.authinfo.gpg} line becomes: + +@example +binddn example\emacsuser password s3cr3t +@end example + +and the @file{.emacs} expressions become: + +@lisp +(eval-after-load "message" + '(define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) +(customize-set-variable 'eudc-server-hotlist '(("" . bbdb) ("" . ldap))) +(customize-set-variable 'ldap-host-parameters-alist '(("" auth-source t))) +@end lisp @node Usage @chapter Usage diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi index 7762158cb0f..fd9f6f543e0 100644 --- a/doc/misc/eww.texi +++ b/doc/misc/eww.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/eww +@setfilename ../../info/eww.info @settitle Emacs Web Wowser @documentencoding UTF-8 @c %**end of header @@ -97,6 +97,12 @@ and the web page is rendered in it. You can leave EWW by pressing web page hit @kbd{g} (@code{eww-reload}). Pressing @kbd{w} (@code{eww-copy-page-url}) will copy the current URL to the kill ring. +@findex eww-readable +@kindex R + The @kbd{R} command (@code{eww-readable}) will attempt to determine +which part of the document contains the ``readable'' text, and will +only display this part. This usually gets rid of menus and the like. + @findex eww-download @vindex eww-download-directory @kindex d @@ -120,6 +126,21 @@ history press @kbd{H} (@code{eww-list-histories}) to open the history buffer @file{*eww history*}. The history is lost when EWW is quit. If you want to remember websites you can use bookmarks. +@vindex eww-history-limit + Along with the URLs visited, EWW also remembers both the rendered +page (as it appears in the buffer) and its source. This can take a +considerable amount of memory, so EWW discards the history entries to +keep their number within a set limit, as specified by +@code{eww-history-limit}; the default being 50. This variable could +also be set to @code{nil} to allow for the history list to grow +indefinitely. + +@cindex PDF + PDFs are viewed inline, by default, with @code{doc-view-mode}, but +this can be customized by using the mailcap (@pxref{mailcap,,, +emacs-mime, Emacs MIME Manual}) +mechanism, in particular @code{mailcap-mime-data}. + @findex eww-add-bookmark @findex eww-list-bookmarks @kindex b @@ -131,6 +152,13 @@ You can view stored bookmarks with @kbd{B} (@code{eww-list-bookmarks}). This will open the bookmark buffer @file{*eww bookmarks*}. +@findex eww-list-buffers +@kindex S +@cindex Multiple Buffers + To get summary of currently opened EWW buffers, press @kbd{S} +(@code{eww-list-buffers}). The @file{*eww buffers*} buffer allows to +quickly kill, flip through and switch to specific EWW buffer. + @findex eww-browse-with-external-browser @vindex shr-external-browser @vindex eww-use-external-browser-for-content-type @@ -204,6 +232,40 @@ contrast. If that is still too low for you, you can customize the variables @code{shr-color-visible-distance-min} and @code{shr-color-visible-luminance-min} to get a better contrast. +@cindex Desktop Support +@cindex Saving Sessions + In addition to maintaining the history at run-time, EWW will also +save the partial state of its buffers (the URIs and the titles of the +pages visited) in the desktop file if one is used. @xref{Saving Emacs +Sessions, , emacs, The GNU Emacs Manual}. + +@vindex eww-desktop-remove-duplicates + EWW history may sensibly contain multiple entries for the same page +URI. At run-time, these entries may still have different associated +point positions or the actual Web page contents. +The latter, however, tend to be overly large to preserve in the +desktop file, so they get omitted, thus rendering the respective +entries entirely equivalent. By default, such duplicate entries are +not saved. Setting @code{eww-desktop-remove-duplicates} to nil will +force EWW to save them anyway. + +@vindex eww-restore-desktop + Restoring EWW buffers' contents may prove to take too long to +finish. When the @code{eww-restore-desktop} variable is set to +@code{nil} (the default), EWW will not try to reload the last visited +Web page when the buffer is restored from the desktop file, thus +allowing for faster Emacs start-up times. When set to @code{t}, +restoring the buffers will also initiate the reloading of such pages. + +@vindex eww-restore-reload-prompt + The EWW buffer restored from the desktop file but not yet reloaded +will contain a prompt, as specified by the +@code{eww-restore-reload-prompt} variable. The value of this variable +will be passed through @code{substitute-command-keys} upon each use, +thus allowing for the use of the usual substitutions, such as +@code{\[eww-reload]} for the current key binding of the +@code{eww-reload} command. + @node History and Acknowledgments @appendix History and Acknowledgments @@ -229,6 +291,11 @@ developers started contributing to it as well. @node Variable Index @unnumbered Variable Index +@vindex eww-after-render-hook +After eww has rendered the data in the buffer, +@code{eww-after-render-hook} is called. It can be used to alter the +contents, for instance. + @printindex vr @node Lisp Function Index diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi index 52683a8abfe..31fa1ab26a9 100644 --- a/doc/misc/flymake.texi +++ b/doc/misc/flymake.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @comment %**start of header -@setfilename ../../info/flymake +@setfilename ../../info/flymake.info @set VERSION 0.3 @set UPDATED April 2004 @settitle GNU Flymake @value{VERSION} diff --git a/doc/misc/forms.texi b/doc/misc/forms.texi index e4571d020f5..433009c8719 100644 --- a/doc/misc/forms.texi +++ b/doc/misc/forms.texi @@ -3,7 +3,7 @@ @c Written by Johan Vromans, and edited by Richard Stallman @comment %**start of header (This is for running Texinfo on a region.) -@setfilename ../../info/forms +@setfilename ../../info/forms.info @settitle Forms Mode User's Manual @syncodeindex vr cp @syncodeindex fn cp diff --git a/doc/misc/gnus-coding.texi b/doc/misc/gnus-coding.texi index d1b372fdf99..bbead6b085b 100644 --- a/doc/misc/gnus-coding.texi +++ b/doc/misc/gnus-coding.texi @@ -1,6 +1,6 @@ \input texinfo -@setfilename gnus-coding +@setfilename gnus-coding.info @settitle Gnus Coding Style and Maintenance Guide @documentencoding UTF-8 @syncodeindex fn cp diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi index 0fb77c10d7a..8eb7c771ab7 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? @@ -869,12 +869,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 @@ -1649,7 +1649,7 @@ aren't they and how to fix it? @subsubheading Answer -The message-ID is an unique identifier for messages you +The message-ID is a unique identifier for messages you send. To make it unique, Gnus need to know which machine name to put after the "@@". If the name of the machine where Gnus is running isn't suitable (it probably isn't diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index ff99868a001..cb808743ec2 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -2,7 +2,7 @@ @include gnus-overrides.texi -@setfilename ../../info/gnus +@setfilename ../../info/gnus.info @settitle Gnus Manual @syncodeindex fn cp @syncodeindex vr cp @@ -705,7 +705,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 @@ -2882,12 +2881,17 @@ news group. @item gcc-self @cindex gcc-self If @code{(gcc-self . t)} is present in the group parameter list, newly -composed messages will be @code{Gcc}'d to the current group. If +composed messages will be @code{gcc}d to the current group. If @code{(gcc-self . none)} is present, no @code{Gcc:} header will be -generated, if @code{(gcc-self . "string")} is present, this string will -be inserted literally as a @code{gcc} header. This parameter takes -precedence over any default @code{Gcc} rules as described later -(@pxref{Archived Messages}), with the exception for messages to resend. +generated, if @code{(gcc-self . "group")} is present, this string will +be inserted literally as a @code{Gcc:} header. It should be a group +name. The @code{gcc-self} value may also be a list of strings and +@code{t}, e.g., @code{(gcc-self "group1" "group2" t)} means to +@code{gcc} the newly composed message into the groups @code{"group1"} +and @code{"group2"}, and into the current group. The @code{gcc-self} +parameter takes precedence over any default @code{Gcc} rules as +described later (@pxref{Archived Messages}), with the exception for +messages to resend. @strong{Caveat}: Adding @code{(gcc-self . t)} to the parameter list of @code{nntp} groups (or the like) isn't valid. An @code{nntp} server @@ -9141,9 +9145,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}. @@ -9806,6 +9807,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 @@ -12815,10 +12829,12 @@ variable, which is a vector of the following headers: number subject from date id references chars lines xref extra. In the case of a string value, if the @code{match} is a regular -expression, a @samp{gnus-match-substitute-replacement} is proceed on -the value to replace the positional parameters @samp{\@var{n}} by the -corresponding parenthetical matches (see @xref{Replacing Match,, -Replacing the Text that Matched, elisp, The Emacs Lisp Reference Manual}.) +expression, or if it takes the form @code{(header @var{match} +@var{regexp})}, a @samp{gnus-match-substitute-replacement} is proceed +on the value to replace the positional parameters @samp{\@var{n}} by +the corresponding parenthetical matches (see @xref{Replacing Match,, +Replacing the Text that Matched, elisp, The Emacs Lisp Reference +Manual}.) @vindex message-reply-headers @@ -12850,6 +12866,10 @@ So here's a new example: ;; @r{If I'm replying to Larsi, set the Organization header.} ((header "from" "larsi.*org") (Organization "Somewhere, Inc.")) + ;; @r{Reply to a message from the same subaddress the message} + ;; @r{was sent to.} + ((header "x-original-to" "me\\(\\+.+\\)@@example.org") + (address "me\\1@@example.org")) ((posting-from-work-p) ;; @r{A user defined function} (signature-file "~/.work-signature") (address "user@@bar.foo") @@ -16852,12 +16872,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 @@ -16933,10 +16949,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 @@ -17134,38 +17146,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 @@ -25973,17 +25953,34 @@ the word ``archive'' is not followed. @defvar gnus-registry-max-entries The number (an integer or @code{nil} for unlimited) of entries the -registry will keep. +registry will keep. If the registry has reached or exceeded this +size, it will reject insertion of new entries. @end defvar -@defvar gnus-registry-max-pruned-entries -The maximum number (an integer or @code{nil} for unlimited) of entries -the registry will keep after pruning. +@defvar gnus-registry-prune-factor +This option (a float between 0 and 1) controls how much the registry +is cut back during pruning. In order to prevent constant pruning, the +registry will be pruned back to less than +@code{gnus-registry-max-entries}. This option controls exactly how +much less: the target is calculated as the maximum number of entries +minus the maximum number times this factor. The default is 0.1: +i.e. if your registry is limited to 50000 entries, pruning will try to +cut back to 45000 entries. Entries with keys marked as precious will +not be pruned. +@end defvar + +@defvar gnus-registry-default-sort-function +This option specifies how registry entries are sorted during pruning. +If a function is given, it should sort least valuable entries first, +as pruning starts from the beginning of the list. The default value +is @code{gnus-registry-sort-by-creation-time}, which proposes the +oldest entries for pruning. Set to nil to perform no sorting, which +will speed up the pruning process. @end defvar @defvar gnus-registry-cache-file The file where the registry will be stored between Gnus sessions. By -default the file name is @code{.gnus.registry.eioio} in the same +default the file name is @code{.gnus.registry.eieio} in the same directory as your @code{.newsrc.eld}. @end defvar @@ -26350,7 +26347,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}. @@ -28427,6 +28424,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/htmlfontify.texi b/doc/misc/htmlfontify.texi index 63e2b75559a..630b5f798a1 100644 --- a/doc/misc/htmlfontify.texi +++ b/doc/misc/htmlfontify.texi @@ -1,6 +1,6 @@ \input texinfo @comment %**start of header -@setfilename ../../info/htmlfontify +@setfilename ../../info/htmlfontify.info @settitle Htmlfontify User Manual @exampleindent 2 @documentencoding UTF-8 diff --git a/doc/misc/idlwave.texi b/doc/misc/idlwave.texi index 5c87dc28d7c..1858a51dd81 100644 --- a/doc/misc/idlwave.texi +++ b/doc/misc/idlwave.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/idlwave +@setfilename ../../info/idlwave.info @settitle IDLWAVE User Manual @synindex ky cp @syncodeindex vr cp diff --git a/doc/misc/ido.texi b/doc/misc/ido.texi index f347beb9eac..25380c08bef 100644 --- a/doc/misc/ido.texi +++ b/doc/misc/ido.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@setfilename ../../info/ido +@setfilename ../../info/ido.info @settitle Interactive Do @documentencoding UTF-8 @include emacsver.texi diff --git a/doc/misc/info.texi b/doc/misc/info.texi index 62567ebedd8..759956d21dc 100644 --- a/doc/misc/info.texi +++ b/doc/misc/info.texi @@ -1151,7 +1151,10 @@ switches to the buffer @file{*info*<2>}, creating it if necessary. If you have created many Info buffers in Emacs, you might find it difficult to remember which buffer is showing which manual. You can use the command @kbd{M-x info-display-manual} to show an Info manual -by name, reusing an existing buffer if there is one. +by name, reusing an existing buffer if there is one. When given a +prefix argument, this command limits the completion alternatives to +currently visited info files, thus giving a convenient way to switch +between several manuals. @node Emacs Info Variables @section Emacs Info-mode Variables diff --git a/doc/misc/mairix-el.texi b/doc/misc/mairix-el.texi index f37b242dcb5..5cf9ab01be6 100644 --- a/doc/misc/mairix-el.texi +++ b/doc/misc/mairix-el.texi @@ -1,6 +1,6 @@ \input texinfo.tex -@setfilename ../../info/mairix-el +@setfilename ../../info/mairix-el.info @settitle Emacs Interface for Mairix @documentencoding UTF-8 diff --git a/doc/misc/message.texi b/doc/misc/message.texi index 0a04e88fa9a..6e49c0a347c 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -2,7 +2,7 @@ @include gnus-overrides.texi -@setfilename ../../info/message +@setfilename ../../info/message.info @settitle Message Manual @documentencoding UTF-8 @synindex fn cp @@ -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/mh-e.texi b/doc/misc/mh-e.texi index de32378d770..fc2303c60e1 100644 --- a/doc/misc/mh-e.texi +++ b/doc/misc/mh-e.texi @@ -3,7 +3,7 @@ @c Note: This document requires makeinfo version 4.6 or greater to build. @c @c %**start of header -@setfilename ../../info/mh-e +@setfilename ../../info/mh-e.info @settitle The MH-E Manual @documentencoding UTF-8 @c %**end of header diff --git a/doc/misc/newsticker.texi b/doc/misc/newsticker.texi index 587811c5a88..a9ebc203e31 100644 --- a/doc/misc/newsticker.texi +++ b/doc/misc/newsticker.texi @@ -1,8 +1,8 @@ \input texinfo @c -*-texinfo-*- @comment %**start of header -@setfilename ../../info/newsticker -@set VERSION 1.99 -@set UPDATED June 2008 +@setfilename ../../info/newsticker.info +@include emacsver.texi +@set VERSION @value{EMACSVER} @settitle Newsticker @value{VERSION} @syncodeindex vr cp @syncodeindex fn cp @@ -11,7 +11,8 @@ @comment %**end of header @copying -This manual is for Newsticker (version @value{VERSION}, @value{UPDATED}). +This manual documents Newsticker, a feed reader for Emacs. It +corresponds to Emacs version @value{EMACSVER}. @noindent Copyright @copyright{} 2004--2015 Free Software Foundation, Inc. @@ -31,12 +32,11 @@ modify this GNU manual.'' @dircategory Emacs network features @direntry -* Newsticker: (newsticker). A Newsticker for Emacs. +* Newsticker: (newsticker). A feed reader for Emacs. @end direntry @titlepage -@title Newsticker---a Newsticker for Emacs -@subtitle for version @value{VERSION}, @value{UPDATED} +@title Newsticker---a feed reader for Emacs @author Ulf Jasper @author @email{ulf.jasper@@web.de} @author @uref{http://ulf.epplejasper.de/} @@ -56,136 +56,419 @@ modify this GNU manual.'' @end ifnottex @menu -* Overview:: General description of newsticker. -* Requirements:: Requirements for using newsticker. -* Installation:: Installing newsticker on your system. -* Usage:: Basic newsticker instructions. -* Configuration:: Customizable newsticker settings. -* Remarks:: Remarks about newsticker. +* Overview:: What is Newsticker? +* Installation:: Things to do before starting Newsticker the first time. +* Retrieving News:: How Newsticker fetches headlines. +* Headline Management:: How Newsticker stores headlines. +* Reading News:: How to read RSS and Atom feeds with Newsticker. +* Automatic Processing:: Automatically process news items. +* Configuration:: Customize Newsticker to your liking. +* Supported Formats:: RSS and Atom formats supported by Newsticker. + * GNU Free Documentation License:: The license for this documentation. -* Index:: Variable, function, and concept index. +* Index:: Variable, function, and concept index. @end menu @node Overview @chapter Overview -Newsticker provides a newsticker for Emacs. A newsticker is a thing -that asynchronously retrieves headlines from a list of news sites, -prepares these headlines for reading, and allows for loading the -corresponding articles in a web browser. +Newsticker provides a @b{Feed Reader} for Emacs. It retrieves +headlines from a list of news sites, processes them, and provides +frontends for reading and managing them. (Standard headline formats +are RSS and Atom which makes Newsticker an ``RSS Reader'', ``Atom +Reader'' or ``Feed Aggregator''.) +Headlines (or news items) consist of a title, (mostly) a description, +and a link to the full story. The description may be a brief summary +in plain text or a full HTML-formatted article. A headline may carry +enclosed data such as images, audio or video files, typically in the +case of so ``podcast feeds''. -Headlines consist of a title and (possibly) a small description. They -are contained in ``RSS'' (RDF Site Summary) or ``Atom'' files. Newsticker -works with the following RSS formats: +Newsticker downloads headlines asynchronously at configurable times, +processes and stores them so that you can read them later. The list +of subscribed feeds, the headline processing, the presentation of the +headlines and almost all other aspects of Newsticker can be +customized to your liking. -@itemize -@item RSS 0.91 (see @uref{http://backend.userland.com/rss091} or -@uref{http://my.netscape.com/publish/formats/rss-spec-0.91.html}), -@item RSS 0.92 (see @uref{http://backend.userland.com/rss092}), -@item RSS 1.0 (see @uref{http://purl.org/rss/1.0/spec} -@item RSS 2.0 (see @uref{http://blogs.law.harvard.edu/tech/rss}), -@end itemize -@itemize -as well as the following Atom formats: -@item Atom 0.3 -@item Atom 1.0 (see -@uref{https://datatracker.ietf.org/doc/rfc4287/}). -@end itemize +@node Installation +@chapter Installation -That makes Newsticker.el an ``Atom aggregator'', ``RSS reader'', ``Feed -aggregator'', or ``Feed reader''. +As Newsticker is part of GNU Emacs there is no need to perform any +installation steps in order to use it. -Newsticker provides several commands for reading headlines, navigating -through them, marking them as read/unread, hiding old headlines etc. -Headlines can be displayed as plain text or as rendered HTML. +Newsticker is highly customizable. All options have reasonable default +values, so that (in most cases) it is not necessary to customize +anything before you start Newsticker for the first time. -Headlines can be displayed in the echo area, either scrolling like -messages in a stock-quote ticker, or just changing. - -Newsticker allows for automatic processing of headlines by providing -hooks and (sample) functions for automatically downloading images and -enclosed files (as delivered by, e.g., podcasts). - -@ignore -@ifhtml -Here are screen shots of the @uref{newsticker-1.7.png, version 1.7 -(current version)} and some older screen shots: -@uref{newsticker-1.6.png, version 1.6}, -@uref{newsticker-1.5.png, version 1.5}, -@uref{newsticker-1.4.png, version 1.4} -@uref{newsticker-1.3.png, version 1.3}, -@uref{newsticker-1.0.png, version 1.0}. -@end ifhtml -@end ignore - -@node Requirements -@chapter Requirements - -Newsticker can be used with -@uref{http://www.gnu.org/software/emacs/emacs.html, GNU Emacs} version -21.1 or later as well as @uref{http://www.xemacs.org, XEmacs}. It -requires an XML-parser (@file{xml.el}), which is part of GNU Emacs. If -you are using XEmacs you want to get the @file{net-utils} package -which contains @file{xml.el} for XEmacs. - -Newsticker retrieves headlines either via Emacs's built-in retrieval -functions, by an arbitrary external program that retrieves files via -http and prints them to stdout (like -@uref{http://www.gnu.org/software/wget/wget.html, wget}, or---on a -per feed basis---via an arbitrary Lisp command. +@node Retrieving News +@chapter Retrieving News +Newsticker downloads news periodically in the background. This is +triggered as soon as you start reading news (@ref{Reading News}). -@node Installation -@chapter Installation +@findex newsticker-start +@findex newsticker-stop +Alternatively you may use the command @code{newsticker-start} +(@code{newsticker-stop}) in order to start (stop) the periodic +download of news without opening the reader. -As Newsticker is part of GNU Emacs there is no need to perform any -installation steps in order to use Newsticker. +The following variables define which feeds are fetched and how this is +done. + +@table @code +@vindex newsticker-url-list-defaults +@item newsticker-url-list-defaults +You may select any number of feeds from this list of (sample) news feeds. + +@vindex newsticker-url-list +@item newsticker-url-list +All your personal news feeds are defined here. Each feed is +identified by its name and an URL. You may set the start-time and the +retrieval interval for each feed as well as the retrieval command +arguments in case that the default values do not fit a certain feed. + +@vindex newsticker-retrieval-method +@vindex newsticker-wget-name +@vindex newsticker-wget-arguments +@item newsticker-retrieval-method +By default Newsticker uses Emacs's built-in download capabilities for +fetching headlines. You may change this to use an external tool like +@code{wget}. In this case you need to set @code{newsticker-wget-name} +and possibly @code{newsticker-wget-arguments}. + +@vindex newsticker-retrieval-interval +@item newsticker-retrieval-interval +The number of seconds between headline retrievals. +@end table + +@node Headline Management +@chapter Headline Management + +@cindex Age +@cindex Status + +Newsticker assigns a status (or ``age'') to each headline which you +can modify manually. This makes it easy to distinguish new headlines +from old ones, to keep important headlines, to hide boring headlines +etc. An item is ``new'' when it has just arrived and has not been +read. You can mark it as ``old'' when you have read it or -- if you +want to keep it -- you can mark it as ``immortal''. You can do that +manually and you can define filters which do that automatically, see +below. When a headline has vanished from the feed it is automatically +marked as ``obsolete'' unless it has the status ``immortal''. +``Obsolete'' headlines get removed automatically after a certain time. + +@table @code +@cindex Filter +@vindex newsticker-auto-mark-filter-list +@item newsticker-auto-mark-filter-list +You may define any number of filters for automatically marking newly +arrived headlines as ``immortal'' or ``old''. A filter looks for a +regular expression in either the title or the description of a +headline and then, if the expression matches, marks the headline as +``immortal'' or as ``old''. This is done only once, when a headline +is fetched for the very first time. + +@vindex newsticker-keep-obsolete-items +@vindex newsticker-obsolete-item-max-age +@item newsticker-keep-obsolete-items +Obsolete headlines are removed immediately unless +@code{newsticker-keep-obsolete-items} is non-nil in which case they +are kept until @code{newsticker-obsolete-item-max-age} is reached. + +@vindex newsticker-automatically-mark-items-as-old +@item newsticker-automatically-mark-items-as-old +If this is set to `t' then a ``new'' item becomes ``old'' as soon as +it is retrieved a second time. + +@end table + +@node Reading News +@chapter Reading News + +@findex newsticker-show-news +Start Newsticker with the command @kbd{M-x newsticker-show-news}. This +will start the asynchronous news download and displays all available +headlines. + +@menu +* Frontends:: Select the way headlines are displayed. +* Navigation:: Move to the next unread headline etc. +* Marking:: Mark important headlines. +* More Actions:: Add new feeds etc.. +@end menu + +@node Frontends +@section Frontends +@cindex Frontends + +@vindex newsticker-frontend +Newsticker provides two different @i{views} for browsing, marking and +reading news. The variable @code{newsticker-frontend} determines the +actual headline reader. + +@subheading Treeview +@cindex Treeview + +In this view separate windows are used for displaying feeds, headlines +and their descriptions. The feeds are shown as a tree on the left +hand side, headlines of the currently selected feed are shown on the +upper right side, and the full contents of the currently selected +headline is shown on the lower right side. + +Feeds can be placed into groups, which themselves can be placed in +groups and so on. This results in the tree which is displayed on the +left. A node represents either a feed or a group of feeds holding a +subtree. The following commands allow for managing groups. + +@table @kbd +@item M-a +@kindex M-a +@findex newsticker-group-add-group +Add a new feed group. Name of the new group and of the parent group +must be entered. If The name of the parent group is the new group +becomes a top-level group. (@code{newsticker-group-add-group}) +@item M-m +@kindex M-m +@findex newsticker-group-move-feed +Moves a feed into a group. The name of the group must be +entered. (@code{newsticker-group-move-feed}) +@end table + +The position of groups and feeds within the tree can be changed with these +commands: + +@table @kbd +@item M-up +@itemx M-down +@kindex M-up +@kindex M-down +@findex newsticker-group-shift-feed-up +@findex newsticker-group-shift-feed-down +Shift the currently selected feed up and down within its group. +@item M-S-up +@itemx M-S-down +@kindex M-S-up +@kindex M-S-down +@findex newsticker-group-shift-group-up +@findex newsticker-group-shift-group-down +Shift the currently selected group up and down within its parent group. +@end table + +The group settings are saved to a file either automatically when +newsticker is being quit or manually when the following command is +executed. + +@table @kbd +@item s +@kindex s +@findex newsticker-treeview-save +Save treeview group settings. +@end table + +The Treeview is updated automatically as soon as new headlines have +arrived. + +The Treeview is used when the variable @code{newsticker-frontend} is +set to the value @code{newsticker-treeview}. (Alternatively it can be +started with the command @code{newsticker-treeview}.) + +@subheading Plainview +@cindex Plainview -However, if you are using imenu, which allows for navigating with the -help of a menu, you should add the following to your Emacs startup file -(@file{~/.emacs}). +In this view all headlines of all feeds are displayed in a single +buffer (@file{*newsticker*}). The modeline in the @file{*newsticker*} +buffer informs you whenever new headlines have arrived. + +You may want to use imenu with Plainview, which allows for navigating +with the help of a menu. In this case add the following to your Emacs +startup file (@file{~/.emacs}). @lisp (add-hook 'newsticker-mode-hook 'imenu-add-menubar-index) @end lisp -That's it. +(Note that preparing the Plainview takes significantly more time than +starting the Treeview because all headlines are displayed in a single +buffer. When you have subscribed to a large amount of feeds you may +find that Newsticker's efforts of minimizing rendering times, caching +rendered items and so on you may find However, when you have +subscribed to a large amount of feeds you may want to give the +Treeview a try.) -@node Usage -@chapter Usage +The Plainview is used when the variable @code{newsticker-frontend} is +set to the value @code{newsticker-plainview}. (Alternatively it can be +started with the command @code{newsticker-plainview}.) -@findex newsticker-show-news -The command @code{newsticker-show-news} will display all available -headlines. It will also start the asynchronous download of headlines. +@subheading Ticker +@cindex Ticker -You can choose between two different frontends for reading headlines: -@itemize -@item Newsticker's @emph{treeview} uses separate windows for the -feeds (in tree form), a list of headlines for the current feed, and -the content of the current headline. Feeds can be placed into groups, -which themselves can be placed in groups and so on. -@item Newsticker's @emph{plainview} displays all headlines in a -single buffer, called @file{*newsticker*}. The modeline in the -@file{*newsticker*} buffer informs you whenever new headlines have -arrived. -@end itemize -In both views clicking mouse-button 2 or pressing @key{RET} on a -headline will call @code{browse-url} to load the corresponding news -story in your favorite web browser. +Additionally, headlines can be displayed in the echo area in the style of a +news ticker. @findex newsticker-start-ticker @findex newsticker-stop-ticker -The scrolling, or flashing of headlines in the echo area, can be +Headlines can be displayed in the echo area, either scrolling like +messages in a stock-quote ticker, or just changing. This can be started with the command @code{newsticker-start-ticker}. It can be stopped with @code{newsticker-stop-ticker}. -@findex newsticker-start -@findex newsticker-stop -If you just want to start the periodic download of headlines use the -command @code{newsticker-start}. Calling @code{newsticker-stop} will -stop the periodic download, but will call -@code{newsticker-stop-ticker} as well. + +@node Navigation +@section Navigation +@cindex Navigation + +Navigating through the list of feeds and headlines is rather +straightforward. You may do this either with the mouse or with the +keyboard. The following key bindings are provided in both, the +Treeview as well as the Plainview. + +@table @kbd +@item f +@findex newsticker-next-feed +@findex newsticker-treeview-next-feed +Move to next feed (@code{newsticker-next-feed}, +@code{newsticker-treeview-next-feed}). +@item F +@findex newsticker-previous-feed +@findex newsticker-treeview-prev-feed +Move to previous feed (@code{newsticker-previous-feed}, +@code{newsticker-treeview-prev-feed}). +@item n +@findex newsticker-next-item +@findex newsticker-treeview-next-item +Move to next item (@code{newsticker-next-item}, +@code{newsticker-treeview-next-item}). +@item N +@findex newsticker-next-new-item +@findex newsticker-treeview-next-new-item +Move to next new item (possibly in another feed) +(@code{newsticker-next-new-item}, +@code{newsticker-treeview-next-new-item}). +@item p +@findex newsticker-previous-item +@findex newsticker-treeview-prev-item +Move to previous item (@code{newsticker-previous-item}, +@code{newsticker-treeview-prev-item}). +@item P +@findex newsticker-previous-new-item +@findex newsticker-treeview-prev-new-item +Move to previous new item (possibly in another feed) +(@code{newsticker-previous-new-item}, +@code{newsticker-treeview-prev-new-item}). +@end table + +@subheading Treeview +@table @kbd +@item j +@findex newsticker-treeview-jump +Enter the name of a feed and jump to it +(@code{newsticker-treeview-jump}). +@end table + + +@node Marking +@section Marking +@cindex Marking + +The following key bindings are provided in both, the Treeview as well +as the Plainview. + +@table @kbd +@item o +@findex newsticker-mark-item-at-point-as-read +@findex newsticker-treeview-mark-item-old +Mark current item as old. +(@code{newsticker-mark-item-at-point-as-read}, +@code{newsticker-treeview-mark-item-old}). +@item i +@findex newsticker-mark-item-at-point-as-immortal +@findex newsticker-treeview-mark-item-immortal +Mark current item as immortal. Immortal items are kept forever. +(@code{newsticker-mark-item-at-point-as-immortal}, +@code{newsticker-treeview-mark-item-immortal}). +@end table + +@node More Actions +@section More Actions +@cindex More Actions + +@subheading View full article +@table @kbd +@cindex Get News +@item v +@itemx RET +@itemx <mouse-1> +@findex newsticker-treeview-browse-url +Open the link to the full article (as contained in the current +headline) in your web browser @code{newsticker-treeview-browse-url}). +@end table + +@subheading Get News +@cindex Get News + +You can force immediate download of news with the following commands. + +@table @kbd +@item g +@findex newsticker-treeview-get-news +Get news for currently shown feed (@code{newsticker-treeview-get-news}). +@item G +@findex newsticker-get-all-news +Get news for all feeds (@code{newsticker-get-all-news}). +@end table + +@subheading Add More Feeds +@cindex Add More Feeds + +@table @kbd +@item a +@findex newsticker-add-url +The command @code{newsticker-add-url} prompts for an URL and a name of +a new feed. It then prepares a customization buffer where the details +of the new feed can be set. +@end table + + +@node Automatic Processing +@chapter Automatic Processing +@cindex Automatic Processing + +Apart from automatic marking of headlines (by means of filters) +Newsticker provides the possibility to fully process newly arrived +headlines. Instead of reading headlines yourself you can tell +Newsticker to do that for you. + +@vindex newsticker-new-item-functions +In order to do so write a function which takes three arguments + +@table @var +@item FEED +the name of the corresponding news feed, +@item TITLE +the title of the headline, +@item DESC +the decoded description of the headline. +@end table + +and add it to @code{newsticker-new-item-functions}. Each function +contained in this list is called once for each new headline. +Depending on the feed, the title and the description of a headline you +can + +@itemize +@item +automatically download images referenced in HTML-formatted +descriptions (for which a function already exists, see +@code{newsticker-download-images}), +@item +automatically save enclosed audio and video files (for which another +function exists as well, see @code{newsticker-download-images}), +@item +flash the screen while playing some sound, +@item +whatever you want. +@end itemize @node Configuration @chapter Configuration @@ -195,11 +478,8 @@ Emacs customization methods. Call the command @code{customize-group} and enter @samp{newsticker} for the customization group. -All Newsticker options have reasonable default values, so that in most -cases it is not necessary to customize settings before starting Newsticker -for the first time. - -The following list shows the available groups of newsticker options +@noindent +The following list shows the available groups of Newsticker options and some of the most important options. @itemize @@ -296,13 +576,35 @@ treeview reader. @end itemize +@noindent For the complete list of options please have a look at the customization buffers. -@node Remarks -@chapter Remarks +@node Supported Formats +@appendix Supported Formats +@cindex Supported Formats + +Newsticker works with the standard RSS and Atom formats listed below +(being lenient with feeds which break the specifications). + +@subheading RSS formats + +@itemize +@item RSS 0.91 (see @uref{http://backend.userland.com/rss091} or +@uref{http://my.netscape.com/publish/formats/rss-spec-0.91.html}) +@item RSS 0.92 (see @uref{http://backend.userland.com/rss092}) +@item RSS 1.0 (see @uref{http://purl.org/rss/1.0/spec}) +@item RSS 2.0 (see @uref{http://blogs.law.harvard.edu/tech/rss}) +@end itemize + +@subheading Atom formats + +@itemize +@item Atom 0.3 +@item Atom 1.0 (see +@uref{https://datatracker.ietf.org/doc/rfc4287/}) +@end itemize -Byte-compiling newsticker.el is recommended. @node GNU Free Documentation License @appendix GNU Free Documentation License @@ -310,7 +612,7 @@ Byte-compiling newsticker.el is recommended. @node Index @unnumbered Index - @printindex cp + @bye diff --git a/doc/misc/nxml-mode.texi b/doc/misc/nxml-mode.texi index bf4341f6f7c..d213355b877 100644 --- a/doc/misc/nxml-mode.texi +++ b/doc/misc/nxml-mode.texi @@ -1,6 +1,6 @@ \input texinfo @c -*- texinfo -*- @c %**start of header -@setfilename ../../info/nxml-mode +@setfilename ../../info/nxml-mode.info @settitle nXML Mode @documentencoding UTF-8 @c %**end of header diff --git a/doc/misc/octave-mode.texi b/doc/misc/octave-mode.texi index 5916953233d..b65c5ee380a 100644 --- a/doc/misc/octave-mode.texi +++ b/doc/misc/octave-mode.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/octave-mode +@setfilename ../../info/octave-mode.info @settitle Octave Mode @documentencoding UTF-8 @c %**end of header diff --git a/doc/misc/org.texi b/doc/misc/org.texi index 86335e5f130..2cb80abb0db 100644 --- a/doc/misc/org.texi +++ b/doc/misc/org.texi @@ -1,6 +1,6 @@ \input texinfo @c %**start of header -@setfilename ../../info/org +@setfilename ../../info/org.info @settitle The Org Manual @set VERSION 8.2.9 @@ -5947,7 +5947,7 @@ sep 15 @result{} @b{2006}-09-15 feb 15 @result{} @b{2007}-02-15 sep 12 9 @result{} 2009-09-12 12:45 @result{} @b{2006}-@b{06}-@b{13} 12:45 -22 sept 0:34 @result{} @b{2006}-09-22 0:34 +22 sept 0:34 @result{} @b{2006}-09-22 00:34 w4 @result{} ISO week for of the current year @b{2006} 2012 w4 fri @result{} Friday of ISO week 4 in 2012 2012-w04-5 @result{} Same as above @@ -8122,7 +8122,7 @@ brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are assumed to be date/time specifications in the standard Org way, and the comparison will be done accordingly. Special values that will be recognized are @code{"<now>"} for now (including time), and @code{"<today>"}, and -@code{"<tomorrow>"} for these days at 0:00 hours, i.e., without a time +@code{"<tomorrow>"} for these days at 00:00 hours, i.e., without a time specification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units @code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year, respectively, can be used. @@ -17538,7 +17538,7 @@ The corresponding block writer function could look like this: (defun org-dblock-write:block-update-time (params) (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) (insert "Last block update at: " - (format-time-string fmt (current-time))))) + (format-time-string fmt)))) @end lisp If you want to make sure that all dynamic blocks are always up-to-date, diff --git a/doc/misc/pcl-cvs.texi b/doc/misc/pcl-cvs.texi index 2dd76d75b6c..6970c69c20a 100644 --- a/doc/misc/pcl-cvs.texi +++ b/doc/misc/pcl-cvs.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/pcl-cvs +@setfilename ../../info/pcl-cvs.info @settitle PCL-CVS---Emacs Front-End to CVS @syncodeindex vr fn @documentencoding UTF-8 diff --git a/doc/misc/pgg.texi b/doc/misc/pgg.texi index 1e38c46cc5e..4518de41415 100644 --- a/doc/misc/pgg.texi +++ b/doc/misc/pgg.texi @@ -2,7 +2,7 @@ @include gnus-overrides.texi -@setfilename ../../info/pgg +@setfilename ../../info/pgg.info @set VERSION 0.1 @settitle PGG @value{VERSION} diff --git a/doc/misc/rcirc.texi b/doc/misc/rcirc.texi index 2be82cf732d..f0241f04f8f 100644 --- a/doc/misc/rcirc.texi +++ b/doc/misc/rcirc.texi @@ -1,6 +1,6 @@ \input texinfo @c %**start of header -@setfilename ../../info/rcirc +@setfilename ../../info/rcirc.info @settitle rcirc Manual @documentencoding UTF-8 @c %**end of header diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi index cdbbf08d13a..567063f2c3b 100644 --- a/doc/misc/reftex.texi +++ b/doc/misc/reftex.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/reftex +@setfilename ../../info/reftex.info @settitle RefTeX User Manual @documentencoding UTF-8 @synindex ky cp diff --git a/doc/misc/remember.texi b/doc/misc/remember.texi index 5690a120e73..ff481b746c1 100644 --- a/doc/misc/remember.texi +++ b/doc/misc/remember.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/remember +@setfilename ../../info/remember.info @settitle Remember Manual @syncodeindex fn cp @documentencoding UTF-8 diff --git a/doc/misc/sasl.texi b/doc/misc/sasl.texi index be486d9e574..f6f0a98ba62 100644 --- a/doc/misc/sasl.texi +++ b/doc/misc/sasl.texi @@ -2,7 +2,7 @@ @include gnus-overrides.texi -@setfilename ../../info/sasl +@setfilename ../../info/sasl.info @set VERSION 0.2 @settitle Emacs SASL Library @value{VERSION} diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi index 50c3349e691..a97e504cb28 100644 --- a/doc/misc/sc.texi +++ b/doc/misc/sc.texi @@ -1,7 +1,7 @@ \input texinfo @comment -*-texinfo-*- @comment 3.48 @comment %**start of header (This is for running Texinfo on a region.) -@setfilename ../../info/sc +@setfilename ../../info/sc.info @settitle Supercite User's Manual @documentencoding UTF-8 @iftex diff --git a/doc/misc/semantic.texi b/doc/misc/semantic.texi index 6b820ee2ca3..090724056a6 100644 --- a/doc/misc/semantic.texi +++ b/doc/misc/semantic.texi @@ -1,5 +1,5 @@ \input texinfo -@setfilename ../../info/semantic +@setfilename ../../info/semantic.info @set TITLE Semantic Manual @set AUTHOR Eric M. Ludlam, David Ponce, and Richard Y. Kim @settitle @value{TITLE} diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi index f49fac578ad..068505089a3 100644 --- a/doc/misc/ses.texi +++ b/doc/misc/ses.texi @@ -1,6 +1,6 @@ \input texinfo @c -*- mode: texinfo; coding: utf-8; -*- @c %**start of header -@setfilename ../../info/ses +@setfilename ../../info/ses.info @settitle @acronym{SES}: Simple Emacs Spreadsheet @setchapternewpage off @syncodeindex fn cp @@ -435,6 +435,13 @@ Centering with dashes and spill-over. Centering with tildes (~) and spill-over. @end table +You can define printer function local to a sheet with command +@code{ses-define-local-printer}. For instance define printer +@samp{foo} to @code{"%.2f"} and then use symbol @samp{foo} as a +printer function. Then, if you call again +@code{ses-define-local-printer} on @samp{foo} to redefine it as +@code{"%.3f"} all the cells using printer @samp{foo} will be reprinted +accordingly. @node Clearing cells @section Clearing cells diff --git a/doc/misc/sieve.texi b/doc/misc/sieve.texi index 670630904b7..ca965e66bdd 100644 --- a/doc/misc/sieve.texi +++ b/doc/misc/sieve.texi @@ -2,7 +2,7 @@ @include gnus-overrides.texi -@setfilename ../../info/sieve +@setfilename ../../info/sieve.info @settitle Emacs Sieve Manual @documentencoding UTF-8 @synindex fn cp diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi index 893c935dadb..314e6a03abc 100644 --- a/doc/misc/smtpmail.texi +++ b/doc/misc/smtpmail.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@setfilename ../../info/smtpmail +@setfilename ../../info/smtpmail.info @settitle Emacs SMTP Library @documentencoding UTF-8 @syncodeindex vr fn @@ -368,7 +368,7 @@ implement support for common requirements. @vindex smtpmail-local-domain The variable @code{smtpmail-local-domain} controls the hostname sent in the first @code{EHLO} or @code{HELO} command sent to the server. -It should only be set if the @code{system-name} function returns a +It should be set only if the @code{system-name} function returns a name that isn't accepted by the server. Do not set this variable unless your server complains. diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi index 5915c6b414b..726f749e05e 100644 --- a/doc/misc/speedbar.texi +++ b/doc/misc/speedbar.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@setfilename ../../info/speedbar +@setfilename ../../info/speedbar.info @settitle Speedbar: File/Tag summarizing utility @documentencoding UTF-8 @syncodeindex fn cp diff --git a/doc/misc/srecode.texi b/doc/misc/srecode.texi index 534cdea314d..b58cc4a204f 100644 --- a/doc/misc/srecode.texi +++ b/doc/misc/srecode.texi @@ -1,6 +1,6 @@ \input texinfo @c %**start of header -@setfilename ../../info/srecode +@setfilename ../../info/srecode.info @set TITLE SRecoder Manual @set AUTHOR Eric M. Ludlam @settitle @value{TITLE} @@ -1191,7 +1191,7 @@ If there is an active region via @code{transient-mark-mode}, or @code{mouse-drag-region}, then the @code{REGION} section will be enabled. -In addition, @code{REGIONTEXT} will be set the the text in the region, +In addition, @code{REGIONTEXT} will be set to the text in the region, and that region of text will be ``killed'' from the current buffer. If standard-output is NOT the current buffer, then the region will not diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index 0f2673c849e..370d4505084 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-12-03.16} % % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, @@ -96,7 +96,9 @@ \let\ptexraggedright=\raggedright \let\ptexrbrace=\} \let\ptexslash=\/ +\let\ptexsp=\sp \let\ptexstar=\* +\let\ptexsup=\sup \let\ptext=\t \let\ptextop=\top {\catcode`\'=\active \global\let\ptexquoteright'}% active in plain's math mode @@ -1010,24 +1012,15 @@ where each line of input produces a line of output.} % paragraph. % \gdef\dosuppressfirstparagraphindent{% - \gdef\indent{% - \restorefirstparagraphindent - \indent - }% - \gdef\noindent{% - \restorefirstparagraphindent - \noindent - }% - \global\everypar = {% - \kern -\parindent - \restorefirstparagraphindent - }% + \gdef\indent {\restorefirstparagraphindent \indent}% + \gdef\noindent{\restorefirstparagraphindent \noindent}% + \global\everypar = {\kern -\parindent \restorefirstparagraphindent}% } - +% \gdef\restorefirstparagraphindent{% - \global \let \indent = \ptexindent - \global \let \noindent = \ptexnoindent - \global \everypar = {}% + \global\let\indent = \ptexindent + \global\let\noindent = \ptexnoindent + \global\everypar = {}% } @@ -2090,12 +2083,9 @@ end \endgroup } - % In order for the font changes to affect most math symbols and letters, -% we have to define the \textfont of the standard families. Since -% texinfo doesn't allow for producing subscripts and superscripts except -% in the main text, we don't bother to reset \scriptfont and -% \scriptscriptfont (which would also require loading a lot more fonts). +% we have to define the \textfont of the standard families. We don't +% bother to reset \scriptfont and \scriptscriptfont; awaiting user need. % \def\resetmathfonts{% \textfont0=\tenrm \textfont1=\teni \textfont2=\tensy @@ -2109,8 +2099,8 @@ end % \tenSTYLE to set the current font. % % Each font-changing command also sets the names \lsize (one size lower) -% and \lllsize (three sizes lower). These relative commands are used in -% the LaTeX logo and acronyms. +% and \lllsize (three sizes lower). These relative commands are used +% in, e.g., the LaTeX logo and acronyms. % % This all needs generalizing, badly. % @@ -2146,7 +2136,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 @@ -2851,6 +2841,8 @@ end \let\v=\check \let\~=\tilde \let\dotaccent=\dot + % have to provide another name for sup operator + \let\mathopsup=\sup $\finishmath } \def\finishmath#1{#1$\endgroup} % Close the group opened by \tex. @@ -2874,6 +2866,18 @@ end } } +% for @sub and @sup, if in math mode, just do a normal sub/superscript. +% If in text, use math to place as sub/superscript, but switch +% into text mode, with smaller fonts. This is a different font than the +% one used for real math sub/superscripts (8pt vs. 7pt), but let's not +% fix it (significant additions to font machinery) until someone notices. +% +\def\sub{\ifmmode \expandafter\sb \else \expandafter\finishsub\fi} +\def\finishsub#1{$\sb{\hbox{\selectfonts\lllsize #1}}$}% +% +\def\sup{\ifmmode \expandafter\ptexsp \else \expandafter\finishsup\fi} +\def\finishsup#1{$\ptexsp{\hbox{\selectfonts\lllsize #1}}$}% + % ctrl is no longer a Texinfo command, but leave this definition for fun. \def\ctrl #1{{\tt \rawbackslash \hat}#1} @@ -5739,13 +5743,16 @@ end % % #1 is the text, #2 is the section type (Ynumbered, Ynothing, % Yappendix, Yomitfromtoc), #3 the chapter number. +% Not used for @heading series. % % To test against our argument. \def\Ynothingkeyword{Ynothing} -\def\Yomitfromtockeyword{Yomitfromtoc} \def\Yappendixkeyword{Yappendix} +\def\Yomitfromtockeyword{Yomitfromtoc} % \def\chapmacro#1#2#3{% + \checkenv{}% chapters, etc., should not start inside an environment. + % % Insert the first mark before the heading break (see notes for \domark). \let\prevchapterdefs=\lastchapterdefs \let\prevsectiondefs=\lastsectiondefs @@ -5798,6 +5805,7 @@ end % {% \chapfonts \rmisbold + \let\footnote=\errfootnoteheading % give better error message % % Have to define \lastsection before calling \donoderef, because the % xref code eventually uses it. On the other hand, it has to be called @@ -5891,22 +5899,29 @@ end % Print any size, any type, section title. % -% #1 is the text, #2 is the section level (sec/subsec/subsubsec), #3 is -% the section type for xrefs (Ynumbered, Ynothing, Yappendix), #4 is the -% section number. +% #1 is the text of the title, +% #2 is the section level (sec/subsec/subsubsec), +% #3 is the section type (Ynumbered, Ynothing, Yappendix, Yomitfromtoc), +% #4 is the section number. % \def\seckeyword{sec} % \def\sectionheading#1#2#3#4{% {% - \checkenv{}% should not be in an environment. + \def\sectionlevel{#2}% + \def\temptype{#3}% + % + % It is ok for the @heading series commands to appear inside an + % environment (it's been historically allowed, though the logic is + % dubious), but not the others. + \ifx\temptype\Yomitfromtockeyword\else + \checkenv{}% non-@*heading should not be in an environment. + \fi + \let\footnote=\errfootnoteheading % % Switch to the right set of fonts. \csname #2fonts\endcsname \rmisbold % - \def\sectionlevel{#2}% - \def\temptype{#3}% - % % Insert first mark before the heading break (see notes for \domark). \let\prevsectiondefs=\lastsectiondefs \ifx\temptype\Ynothingkeyword @@ -6333,6 +6348,7 @@ end % other math active characters (just in case), to plain's definitions. \mathactive % + % Inverse of the list at the beginning of the file. \let\b=\ptexb \let\bullet=\ptexbullet \let\c=\ptexc @@ -6348,7 +6364,9 @@ end \let\+=\tabalign \let\}=\ptexrbrace \let\/=\ptexslash + \let\sp=\ptexsp \let\*=\ptexstar + %\let\sup=\ptexsup % do not redefine, we want @sup to work in math mode \let\t=\ptext \expandafter \let\csname top\endcsname=\ptextop % we've made it outer \let\frenchspacing=\plainfrenchspacing @@ -7414,7 +7432,6 @@ end % % \anythingelse will almost certainly be an error of some kind. - % \mbodybackslash is the definition of \ in @macro bodies. % It maps \foo\ => \csname macarg.foo\endcsname => #N % where N is the macro parameter number. @@ -7523,8 +7540,7 @@ end % the catcode regime underwhich the body was input). % % If you compile with TeX (not eTeX), and you have macros with 10 or more -% arguments, you need that no macro has more than 256 arguments, otherwise an -% error is produced. +% arguments, no macro can have more than 256 arguments (else error). \def\parsemargdef#1;{% \paramno=0\def\paramlist{}% \let\hash\relax @@ -8359,9 +8375,6 @@ end % % Auto-number footnotes. Otherwise like plain. \gdef\footnote{% - \let\indent=\ptexindent - \let\noindent=\ptexnoindent - % \global\advance\footnoteno by \@ne \edef\thisfootno{$^{\the\footnoteno}$}% % @@ -8388,7 +8401,7 @@ end % % Nested footnotes are not supported in TeX, that would take a lot % more work. (\startsavinginserts does not suffice.) - \let\footnote=\errfootnote + \let\footnote=\errfootnotenest % % We want to typeset this text as a normal paragraph, even if the % footnote reference occurs in (for example) a display environment. @@ -8427,12 +8440,17 @@ end } }%end \catcode `\@=11 -\def\errfootnote{% +\def\errfootnotenest{% \errhelp=\EMsimple \errmessage{Nested footnotes not supported in texinfo.tex, even though they work in makeinfo; sorry} } +\def\errfootnoteheading{% + \errhelp=\EMsimple + \errmessage{Footnotes in chapters, sections, etc., are not supported} +} + % In case a @footnote appears in a vbox, save the footnote text and create % the real \insert just after the vbox finished. Otherwise, the insertion % would be lost. @@ -8856,20 +8874,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. @@ -9279,6 +9297,18 @@ directory should work if nowhere else does.} \UTFviiiLoop \endgroup +\def\globallet{\global\let} % save some \expandafter's below + +% @U{xxxx} to produce U+xxxx, if we support it. +\def\U#1{% + \expandafter\ifx\csname uni:#1\endcsname \relax + \errhelp = \EMsimple + \errmessage{Unicode character U+#1 not supported, sorry}% + \else + \csname uni:#1\endcsname + \fi +} + \begingroup \catcode`\"=12 \catcode`\<=12 @@ -9287,7 +9317,6 @@ directory should work if nowhere else does.} \catcode`\;=12 \catcode`\!=12 \catcode`\~=13 - \gdef\DeclareUnicodeCharacter#1#2{% \countUTFz = "#1\relax %\wlog{\space\space defining Unicode char U+#1 (decimal \the\countUTFz)}% @@ -9302,6 +9331,8 @@ directory should work if nowhere else does.} \expandafter\expandafter\expandafter\expandafter \expandafter\expandafter\expandafter \gdef\UTFviiiTmp{#2}% + % define an additional control sequence for this code point. + \expandafter\globallet\csname uni:#1\endcsname \UTFviiiTmp \endgroup} \gdef\parseXMLCharref{% diff --git a/doc/misc/todo-mode.texi b/doc/misc/todo-mode.texi index bad9afacba2..6f684dea5d5 100644 --- a/doc/misc/todo-mode.texi +++ b/doc/misc/todo-mode.texi @@ -1,6 +1,6 @@ \input texinfo.tex @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/todo-mode +@setfilename ../../info/todo-mode.info @settitle Todo Mode User Manual @syncodeindex fn cp @syncodeindex vr cp @@ -158,7 +158,7 @@ you want. All todo files reside in a single directory, whose location is specified by the user option @code{todo-directory}. This directory may also contain other types of Todo files, which are discussed later -(@pxref{Todo Archive Mode} and @ref{Todo Filtered Items Mode}). +(@pxref{Todo Archive Mode} and @ref{Todo Filtered Items Mode}). @c Emacs recognizes Todo files by their extension, so when you visit @c the files the buffer is in the appropriate mode and the current @c category is correctly displayed. diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 503bf8b94d1..bc7f9331874 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@setfilename ../../info/tramp +@setfilename ../../info/tramp.info @c %**start of header @settitle TRAMP User Manual @documentencoding UTF-8 @@ -2711,6 +2711,21 @@ following code in your @file{.emacs}: (setq tramp-remote-process-environment process-environment)) @end lisp +When running @code{process-file} or @code{start-file-process} on a +remote @code{default-directory}, the default settings in +@code{process-environment} are not used as it is the case for local +processes. However, if you need environment variables other than set +in @code{tramp-remote-process-environment}, you can let-bind them to +@code{process-environment}. Only those variables will be set then: + +@lisp +(let ((process-environment (cons "HGPLAIN=1" process-environment))) + (process-file @dots{})) +@end lisp + +This works only for environment variables which are not set already in +@code{process-environment}. + If you use other @value{emacsname} packages which do not run out-of-the-box on a remote host, please let us know. We will try to integrate them as well. @xref{Bug Reports}. @@ -2828,7 +2843,7 @@ uid=0(root) gid=0(root) groups=0(root) @cindex gdb @cindex perldb -@file{gud.el} offers an unified interface to several symbolic +@file{gud.el} offers a unified interface to several symbolic debuggers @ifset emacs @ifinfo diff --git a/doc/misc/url.texi b/doc/misc/url.texi index 4b97fa64b71..a1fa31fe6ce 100644 --- a/doc/misc/url.texi +++ b/doc/misc/url.texi @@ -1,5 +1,5 @@ \input texinfo -@setfilename ../../info/url +@setfilename ../../info/url.info @settitle URL Programmer's Manual @documentencoding UTF-8 diff --git a/doc/misc/vhdl-mode.texi b/doc/misc/vhdl-mode.texi new file mode 100644 index 00000000000..524a534c38d --- /dev/null +++ b/doc/misc/vhdl-mode.texi @@ -0,0 +1,1022 @@ +\input texinfo @c -*- texinfo -*- + +@setfilename ../../info/vhdl-mode.info +@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, 2015 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 components 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 statements +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 offsets 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 tweaked 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 diff --git a/doc/misc/vip.texi b/doc/misc/vip.texi index 7d435609e51..9a5255d43af 100644 --- a/doc/misc/vip.texi +++ b/doc/misc/vip.texi @@ -1,5 +1,5 @@ \input texinfo -@setfilename ../../info/vip +@setfilename ../../info/vip.info @settitle VIP @documentencoding UTF-8 diff --git a/doc/misc/viper.texi b/doc/misc/viper.texi index 1aa87a1eb17..bea7f47edbb 100644 --- a/doc/misc/viper.texi +++ b/doc/misc/viper.texi @@ -4,7 +4,7 @@ @comment Using viper.info instead of viper in setfilename breaks DOS. @comment @setfilename viper @comment @setfilename viper.info -@setfilename ../../info/viper +@setfilename ../../info/viper.info @documentencoding UTF-8 diff --git a/doc/misc/widget.texi b/doc/misc/widget.texi index 963fad1c5ca..6d5b6d37afd 100644 --- a/doc/misc/widget.texi +++ b/doc/misc/widget.texi @@ -1,6 +1,6 @@ \input texinfo.tex @c %**start of header -@setfilename ../../info/widget +@setfilename ../../info/widget.info @settitle The Emacs Widget Library @syncodeindex fn cp @syncodeindex vr cp diff --git a/doc/misc/wisent.texi b/doc/misc/wisent.texi index 0d4e11666d9..16b5d122df1 100644 --- a/doc/misc/wisent.texi +++ b/doc/misc/wisent.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/wisent +@setfilename ../../info/wisent.info @set TITLE Wisent Parser Development @set AUTHOR Eric M. Ludlam, David Ponce, and Richard Y. Kim @settitle @value{TITLE} diff --git a/doc/misc/woman.texi b/doc/misc/woman.texi index fe16dc5f95b..d199afcf99f 100644 --- a/doc/misc/woman.texi +++ b/doc/misc/woman.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename ../../info/woman +@setfilename ../../info/woman.info @settitle WoMan: Browse Unix Manual Pages ``W.O. (without) Man'' @include emacsver.texi @afourpaper |