From f4c11edc86f16b7ce88c33dc6112e17e751171dc Mon Sep 17 00:00:00 2001 From: grtcdr Date: Thu, 19 Sep 2024 07:51:22 +0100 Subject: [PATCH] Rename MANUAL to the name of the library This will improve support for the Borg package manager which only installs info files if the file stem is equivalent to the name of the library. --- MANUAL.md | 167 ----------------------- MANUAL.texi | 268 ------------------------------------ darkman.info | 276 ++++++++++++++++++++++++++++++++++++++ MANUAL.org => darkman.org | 0 4 files changed, 276 insertions(+), 435 deletions(-) delete mode 100644 MANUAL.md delete mode 100644 MANUAL.texi create mode 100644 darkman.info rename MANUAL.org => darkman.org (100%) diff --git a/MANUAL.md b/MANUAL.md deleted file mode 100644 index f6d1e6f..0000000 --- a/MANUAL.md +++ /dev/null @@ -1,167 +0,0 @@ - - - - -This is the manual for `darkman.el` version 1.1.0. - -- Homepage: -- Repository: -- Mailing list: -- Issue tracker: - - -# GNU Free Documentation License - -Copyright (C) 2023 Taha Aziz Ben Ali. - -> 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, no Front-Cover Texts, and no Back-Cover Texts. A -> copy of the license is included in the section entitled "GNU Free -> Documentation License". - - -# Installation - -This package is available from [MELPA](https://melpa.org) provided you've added that to the -list of package archives to fetch from, install it by evaluating the -following: - - (package-install 'darkman) - -For a manual installation, begin by cloning the repository: - - git clone --branch 1.0.3 https://github.com/grtcdr/darkman.el darkman - -Next, add the package to your [load path](https://www.gnu.org/software/emacs/manual/html_node/emacs/Lisp-Libraries.html): - - (add-to-list 'load-path "darkman") - -Finally, require the package like so: - - (require 'darkman) - - -# Usage - -In your `init.el` file, define which theme is associated with which -mode. By default, `modus-themes` will be used, but we'll choose the -`tango` variants in this example. - - (setq darkman-themes '(:light tango :dark tango-dark)) - -You can also use `M-x customize-group darkman RET` to customize the -variable. - -`darkman` can listen for any signals to change the theme without -requiring you to manually create any scripts. You can enable this -behavior by enabling the minor mode: - - (darkman-mode) - -You should not call `load-theme` in your configuration as -`darkman-mode` when enabled will do that for you, even on startup. - - -## Other functions - -`M-x darkman-toggle` will toggle the mode of the Darkman service from -within Emacs. - -Additionally, you can use the `darkman-get` and `darkman-set` -functions to manually get and set the mode of the service -respectively. - - -# Tips - - -## Working alongside the built-in safety features - -`load-theme` is part of the `custom` library and it comes with certain -[security features](emacs#Custom Themes) that you may regard as inconvenient, but they're -absolutely necessary to preserve the security of your system. We have -decided to work hand in hand with these pre-existing safety mechanisms -in lieu of implementing our own. - -Problems may arise 1 if this package is loaded in a [server -setting](emacs#Emacs Server) and too early during the initialization phase, i.e. before -`custom-file`, you can prevent this from happening by activating the -mode **only** when the session has been fully initialized: - - (when (daemonp) - (add-hook 'server-after-make-frame-hook #'darkman-mode) - (advice-add 'darkman-mode - :after - (lambda () - (remove-hook 'server-after-make-frame-hook - #'darkman-mode)))) - - -## Working alongside the third-party `spacious-padding` package - -`spacious-padding` significantly improves the aesthetics of our beloved Emacs by -padding the windows and mode line. I've personally encountered an issue that -made `spacious-padding` behave incorrectly when (1) used in conjuction with -`darkman-mode` and (2) when Emacs is started as a daemon, resulting in -window/mode line borders being assigned the wrong color. - -I found, through trial and error, that simply delaying the activation of -`spacious-padding` when started in daemon mode until the first frame has -appeared solved the problem. - - (if (daemonp) - (add-hook 'server-after-make-frame-hook #'spacious-padding-mode) - (spacious-padding-mode)) - - -## Disabling existing themes - -Emacs does not by default disable the current theme when another one -is loaded, and while this behavior might seem counter-intuitive, we -can always advise `darkman-set` (and by extension `darkman-toggle`), or -even `load-theme` if you prefer, to disable any existing themes first. - - (defadvice darkman-set (before no-theme-stacking activate) - "Disable the previous theme before loading a new one." - (mapc #'disable-theme custom-enabled-themes)) - - -# Debugging - - -## Is D-Bus running? - -Use your service manager to verify whether the `darkman` service is running, -here's an example using `systemd`: - - systemctl status dbus - - dbus.service - D-Bus System Message Bus - Loaded: loaded - Active: active (running) - - -## Is Darkman running? - -Use your service manager to verify whether the `darkman` service is running, -here's an example using `systemd`: - - systemctl status --user darkman - - darkman.service - Framework for dark-mode and light-mode transitions. - Loaded: loaded - Active: active (running) - - -## Is Emacs built with D-Bus support? - -Usually it is, unless you're building from source, in which case you -can verify whether or not Emacs was built with D-Bus support using -`C-h v system-configuration-features RET` which should list `DBUS`. - - -# Footnotes - -1 This is [known to happen](https://github.com/grtcdr/darkman.el/pull/7#issuecomment-1422666665) in Doom Emacs. diff --git a/MANUAL.texi b/MANUAL.texi deleted file mode 100644 index ebcc6d3..0000000 --- a/MANUAL.texi +++ /dev/null @@ -1,268 +0,0 @@ -\input texinfo @c -*- texinfo -*- -@c %**start of header -@setfilename darkman.info -@settitle Darkman for Emacs -@documentencoding UTF-8 -@documentlanguage en -@c %**end of header - -@copying -Copyright (C) 2023 Taha Aziz Ben Ali. - -@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, no Front-Cover Texts, and no Back-Cover Texts. A -copy of the license is included in the section entitled "GNU Free -Documentation License". - -@end quotation -@end copying - -@dircategory Emacs misc features -@direntry -* Darkman: (darkman). Seamless integration with Darkman using the D-Bus protocol. -@end direntry - -@finalout -@titlepage -@title Darkman for Emacs -@author Taha Aziz Ben Ali -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@ifnottex -@node Top -@top Darkman for Emacs - - - - -This is the manual for @samp{darkman.el} version 1.1.0. - -@itemize -@item -Homepage: @uref{https://darkman.grtcdr.tn} -@item -Repository: @uref{https://git.sr.ht/~grtcdr/darkman.el} -@item -Mailing list: @uref{https://lists.sr.ht/~grtcdr/pub} -@item -Issue tracker: @uref{https://todo.sr.ht/~grtcdr/darkman.el} -@end itemize -@end ifnottex - -@menu -* Installation:: -* Usage:: -* Tips:: -* Debugging:: - -@detailmenu ---- The Detailed Node Listing --- - -Usage - -* Other functions:: - -Tips - -* Working alongside the built-in safety features:: -* Working alongside the third-party @samp{spacious-padding} package:: -* Disabling existing themes:: - -Debugging - -* Is D-Bus running?:: -* Is Darkman running?:: -* Is Emacs built with D-Bus support?:: - -@end detailmenu -@end menu - -@node Installation -@chapter Installation - -This package is available from @uref{https://melpa.org, MELPA} provided you've added that to the -list of package archives to fetch from, install it by evaluating the -following: - -@lisp -(package-install 'darkman) -@end lisp - -For a manual installation, begin by cloning the repository: - -@example -git clone --branch 1.0.3 https://github.com/grtcdr/darkman.el darkman -@end example - -Next, add the package to your @uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Lisp-Libraries.html, load path}: - -@lisp -(add-to-list 'load-path "darkman") -@end lisp - -Finally, require the package like so: - -@lisp -(require 'darkman) -@end lisp - -@node Usage -@chapter Usage - -In your @samp{init.el} file, define which theme is associated with which -mode. By default, @samp{modus-themes} will be used, but we'll choose the -@samp{tango} variants in this example. - -@lisp -(setq darkman-themes '(:light tango :dark tango-dark)) -@end lisp - -You can also use @samp{M-x customize-group darkman RET} to customize the -variable. - -@code{darkman} can listen for any signals to change the theme without -requiring you to manually create any scripts. You can enable this -behavior by enabling the minor mode: - -@lisp -(darkman-mode) -@end lisp - -You should not call @code{load-theme} in your configuration as -@code{darkman-mode} when enabled will do that for you, even on startup. - -@menu -* Other functions:: -@end menu - -@node Other functions -@section Other functions - -@samp{M-x darkman-toggle} will toggle the mode of the Darkman service from -within Emacs. - -Additionally, you can use the @code{darkman-get} and @code{darkman-set} -functions to manually get and set the mode of the service -respectively. - -@node Tips -@chapter Tips - -@menu -* Working alongside the built-in safety features:: -* Working alongside the third-party @samp{spacious-padding} package:: -* Disabling existing themes:: -@end menu - -@node Working alongside the built-in safety features -@section Working alongside the built-in safety features - -@code{load-theme} is part of the @code{custom} library and it comes with certain -@ref{Custom Themes,security features,,emacs,} that you may regard as inconvenient, but they're -absolutely necessary to preserve the security of your system. We have -decided to work hand in hand with these pre-existing safety mechanisms -in lieu of implementing our own. - -Problems may arise @footnote{This is @uref{https://github.com/grtcdr/darkman.el/pull/7#issuecomment-1422666665, known to happen} in Doom Emacs.} if this package is loaded in a @ref{Emacs Server,server -setting,,emacs,} and too early during the initialization phase, i.e. before -@code{custom-file}, you can prevent this from happening by activating the -mode @strong{only} when the session has been fully initialized: - -@lisp -(when (daemonp) - (add-hook 'server-after-make-frame-hook #'darkman-mode) - (advice-add 'darkman-mode - :after - (lambda () - (remove-hook 'server-after-make-frame-hook - #'darkman-mode)))) -@end lisp - -@node Working alongside the third-party @samp{spacious-padding} package -@section Working alongside the third-party @samp{spacious-padding} package - -@samp{spacious-padding} significantly improves the aesthetics of our beloved Emacs by -padding the windows and mode line. I've personally encountered an issue that -made @samp{spacious-padding} behave incorrectly when (1) used in conjuction with -@samp{darkman-mode} and (2) when Emacs is started as a daemon, resulting in -window/mode line borders being assigned the wrong color. - -I found, through trial and error, that simply delaying the activation of -@samp{spacious-padding} when started in daemon mode until the first frame has -appeared solved the problem. - -@lisp -(if (daemonp) - (add-hook 'server-after-make-frame-hook #'spacious-padding-mode) - (spacious-padding-mode)) -@end lisp - -@node Disabling existing themes -@section Disabling existing themes - -Emacs does not by default disable the current theme when another one -is loaded, and while this behavior might seem counter-intuitive, we -can always advise @code{darkman-set} (and by extension @code{darkman-toggle}), or -even @code{load-theme} if you prefer, to disable any existing themes first. - -@lisp -(defadvice darkman-set (before no-theme-stacking activate) - "Disable the previous theme before loading a new one." - (mapc #'disable-theme custom-enabled-themes)) -@end lisp - -@node Debugging -@chapter Debugging - -@menu -* Is D-Bus running?:: -* Is Darkman running?:: -* Is Emacs built with D-Bus support?:: -@end menu - -@node Is D-Bus running? -@section Is D-Bus running? - -Use your service manager to verify whether the @samp{darkman} service is running, -here's an example using @samp{systemd}: - -@example -systemctl status dbus -@end example - -@example -dbus.service - D-Bus System Message Bus - Loaded: loaded - Active: active (running) -@end example - -@node Is Darkman running? -@section Is Darkman running? - -Use your service manager to verify whether the @samp{darkman} service is running, -here's an example using @samp{systemd}: - -@example -systemctl status --user darkman -@end example - -@example -darkman.service - Framework for dark-mode and light-mode transitions. - Loaded: loaded - Active: active (running) -@end example - -@node Is Emacs built with D-Bus support? -@section Is Emacs built with D-Bus support? - -Usually it is, unless you're building from source, in which case you -can verify whether or not Emacs was built with D-Bus support using -@samp{C-h v system-configuration-features RET} which should list @samp{DBUS}. - -@bye \ No newline at end of file diff --git a/darkman.info b/darkman.info new file mode 100644 index 0000000..a77e23f --- /dev/null +++ b/darkman.info @@ -0,0 +1,276 @@ +This is darkman.info, produced by makeinfo version 7.1.1 from +darkman.texi. + +Copyright (C) 2023 Taha Aziz Ben Ali. + + 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, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". + +INFO-DIR-SECTION Emacs misc features +START-INFO-DIR-ENTRY +* Darkman: (darkman). Seamless integration with Darkman using the D-Bus protocol. +END-INFO-DIR-ENTRY + + +File: darkman.info, Node: Top, Next: Installation, Up: (dir) + +Darkman for Emacs +***************** + +This is the manual for ‘darkman.el’ version 1.1.0. + + • Homepage: + • Repository: + • Mailing list: + • Issue tracker: + +* Menu: + +* Installation:: +* Usage:: +* Tips:: +* Debugging:: + +-- The Detailed Node Listing -- + +Usage + +* Other functions:: + +Tips + +* Working alongside the built-in safety features:: +* Working alongside the third-party spacious-padding package:: +* Disabling existing themes:: + +Debugging + +* Is D-Bus running?:: +* Is Darkman running?:: +* Is Emacs built with D-Bus support?:: + + + +File: darkman.info, Node: Installation, Next: Usage, Prev: Top, Up: Top + +1 Installation +************** + +This package is available from MELPA (https://melpa.org) provided you've +added that to the list of package archives to fetch from, install it by +evaluating the following: + + (package-install 'darkman) + + For a manual installation, begin by cloning the repository: + + git clone --branch 1.0.3 https://github.com/grtcdr/darkman.el darkman + + Next, add the package to your load path +(https://www.gnu.org/software/emacs/manual/html_node/emacs/Lisp-Libraries.html): + + (add-to-list 'load-path "darkman") + + Finally, require the package like so: + + (require 'darkman) + + +File: darkman.info, Node: Usage, Next: Tips, Prev: Installation, Up: Top + +2 Usage +******* + +In your ‘init.el’ file, define which theme is associated with which +mode. By default, ‘modus-themes’ will be used, but we'll choose the +‘tango’ variants in this example. + + (setq darkman-themes '(:light tango :dark tango-dark)) + + You can also use ‘M-x customize-group darkman RET’ to customize the +variable. + + ‘darkman’ can listen for any signals to change the theme without +requiring you to manually create any scripts. You can enable this +behavior by enabling the minor mode: + + (darkman-mode) + + You should not call ‘load-theme’ in your configuration as +‘darkman-mode’ when enabled will do that for you, even on startup. + +* Menu: + +* Other functions:: + + +File: darkman.info, Node: Other functions, Up: Usage + +2.1 Other functions +=================== + +‘M-x darkman-toggle’ will toggle the mode of the Darkman service from +within Emacs. + + Additionally, you can use the ‘darkman-get’ and ‘darkman-set’ +functions to manually get and set the mode of the service respectively. + + +File: darkman.info, Node: Tips, Next: Debugging, Prev: Usage, Up: Top + +3 Tips +****** + +* Menu: + +* Working alongside the built-in safety features:: +* Working alongside the third-party spacious-padding package:: +* Disabling existing themes:: + + +File: darkman.info, Node: Working alongside the built-in safety features, Next: Working alongside the third-party spacious-padding package, Up: Tips + +3.1 Working alongside the built-in safety features +================================================== + +‘load-theme’ is part of the ‘custom’ library and it comes with certain +*note security features: (emacs)Custom Themes. that you may regard as +inconvenient, but they're absolutely necessary to preserve the security +of your system. We have decided to work hand in hand with these +pre-existing safety mechanisms in lieu of implementing our own. + + Problems may arise (1) if this package is loaded in a *note server +setting: (emacs)Emacs Server. and too early during the initialization +phase, i.e. before ‘custom-file’, you can prevent this from happening +by activating the mode *only* when the session has been fully +initialized: + + (when (daemonp) + (add-hook 'server-after-make-frame-hook #'darkman-mode) + (advice-add 'darkman-mode + :after + (lambda () + (remove-hook 'server-after-make-frame-hook + #'darkman-mode)))) + + ---------- Footnotes ---------- + + (1) This is known to happen +(https://github.com/grtcdr/darkman.el/pull/7#issuecomment-1422666665) in +Doom Emacs. + + +File: darkman.info, Node: Working alongside the third-party spacious-padding package, Next: Disabling existing themes, Prev: Working alongside the built-in safety features, Up: Tips + +3.2 Working alongside the third-party ‘spacious-padding’ package +================================================================ + +‘spacious-padding’ significantly improves the aesthetics of our beloved +Emacs by padding the windows and mode line. I've personally encountered +an issue that made ‘spacious-padding’ behave incorrectly when (1) used +in conjuction with ‘darkman-mode’ and (2) when Emacs is started as a +daemon, resulting in window/mode line borders being assigned the wrong +color. + + I found, through trial and error, that simply delaying the activation +of ‘spacious-padding’ when started in daemon mode until the first frame +has appeared solved the problem. + + (if (daemonp) + (add-hook 'server-after-make-frame-hook #'spacious-padding-mode) + (spacious-padding-mode)) + + +File: darkman.info, Node: Disabling existing themes, Prev: Working alongside the third-party spacious-padding package, Up: Tips + +3.3 Disabling existing themes +============================= + +Emacs does not by default disable the current theme when another one is +loaded, and while this behavior might seem counter-intuitive, we can +always advise ‘darkman-set’ (and by extension ‘darkman-toggle’), or even +‘load-theme’ if you prefer, to disable any existing themes first. + + (defadvice darkman-set (before no-theme-stacking activate) + "Disable the previous theme before loading a new one." + (mapc #'disable-theme custom-enabled-themes)) + + +File: darkman.info, Node: Debugging, Prev: Tips, Up: Top + +4 Debugging +*********** + +* Menu: + +* Is D-Bus running?:: +* Is Darkman running?:: +* Is Emacs built with D-Bus support?:: + + +File: darkman.info, Node: Is D-Bus running?, Next: Is Darkman running?, Up: Debugging + +4.1 Is D-Bus running? +===================== + +Use your service manager to verify whether the ‘darkman’ service is +running, here's an example using ‘systemd’: + + systemctl status dbus + + dbus.service - D-Bus System Message Bus + Loaded: loaded + Active: active (running) + + +File: darkman.info, Node: Is Darkman running?, Next: Is Emacs built with D-Bus support?, Prev: Is D-Bus running?, Up: Debugging + +4.2 Is Darkman running? +======================= + +Use your service manager to verify whether the ‘darkman’ service is +running, here's an example using ‘systemd’: + + systemctl status --user darkman + + darkman.service - Framework for dark-mode and light-mode transitions. + Loaded: loaded + Active: active (running) + + +File: darkman.info, Node: Is Emacs built with D-Bus support?, Prev: Is Darkman running?, Up: Debugging + +4.3 Is Emacs built with D-Bus support? +====================================== + +Usually it is, unless you're building from source, in which case you can +verify whether or not Emacs was built with D-Bus support using ‘C-h v +system-configuration-features RET’ which should list ‘DBUS’. + + + +Tag Table: +Node: Top678 +Node: Installation1429 +Node: Usage2117 +Node: Other functions2910 +Node: Tips3244 +Node: Working alongside the built-in safety features3490 +Ref: Working alongside the built-in safety features-Footnote-14717 +Node: Working alongside the third-party spacious-padding package4834 +Node: Disabling existing themes5843 +Node: Debugging6511 +Node: Is D-Bus running?6694 +Node: Is Darkman running?7082 +Node: Is Emacs built with D-Bus support?7557 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff --git a/MANUAL.org b/darkman.org similarity index 100% rename from MANUAL.org rename to darkman.org -- 2.45.2