From 805204f3efdf3e9cb3ccd2783b7ba44f8c1fdb5a Mon Sep 17 00:00:00 2001 From: Lars Ingebrigtsen Date: Tue, 3 May 2016 00:02:50 +0200 Subject: Mention what a missing :group does * doc/lispref/customize.texi (Common Keywords): Document that a missing :group reuses the group from the preceding item (bug#21601). --- doc/lispref/customize.texi | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index 14e6eb3ab25..de130d57d30 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -66,9 +66,13 @@ cause confusion.} @kindex group@r{, customization keyword} @item :group @var{group} -Put this customization item in group @var{group}. When you use -@code{:group} in a @code{defgroup}, it makes the new group a subgroup of -@var{group}. +Put this customization item in group @var{group}. If this keyword is +missing from a customization item, it'll be placed in the same group +as the previous customization item that had a @code{:group} spec (in +the same file). + +When you use @code{:group} in a @code{defgroup}, it makes the new +group a subgroup of @var{group}. If you use this keyword more than once, you can put a single item into more than one group. Displaying any of those groups will show this -- cgit v1.2.1 From 2ea2a2f1a5b5b2e1b20f1ee8c86058334d0a2652 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Tue, 3 May 2016 08:02:16 -0700 Subject: Doc fixes for quoting * doc/emacs/text.texi, doc/lispintro/emacs-lisp-intro.texi: * doc/lispref/control.texi, doc/lispref/display.texi: * doc/lispref/help.texi, doc/lispref/strings.texi, lisp/subr.el: * src/callint.c, src/doprnt.c, src/editfns.c: Document quoting a bit more systematically. Problem reported by Alan Mackenzie (Bug#23425). --- doc/emacs/text.texi | 4 ++-- doc/lispintro/emacs-lisp-intro.texi | 28 +++++++++++----------------- doc/lispref/control.texi | 10 ++++++---- doc/lispref/display.texi | 10 ++++++---- doc/lispref/help.texi | 4 ++++ doc/lispref/strings.texi | 10 ++++++++-- 6 files changed, 37 insertions(+), 29 deletions(-) (limited to 'doc') diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi index 66f01b495d1..579f7880cfe 100644 --- a/doc/emacs/text.texi +++ b/doc/emacs/text.texi @@ -862,8 +862,8 @@ indenting the current line. @xref{Indentation}, for details. Text mode turns off the features concerned with comments except when you explicitly invoke them. It changes the syntax table so that -single-quotes are considered part of words (e.g., @samp{don't} is -considered one word). However, if a word starts with a single-quote, +apostrophes are considered part of words (e.g., @samp{don't} is +considered one word). However, if a word starts with an apostrophe, it is treated as a prefix for the purposes of capitalization (e.g., @kbd{M-c} converts @samp{'hello'} into @samp{'Hello'}, as expected). diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 78c1865703e..eea46af6b19 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -1004,11 +1004,11 @@ the name stands for ``Lots of Isolated Silly Parentheses''. But the claim is unwarranted. Lisp stands for LISt Processing, and the programming language handles @emph{lists} (and lists of lists) by putting them between parentheses. The parentheses mark the boundaries -of the list. Sometimes a list is preceded by a single apostrophe or -quotation mark, @samp{'}@footnote{The single apostrophe or quotation -mark is an abbreviation for the function @code{quote}; you need not -think about functions now; functions are defined in @ref{Making -Errors, , Generate an Error Message}.} Lists are the basis of Lisp. +of the list. Sometimes a list is preceded by an apostrophe @samp{'}, +called a @dfn{single-quote} in Lisp.@footnote{A single-quote is an +abbreviation for the special form @code{quote}; you need not think +about special forms now. @xref{Complications}.} Lists are the basis +of Lisp. @menu * Lisp Lists:: What are lists? @@ -2490,14 +2490,7 @@ in the list and then at the function definition bound to that symbol. Then the instructions in the function definition are carried out. @item -A single quotation mark, -@ifinfo -' -@end ifinfo -@ifnotinfo -@code{'} -@end ifnotinfo -, tells the Lisp interpreter that it should +A single-quote @samp{'} tells the Lisp interpreter that it should return the following expression as written, and not evaluate it as it would if the quote were not there. @@ -7610,7 +7603,8 @@ displays in which grave accent and apostrophe were often mirror images suitable for use as quotes. On most modern displays this is no longer true, and when these two ASCII characters appear in documentation strings or diagnostic message formats, Emacs typically transliterates -them to curved single quotes, so that the abovequoted symbol appears +them to @dfn{curved quotes} (left and right single quotation marks), +so that the abovequoted symbol appears as @t{‘case-fold-search’}. Source-code strings can also simply use curved quotes directly. @@ -17117,7 +17111,7 @@ This line is a short, but complete Emacs Lisp expression. We are already familiar with @code{setq}. It sets the following variable, @code{major-mode}, to the subsequent value, which is @code{text-mode}. -The single quote mark before @code{text-mode} tells Emacs to deal directly +The single-quote before @code{text-mode} tells Emacs to deal directly with the @code{text-mode} symbol, not with whatever it might stand for. @xref{set & setq, , Setting the Value of a Variable}, for a reminder of how @code{setq} works. @@ -17284,11 +17278,11 @@ Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for details.) The command invoked by the keys is @code{compare-windows}. Note that -@code{compare-windows} is preceded by a single quote; otherwise, Emacs +@code{compare-windows} is preceded by a single-quote; otherwise, Emacs would first try to evaluate the symbol to determine its value. These three things, the double quotation marks, the backslash before -the @samp{C}, and the single quote mark are necessary parts of +the @samp{C}, and the single-quote are necessary parts of keybinding that I tend to forget. Fortunately, I have come to remember that I should look at my existing @file{.emacs} file, and adapt what is there. diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 3f48c458c02..75d8d284623 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1100,10 +1100,12 @@ These examples show typical uses of @code{error}: error symbol @code{error}, and a list containing the string returned by @code{format-message}. -In a format string containing single quotes, curved quotes @t{‘like -this’} and grave quotes @t{`like this'} work better than straight -quotes @t{'like this'}, as @code{error} typically formats every -straight quote as a curved closing quote. +A format that quotes with grave accents and apostrophes @t{`like +this'} typically generates curved quotes @t{‘like this’}. In +contrast, a format that quotes with only apostrophes @t{'like this'} +typically generates two closing curved quotes @t{’like this’}, an +unusual style in English. @xref{Keys in Documentation}, for how the +@code{text-quoting-style} variable affects generated quotes. @strong{Warning:} If you want to use your own string as an error message verbatim, don't just write @code{(error @var{string})}. If @var{string} diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index c80f78c0e3b..b0cd8731fe2 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -265,10 +265,12 @@ properties, it is displayed with the specified faces (@pxref{Faces}). The string is also added to the @file{*Messages*} buffer, but without text properties (@pxref{Logging Messages}). -In a format string containing single quotes, curved quotes @t{‘like -this’} and grave quotes @t{`like this'} work better than straight -quotes @t{'like this'}, as @code{message} typically formats every -straight quote as a curved closing quote. +A format that quotes with grave accents and apostrophes @t{`like +this'} typically generates curved quotes @t{‘like this’}. In +contrast, a format that quotes with only apostrophes @t{'like this'} +typically generates two closing curved quotes @t{’like this’}, an +unusual style in English. @xref{Keys in Documentation}, for how the +@code{text-quoting-style} variable affects generated quotes. In batch mode, the message is printed to the standard error stream, followed by a newline. diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 58a11f29a4c..b945e438f55 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -335,10 +335,14 @@ specifies @var{mapvar}'s value as the keymap for any following @item ‘ @itemx ` (left single quotation mark and grave accent) both stand for a left quote. +This generates a left single quotation mark, an apostrophe, or a grave +accent depending on the value of @code{text-quoting-style}. @item ’ @itemx ' (right single quotation mark and apostrophe) both stand for a right quote. +This generates a right single quotation mark or an apostrophe +depending on the value of @code{text-quoting-style}. @item \= quotes the following character and is discarded; thus, @samp{\=`} puts diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 9d6613c522c..c6563f7e03c 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -834,8 +834,14 @@ if any. This function acts like @code{format}, except it also converts any curved single quotes in @var{string} as per the value of @code{text-quoting-style}, and treats grave accent (@t{`}) and -apostrophe (@t{'}) as if they were curved single quotes. @xref{Keys -in Documentation}. +apostrophe (@t{'}) as if they were curved single quotes. + +A format that quotes with grave accents and apostrophes @t{`like +this'} typically generates curved quotes @t{‘like this’}. In +contrast, a format that quotes with only apostrophes @t{'like this'} +typically generates two closing curved quotes @t{’like this’}, an +unusual style in English. @xref{Keys in Documentation}, for how the +@code{text-quoting-style} variable affects generated quotes. @end defun @cindex @samp{%} in format -- cgit v1.2.1 From 79e58003aa91ea1273f2588c3891a6ad9c5d282e Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Tue, 3 May 2016 19:14:31 +0300 Subject: Improve documentation of Dired's 'A' and 'Q' commands * lisp/dired-aux.el (dired-do-find-regexp) (dired-do-find-regexp-and-replace): Mention 'grep-find-ignored-files' and 'vc-directory-exclusion-list', and also the fact that REGEXP should be palatable by Grep. (Bug#23426) * lisp/dired.el: Update the corresponding autoload forms. * doc/emacs/dired.texi (Operating on Files): Mention 'grep-find-ignored-files' and 'vc-directory-exclusion-list'. (Bug#23429) --- doc/emacs/dired.texi | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'doc') diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index 089b1091618..aa717dfad54 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -795,6 +795,14 @@ This command is a variant of @code{xref-find-references} where you can navigate between matches and display them as needed using the commands described in @ref{Xref Commands}. +@vindex grep-find-ignored-files @r{(Dired)} +@vindex vc-directory-exclusion-list @r{(Dired)} +If any of the marked files are directories, then this command searches +all of the files in those directories, and any of their +subdirectories, recursively, except files whose names match +@code{grep-find-ignored-files} and subdirectories whose names match +@code{vc-directory-exclusion-list}. + @kindex Q @r{(Dired)} @findex dired-do-find-regexp-and-replace @cindex search and replace in multiple files (in Dired) @@ -809,6 +817,12 @@ and you can use the special commands in that buffer (@pxref{Xref Commands}). In particular, if you exit the query replace loop, you can use @kbd{r} in that buffer to replace more matches. @xref{Identifier Search}. + +Like with @code{dired-do-find-regexp}, if any of the marked files are +directories, this command performs replacements in all of the files in +those directories, and in any of their subdirectories, recursively, +except for files whose names match @code{grep-find-ignored-files} and +subdirectories whose names match @code{vc-directory-exclusion-list}. @end table @node Shell Commands in Dired -- cgit v1.2.1 From 93703c547a96bc257d4e4c1ae4c84e60cf217810 Mon Sep 17 00:00:00 2001 From: Lars Ingebrigtsen Date: Tue, 3 May 2016 19:06:13 +0200 Subject: (Common Keywords): Correct what missing :group means * doc/lispref/customize.texi (Common Keywords): Correct what missing :group means. --- doc/lispref/customize.texi | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index de130d57d30..4a6f7f2162b 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -68,8 +68,7 @@ cause confusion.} @item :group @var{group} Put this customization item in group @var{group}. If this keyword is missing from a customization item, it'll be placed in the same group -as the previous customization item that had a @code{:group} spec (in -the same file). +that was last defined (in the current file). When you use @code{:group} in a @code{defgroup}, it makes the new group a subgroup of @var{group}. -- cgit v1.2.1 From 6428aa044ad872e9b8b60d825b7cbcb38ae3e492 Mon Sep 17 00:00:00 2001 From: Dmitry Gutov Date: Wed, 4 May 2016 01:02:43 +0300 Subject: Use grep-find-ignored-directories instead of vc-directory-exclusion-list * lisp/dired-aux.el (dired-do-find-regexp): Use grep-find-ignored-directories instead of vc-directory-exclusion-list. The result should be functionally similar (the former uses the latter as the default value), but it should be more consistent and appropriate WRT user customizations. (dired-do-find-regexp-and-replace): Update the docstring. * lisp/dired.el: Update the corresponding autoloads. * doc/emacs/dired.texi (Operating on Files): Update the documentation accordingly. --- doc/emacs/dired.texi | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index aa717dfad54..1b10ebc8758 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -796,12 +796,12 @@ where you can navigate between matches and display them as needed using the commands described in @ref{Xref Commands}. @vindex grep-find-ignored-files @r{(Dired)} -@vindex vc-directory-exclusion-list @r{(Dired)} +@vindex grep-find-ignored-directories @r{(Dired)} If any of the marked files are directories, then this command searches all of the files in those directories, and any of their subdirectories, recursively, except files whose names match @code{grep-find-ignored-files} and subdirectories whose names match -@code{vc-directory-exclusion-list}. +@code{grep-find-ignored-directories}. @kindex Q @r{(Dired)} @findex dired-do-find-regexp-and-replace @@ -822,7 +822,7 @@ Like with @code{dired-do-find-regexp}, if any of the marked files are directories, this command performs replacements in all of the files in those directories, and in any of their subdirectories, recursively, except for files whose names match @code{grep-find-ignored-files} and -subdirectories whose names match @code{vc-directory-exclusion-list}. +subdirectories whose names match @code{grep-find-ignored-directories}. @end table @node Shell Commands in Dired -- cgit v1.2.1 From 5e814e02f0b0b85fa486975eced09e4a7ed8ce5c Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Thu, 5 May 2016 06:39:17 -0700 Subject: Minor doc fixes for quoting * doc/lispref/control.texi (Signaling Errors): * doc/lispref/display.texi (Displaying Messages): Don’t say that formats “generate”. Try to word more clearly. * etc/NEWS: Coalesce near-duplicate entries. --- doc/lispref/control.texi | 13 +++++++------ doc/lispref/display.texi | 13 +++++++------ 2 files changed, 14 insertions(+), 12 deletions(-) (limited to 'doc') diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 75d8d284623..0cdb03548bf 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1100,12 +1100,13 @@ These examples show typical uses of @code{error}: error symbol @code{error}, and a list containing the string returned by @code{format-message}. -A format that quotes with grave accents and apostrophes @t{`like -this'} typically generates curved quotes @t{‘like this’}. In -contrast, a format that quotes with only apostrophes @t{'like this'} -typically generates two closing curved quotes @t{’like this’}, an -unusual style in English. @xref{Keys in Documentation}, for how the -@code{text-quoting-style} variable affects generated quotes. +The @code{text-quoting-style} variable controls what quotes are +generated; @xref{Keys in Documentation}. A call using a format like +@t{"Missing `%s'"} with grave accents and apostrophes typically +generates a message like @t{"Missing ‘foo’"} with matching curved +quotes. In contrast, a call using a format like @t{"Missing '%s'"} +with only apostrophes typically generates a message like @t{"Missing +’foo’"} with only closing curved quotes, an unusual style in English. @strong{Warning:} If you want to use your own string as an error message verbatim, don't just write @code{(error @var{string})}. If @var{string} diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index b0cd8731fe2..181bff09b55 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -265,12 +265,13 @@ properties, it is displayed with the specified faces (@pxref{Faces}). The string is also added to the @file{*Messages*} buffer, but without text properties (@pxref{Logging Messages}). -A format that quotes with grave accents and apostrophes @t{`like -this'} typically generates curved quotes @t{‘like this’}. In -contrast, a format that quotes with only apostrophes @t{'like this'} -typically generates two closing curved quotes @t{’like this’}, an -unusual style in English. @xref{Keys in Documentation}, for how the -@code{text-quoting-style} variable affects generated quotes. +The @code{text-quoting-style} variable controls what quotes are +generated; @xref{Keys in Documentation}. A call using a format like +@t{"Missing `%s'"} with grave accents and apostrophes typically +generates a message like @t{"Missing ‘foo’"} with matching curved +quotes. In contrast, a call using a format like @t{"Missing '%s'"} +with only apostrophes typically generates a message like @t{"Missing +’foo’"} with only closing curved quotes, an unusual style in English. In batch mode, the message is printed to the standard error stream, followed by a newline. -- cgit v1.2.1 From 50650cb6887d99b01eeb1e686fc1f695c2a0c64a Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Thu, 5 May 2016 12:48:33 -0700 Subject: Doc fixes for fclist and grep A newline is needed between two fc-list calls. egrep and fgrep have been withdrawn from POSIX, so document grep -E and grep -F instead. --- doc/emacs/frames.texi | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index 23ccd6a8f41..a7e709f9221 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -764,7 +764,8 @@ Fontconfig fonts, you can use the @command{fc-list} command to list the available fixed-width fonts, like this: @example -fc-list :spacing=mono fc-list :spacing=charcell +fc-list :spacing=mono +fc-list :spacing=charcell @end example @noindent @@ -772,7 +773,7 @@ For server-side X fonts, you can use the @command{xlsfonts} program to list the available fixed-width fonts, like this: @example -xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+" +xlsfonts -fn '*x*' | grep -E '^[0-9]+x[0-9]+' xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*' xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*' @end example -- cgit v1.2.1