Commit 1bc4def8 authored by Eli Zaretskii's avatar Eli Zaretskii

More proofreading of the Emacs manual

* doc/emacs/trouble.texi (DEL Does Not Delete): Improve wording.
(Screen Garbled): Mention the command name.
(Bug Criteria): Mention that problems in packages should first be
reported to the respective maintainers.
(Checklist): Fix wording.
(Contributing, Copyright Assignment): Minor copyedits.
* doc/emacs/misc.texi (Amusements): Remove Landmark.
* doc/emacs/picture-xtra.texi (Tabs in Picture): Improve wording.
(Rectangles in Picture): Add a cross-reference to "Registers".
* doc/emacs/misc.texi (Gnus Group Buffer, Gnus Summary Buffer):
Mention command names in parentheses.
(Gnus Summary Buffer): Document "M-r".
(Network Security): Document that current NSM works with TLS
encryption.  Fix markup.
(Document View): Improve wording and fix a typo.
(DocView Conversion): Rephrase description of
doc-view-cache-directory.
(Single Shell): Mention variables that control when shell output
appears in the echo area.
(Shell Mode): Improve wording.
(Shell Prompts): Fix a typo.
(Shell Ring, Term Mode): Mention command names.
(History References): Add a cross-reference to "Rebinding".
(Remote Host): Mention SSH.
(TCP Emacs server): Improve wording.
(emacsclient Options): Minor improvements.
(PostScript): Fix wording.
(PostScript Variables): Mention that ps-font-size could be a cons.
(Sorting): Minor improvements.  Suggested by Michael Albinus
<michael.albinus@gmx.de> in emacs-manual-bugs@gnu.org
parent b8ebf5fb
......@@ -132,7 +132,8 @@ sessions.
@kindex SPC @r{(Gnus Group mode)}
@findex gnus-group-read-group
@item @key{SPC}
Switch to the summary buffer for the group on the current line.
Switch to the summary buffer for the group on the current line
(@code{gnus-group-read-group}).
@kindex l @r{(Gnus Group mode)}
@kindex A s @r{(Gnus Group mode)}
......@@ -140,7 +141,8 @@ Switch to the summary buffer for the group on the current line.
@item l
@itemx A s
In the group buffer, list only the groups to which you subscribe and
which contain unread articles (this is the default listing).
which contain unread articles (@code{gnus-group-list-groups}; this is
the default listing).
@kindex L @r{(Gnus Group mode)}
@kindex A u @r{(Gnus Group mode)}
......@@ -148,24 +150,25 @@ which contain unread articles (this is the default listing).
@item L
@itemx A u
List all subscribed and unsubscribed groups, but not killed or zombie
groups.
groups (@code{gnus-group-list-all-groups}).
@kindex A k @r{(Gnus Group mode)}
@findex gnus-group-list-killed
@item A k
List killed groups.
List killed groups (@code{gnus-group-list-killed}).
@kindex A z @r{(Gnus Group mode)}
@findex gnus-group-list-zombies
@item A z
List zombie groups.
List zombie groups (@code{gnus-group-list-zombies}).
@kindex u @r{(Gnus Group mode)}
@findex gnus-group-unsubscribe-current-group
@cindex subscribe groups
@cindex unsubscribe groups
@item u
Toggle the subscription status of the group on the current line
Toggle the subscription status of the group
(@code{gnus-group-unsubscribe-current-group}) on the current line
(i.e., turn a subscribed group into an unsubscribed group, or vice
versa). Invoking this on a killed or zombie group turns it into an
unsubscribed group.
......@@ -173,28 +176,31 @@ unsubscribed group.
@kindex C-k @r{(Gnus Group mode)}
@findex gnus-group-kill-group
@item C-k
Kill the group on the current line. Killed groups are not recorded in
the @file{.newsrc} file, and they are not shown in the @kbd{l} or
@kbd{L} listings.
Kill the group on the current line (@code{gnus-group-kill-group}).
Killed groups are not recorded in the @file{.newsrc} file, and they
are not shown in the @kbd{l} or @kbd{L} listings.
@kindex DEL @r{(Gnus Group mode)}
@item @key{DEL}
Move point to the previous group containing unread articles.
Move point to the previous group containing unread articles
(@code{gnus-group-prev-unread-group}.)
@kindex n @r{(Gnus Group mode)}
@findex gnus-group-next-unread-group
@item n
Move point to the next unread group.
Move point to the next unread group
(@code{gnus-group-next-unread-group}).
@kindex p @r{(Gnus Group mode)}
@findex gnus-group-prev-unread-group
@item p
Move point to the previous unread group.
Move point to the previous unread group
(@code{gnus-group-prev-unread-group}).
@kindex q @r{(Gnus Group mode)}
@findex gnus-group-exit
@item q
Update your Gnus settings, and quit Gnus.
Update your Gnus settings, and quit Gnus (@code{gnus-group-exit}).
@end table
@node Gnus Summary Buffer
......@@ -209,7 +215,7 @@ Update your Gnus settings, and quit Gnus.
If there is no article selected, select the article on the current
line and display its article buffer. Otherwise, try scrolling the
selected article buffer in its window; on reaching the end of the
buffer, select the next unread article.
buffer, select the next unread article (@code{gnus-summary-next-page}).
Thus, you can read through all articles by repeatedly typing
@key{SPC}.
......@@ -217,33 +223,44 @@ Thus, you can read through all articles by repeatedly typing
@kindex DEL @r{(Gnus Summary mode)}
@findex gnus-summary-prev-page
@item @key{DEL}
Scroll the text of the article backwards.
Scroll the text of the article backwards
(@code{gnus-summary-prev-page}).
@kindex n @r{(Gnus Summary mode)}
@findex gnus-summary-next-unread-article
@item n
Select the next unread article.
Select the next unread article
(@code{gnus-summary-next-unread-article}).
@kindex p @r{(Gnus Summary mode)}
@findex gnus-summary-prev-unread-article
@item p
Select the previous unread article.
Select the previous unread article
(@code{gnus-summary-prev-unread-article}).
@kindex s @r{(Gnus Summary mode)}
@findex gnus-summary-isearch-article
@item s
Do an incremental search on the selected article buffer, as if you
switched to the buffer and typed @kbd{C-s} (@pxref{Incremental
Search}).
Do an incremental search on the selected article buffer
(@code{gnus-summary-isearch-article}), as if you switched to the
buffer and typed @kbd{C-s} (@pxref{Incremental Search}).
@kindex M-s @r{(Gnus Summary mode)}
@findex gnus-summary-search-article-forward
@item M-s @var{regexp} @key{RET}
Search forward for articles containing a match for @var{regexp}.
Search forward for articles containing a match for @var{regexp}
(@code{gnus-summary-search-article-forward}).
@kindex M-r @r{(Gnus Summary mode)}
@findex gnus-summary-search-article-backward
@item M-r @var{regexp} @key{RET}
Search back for articles containing a match for @var{regexp}
(@code{gnus-summary-search-article-backward}).
@kindex q @r{(Gnus Summary mode)}
@item q
Exit the summary buffer and return to the group buffer.
Exit the summary buffer and return to the group buffer
(@code{gnus-summary-exit}).
@end table
@node Host Security
......@@ -273,12 +290,14 @@ Emacs as part of a larger application.
@cindex encryption
@cindex SSL
@cindex TLS
@cindex Transport Layer Security
@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.
network security under your control. Currently, this works by using
the Transport Layer Security (@acronym{TLS}) features.
@vindex network-security-level
The @code{network-security-level} variable determines the security
......@@ -381,7 +400,8 @@ 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.
@acronym{NSM} will also save host names in the
@code{nsm-settings-file}.
@end table
......@@ -411,7 +431,7 @@ is needed. For OpenDocument and Microsoft Office documents, the
@findex doc-view-toggle-display
@findex doc-view-minor-mode
When you visit a document file that can be displayed with DocView
mode, Emacs automatically uses DocView mode @footnote{The needed
mode, Emacs automatically uses that mode @footnote{The needed
external tools for the document type must be available, and Emacs must
be running in a graphical frame and have PNG image support. If these
requirements is not fulfilled, Emacs falls back to another major
......@@ -426,7 +446,7 @@ underlying file contents.
@findex doc-view-open-text
When you visit a file which would normally be handled by DocView
mode but some requirement is not met (e.g., you operate in a terminal
frame or emacs has no PNG support), you are queried if you want to
frame or Emacs has no PNG support), you are queried if you want to
view the document's contents as plain text. If you confirm, the
buffer is put in text mode and DocView minor mode is activated. Thus,
by typing @kbd{C-c C-c} you switch to the fallback mode. With another
......@@ -574,7 +594,7 @@ including its entire margins.
@vindex doc-view-cache-directory
@findex doc-view-clear-cache
For efficiency, DocView caches the images produced by @command{gs}.
The name of this directory is given by the variable
The name of the directory where it caches images is given by the variable
@code{doc-view-cache-directory}. You can clear the cache directory by
typing @kbd{M-x doc-view-clear-cache}.
......@@ -660,7 +680,9 @@ for that command. Standard input for the command comes from the null
device. If the shell command produces any output, the output appears
either in the echo area (if it is short), or in an Emacs buffer named
@file{*Shell Command Output*}, displayed in another window (if the
output is long).
output is long). The variables @code{resize-mini-windows} and
@code{max-mini-window-height} (@pxref{Minibuffer Edit}) control when
the output is considered too long for the echo area.
For instance, one way to decompress a file named @file{foo.gz} is to
type @kbd{M-! gunzip foo.gz @key{RET}}. That shell command normally
......@@ -872,11 +894,12 @@ line---but after @kbd{C-c @key{SPC}} the process mark may be in a
previous line.)
@item C-c @key{SPC}
Accumulate multiple lines of input, then send them together. This
command inserts a newline before point, but does not send the preceding
text as input to the subshell---at least, not yet. Both lines, the one
before this newline and the one after, will be sent together (along with
the newline that separates them), when you type @key{RET}.
Accumulate multiple lines of input, then send them together
(@code{comint-accumulate}). This command inserts a newline before
point, but does not send the preceding text as input to the
subshell---at least, not yet. Both lines, the one before this newline
and the one after, will be sent together (along with the newline that
separates them), when you type @key{RET}.
@item C-c C-u
@kindex C-c C-u @r{(Shell mode)}
......@@ -936,7 +959,7 @@ of the window; also move the cursor there (@code{comint-show-output}).
@item C-c C-e
@kindex C-c C-e @r{(Shell mode)}
@findex comint-show-maximum-output
Scroll to put the end of the buffer at the bottom of the window
Scroll to put the last line of the buffer at the bottom of the window
(@code{comint-show-maximum-output}).
@item C-c C-f
......@@ -1027,9 +1050,9 @@ specializations of Shell mode.
@cindex prompt, shell
A prompt is text output by a program to show that it is ready to
accept new user input. Normally, Comint mode (and thus Shell mode)
automatically figures out part of the buffer is a prompt, based on the
output of the subprocess. (Specifically, it assumes that any received
output line which doesn't end with a newline is a prompt.)
automatically figures out which part of the buffer is a prompt, based
on the output of the subprocess. (Specifically, it assumes that any
received output line which doesn't end with a newline is a prompt.)
Comint mode divides the buffer into two types of @dfn{fields}: input
fields (where user input is typed) and output fields (everywhere
......@@ -1082,28 +1105,32 @@ resubmit them or copy them to the end. Or you can use a
@kindex M-p @r{(Shell mode)}
@item M-p
@itemx C-@key{UP}
Fetch the next earlier old shell command.
Fetch the next earlier old shell command
(@code{comint-previous-input}).
@kindex M-n @r{(Shell mode)}
@findex comint-next-input
@item M-n
@itemx C-@key{DOWN}
Fetch the next later old shell command.
Fetch the next later old shell command (@code{comint-next-input}).
@kindex M-r @r{(Shell mode)}
@findex comint-history-isearch-backward-regexp
@item M-r
Begin an incremental regexp search of old shell commands.
Begin an incremental regexp search of old shell commands
(@code{comint-history-isearch-backward-regexp}).
@item C-c C-x
@kindex C-c C-x @r{(Shell mode)}
@findex comint-get-next-from-history
Fetch the next subsequent command from the history.
Fetch the next subsequent command from the history
(@code{comint-get-next-from-history}).
@item C-c .
@kindex C-c . @r{(Shell mode)}
@findex comint-input-previous-argument
Fetch one argument from an old shell command.
Fetch one argument from an old shell command
(@code{comint-input-previous-argument}).
@item C-c C-l
@kindex C-c C-l @r{(Shell mode)}
......@@ -1231,7 +1258,7 @@ typing @key{RET}.
when you send them to the shell. To request this, set the variable
@code{comint-input-autoexpand} to @code{input}. You can make
@key{SPC} perform history expansion by binding @key{SPC} to the
command @code{comint-magic-space}.
command @code{comint-magic-space}. @xref{Rebinding}.
Shell mode recognizes history references when they follow a prompt.
@xref{Shell Prompts}, for how Shell mode recognizes prompts.
......@@ -1419,9 +1446,6 @@ examining your input. But some shells can tell Term what the current
directory is. This is done automatically by @code{bash} version 1.15
and later.
@node Term Mode
@subsection Term Mode
@cindex Term mode
......@@ -1448,7 +1472,8 @@ char mode.
@table @kbd
@item C-c C-c
Send a literal @kbd{C-c} to the sub-shell.
Send a literal @kbd{C-c} to the sub-shell
(@code{term-interrupt-subjob}).
@item C-c @var{char}
This is equivalent to @kbd{C-x @var{char}} in normal Emacs. For
......@@ -1464,13 +1489,13 @@ output pause at the end of each screenful:
@kindex C-c C-q @r{(Term mode)}
@findex term-pager-toggle
@item C-c C-q
Toggle the page-at-a-time feature. This command works in both line
and char modes. When the feature is enabled, the mode-line displays
the word @samp{page}, and each time Term receives more than a
screenful of output, it pauses and displays @samp{**MORE**} in the
mode-line. Type @key{SPC} to display the next screenful of output, or
@kbd{?} to see your other options. The interface is similar to the
@code{more} program.
Toggle the page-at-a-time feature (@code{term-pager-toggle}). This
command works in both line and char modes. When the feature is
enabled, the mode-line displays the word @samp{page}, and each time
Term receives more than a screenful of output, it pauses and displays
@samp{**MORE**} in the mode-line. Type @key{SPC} to display the next
screenful of output, or @kbd{?} to see your other options. The
interface is similar to the @code{more} program.
@end table
@node Remote Host
......@@ -1481,8 +1506,8 @@ mode-line. Type @key{SPC} to display the next screenful of output, or
@cindex Rlogin
You can login to a remote computer, using whatever commands you
would from a regular terminal (e.g., using the @code{telnet} or
@code{rlogin} commands), from a Term window.
would from a regular terminal (e.g., using the @code{ssh} or
@code{telnet} or @code{rlogin} commands), from a Term window.
A program that asks you for a password will normally suppress
echoing of the password, so the password will not show up in the
......@@ -1621,7 +1646,7 @@ name, using the @samp{-s} option (@pxref{emacsclient Options}).
you can give each daemon its own server name like this:
@example
emacs --eval "(setq server-name \"foo\")" --daemon
emacs --daemon=foo
@end example
@findex server-eval-at
......@@ -1656,7 +1681,7 @@ not support local sockets.
@vindex server-host
@vindex server-port
If the Emacs server is set to use TCP, it will by default listen to
If the Emacs server is set to use TCP, it will by default listen on
a random port on the localhost interface. This can be changed to
another interface and/or a fixed port using the variables
@code{server-host} and @code{server-port}.
......@@ -1848,7 +1873,7 @@ evaluate, @emph{not} as a list of files to visit.
Specify a server file (@pxref{TCP Emacs server}) for connecting to an
Emacs server via TCP. Alternatively, you can set the
@env{EMACS_SERVER_FILE} environment variable to point to the server
file.
file. (The command-line option overrides the environment variable.)
An Emacs server usually uses a local socket to listen for connections,
but also supports connections over TCP. To connect to a TCP Emacs
......@@ -1904,14 +1929,15 @@ terminal.
@item -T @var{tramp-prefix}
@itemx --tramp-prefix=@var{tramp-prefix}
Set the prefix to add to filenames for Emacs to locate files on remote
machines using TRAMP (@pxref{Top, The Tramp Manual,, tramp, The Tramp
Manual}). This is mostly useful in combination with using the Emacs
server over TCP (@pxref{TCP Emacs server}). By ssh-forwarding the
listening port and making the @var{server-file} available on a remote
machine, programs on the remote machine can use @command{emacsclient}
as the value for the @env{EDITOR} and similar environment variables,
but instead of talking to an Emacs server on the remote machine, the
files will be visited in the local Emacs session using TRAMP.
machines (@pxref{Remote Files}) using TRAMP (@pxref{Top, The Tramp
Manual,, tramp, The Tramp Manual}). This is mostly useful in
combination with using the Emacs server over TCP (@pxref{TCP Emacs
server}). By ssh-forwarding the listening port and making the
@var{server-file} available on a remote machine, programs on the
remote machine can use @command{emacsclient} as the value for the
@env{EDITOR} and similar environment variables, but instead of talking
to an Emacs server on the remote machine, the files will be visited in
the local Emacs session using TRAMP.
@vindex EMACSCLIENT_TRAMP@r{, environment variable}
Setting the environment variable @env{EMACSCLIENT_TRAMP} has the same
......@@ -2068,8 +2094,8 @@ buffer; the other, just the region. The commands
@code{ps-print-region-with-faces} behave similarly, but use PostScript
features to show the faces (fonts and colors) of the buffer text.
Interactively, when you use a prefix argument (@kbd{C-u}), the command
prompts the user for a file name, and saves the PostScript image in that file
Interactively, when you use a prefix argument (@kbd{C-u}), these commands
prompt the user for a file name, and save the PostScript image in that file
instead of sending it to the printer.
@findex ps-spool-region
......@@ -2161,7 +2187,9 @@ default is 1.
for printing ordinary text. Legitimate values include @code{Courier},
@code{Helvetica}, @code{NewCenturySchlbk}, @code{Palatino} and
@code{Times}. The variable @code{ps-font-size} specifies the size of
the font for ordinary text. It defaults to 8.5 points.
the font for ordinary text and defaults to 8.5 points. The value of
@code{ps-font-size} can also be a cons of 2 floats: one for landscape
mode, the other for portrait mode.
@vindex ps-multibyte-buffer
@cindex Intlfonts for PostScript printing
......@@ -2229,7 +2257,8 @@ into the order determined by the sort keys. The records are ordered so
that their keys are in alphabetical order, or, for numeric sorting, in
numeric order. In alphabetic sorting, all upper-case letters @samp{A}
through @samp{Z} come before lower-case @samp{a}, in accordance with the
@acronym{ASCII} character sequence.
@acronym{ASCII} character sequence (but @code{sort-fold-case},
described below, can change that).
The various sort commands differ in how they divide the text into sort
records and in which part of each record is used as the sort key. Most of
......@@ -2267,10 +2296,11 @@ in a line constitutes field 1, the second such run constitutes field
2, etc.
Specify which field to sort by with a numeric argument: 1 to sort by
field 1, etc. A negative argument means count fields from the right
instead of from the left; thus, minus 1 means sort by the last field.
If several lines have identical contents in the field being sorted, they
keep the same relative order that they had in the original buffer.
field 1, etc.; the default is 1. A negative argument means count
fields from the right instead of from the left; thus, minus 1 means
sort by the last field. If several lines have identical contents in
the field being sorted, they keep the same relative order that they
had in the original buffer.
@item M-x sort-numeric-fields
Like @kbd{M-x sort-fields} except the specified field is converted
......@@ -2943,13 +2973,6 @@ bored, try an argument of 9. Sit back and watch.
@cindex Life
@kbd{M-x life} runs Conway's Game of Life cellular automaton.
@findex landmark
@cindex landmark game
@kbd{M-x landmark} runs a relatively non-participatory game in which
a robot attempts to maneuver towards a tree at the center of the
window based on unique olfactory cues from each of the four
directions.
@findex morse-region
@findex unmorse-region
@findex nato-region
......
......@@ -199,7 +199,7 @@ C-b} (@code{picture-motion-reverse}) moves in the opposite direction.
With no argument, it moves to a point underneath the next
``interesting'' character that follows whitespace in the previous
nonblank line. ``Next'' here means ``appearing at a horizontal position
greater than the one point starts out at''. With an argument, as in
greater than the one point starts out at''. With prefix argument, as in
@kbd{C-u M-@key{TAB}}, this command moves to the next such interesting
character in the current line. @kbd{M-@key{TAB}} does not change the
text; it only moves point. ``Interesting'' characters are defined by
......@@ -250,7 +250,7 @@ Clear out the region-rectangle with spaces
text.
@item C-c C-w @var{r}
Similar, but save rectangle contents in register @var{r} first
(@code{picture-clear-rectangle-to-register}).
(@code{picture-clear-rectangle-to-register}). @xref{Registers}.
@item C-c C-y
Copy last killed rectangle into the buffer by overwriting, with upper
left corner at point (@code{picture-yank-rectangle}). With argument,
......
......@@ -185,8 +185,8 @@ command @kbd{M-x normal-erase-is-backspace-mode}. This toggles
between the two modes that Emacs supports for handling @key{DEL}, so
if Emacs starts in the wrong mode, this should switch to the right
mode. On a text terminal, if you want to ask for help when @key{BS}
is treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also work, if it
sends character code 127.
is treated as @key{DEL}, use @key{F1} instead of @kbd{C-h}; @kbd{C-?}
may also work, if it sends character code 127.
To fix the problem in every Emacs session, put one of the following
lines into your initialization file (@pxref{Init File}). For the
......@@ -233,10 +233,10 @@ top-level}. @xref{Recursive Edit}.
@cindex screen display, wrong
If the text on a text terminal looks wrong, the first thing to do is
see whether it is wrong in the buffer. Type @kbd{C-l} to redisplay
the entire screen. If the screen appears correct after this, the
problem was entirely in the previous screen update. (Otherwise, see
the following section.)
see whether it is wrong in the buffer. Type @kbd{C-l}
(@code{recenter-top-bottom}) to redisplay the entire screen. If the
screen appears correct after this, the problem was entirely in the
previous screen update. (Otherwise, see the following section.)
Display updating problems often result from an incorrect terminfo
entry for the terminal you are using. The file @file{etc/TERMS} in
......@@ -251,16 +251,17 @@ bug in Emacs that appears for certain terminal types.
@cindex garbled text
@cindex buffer text garbled
If @kbd{C-l} shows that the text is wrong, first type @kbd{C-h l} to
see what commands you typed to produce the observed results. Then try
undoing the changes step by step using @kbd{C-x u}, until it gets back
to a state you consider correct.
If @kbd{C-l} shows that the text is wrong, first type @kbd{C-h l}
(@code{view-lossage}) to see what commands you typed to produce the
observed results. Then try undoing the changes step by step using
@kbd{C-x u} (@code{undo}), until it gets back to a state you consider
correct.
If a large portion of text appears to be missing at the beginning or
end of the buffer, check for the word @samp{Narrow} in the mode line.
If it appears, the text you don't see is probably still present, but
temporarily off-limits. To make it accessible again, type @kbd{C-x n
w}. @xref{Narrowing}.
w} (@code{widen}). @xref{Narrowing}.
@node Memory Full
@subsection Running out of Memory
......@@ -268,12 +269,13 @@ w}. @xref{Narrowing}.
@cindex out of memory
If you get the error message @samp{Virtual memory exceeded}, save
your modified buffers with @kbd{C-x s}. This method of saving them
has the smallest need for additional memory. Emacs keeps a reserve of
memory which it makes available when this error happens; that should
be enough to enable @kbd{C-x s} to complete its work. When the
reserve has been used, @samp{!MEM FULL!} appears at the beginning of
the mode line, indicating there is no more reserve.
your modified buffers with @kbd{C-x s} (@code{save-some-buffers}).
This method of saving them has the smallest need for additional
memory. Emacs keeps a reserve of memory which it makes available when
this error happens; that should be enough to enable @kbd{C-x s} to
complete its work. When the reserve has been used, @samp{!MEM FULL!}
appears at the beginning of the mode line, indicating there is no more
reserve.
Once you have saved your modified buffers, you can exit this Emacs
session and start another, or you can use @kbd{M-x kill-some-buffers}
......@@ -589,6 +591,9 @@ important to report documentation bugs as program bugs.
If the built-in documentation for a function or variable disagrees
with the manual, one of them must be wrong; that is a bug.
For problems with packages that are not part of Emacs, it is better
to begin by reporting them to the package developers.
@node Understanding Bug Reporting
@subsection Understanding Bug Reporting
@cindex bug reporting
......@@ -706,7 +711,10 @@ tracker.
If your data is more than 500,000 bytes, please don't include it
directly in the bug report; instead, offer to send it on request, or
make it available by ftp and say where.
make it available online and say where.
The Gnu Bug Tracker will assign a bug number to your report; please
use it in the following discussions.
To enable maintainers to investigate a bug, your report
should include all these things:
......@@ -770,20 +778,21 @@ customizations.
@cindex dribble file
@cindex logging keystrokes
One way to record the input to Emacs precisely is to write a dribble
file. To start the file, use the @kbd{M-x open-dribble-file
@key{RET}} command. From then on, Emacs copies all your input to the
specified dribble file until the Emacs process is killed. Be aware
that sensitive information (such as passwords) may end up recorded in
the dribble file.
file. To start the file, use the @kbd{M-x open-dribble-file} command.
From then on, Emacs copies all your input to the specified dribble
file until the Emacs process is killed. Be aware that sensitive
information (such as passwords) may end up recorded in the dribble
file.
@item
@findex open-termscript
@cindex termscript file
@vindex TERM@r{, environment variable, and display bugs}
For possible display bugs, the terminal type (the value of environment
variable @env{TERM}), the complete termcap entry for the terminal from
@file{/etc/termcap} (since that file is not identical on all machines),
and the output that Emacs actually sent to the terminal.
For possible display bugs on text-mode terminals, the terminal type
(the value of environment variable @env{TERM}), the complete termcap
entry for the terminal from @file{/etc/termcap} (since that file is
not identical on all machines), and the output that Emacs actually
sent to the terminal.
The way to collect the terminal output is to execute the Lisp expression
......@@ -926,13 +935,13 @@ However, you need to think when you collect the additional information
if you want it to show what causes the bug.
@cindex backtrace for bug reports
For example, many people send just a backtrace, but that is not very
useful by itself. A simple backtrace with arguments often conveys
little about what is happening inside GNU Emacs, because most of the
arguments listed in the backtrace are pointers to Lisp objects. The
numeric values of these pointers have no significance whatever; all that
matters is the contents of the objects they point to (and most of the
contents are themselves pointers).
For example, many people send just a C-level backtrace, but that is
not very useful by itself. A simple backtrace with arguments often
conveys little about what is happening inside GNU Emacs, because most
of the arguments listed in the backtrace are pointers to Lisp objects.
The numeric values of these pointers have no significance whatever;
all that matters is the contents of the objects they point to (and
most of the contents are themselves pointers).
@findex debug_print
To provide useful information, you need to show the values of Lisp
......@@ -1217,8 +1226,8 @@ 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}).
write documentation, either on the @uref{https://www.emacswiki.org/,
wiki}, or in the Emacs source repository (@pxref{Sending Patches}).
@item
check if existing bug reports are fixed in newer versions of Emacs
......@@ -1283,7 +1292,7 @@ downloaded the repository source, you should read the file
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
@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
......@@ -1385,9 +1394,10 @@ 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{https://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{https://www.gnu.org/licenses/why-assign.html}.
Generally speaking, for non-trivial contributions to GNU Emacs and
packages stored in GNU ELPA, we require that the copyright be assigned
to the FSF@. For the reasons behind this, see
@url{https://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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment