procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

; * doc/misc/erc.texi: Improve Local Modules section.

Browse source
This commit is contained in:
F. Jason Park 2023-01-24 19:49:02 -08:00
parent 3846e79c93
commit 987e53f3e2
1 changed files with 33 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

47
doc/misc/erc.texi
View file

@ -539,36 +539,55 @@ so demands special precautions to avoid degrading the user experience.
At present, the only such module is @code{networks}, whose library ERC At present, the only such module is @code{networks}, whose library ERC
always loads anyway. always loads anyway.
@anchor{Local Modules}
@subheading Local Modules @subheading Local Modules
@cindex local modules @cindex local modules
All modules operate as minor modes under the hood, and some newer ones All modules operate as minor modes under the hood, and some newer ones
may be defined as buffer-local. These so-called ``local modules'' are may be defined as buffer-local. These so-called ``local modules'' are
a work in progress and their behavior and interface are subject to a work in progress and their behavior and interface are subject to
change. As of ERC 5.5, the only practical differences are change. As of ERC 5.5, the only practical differences are as follows:
@enumerate @enumerate
@item @item
``Control variables,'' like @code{erc-sasl-mode}, are stateful across ``Control variables,'' like @code{erc-sasl-mode}, retain their values
IRC sessions and override @code{erc-module} membership when influencing across IRC sessions and override @code{erc-module} membership when
module activation in new sessions. influencing module activation.
@item @item
Removing a local module from @code{erc-modules} via Customize not only Removing a local module from @code{erc-modules} via Customize not only
disables its mode but also kills its control variable in all ERC disables its mode but also kills its control variable in all ERC
buffers. buffers.
@item @item
``Mode toggles,'' like @code{erc-sasl-mode} and ``Mode toggles,'' like @code{erc-sasl-mode} and the complementary
@code{erc-sasl-enable}, behave differently relative to each other and @code{erc-sasl-enable}/@code{erc-sasl-disable} pairing, behave
to their global counterparts. (More on this just below.) differently than their global counterparts.
@end enumerate @end enumerate
By default, all local-mode toggles, like @code{erc-sasl-mode}, only In target buffers, a local module's activation state survives
affect the current buffer, but their ``non-mode'' variants, such as ``reassociation'' by default, but modules themselves always have the
@code{erc-sasl-enable}, operate on all buffers belonging to a final say. For example, a module may reset all instances of itself in
connection when called interactively. Keep in mind that whether its network context upon reconnecting. Moreover, the value of a mode
enabled or not, a module may effectively be ``inert'' in certain types variable may be meaningless in buffers that its module has no interest
of buffers, such as queries and channels. Whatever the case, a local in. For example, the value of @code{erc-sasl-mode} doesn't matter in
toggle never mutates @code{erc-modules}. target buffers and may even remain non-@code{nil} after SASL has been
disabled for the current connection (and vice versa).
When it comes to server buffers, a module's activation state only
persists for sessions revived via the automatic reconnection mechanism
or a manual @samp{/reconnect} issued at the prompt. In other words,
this doesn't apply to sessions revived by an entry-point command, such
as @code{erc-tls}, because such commands always ensure a clean slate
by looking only to @code{erc-modules}. Although a session revived in
this manner may indeed harvest other information from a previous
server buffer, it simply doesn't care which modules might have been
active during that connection.
Lastly, a local mode's toggle command, like @code{erc-sasl-mode}, only
affects the current buffer, but its ``non-mode'' cousins, like
@code{erc-sasl-enable} and @code{erc-sasl-disable}, operate on all
buffers belonging to their connection (when called interactively).
And unlike global toggles, none of these ever mutates
@code{erc-modules}.
@c PRE5_4: Document every option of every module in its own subnode @c PRE5_4: Document every option of every module in its own subnode