diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index bcf89fc9ab1..071ec0f518d 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -279,12 +279,6 @@ whether they are numerically equal. For example, when @var{x} and conversely, @code{(equal 0.0 -0.0)} returns @code{nil} whereas @code{(= 0.0 -0.0)} returns @code{t}. - Infinities and NaNs are not available on legacy systems that lack -IEEE floating-point arithmetic. On a circa 1980 VAX, for example, the -Lisp reader approximates an infinity with the nearest finite value, -and a NaN with some other non-numeric Lisp object that provokes an -error if used numerically. - Here are read syntaxes for these special floating-point values: @table @asis @@ -294,6 +288,12 @@ Here are read syntaxes for these special floating-point values: @samp{0.0e+NaN} and @samp{-0.0e+NaN} @end table + Infinities and NaNs are not available on legacy systems that lack +IEEE floating-point arithmetic. On a circa 1980 VAX, for example, +Lisp reads @samp{1.0e+INF} as a large but finite floating-point number, +and @samp{0.0e+NaN} as some other non-numeric Lisp object that provokes an +error if used numerically. + The following functions are specialized for handling floating-point numbers: diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index ddfdb2e2b64..63ea94d9b2e 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -144,11 +144,11 @@ the @samp{#emacs} channels where you can chat with other Emacs users, and if you're having trouble with ERC, you can join the @samp{#erc} channel and ask for help there. -If you want to place ERC settings in their own file, you can place them -in @file{~/.emacs.d/.ercrc.el}, creating it if necessary. - -If you would rather use the Customize interface to change how ERC -works, do @kbd{M-x customize-group @key{RET} erc @key{RET}}. In +At some point in your ERC journey, you'll inevitably want to change +how the client looks and behaves. As with other Emacs applications, +the typical place to store your settings is your @file{init.el}. If +you would rather use the Customize interface, a good place to start is +by running @kbd{M-x customize-group @key{RET} erc @key{RET}}. In particular, ERC comes with lots of modules that may be enabled or disabled; to select which ones you want, do @kbd{M-x customize-variable @key{RET} erc-modules @key{RET}}. @@ -161,69 +161,90 @@ customize-variable @key{RET} erc-modules @key{RET}}. @node Sample Session @section Sample Session -This is an example ERC session which shows how to connect to the -@samp{#emacs} channel on Libera.Chat. Another IRC channel on -Libera.Chat that may be of interest is @samp{#erc}, which is a channel -where ERC users and developers hang out. These channels used to live -on the Freenode IRC network until June 2021, when they---along with -the official IRC channels of the GNU Project, the Free Software -Foundation, and many other free software communities---relocated to -the Libera.Chat network in the aftermath of changes in governance and -policies of Freenode in May and June 2021. GNU and FSF's -announcements about this are at -@uref{https://lists.gnu.org/archive/html/info-gnu/2021-06/msg00005.html}, -@uref{https://lists.gnu.org/archive/html/info-gnu/2021-06/msg00007.html}, -and -@uref{https://lists.gnu.org/archive/html/info-gnu-emacs/2021-06/msg00000.html}. +This example ERC session describes how to connect to the @samp{#emacs} +channel on Libera.Chat. Also worth checking out is Libera's own +introductory guide to IRC, @uref{https://libera.chat/guides/basics}, +which presents a more comprehensive overview without instructions +specific to ERC. @itemize @bullet @item Connect to Libera.Chat -Run @kbd{M-x erc}. Use ``irc.libera.chat'' as the IRC server, ``6667'' -as the port, and choose a nickname. +Run @kbd{M-x erc @key{RET}}. Use @samp{irc.libera.chat} for the +server and @samp{6667} for the port. Choose a nickname, and hit +@key{y} when asked if you'd prefer to connect over @acronym{TLS}. @item Get used to the interface -Switch to the ``irc.libera.chat:6667'' buffer, if you're not already -there. You will see first some messages about checking for ident, and -then a bunch of other messages that describe the current IRC server. +Switch to the @file{Libera.Chat} buffer if you're not already there. +ERC calls this a @dfn{server buffer}, and it must exist for the +duration of the session. You will likely see some messages about +``ident'', authentication, and the like, followed by information +describing the current server and the network. @item Join the #emacs channel -In that buffer, type ``/join @key{SPC} #emacs'' and hit @kbd{RET}. Depending -on how you've set up ERC, either a new buffer for ``#emacs'' will be -displayed, or a new buffer called ``#emacs'' will be created in the -background. If the latter, switch to the ``#emacs'' buffer. You will -see the channel topic and a list of the people who are currently on the -channel. +In the server buffer, type @kbd{/join #emacs @key{RET}} at the prompt. +ERC will create a new buffer called @file{#emacs}. If you've already +configured ERC, you may need to switch to it manually. Once there, +you will see the channel's ``topic'' in the buffer's header line +(@pxref{Header Lines,,,elisp,}) and a list of people currently in the +channel. If you can't see the full topic, mouse over it or type +@kbd{/topic @key{RET}} at the prompt. @item Register your nickname with Libera.Chat -If you would like to be able to talk with people privately on the -Libera.Chat network, you will have to ``register'' your nickname. -To do so, switch to the ``irc.libera.chat:6667'' buffer and type -``/msg NickServ register '', replacing ``'' with -your desired password. It should tell you that the operation was -successful. +In order to access essential network features, like speaking in +certain channels and participating in private conversations, you'll +likely have to ``register'' your nickname. To do so, switch to the +@file{Libera.Chat} buffer and type @kbd{/msg NickServ register +@samp{} @samp{} @key{RET}}, replacing +@samp{} and @samp{} with your desired account +password and contact email (both sans quotes). The server should tell +you that the operation was successful. See the official Libera.Chat +docs if you encounter problems. + +In addition to creating an account, this process also +``authenticates'' you to the network's ``account services'' system for +the duration of the session. In other words, you're now logged in. +However, when you connect in the future, you'll need to authenticate +again by providing the same credentials somehow. When you're finished +with this walk through, see ``Next Steps'', below, to learn some ways +to do that. @item Talk to people in the channel -If you switch back to the ``#emacs'' buffer, you can type a message, and -everyone on the channel will see it. +Switch back to the @file{#emacs} buffer and type a message at the +prompt, hitting @kbd{RET} once satisfied. Everyone in the channel +will now see your message. @item Open a query buffer to talk to someone -If you want to talk with someone in private (this should usually not be -done for technical help, only for personal questions), type ``/query -'', replacing ``'' with the nickname of the person you would -like to talk to. Depending on how ERC is set up, you will either see a -new buffer with the name of the person, or such a buffer will be created -in the background and you will have to switch to it. Begin typing -messages, and you will be able to have a conversation. +If you want to talk with someone in private, type @kbd{/query +@samp{} @key{RET}}, replacing @samp{} with the their +nickname. As before, with the server buffer, if this new @dfn{query +buffer} doesn't appear in the current window, you may have to switch +to it. Regardless, its name should match @samp{}. Once there, +type something at the prompt and hit @kbd{RET}, and the other party +will see it. -Note that if the other person is not registered, you will not be able to -talk with them. +Keep in mind that if either party isn't authenticated, you may not be +able to converse at all. Also, depending on the network, certain +social conventions may apply to the practice of direct messaging. As +a general rule, queries should usually be reserved for personal +matters rather than technical help, which can often benefit (and +benefit @emph{from}) a larger audience. + +@item Next steps + +Try joining another channel, such as @samp{#erc}, where ERC users and +developers hang out (@pxref{Official IRC channels} for more on the +history of @samp{#emacs}). For ideas on various options to customize, +@pxref{Sample Configuration}. To learn how ERC can authenticate you +to the network automatically whenever you connect, @pxref{SASL}. As +always, if you encounter problems, @pxref{Getting Help and Reporting +Bugs}. @end itemize @@ -414,9 +435,10 @@ Set away status automatically @item autojoin Join channels automatically -@cindex modules, bbdb -@item bbdb -Integrate with the Big Brother Database +@cindex modules, bufbar +@item bufbar +List buffers belonging to a connection in a side window; part of +Custom group @code{erc-status-sidebar} @cindex modules, button @item button @@ -443,6 +465,10 @@ Launch an identd server on port 8113 @item irccontrols Highlight or remove IRC control characters +@cindex modules, keep-place +@item keep-place +Remember your position in buffers + @cindex modules, log @item log Save buffers in logs @@ -459,6 +485,15 @@ Display a menu in ERC buffers @item netsplit Detect netsplits +@cindex modules, nicks +@item nicks +Automatically colorize nicks + +@cindex modules, nickbar +@item nickbar +List participating nicks for the current target buffer in a side +window; part of Custom group @code{erc-speedbar} + @cindex modules, noncommands @item noncommands Don't display non-IRC commands after evaluation @@ -530,6 +565,33 @@ Translate morse code in messages @end table +@anchor{Auxiliary Modules} +@subheading Auxiliary Modules +@cindex auxiliary modules + +For various reasons, the following modules aren't currently listed in +the Custom interface for @code{erc-modules}, but feel free to add them +explicitly. They may be managed by another module or considered more +useful when toggled interactively or just deemed experimental. + +@table @code + +@cindex modules, fill-wrap +@item fill-wrap +Wrap long lines using @code{visual-line-mode} + +@cindex modules, keep-place-indicator +@item keep-place-indicator +Remember your place in buffers with a visible reminder; activated +interactively or via something like @code{erc-join-hook} + +@cindex modules, services-regain +@item services-regain +Automatically ask NickServ to reclaim your nick when reconnecting; +experimental as of ERC 5.6 + +@end table + @anchor{Required Modules} @subheading Required Modules @cindex required modules @@ -613,6 +675,7 @@ Integrations * URL:: Opening IRC URLs in ERC. * SOCKS:: Connecting to IRC with a SOCKS proxy. * auth-source:: Retrieving auth-source entries with ERC. +* display-buffer:: Controlling how ERC displays buffers. @end detailmenu @end menu @@ -1150,82 +1213,284 @@ case, you'll probably want to temporarily disable @section Sample Configuration @cindex configuration, sample -Here is an example of configuration settings for ERC@. This can go into -your Emacs configuration file. Everything after the @code{(require -'erc)} command can optionally go into @file{~/.emacs.d/.ercrc.el}. +Here is an example configuration for ERC@. @strong{Don't panic} if +you aren't familiar with @samp{use-package} or have no interest in +learning it. For our purposes, it's just a means of presenting +configuration details in a tidy, standardized format. If it helps, +just pretend it's some make-believe, pseudo configuration language. +Although the syntax below is easy enough to intuit and adapt to your +setup, you may wish to keep the following in mind (or @pxref{Top,,, +use-package,}): + +@itemize @bullet +@item +Each @code{use-package} ``declaration'' focuses on a library +``feature'', which is just a symbol you'd normally @code{require} in +your config @pxref{Named Features,,, elisp,}). + +@item +Emacs loads anything in a @code{:config} section @emph{after} loading +whatever library @code{provide}s the declaration's feature. + +@item +Everything in a @code{:custom} or @code{:custom-face} section is +basically something you'd find in your @code{custom-file}. +@end itemize + +@noindent +The following would typically go in your init file. Experienced users +may opt to keep any non-settings, like commands and functions, in a +dedicated @file{~/.emacs.d/.ercrc.el}. Whatever the case, please keep +in mind that you can replace nearly all of the following with Custom +settings (@pxref{Sample configuration via Customize}). @lisp -;;; Sample ERC configuration +;;; My ERC configuration -*- lexical-binding: t -*- -;; Load authentication info from an external source. Put sensitive -;; passwords and the like in here. -(load "~/.emacs.d/.erc-auth") +(use-package erc + :config + ;; Prefer SASL to NickServ, colorize nicknames, interpret mIRC colors, + ;; and list buffers and channel members in separate side panels. + (setopt erc-modules + (seq-union '(sasl nicks irccontrols bufbar nickbar scrolltobottom) + erc-modules)) -;; This is an example of how to make a new command. Type "/uptime" to -;; use it. -(defun erc-cmd-UPTIME (&rest ignore) - "Display the uptime of the system, as well as some load-related -stuff, to the current ERC buffer." - (let ((uname-output - (replace-regexp-in-string - ", load average: " "] @{Load average@} [" - ;; Collapse spaces, remove - (replace-regexp-in-string - " +" " " - ;; Remove beginning and trailing whitespace - (replace-regexp-in-string - "^ +\\|[ \n]+$" "" - (shell-command-to-string "uptime")))))) - (erc-send-message - (concat "@{Uptime@} [" uname-output "]")))) + :custom + ;; Protect me from accidentally sending excess lines. + (erc-inhibit-multiline-input t) + (erc-send-whitespace-lines t) + (erc-ask-about-multiline-input t) -;; This causes ERC to connect to the Libera.Chat network upon hitting -;; C-c e f. Replace MYNICK with your IRC nick. -(global-set-key "\C-cef" (lambda () (interactive) - (erc :server "irc.libera.chat" :port "6667" - :nick "MYNICK"))) + ;; Reconnect automatically using a fancy strategy. + (erc-server-reconnect-function #'erc-server-delayed-check-reconnect) + (erc-server-reconnect-timeout 30) -;; This causes ERC to connect to the IRC server on your own machine (if -;; you have one) upon hitting C-c e b. Replace MYNICK with your IRC -;; nick. Often, people like to run bitlbee (https://bitlbee.org/) as an -;; AIM/Jabber/MSN to IRC gateway, so that they can use ERC to chat with -;; people on those networks. -(global-set-key "\C-ceb" (lambda () (interactive) - (erc :server "localhost" :port "6667" - :nick "MYNICK"))) + ;; Insert a newline when I hit at the prompt, and prefer + ;; something more deliberate for actually sending messages. + :bind (:map erc-mode-map + ("RET" . nil) + ("C-c C-c" . #'erc-send-current-line)) -;; Make C-c RET (or C-c C-RET) send messages instead of RET. This has -;; been commented out to avoid confusing new users. -;; (define-key erc-mode-map (kbd "RET") nil) -;; (define-key erc-mode-map (kbd "C-c RET") 'erc-send-current-line) -;; (define-key erc-mode-map (kbd "C-c C-RET") 'erc-send-current-line) + ;; Emphasize buttonized text in notices. + :custom-face (erc-notice-face ((t (:slant italic :weight unspecified))))) -;;; Options +(use-package erc-sasl + ;; Since my account name is the same as my nick, free me from having + ;; to hit C-u before M-x erc to trigger a username prompt. + :custom (erc-sasl-user :nick)) -;; Join the #emacs and #erc channels whenever connecting to -;; Libera.Chat. -(setq erc-autojoin-channels-alist - '(("Libera.Chat" "#emacs" "#erc"))) +(use-package erc-join + ;; Join #emacs and #erc whenever I connect to Libera.Chat. + :custom (erc-autojoin-channels-alist '((Libera.Chat "#emacs" "#erc")))) -;; Interpret mIRC-style color commands in IRC chats -(setq erc-interpret-mirc-color t) +(use-package erc-fill + :custom + ;; Prefer one message per line without continuation indicators. + (erc-fill-function #'erc-fill-wrap) + (erc-fill-static-center 18) + + :bind (:map erc-fill-wrap-mode-map ("C-c =" . #'erc-fill-wrap-nudge))) + +(use-package erc-track + ;; Prevent JOINs and PARTs from lighting up the mode-line. + :config (setopt erc-track-faces-priority-list + (remq 'erc-notice-face erc-track-faces-priority-list)) + + :custom (erc-track-priority-faces-only 'all)) + +(use-package erc-goodies + ;; Turn on read indicators when joining channels. + :hook (erc-join . my-erc-enable-read-indicator-on-join)) + +(defvar my-erc-read-indicator-channels '("#emacs") + "Channels in which to show a `keep-place-indicator'.") + +(defun my-erc-enable-read-indicator-on-join () + "Enable read indicators for certain queries or channels." + (when (member (erc-default-target) my-erc-read-indicator-channels) + (erc-keep-place-indicator-mode +1))) + +;; Handy commands from the Emacs Wiki. +(defun erc-cmd-TRACK (&optional target) + "Start tracking TARGET or that of current buffer." + (setq erc-track-exclude (delete (or target (erc-default-target)) + erc-track-exclude))) + +(defun erc-cmd-UNTRACK (&optional target) + "Stop tracking TARGET or that of current buffer." + (setq erc-track-exclude (cl-pushnew (or target (erc-default-target)) + erc-track-exclude + :test #'equal))) -;; The following are commented out by default, but users of other -;; non-Emacs IRC clients might find them useful. -;; Kill buffers for channels after /part -;; (setq erc-kill-buffer-on-part t) -;; Kill buffers for private queries after quitting the server -;; (setq erc-kill-queries-on-quit t) -;; Kill buffers for server messages after quitting the server -;; (setq erc-kill-server-buffer-on-quit t) @end lisp +@noindent +Those familiar with @code{use-package} may have noticed the lack of +@code{:defer} keyword args. This was done to conserve space, but you +can just pretend that this user has enabled +@code{use-package-always-defer} elsewhere. + +@anchor{Sample configuration via Customize} +@subheading Via Customize +@cindex configuration, via customize + +As mentioned, Customize users can accomplish nearly all of the above +via the Customize interface. Start by running @kbd{M-x +customize-group @key{RET} erc @key{RET}}, and search for ``Modules'' +with @kbd{C-s modules @key{RET}}. Toggle open the flyout menu to +reveal the full ``widget'' panel, a web-form-like interface for ``Erc +Modules''. Tick the boxes for @samp{bufbar}, @samp{irccontrols}, +@samp{nickbar}, @samp{nicks}, @samp{sasl}, and @samp{scrolltobottom}. + +Next, search for the phrases ``Erc Ask About Multiline Input'', ``Erc +Inhibit Mulitline Input'', and ``Erc Send Whitespace Lines''. These +are the print names of three Boolean options that control how ERC +treats prompt input containing line breaks. When visiting each +option's section, twirl open its triangle icon to reveal its widget +UI, and click its @samp{[Toggle]} button to set its value to @code{t}. +While going about this, you may find it helpful to glance at the +descriptions just in case you want to disable them later. When +finished, hit @kbd{C-x C-s} or click @samp{[Apply and Save]} atop the +buffer. + +Now do the same for another couple options, this time having to do +with automatic reconnection. But instead of searching for their print +names, try running @kbd{M-x customize-option @key{RET} @samp{