branch: elpa/casual
commit e1d7e8769d73e5222d6cd9e03b0749cab532464e
Author: Charles Choi <[email protected]>
Commit: Charles Choi <[email protected]>
Support batch processing of Casual documentation
This commit includes changes to automate the generation of Info and HTML
documentation for Casual.
---
.github/workflows/basic.yml | 7 +-
.github/workflows/pages.yml | 4 +
Makefile | 6 +-
docs/Makefile | 21 +-
docs/casual.info | Bin 148775 -> 0 bytes
docs/casual.org | 2 +-
docs/casual.texi | 3709 -------------------------------------------
docs/casualdocs.el | 138 ++
8 files changed, 169 insertions(+), 3718 deletions(-)
diff --git a/.github/workflows/basic.yml b/.github/workflows/basic.yml
index 77973a3dea..85c8c2911d 100644
--- a/.github/workflows/basic.yml
+++ b/.github/workflows/basic.yml
@@ -25,6 +25,11 @@ jobs:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can
access it
- uses: actions/checkout@v4
+ - name: Install Emacs
+ run: |
+ sudo apt-get update
+ sudo apt-get install emacs
+
# Runs a single command using the runners shell
- name: Run a one-line script
run: echo Hello, world!
@@ -33,5 +38,5 @@ jobs:
- name: Run a multi-line script
run: |
echo Generating Casual User Guide
- make -C docs gen-html
+ make -C docs gen-info gen-html
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 45f8d14deb..428883b1d4 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -31,6 +31,10 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v4
+ - name: Install Emacs
+ run: |
+ sudo apt-get update
+ sudo apt-get install emacs
- name: Setup Pages
uses: actions/configure-pages@v5
- name: Generate Casual User Guide
diff --git a/Makefile b/Makefile
index 13662e254b..e8d0fe8ea9 100644
--- a/Makefile
+++ b/Makefile
@@ -76,12 +76,12 @@ tests:
bump-casual:
sed -i 's/;; Version: $(VERSION)/;; Version: $(VERSION_BUMP)/'
$(MAIN_EL)
-bump-casual-info: VERSION_BUMP:=$(shell python -m semver nextver $(VERSION)
$(BUMP_LEVEL))
+# bump-casual-info: VERSION_BUMP:=$(shell python -m semver nextver $(VERSION)
$(BUMP_LEVEL))
bump-casual-info:
sed -i 's/+MACRO: version $(VERSION)/+MACRO: version $(VERSION_BUMP)/'
docs/casual.org
-bump: bump-casual
- git commit -m 'Bump version to $(VERSION_BUMP)' $(MAIN_EL)
+bump: bump-casual bump-casual-info
+ git commit -m 'Bump version to $(VERSION_BUMP)' $(MAIN_EL)
docs/casual.org
git push
checkout-development:
diff --git a/docs/Makefile b/docs/Makefile
index 2e22414315..73eba78d11 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -14,6 +14,12 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <https://www.gnu.org/licenses/>.
+ifdef EMACS_APP_EXEC
+ EXEC_NAME=$(EMACS_APP_EXEC)
+else
+ EXEC_NAME=emacs
+endif
+
TIMESTAMP := $(shell /bin/date "+%Y%m%d_%H%M%S")
PKG_NAME=casual
@@ -24,14 +30,21 @@ $(PKG_NAME).info: $(PKG_NAME).texi
run: $(PKG_NAME).info
.PHONY: clean
-clean:
- - rm $(PKG_NAME).texi
+clean: clean-html
+ - rm $(PKG_NAME).texi $(PKG_NAME).info
+
+.PHONY: gen-info
+gen-info:
+ $(EXEC_NAME) -Q --batch
\
+-l casualdocs.el
\
+casual.org
\
+--eval "(with-current-buffer (find-file-noselect \"casual.org\")
(org-texinfo-export-to-info))"
html:
mkdir html
.PHONY: gen-html
-gen-html: html html/images html/main.css sync-images
+gen-html: gen-info html html/images html/main.css sync-images
makeinfo \
--html \
--css-ref=main.css \
@@ -54,7 +67,7 @@ html/main.css: main.css
.PHONY: clean-html
clean-html:
- rm -rf html
+ - rm -rf html
.PHONY: open-html
open-html:
diff --git a/docs/casual.info b/docs/casual.info
deleted file mode 100644
index 2f5072094b..0000000000
Binary files a/docs/casual.info and /dev/null differ
diff --git a/docs/casual.org b/docs/casual.org
index 5af1a47240..c8bc38ea25 100644
--- a/docs/casual.org
+++ b/docs/casual.org
@@ -5,7 +5,7 @@
#+EMAIL: [email protected]
#+OPTIONS: ':t toc:t author:t email:t H:4 f:t
#+LANGUAGE: en
-#+MACRO: version 2.11.2
+#+MACRO: version 2.11.3-rc.1
#+MACRO: kbd (eval (org-texinfo-kbd-macro $1))
#+TEXINFO_FILENAME: casual.info
#+TEXINFO_CLASS: casual
diff --git a/docs/casual.texi b/docs/casual.texi
deleted file mode 100644
index b4424867d3..0000000000
--- a/docs/casual.texi
+++ /dev/null
@@ -1,3709 +0,0 @@
-\input texinfo @c -*- texinfo -*-
-@c %**start of header
-@setfilename casual.info
-@settitle Casual User Guide
-@documentencoding UTF-8
-@documentlanguage en
-@syncodeindex pg cp
-@paragraphindent none
-@c %**end of header
-
-@copying
-Copyright © 2024-2025 Charles Y@. Choi
-@end copying
-
-@dircategory Emacs misc features
-@direntry
-* Casual: (casual). Transient user interfaces for different Emacs modes.
-@end direntry
-
-@finalout
-@titlepage
-@title Casual User Guide
-@subtitle for version 2.11.2
-@author Charles Y@. Choi (@email{kickingvegas@@gmail.com})
-@page
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-
-@contents
-
-@ifnottex
-@node Top
-@top Casual User Guide
-
-Version: 2.11.2
-
-Copyright © 2024-2026 @w{Charles Y. Choi}
-
-Casual is a project to re-imagine the primary user interface for Emacs using
keyboard-driven menus.
-
-Emacs has many commands that are easy to forget if not used frequently. Menus
are a user interface (UI) affordance that offers discoverability and
recognition. While menus are commonly associated with mouse-driven UI, the
inclusion of Transient (@ref{Top,,,transient,}) in Emacs core allows for
building menus that are keyboard-driven instead. This appeals to users that
prefer keyboard-driven workflows.
-
-Casual organizes itself primarily around the different built-in modes Emacs
provides. For each mode Casual supports, there is a bespoke designed library of
Transient menus for that mode's command set.
-
-Casual has no aims to be a mutually exclusive user interface. All existing
user interfaces to commands (keybinding, mini-buffer prompt, mouse menus) are
still available to the user.
-
-To learn more about the motivations and design considerations for Casual and
to see it at work, please watch the presentation
@uref{https://emacsconf.org/2024/talks/casual/, “Re-imagining the Emacs User
Experience with Casual Suite”} from EmacsConf 2024.
-
-@emph{Example Casual menu - Dired}
-
-@image{images/casual-dired-screenshot,,,,png}
-
-@emph{Example Casual menu - EditKit}
-
-@image{images/casual-editkit-main-screenshot,,,,png}
-
-@emph{Example Casual menu - Calc}
-
-@image{images/casual-calc-tmenu,,,,png}
-
-It costs money to make, enhance, and maintain Casual as ideologically free
software. If you enjoy using Casual, please buy me a coffee to help support its
development and maintenance.
-
-@image{images/default-yellow,,,,png}
-
-@uref{https://www.buymeacoffee.com/kickingvegas}
-
-@end ifnottex
-
-@menu
-* Introduction::
-* Requirements::
-* Install::
-* UX Conventions::
-* Casual Modes::
-* Customization::
-* Feedback & Discussion::
-* Sponsorship::
-* About Casual::
-* Acknowledgments::
-* Main Index::
-* Variable Index::
-
-@detailmenu
---- The Detailed Node Listing ---
-
-Introduction
-
-* Motivations::
-* Transient Conventions::
-
-Install
-
-* A Note on Package Dependencies::
-* Upgrading to Casual 1.x to 2.x: Upgrading to Casual 1x to 2x.
-
-Upgrading to Casual 1.x to 2.x
-
-* If you do not use @code{use-package} to configure Casual::
-* If you have used @code{use-package} to configure Casual::
-
-Casual Modes
-
-* Agenda::
-* Bib@TeX{}::
-* Bookmarks::
-* Calc::
-* Calendar::
-* Compile::
-* CSS::
-* CSV::
-* Dired::
-* Ediff::
-* EditKit::
-* Elisp::
-* Eshell::
-* Help::
-* HTML::
-* IBuffer::
-* Image::
-* Info::
-* I-Search::
-* Make::
-* Man::
-* RE-Builder::
-* Timezone::
-
-Agenda
-
-* Agenda Install::
-* Agenda Usage::
-
-Bib@TeX{}
-
-* Bib@TeX{} Install::
-* Bib@TeX{} Usage::
-
-Bib@TeX{} Usage
-
-* Bib@TeX{} Navigation::
-* Creating, Updating, and Deleting Bib@TeX{} Structures: Creating Updating and
Deleting Bib@TeX{} Structures.
-* Bib@TeX{} Settings::
-
-Bookmarks
-
-* Bookmarks Install::
-* Bookmarks Usage::
-
-Calc
-
-* Calc Install::
-* Calc Usage::
-
-Calendar
-
-* Calendar Install::
-* Calendar Usage::
-
-Calendar Usage
-
-* Diary & Goto Menu::
-* Calendar System Date Conversion::
-* Calendar Settings Menu::
-* Calendar Unicode Symbol Support::
-
-Compile
-
-* Compile Install::
-* Compile Usage::
-
-CSS
-
-* CSS Install::
-* CSS Usage::
-
-CSV
-
-* CSV Install::
-* CSV Usage::
-
-Dired
-
-* Dired Requirements::
-* Dired Install::
-* Dired Usage::
-
-Dired Requirements
-
-* macOS::
-* Windows::
-
-Dired Usage
-
-* Dired Enhanced Sorting::
-* Dired Search & Replace::
-* Bulk Dired Operations::
-* Dired Link::
-* Dired Unicode Symbol Support::
-
-Ediff
-
-* Ediff Install::
-* Ediff Usage::
-
-Ediff Usage
-
-* Ediff Basic Operation::
-* Comparing a Version-Controlled File::
-* Resolving a Merge Conflict::
-* Ediff Unicode Symbol Support::
-
-EditKit
-
-* EditKit Install::
-* EditKit Usage::
-
-EditKit Usage
-
-* Register commands::
-* Edit commands::
-* Window management::
-* Search & Replace commands::
-* Open commands::
-* Project commands::
-* Bookmark commands::
-* Emoji & Symbol Insertion::
-* Tool commands::
-* Narrow/Widen Commands::
-* Macro::
-* EditKit Settings::
-
-Elisp
-
-* Elisp Install::
-* Elisp Usage::
-
-Eshell
-
-* Eshell Install::
-* Eshell Usage::
-
-Help
-
-* Help Install::
-* Help Usage::
-
-HTML
-
-* HTML Install::
-* HTML Usage::
-
-IBuffer
-
-* IBuffer Install::
-* IBuffer Usage::
-
-IBuffer Usage
-
-* IBuffer Marking and Operating::
-* IBuffer Filtering::
-* IBuffer Sorting::
-* IBuffer Unicode Symbol Support::
-
-Image
-
-* Image Install::
-* Image Usage::
-
-Image Usage
-
-* Image Resize::
-* Image Unicode Symbol Support::
-* Image Mode Command Naming::
-
-Info
-
-* Info Install::
-* Info Usage::
-
-I-Search
-
-* I-Search Install::
-* I-Search Usage::
-
-Make
-
-* Make Install::
-* Make Usage::
-
-Make Usage
-
-* Makefile Type Selection::
-* Automatic Variables::
-* Make Unicode Symbol Support::
-
-Man
-
-* Man Install::
-* Man Usage::
-
-RE-Builder
-
-* RE-Builder Install::
-* RE-Builder Usage::
-
-Timezone
-
-* Timezone Install::
-* Timezone Usage::
-
-Timezone Usage
-
-* Timezone Formatting::
-* Planner Configuration::
-* Zoneinfo Database::
-* Timezone Unicode Symbol Support::
-
-@end detailmenu
-@end menu
-
-@node Introduction
-@chapter Introduction
-
-@cindex Introduction
-
-@menu
-* Motivations::
-* Transient Conventions::
-@end menu
-
-@node Motivations
-@section Motivations
-
-@cindex Motivations
-
-@subheading Goals
-
-@itemize
-@item
-To provide a keyboard-driven menu UI toolkit for common Emacs commands.
-
-@item
-To allow for casual discovery and use of infrequently used Emacs commands.
-
-@item
-To be a frequently used interface for modes supported by Casual.
-@end itemize
-
-
-@subheading Non-Goals
-
-@itemize
-@item
-Full coverage of all Emacs commands.
-
-Casual is not intended to be a power user tool nor is it intended to be a
replacement for mouse-driven menus. Casual has no intent to exhaustively cover
all modes available in Emacs with keyboard-driven menus.
-
-@item
-Strict adherence to Emacs command naming.
-
-While Casual is @strong{mostly} in alignment with Emacs command naming, there
are cases where it will make an opinionated change if the name is deemed too
vague or idiomatic.
-
-@item
-No intention is made by Casual to help on-board users to the existing default
bindings of a mode, nor cater to users who already know them.
-
-That said, many existing default Emacs bindings are replicated in Casual. Such
correspondence should be considered incidental.
-
-@item
-UX Stability (for now).
-
-Given that Casual is early in its life-cycle, expect changes to its user
experience in terms of menu hierarchy and keybinding choices in future releases.
-@end itemize
-
-Editorially, all design decisions for Casual are ultimately the opinion of
Charles Y@. Choi.
-
-@node Transient Conventions
-@section Transient Conventions
-
-@cindex Transient Conventions
-
-Casual is built using Transient menus and as such adopts its default behavior.
-
-Each menu item has a key and a label. The key is what is typed by the user to
select the menu item. A key can be prefixed with a meta @kbd{M-} or control
@kbd{C-} key.
-
-Transient supports nested menus. Exiting a menu can be done in two ways:
-
-@itemize
-@item
-@kbd{C-g} (@code{transient-quit-one}) will exit the current sub-menu and
return you back to its parent menu.
-
-@item
-@kbd{C-q} (@code{transient-quit-all}) will exit you completely from a
Transient menu stack.
-@end itemize
-
-If a mouse is available, a menu item can be selected by moving the mouse
cursor over its label and pressing down button 1.
-
-Pressing the @kbd{?} key or @kbd{C-h} will toggle help for all the menu items.
Press the key of interest to get help for it.
-
-When a Transient menu is raised, a command prefix argument (@kbd{C-u}) and an
optional argument can be entered before selecting a menu item. Menu items which
particularly use a command prefix are annotated with the ✦ glyph. The command
prefix can be cancelled with @kbd{C-g}.
-
-For Transient menus that offer setting different values, the following
bindings will allow you save them:
-
-@itemize
-@item
-@kbd{C-x s} (@code{transient-set})
-
-Saves the value of the active transient for this Emacs session.
-
-@item
-@kbd{C-x C-s} (@code{transient-save})
-
-Saves the value of the active transient persistently across Emacs sessions.
-
-@item
-@kbd{C-x C-k} (@code{transient-reset})
-
-Clears the set and saved values of the active transient.
-@end itemize
-
-@subheading References
-
-@itemize
-@item
-@ref{Aborting and Resuming Transients,,,transient,}
-
-@item
-@ref{Saving Values,,,transient,}
-@end itemize
-
-@node Requirements
-@chapter Requirements
-
-@cindex Requirements
-
-Casual requires Emacs 29.1+, Transient 0.9.0+.
-
-Certain menus require more installed software:
-
-@itemize
-@item
-Casual Dired: GNU Coreutils
-@item
-Casual Image: ImageMagick 6+
-@end itemize
-
-@node Install
-@chapter Install
-
-@cindex Install
-
-Standard installation of the @code{casual} package is via
@uref{https://melpa.org/#/casual, MELPA distribution}.
-
-Configuration of a particular Casual user interface is performed per mode. Go
to the @strong{Install} section for a mode of interest below for guidance on
its configuration.
-
-@itemize
-@item
-@ref{Agenda Install, , Agenda}
-@item
-@ref{Bib@TeX{} Install, , Bib@TeX{}}
-@item
-@ref{Bookmarks Install, , Bookmarks}
-@item
-@ref{Calc Install, , Calc}
-@item
-@ref{Calendar Install, , Calendar}
-@item
-@ref{Compile Install, , Compile (Grep)}
-@item
-@ref{CSS Install, , CSS}
-@item
-@ref{CSV Install, , CSV}
-@item
-@ref{Dired Install, , Dired}
-@item
-@ref{Ediff Install, , Ediff}
-@item
-@ref{EditKit Install, , EditKit}
-@item
-@ref{Elisp Install, , Elisp}
-@item
-@ref{Eshell Install, , Eshell}
-@item
-@ref{Help Install, , Help}
-@item
-@ref{HTML Install, , HTML}
-@item
-@ref{IBuffer Install, , IBuffer}
-@item
-@ref{Image Install, , Image}
-@item
-@ref{Info Install, , Info}
-@item
-@ref{I-Search Install, , I-Search}
-@item
-@ref{Make Install, , Make}
-@item
-@ref{Man Install, , Man}
-@item
-@ref{RE-Builder Install, , Re-Builder}
-@item
-@ref{Timezone Install, , Timezone}
-@end itemize
-
-@menu
-* A Note on Package Dependencies::
-* Upgrading to Casual 1.x to 2.x: Upgrading to Casual 1x to 2x.
-@end menu
-
-@node A Note on Package Dependencies
-@section A Note on Package Dependencies
-
-Casual requires a recent installation of Transient 0.9.0+ from either
@uref{https://elpa.gnu.org/packages/transient.html, ELPA} or
@uref{https://melpa.org/#/transient, MELPA}. If your version of Emacs is ≤ 30
but also includes Transient as a built-in package, you will need to set the
customizable variable @code{package-install-upgrade-built-in} to @code{t} to
enable updating it via @code{package.el}. Set this variable and proceed with
installing Casual. Alternately invoking @code{packa [...]
-
-If you already have the latest version of Magit installed (via
@uref{https://elpa.nongnu.org/nongnu/magit.html, non-GNU ELPA} or
@uref{https://melpa.org/#/magit, MELPA}), you can bypass the above instruction
as Magit already includes the Transient package as a dependency.
-
-@node Upgrading to Casual 1x to 2x
-@section Upgrading to Casual 1.x to 2.x
-
-If you have been using an earlier version 1.x of Casual, thank you. Please use
the following guidance:
-
-@menu
-* If you do not use @code{use-package} to configure Casual::
-* If you have used @code{use-package} to configure Casual::
-@end menu
-
-@node If you do not use @code{use-package} to configure Casual
-@subsection If you do not use @code{use-package} to configure Casual
-
-Before installing Casual, you should update all of your existing Casual
packages. This is most easily done via the package menu buffer (@ref{Package
Menu,,,emacs,}) . After updating your packages, install the @code{casual}
package.
-
-Migrate your existing Casual packages from 1.x to 2.x by running the following
commands:
-
-@lisp
-M-x load-library casual
-M-x casual-upgrade-base-to-version-2
-@end lisp
-
-Any Casual v1.x packages that have been superseded by this package will be
uninstalled.
-
-While not necessary, it is recommended to run @code{M-x package-autoremove} to
purge any dangling dependent packages. Cautious readers can choose to audit any
packages that are targeted to be removed.
-
-@node If you have used @code{use-package} to configure Casual
-@subsection If you have used @code{use-package} to configure Casual
-
-For version 2.x going forward, I (Charles Choi) have decided to not offer any
documented guidance on using @code{use-package} to configure Casual due my lack
of expertise in using it. I leave it to more skilled readers to determine how
to best use @code{use-package} (@ref{Top,,,use-package,}) for their
configuration. Please also note that this is not a prohibition on using
@code{use-package} with Casual. I am simply admitting that I don't know how to
use it.
-
-That said, if you have used @code{:ensure t} to install a superseded package,
you @emph{must} remove that configuration. After doing so, please follow the
above instructions for installing @code{casual}.
-
-@node UX Conventions
-@chapter UX Conventions
-
-@cindex UX Conventions
-
-The Casual menus share common user experience (UX) conventions to facilitate
usability. This section details this.
-
-@subheading Common Menu Navigation
-
-Casual organizes a mode's command set into a menu hierarchy. As the user
descends down different menu levels, the user is given the option to dismiss
the current menu or to dismiss completely all menu levels descended. Transient
provides a standard convention for menu dismissal via the @kbd{C-g}
(@code{transient-quit-one}) and @kbd{C-q} (@code{transient-quit-all}) commands.
By default Transient does not display these commands in the menu though, rather
they make the assumption that the u [...]
-
-@vindex casual-lib-hide-navigation
-In contrast, Casual makes these bindings explicitly known to user by
displaying them at the bottom of the menu. Users who wish to have them hidden
can set the customizable variable @code{casual-lib-hide-navigation} to a
non-nil value. This can be changed from a Casual mode-specific settings menu.
-
-@subheading Settings Menu
-
-Most all Casual main menus support invoking a mode-specific settings menu via
the binding @kbd{,}.
-
-@subheading Unicode Symbol Support
-@vindex casual-lib-use-unicode
-
-The customizable variable named @code{casual-lib-use-unicode} which when
non-nil will inform Casual menus to use Unicode symbol labels whenever
supported. This can be changed from Casual mode-specific settings menu.
-
-If @code{casual-lib-use-unicode} is set to @code{t}, it is also recommended
that the variable @code{transient-align-variable-pitch} also be set to @code{t}.
-
-@subheading Common Key Bindings
-
-Listed below are keybindings which are common among Casual menus.
-
-@itemize
-@item
-@kbd{J} Jump to Bookmark…
-
-Casual places great emphasis on using Emacs Bookmarks to track different
places of note. The binding @kbd{J} is used in many main menus to support this.
-
-@item
-@kbd{,} Settings›
-
-Many modes have settings specific to them. The binding @kbd{,} is used in many
main menus to support the configuration of mode-specific settings.
-
-@item
-@kbd{j} Goto… (mode specific)
-
-Many modes provide a list of items. If a command exists that allows the user
to jump to a specified item, the binding @kbd{j} is mapped to it.
-
-@item
-@kbd{n} Next, @kbd{p} Previous
-
-For modes that provide a list of items, navigation to a next or previous item
is bound to @kbd{n} and @kbd{p} respectively.
-
-@item
-@kbd{[} Next Section, @kbd{]} Previous Section
-
-For modes that organize items into sections, navigation to a next or previous
section is bound to @kbd{[} and @kbd{]} respectively.
-@end itemize
-
-
-@subheading Label Conventions
-
-Casual annotates menu labels with the following conventions:
-
-@table @asis
-@item ‘…’
-If the label ends with an ellipsis, then the command will prompt the user for
input.
-@item ‘›’
-If the label ends with a right-pointing arrow, then the item will raise a
sub-menu.
-@item ‘✦’
-If the label ends with the glyph ✦ (BLACK FOUR POINTED STAR), then the command
supports a prefix @kbd{C-u}.
-@end table
-
-@node Casual Modes
-@chapter Casual Modes
-
-@cindex Casual Modes
-
-Casual employs the convention of using the same keybinding to invoke a
mode-specific main menu. This keybinding is re-used for each mode-specific
keymap. The document recommends the default keybinding @code{C-o} for this
purpose. Users who prefer a different binding are always free to use another.
-
-Casual is organized into different libraries typically using the naming
convention of @code{casual-<mode name>}. Each library has within it a ``main
menu'' which serves as the top level interface to access functions related to
that mode. All main menus are auto-loaded, which means that it is not necessary
to include a @code{require} call to load that library.
-
-The following modes are supported by Casual:
-
-@menu
-* Agenda::
-* Bib@TeX{}::
-* Bookmarks::
-* Calc::
-* Calendar::
-* Compile::
-* CSS::
-* CSV::
-* Dired::
-* Ediff::
-* EditKit::
-* Elisp::
-* Eshell::
-* Help::
-* HTML::
-* IBuffer::
-* Image::
-* Info::
-* I-Search::
-* Make::
-* Man::
-* RE-Builder::
-* Timezone::
-@end menu
-
-@node Agenda
-@section Agenda
-
-@cindex Agenda
-@cindex Org Agenda
-@vindex casual-agenda-tmenu
-Casual Agenda is a user interface for Org Agenda (@ref{Agenda Views,,,org,}),
a feature of Emacs Org Mode (@ref{Top,,,org,}) to help plan your day. Its
top-level library is @code{casual-agenda}.
-
-@image{images/casual-agenda-screenshot,,,,png}
-
-@menu
-* Agenda Install::
-* Agenda Usage::
-@end menu
-
-@node Agenda Install
-@subsection Agenda Install
-
-@cindex Agenda Install
-Add these lines to your Emacs initialization file with your binding of
preference.
-
-@lisp
-(keymap-set org-agenda-mode-map "C-o" #'casual-agenda-tmenu)
-@end lisp
-
-Use these bindings to configure Org Agenda to be consistent with bindings used
by Casual Agenda. This is optional.
-
-@lisp
-; bindings to make jumping consistent between Org Agenda and Casual Agenda
-(keymap-set org-agenda-mode-map "M-j" #'org-agenda-clock-goto)
-(keymap-set org-agenda-mode-map "J" #'bookmark-jump)
-@end lisp
-
-@node Agenda Usage
-@subsection Agenda Usage
-
-@cindex Agenda Usage
-
-
-@image{images/casual-agenda-screenshot,,,,png}
-
-The main menu for Casual Agenda is @code{casual-agenda-tmenu}. It is divided
into five sections:
-
-@table @asis
-@item Agenda
-Modify the view duration (day, week, year)
-@item Filter
-Filter displayed headlines with different criteria
-@item Actions
-Perform an activity on a headline, create/capture a headline or even generate
a different agenda view.
-@item Navigation
-move the point to where you want it to be.
-@item Utils
-Set a timer, get almanac info.
-@end table
-
-
-@subheading Operating on Headlines
-Use “@kbd{o} Operations›” from @code{casual-agenda-tmenu} to change a
headline's attributes such as TODO state, scheduling, tags, and priority. The
following menu will be displayed.
-
-@image{images/casual-agenda-operations-screenshot,,,,png}
-
-
-@subheading Marking Headlines
-
-Use “@kbd{M} Mark›” menu from @code{casual-agenda-tmenu} to mark different
headlines and perform a bulk action on them.
-
-@image{images/casual-agenda-mark-screenshot,,,,png}
-
-@subheading Almanac
-Get sunrise/sunset times, lunar cycle dates, and holidays with respect to a
date via the “@kbd{l} Almanac›” menu from @code{casual-agenda-tmenu}.
-
-@image{images/casual-agenda-almanac-screenshot,,,,png}
-
-@subheading Changing Modes and Settings
-Agenda views have different display modes and behavior that can be modified
from the “@kbd{,} Settings›” menu from @code{casual-agenda-tmenu}.
-
-@image{images/casual-agenda-settings-screenshot,,,,png}
-
-@subheading Agenda Unicode Symbol Support
-By enabling “@kbd{u} Use Unicode Settings” from the Settings menu, Casual
Agenda will use Unicode symbols as appropriate in its menus.
-
-@image{images/casual-agenda-unicode-screenshot,,,,png}
-
-@node Bib@TeX{}
-@section Bib@TeX{}
-
-@cindex BibTeX
-@cindex bibtex
-@vindex casual-bibtex-tmenu
-
-Casual Bib@TeX{} is an opinionated user interface for Bib@TeX{} mode (@ref{TeX
Mode,info ``(emacs) @TeX{} Mode'',,emacs,}), a major mode for working with
Bib@TeX{} files (@uref{https://bibtex.eu, Bib@TeX{} Guide}).
-
-A Bib@TeX{} file is typically named using the suffix @code{.bib} to identify
its file type.
-
-To appreciate the benefits of Casual Bib@TeX{}, it helps to understand what
BibTex is and what Bib@TeX{} mode offers.
-
-Bib@TeX{} is a database schema for bibliography data. This data is best
understood as a collection of records (or entries) that is stored in a
plain-text file. Multiple text files can be supported. While most tooling for
Bib@TeX{} is tuned for @LaTeX{} documentation workflows, Bib@TeX{} can be used
as generalized storage for bibliography data. Org provides extensive support
for citing using Bib@TeX{} (@ref{Citation handling,info ``(org) Citation
handling'',,org,}).
-
-As a Bib@TeX{} file is plain-text based, any plain-text editor can be used to
edit it. This flexibility is problematic as plain-text editors will not enforce
the schema of Bib@TeX{} by default.
-
-Emacs distinguishes itself from other editors in that support for working with
Bib@TeX{} files is built-in with the package @code{bibtex}.
-
-The @code{bibtex} package provides commands for both navigating and editing
Bib@TeX{} data structures (entries and the fields within an entry) in a
quasi-``form-based'' way.
-
-Casual Bib@TeX{} organizes and augments Bib@TeX{} mode commands into a
keyboard-driven menu.
-
-The screenshot below shows the menu for Casual Bib@TeX{}.
-
-@image{images/casual-bibtex-screenshot,,,,png}
-
-@menu
-* Bib@TeX{} Install::
-* Bib@TeX{} Usage::
-@end menu
-
-@node Bib@TeX{} Install
-@subsection Bib@TeX{} Install
-
-@cindex BibTeX Install
-
-In your initialization file, bind the Transient @code{casual-bibtex-tmenu} to
your key binding of preference in @code{bibtex-mode-map}. The binding @kbd{M-m}
is suggested so as to not conflict with @kbd{C-o} that is bound to
@code{casual-editkit-main-tmenu}. (@ref{EditKit Install})
-
-@lisp
-(keymap-set bibtex-mode-map "M-m" #'casual-bibtex-tmenu)
-@end lisp
-
-@code{casual-bibtex-tmenu} is opinionated in making editing and navigation
commands emulate a form-based interface
(@uref{https://simple.wikipedia.org/wiki/Form-based_interface#:~:text=A%20form%2Dbased%20interface%20is,the%20fields%20that%20accept%20it.,
form-based interface}) in a @code{bibtex-mode} window. The following
keybindings are recommended to support consistent behavior between
@code{bibtex-mode-map} and @code{casual-bibtex-tmenu}.
-
-@lisp
-(add-hook 'bibtex-mode-hook 'hl-line-mode)
-
-(keymap-set bibtex-mode-map "<TAB>" #'bibtex-next-field)
-(keymap-set bibtex-mode-map "<backtab>" #'previous-line)
-
-(keymap-set bibtex-mode-map "C-n" #'bibtex-next-field)
-(keymap-set bibtex-mode-map "M-n" #'bibtex-next-entry)
-(keymap-set bibtex-mode-map "M-p" #'bibtex-previous-entry)
-
-(keymap-set bibtex-mode-map "<prior>" #'bibtex-previous-entry)
-(keymap-set bibtex-mode-map "<next>" #'bibtex-next-entry)
-
-(keymap-set bibtex-mode-map "C-c C-o" #'bibtex-url)
-(keymap-set bibtex-mode-map "C-c C-c" #'casual-bibtex-fill-and-clean)
-
-(keymap-set bibtex-mode-map "<clear>" #'bibtex-empty-field)
-(keymap-set bibtex-mode-map "M-<clear>" #'bibtex-kill-field)
-(keymap-set bibtex-mode-map "M-DEL" #'bibtex-kill-field)
-
-@end lisp
-
-@node Bib@TeX{} Usage
-@subsection Bib@TeX{} Usage
-
-@cindex BibTeX Usage
-
-@image{images/casual-bibtex-screenshot,,,,png}
-
-The main menu for Casual Bib@TeX{} is organized into the following sections:
-
-@table @asis
-@item Field
-Commands to edit or navigate fields within an entry.
-@item Entry
-Commands to edit or navigate entries within a Bib@TeX{} file.
-@item Misc
-Miscellaneous Bib@TeX{} commands.
-@end table
-
-@menu
-* Bib@TeX{} Navigation::
-* Creating, Updating, and Deleting Bib@TeX{} Structures: Creating Updating and
Deleting Bib@TeX{} Structures.
-* Bib@TeX{} Settings::
-@end menu
-
-@node Bib@TeX{} Navigation
-@subsubsection Bib@TeX{} Navigation
-
-@cindex BibTeX Navigation
-
-@image{images/casual-bibtex-screenshot,,,,png}
-
-Casual Bib@TeX{} re-purposes conventional Emacs navigation bindings so that
instead of navigating a text edit buffer, it instead navigates Bib@TeX{}
structures (entry, field).
-
-The following table shows the bindings for Bib@TeX{} navigation.
-
-@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
{aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
-@headitem Binding
-@tab Command
-@item @kbd{C-n}
-@tab bibtex-next-field (bound to @kbd{n} in menu)
-@item @kbd{C-p}
-@tab previous-line (bound to @kbd{p} in menu)
-@item @kbd{C-a}
-@tab casual-bibtex-beginning-of-field
-@item @kbd{C-e}
-@tab casual-bibtex-end-of-field
-@item @kbd{M-p}
-@tab bibtex-previous-entry
-@item @kbd{M-n}
-@tab bibtex-next-entry
-@item @kbd{<}
-@tab bibtex-beginning-of-entry
-@item @kbd{>}
-@tab bibtex-end-of-entry
-@end multitable
-
-@node Creating Updating and Deleting Bib@TeX{} Structures
-@subsubsection Creating, Updating, and Deleting Bib@TeX{} Structures
-
-@cindex BibTeX CRUD
-
-@image{images/casual-bibtex-screenshot,,,,png}
-
-In Casual Bib@TeX{}, CRUD (CReate, Update, Delete) operations for entry and
field structures are intended to be achieved through their respective commands.
This contrasts with manual editing of a buffer to achieve the same end, which
is prone to errors.
-
-@subheading Creating an Entry
-
-To create a new entry, use the “@kbd{A} Add…” command. You will be prompted in
the mini-buffer with completion support for the entry type. This new entry will
be inserted relative to existing entry where the point is with all fields
supported by the entry type enumerated. Fields with the temporary prefix of
``ALT'' or ``OPT'' denote a field that is alternate or optional. Use the
command “@kbd{o} Remove OPT/ALT” to remove this prefix.
-
-When all desired information for a Bib@TeX{} entry has been entered, it can be
``cleaned'' using the command “@kbd{C-c} Clean”. Cleaning an entry will:
-
-@enumerate
-@item
-Generate a unique citation key, if needed.
-@item
-Remove all unused fields.
-@end enumerate
-
-By default, cleaning an entry will not format (or ``fill'') the entry. This
can be changed by setting the customizable variable
@code{bibtex-clean-entry-hook} to include the command @code{bibtex-fill-entry}.
This can be done from ``Hooks'' section in the Settings menu (@ref{Bib@TeX{}
Settings, , Settings)}.
-
-@subheading Creating a Field
-
-To create a new field, use the “@kbd{a} Add…” command. You will be prompted in
the mini-buffer with completion support for the field type. This new field will
be inserted relative to existing field where the point is.
-
-There are two components to a field:
-
-@table @asis
-@item key
-the field name, referred to in the menu as 'k'.
-@item value
-the value of the field, referred to in the menu as 'v'.
-@end table
-
-A ``brute-force'' command to enumerate all fields for an entry is provided by
the “@kbd{u} Update…” command. Clean the entry to remove all unpopulated fields
after using it.
-
-@subheading BibTeX mode has its own kill-ring
-
-Bib@TeX{} has its own kill-ring variable @code{bibtex-entry-kill-ring} which
the following menu commands use:
-
-@table @asis
-@item @kbd{c} Copy∙ k,v
-Copy the whole field, both key and value.
-@item @kbd{C} Copy∙
-Copy the entry.
-@item @kbd{k} Kill∙
-Kill the entry.
-@item @kbd{y} Yank∙
-Yank the entry or field.
-@item @kbd{M-y} Yank-Pop∙
-Yank-pop the entry or field.
-@end table
-
-The ``∙'' annotation in a menu label denotes commands that do @emph{not} use
the @code{kill-ring}, but @code{bibtex-entry-kill-ring} instead.
-
-@subheading Search and Jump
-
-The ability to search and jump to a position in a Bib@TeX{} database are
offered by the following menu commands:
-
-@table @asis
-@item @kbd{/} Search…
-Search the Bib@TeX{} database.
-@item @kbd{j} Jump…
-Move point to a citation key.
-@end table
-
-@node Bib@TeX{} Settings
-@subsubsection Bib@TeX{} Settings
-
-@cindex BibTeX Settings
-
-@image{images/casual-bibtex-settings-screenshot,,,,png}
-
-
-This menu offers access to commonly configured Bib@TeX{} mode settings.
-
-Settings are organized into the following sections:
-
-@table @asis
-@item Settings
-Miscellaneous Bib@TeX{} settings.
-@item Files
-File and path related settings.
-@item Search
-Search settings.
-@item Hooks
-Hook settings for cleaning and adding.
-@end table
-
-@subsubheading BibTeX Clean Hook
-
-By default Bib@TeX{} mode does not format (or ``fill'') an entry upon
cleaning. To support filling an entry upon clean, add the command
@code{bibtex-fill-entry} to @code{bibtex-clean-entry-hook} using the “@kbd{C}
Clean” command as shown below:
-
-@image{images/casual-bibtex-clean-entry-hook,,,,png}
-
-@subsubheading BibTeX Mode Unicode Symbol Support
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual
Bib@TeX{} will use Unicode symbols as appropriate in its menus.
-
-@image{images/casual-bibtex-unicode-screenshot,,,,png}
-
-@node Bookmarks
-@section Bookmarks
-
-@cindex Bookmarks
-@vindex casual-bookmarks-tmenu
-
-Casual Bookmarks is a user interface for the Emacs Bookmarks list
(@ref{Bookmarks,,,emacs,}). Its top-level library is @code{casual-bookmarks}.
-
-@image{images/casual-bookmarks-screenshot,,,,png}
-
-@menu
-* Bookmarks Install::
-* Bookmarks Usage::
-@end menu
-
-@node Bookmarks Install
-@subsection Bookmarks Install
-
-@cindex Bookmarks Install
-
-To install Casual Bookmarks, add the following line to your Emacs
initialization file with your binding of preference.
-
-@lisp
-(keymap-set bookmark-bmenu-mode-map "C-o" #'casual-bookmarks-tmenu)
-@end lisp
-
-Use these keybindings to configure the bookmark list to be consistent with
keybindings used by Casual Bookmarks.
-
-@lisp
-(keymap-set bookmark-bmenu-mode-map "J" #'bookmark-jump)
-@end lisp
-
-Casual Bookmarks also includes the keymap @code{casual-bookmarks-main-menu}
which inserts a @emph{Bookmarks} menu into the main menu bar as shown below.
-
-@image{images/bookmarks-main-menu,,,,png}
-
-To enable this, add the following configuration to your initialization file.
-
-@lisp
-(require 'casual-bookmarks)
-(easy-menu-add-item global-map '(menu-bar)
- casual-bookmarks-main-menu
- "Tools")
-@end lisp
-
-While not necessary, having the current bookmark highlighted is convenient.
Enable @code{hl-line-mode} for the bookmark list as shown below.
-
-@lisp
-(require 'hl-line)
-(add-hook 'bookmark-bmenu-mode-hook #'hl-line-mode)
-@end lisp
-
-Finally, customize the variable @code{bookmark-save-flag} to the value
@code{1} to ensure that your bookmark changes are always saved.
-
-The above guidance largely extends the work done in the blog post
@uref{http://yummymelon.com/devnull/using-bookmarks-in-emacs-like-you-do-in-web-browsers.html,
Using Bookmarks in Emacs like you do in Web Browsers}.
-
-@node Bookmarks Usage
-@subsection Bookmarks Usage
-
-@cindex Bookmarks Usage
-
-@image{images/casual-bookmarks-screenshot,,,,png}
-
-
-Casual Bookmarks organizes its main menu into the following sections:
-
-@table @asis
-@item Operations
-Commands that can operate on a bookmark such as editing or opening them.
-
-@item Mark
-Commands that allow for bulk operation on multiple bookmarks.
-
-@item Display
-Control how bookmarks are displayed and filtered.
-
-@item Annotation
-Commands for annotating a bookmark.
-
-@item Navigation
-Commands for navigating to a bookmark.
-
-@item Column
-Commands to navigate and control the display of the table layout for bookmarks.
-@end table
-
-
-@subheading Unicode Symbol Support
-
-@image{images/casual-bookmarks-unicode-screenshot,,,,png}
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual
Bookmarks will use Unicode symbols as appropriate in its menus. The following
mapping is shown in the table below:
-
-@multitable {aaaaaaaaaaaaaaaaaaaa} {aaaaaaaaa} {aaaaaaa}
-@headitem Name
-@tab Plain
-@tab Unicode
-@item :previous
-@tab Previous
-@tab ↑
-@item :next
-@tab Next
-@tab ↓
-@item :jump
-@tab Jump
-@tab 🚀
-@item :beginning-of-buffer
-@tab Beginning
-@tab ⤒
-@item :end-of-buffer
-@tab End
-@tab ⤓
-@item :backward
-@tab Backward
-@tab ←
-@item :forward
-@tab Forward
-@tab →
-@item :narrow
-@tab Narrow
-@tab →←
-@item :widen
-@tab Widen
-@tab ←→
-@end multitable
-
-@node Calc
-@section Calc
-
-@cindex Calc
-@vindex casual-calc-tmenu
-Casual Calc is a user interface for Emacs Calc (@ref{Top,,,calc,}).
-
-@image{images/casual-calc-tmenu,,,,png}
-
-@menu
-* Calc Install::
-* Calc Usage::
-@end menu
-
-@node Calc Install
-@subsection Calc Install
-
-@cindex Calc Install
-
-To install Casual Calc, add the following lines to your Emacs initialization
file with your binding of preference.
-
-@lisp
-(keymap-set calc-mode-map "C-o" #'casual-calc-tmenu)
-(keymap-set calc-alg-map "C-o" #'casual-calc-tmenu)
-@end lisp
-
-@node Calc Usage
-@subsection Calc Usage
-
-@cindex Calc Usage
-
-@image{images/casual-calc-tmenu,,,,png}
-
-To launch Calc, invoke @code{M-x calc}. When the point is in the Calc window,
invoke @kbd{C-o} (or a binding of your choosing) to launch the Casual Calc
interface.
-
-For nearly all menus, algebraic entry via the @kbd{'} binding is available, as
well as basic calculator operations (addition, subtraction, multiplication,
division) and stack operations (pop, enter).
-
-Casual Calc organizes its main menu into the following sections:
-
-@table @asis
-@item Calc
-Commands for common calculator functions.
-@item Constants
-Common math constants.
-@item Operators
-Common math operators.
-@item Stack
-Commands for stack operations.
-@item Arithmetic
-Entry point for sub-menus of commands classified as arithmetic operations.
-@item Functions
-Entry point for sub-menus of commands organized into different classes of
functionality.
-@item Settings
-Entry point for sub-menus of commands to configure Calc settings.
-@end table
-
-@subheading Calc Basics
-
-It helps to know some basics about Calc.
-
-@itemize
-@item
-Calc is a stack-based calculator that supports both RPN and algebraic style
entry.
-@itemize
-@item
-By default it uses RPN entry, but this can be changed to algebraic.
-@end itemize
-@item
-Stack based operations are always RPN-style.
-@item
-Undo has the keybinding @code{U}, redo is @code{D}.
-@item
-The top of the stack is referred to as @code{1:}
-@item
-Calc vectors are punctuated with @code{[} and @code{]} (e.g. @code{[2 3]})
Matrix values are represented as vectors within a vector. For example,
@code{[[1 0] [0 1]]} is a square diagonal matrix.
-@item
-Calc vector indexes are 1-offset.
-@item
-Intervals
-@itemize
-@item
-Inclusive intervals are represented as [𝑛..𝑚], where 𝑛 < 𝑚.
-@item
-Exclusive intervals are represented as (𝑛..𝑚), where 𝑛 < 𝑚.
-@item
-Any combination of lower and upper bounds set to be inclusive or exclusive is
supported.
-@end itemize
-@item
-Complex numbers are entered as (𝑟, 𝑖), where 𝑟 is the real part and 𝑖 is the
imaginary.
-@item
-Radix numbers are entered as 𝑏#𝑛 where 𝑏 is the base value and 𝑛 is the
number. For example entering @code{2#0101} will put @code{5} on the stack.
-@item
-H:M:S values are default entered as ℎ@@ 𝑚" 𝑠'.
-@item
-Org-mode active timestamps can be entered into Calc.
-@item
-The top of the stack (1:) can be edited by pressing the @code{`} key.
-@item
-Entering a single quote (') will prompt you for an algebraic entry.
-@end itemize
-
-@node Calendar
-@section Calendar
-
-@cindex Calendar
-@vindex casual-calendar
-@vindex casual-calendar-tmenu
-Casual Calendar is a user interface for Emacs Calendar/Diary. Its top-level
library is @code{casual-calendar}. Access to numerous calendar and diary
commands are made available, most notably support for non-Gregorian calendar
systems.
-
-
-@image{images/casual-calendar-screenshot,,,,png}
-
-@menu
-* Calendar Install::
-* Calendar Usage::
-@end menu
-
-@node Calendar Install
-@subsection Calendar Install
-
-@cindex Calendar Install
-
-The main menu for Casual Calendar (@code{casual-calendar-tmenu)} is invoked by
the command @code{casual-calendar}. Bind this command in the keymap
@code{calendar-mode-map} as follows in your initialization file.
-
-@lisp
-(keymap-set calendar-mode-map "C-o" #'casual-calendar)
-@end lisp
-
-@node Calendar Usage
-@subsection Calendar Usage
-
-@cindex Calendar Usage
-
-@image{images/casual-calendar-screenshot,,,,png}
-
-Whenever the @code{calendar} window (showing three months) is raised, the
Casual user interface is invoked via the command @code{casual-calendar}. This
command is typically bound to a keybinding (e.g. @kbd{C-o}).
-
-Casual Calendar organizes its main menu into the following sections:
-
-@table @asis
-@item Navigation
-Commands to move the point to a desired date, adjusting the view as necessary.
-
-@item Conversions
-Commands to convert a date across different calendar systems.
-
-@item Holidays
-Holiday related commands.
-
-@item Misc
-Commands related to the Diary and Org Agenda are placed here.
-
-@item Almanac
-Almanac-related commands such the lunar phase, sunrise/sunset times are found
here.
-
-@item Region
-Support for counting days defined in a region is offered here.
-@end table
-
-Also made available is access to a Settings menu (more below) and to the Info
documentation for @code{calendar}.
-
-@menu
-* Diary & Goto Menu::
-* Calendar System Date Conversion::
-* Calendar Settings Menu::
-* Calendar Unicode Symbol Support::
-@end menu
-
-@node Diary & Goto Menu
-@subsubsection Diary & Goto Menu
-
-From the main menu, choosing “(D) Diary & Goto›” will present choices for
diary event insertion and to “goto” a particular date via different
specifications.
-
-@image{images/casual-calendar-diary-menu,,,,png}
-
-@node Calendar System Date Conversion
-@subsubsection Calendar System Date Conversion
-
-Calendar supports conversion of dates from Gregorian (default) to a number of
different calendar systems. Choose ``(c) Conversions›'' from the main menu to
select from a list of such calendars.
-
-@image{images/casual-calendar-calendars-menu,,,,png}
-
-Supported calendar systems:
-
-@itemize
-@item
-Astronomical
-@item
-Bahá’í
-@item
-Ethiopic
-@item
-French Revolutionary
-@item
-Hebrew
-@item
-Islamic
-@item
-Julian
-@item
-Lunar (Chinese)
-@item
-Mayan
-@item
-Persian
-@end itemize
-
-Selecting a calendar system will raise a menu that offers date conversion
commands between it and the Gregorian system. In the screenshot below, the
Lunar (Chinese) calendar system menu is shown.
-
-To convert a Gregorian date to Lunar (Chinese):
-
-@enumerate
-@item
-Move cursor (point) in Calendar window to desired date. (The command “(g)
Goto…” can be used to accomplish this.)
-@item
-Choose “(c) Date at Cursor”.
-@end enumerate
-
-To convert a Lunar (Chinese) date to Gregorian:
-
-@enumerate
-@item
-Choose “(G) Goto…” and follow the prompts.
-@end enumerate
-
-
-@image{images/casual-calendar-lunar-menu,,,,png}
-
-Certain non-Gregorian calendar systems are supported by the diary (Bahá’í,
Hebrew, Islamic, Lunar (Chinese)). For such systems, their menus will offer
choices to insert diary events.
-
-Note that inserting non-Gregorian diary events require configuration of the
variables @code{diary-nongregorian-listing-hook} and
@code{diary-nongregorian-marking-hook} as detailed in Diary Entries using
non-Gregorian Calendars (@ref{Non-Gregorian Diary,,,emacs,}).
-
-Both of these variables can be configured from the Calendar Settings menu.
-
-@node Calendar Settings Menu
-@subsubsection Calendar Settings Menu
-
-From the main menu, choosing “@kbd{,} Settings›” will provide a menu of
frequently configured calendar and diary-related variables.
-
-@image{images/casual-calendar-settings-menu,,,,png}
-
-@node Calendar Unicode Symbol Support
-@subsubsection Calendar Unicode Symbol Support
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual
Calendar will use Unicode symbols as appropriate in its menus.
-
-@node Compile
-@section Compile
-
-@cindex Compile
-@cindex compilation-mode
-@cindex grep-mode
-@vindex casual-compile-tmenu
-
-Casual Compile is a user interface for the output of the @code{compile}
command (@ref{Compilation,,,emacs,}). The output buffer's major mode is
@code{compilation-mode} whose commands are surfaced by Casual Compile.
-
-In similar fashion, output of Emacs-wrapped Grep commands (@ref{Grep
Searching,,,emacs,}) is also supported by Casual Compile. This is because the
output of Grep commands use the major mode @code{grep-mode} which is derived
from @code{compilation-mode}.
-
-The screenshot below shows the menu for compilation results.
-
-@image{images/casual-compile-screenshot,,,,png}
-
-The screenshot below shows the menu for Grep results. Note the menu label
changes based on the output mode (in this case @code{grep-mode}).
-
-@image{images/casual-compile-grep-screenshot,,,,png}
-
-@menu
-* Compile Install::
-* Compile Usage::
-@end menu
-
-@node Compile Install
-@subsection Compile Install
-
-@cindex Compile Install
-
-In your initialization file, bind the Transient @code{casual-compile-tmenu} to
your key binding of preference. It should be bound in two maps:
@code{compilation-mode-map} and @code{grep-mode-map}.
-
-@lisp
-(keymap-set compilation-mode-map "C-o" #'casual-compile-tmenu)
-(keymap-set grep-mode-map "C-o" #'casual-compile-tmenu)
-@end lisp
-
-@code{casual-compile-tmenu} deviates from the default bindings of
@code{compilation-mode-map} as shown in the table below to support using a
single key on an @samp{en.US} keyboard.
-
-@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaa}
-@headitem Default Binding
-@tab Casual Binding
-@tab Command
-@item M-p
-@tab k
-@tab compilation-previous-error
-@item M-n
-@tab j
-@tab compilation-next-error
-@item M-@{
-@tab [
-@tab compilation-previous-file
-@item M-@}
-@tab ]
-@tab compilation-next-file
-@item C-o
-@tab o
-@tab compilation-display-error
-@end multitable
-
-The following keybindings are recommended to support consistent behavior
between @code{compilation-mode-map} and @code{casual-compile-tmenu}.
-
-@lisp
-(keymap-set compilation-mode-map "k" #'compilation-previous-error)
-(keymap-set compilation-mode-map "j" #'compilation-next-error)
-(keymap-set compilation-mode-map "o" #'compilation-display-error)
-(keymap-set compilation-mode-map "[" #'compilation-previous-file)
-(keymap-set compilation-mode-map "]" #'compilation-next-file)
-@end lisp
-
-Similar treatment for @code{grep-mode-map} can be done.
-
-@lisp
-(keymap-set grep-mode-map "k" #'compilation-previous-error)
-(keymap-set grep-mode-map "j" #'compilation-next-error)
-(keymap-set grep-mode-map "o" #'compilation-display-error)
-(keymap-set grep-mode-map "[" #'compilation-previous-file)
-(keymap-set grep-mode-map "]" #'compilation-next-file)
-@end lisp
-
-@node Compile Usage
-@subsection Compile Usage
-
-@cindex Compile Usage
-
-@image{images/casual-compile-screenshot,,,,png}
-
-After running @code{compile}, invoke @code{casual-compile-tmenu} in the buffer
named @samp{✳︎compilation✳︎} using the binding @code{C-o} (or your binding of
preference).
-
-The following sections are offered in the menu:
-
-@table @asis
-@item Follow
-Navigate the point while opening the location of the error in the source file
in another window.
-@item Error
-Error commands for navigation and viewing.
-@item File
-If there are errors in multiple files, navigate to the file.
-@item Compile
-Get compile for different Elisp types. Note that the “@kbd{k} Kill” item is
displayed when there is a running job.
-@end table
-
-If the output window is from a Grep command, @code{casual-compile-tmenu} will
adjust its labels accordingly as shown below.
-
-@image{images/casual-compile-grep-screenshot,,,,png}
-
-
-@subheading Compile Mode Unicode Symbol Support
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual
Compile will use Unicode symbols as appropriate in its menus.
-
-@node CSS
-@section CSS
-
-@cindex CSS
-@vindex casual-css-tmenu
-
-Casual CSS is a user interface for @code{css-mode}.
-
-@image{images/casual-css-screenshot,,,,png}
-Casual also has support for HTML editing (@ref{HTML}).
-
-@menu
-* CSS Install::
-* CSS Usage::
-@end menu
-
-@node CSS Install
-@subsection CSS Install
-
-@cindex CSS Install
-
-In your initialization file, bind the Transient @code{casual-css-tmenu} to
your key binding of preference.
-
-@lisp
-(keymap-set css-mode-map "M-m" #'casual-css-tmenu)
-@end lisp
-
-A different binding (@kbd{M-m}) is used as @code{casual-css-tmenu} is intended
to work alongside with @ref{EditKit Install, , Casual EditKit}.
-
-@node CSS Usage
-@subsection CSS Usage
-
-@cindex CSS Usage
-
-@image{images/casual-css-screenshot,,,,png}
-
-
-The following sections are offered in the menu:
-
-@table @asis
-@item CSS
-CSS specific commands.
-@itemize
-@item
-“@kbd{l} Lookup Symbol” will reference the symbol's documentation from the
Mozilla Developer Network (MDN) website.
-@item
-“@kbd{c} Cycle Color” should be selected when the point is on a color
specification.
-@end itemize
-@item Edit
-Editing commands.
-@itemize
-@item
-“@kbd{f} Indent CSS Rule” is a call to @code{fill-paragraph} whose behavior is
adjusted for @code{css-mode}.
-@end itemize
-@item Misc
-Miscellaneous commands.
-@itemize
-@item
-“@kbd{h} Highlight Line” toggles @code{hl-line-mode} to avoid interfering the
display of color specifications.
-@end itemize
-@end table
-
-
-@subheading CSS Settings
-@vindex casual-css-settings-tmenu
-
-Settings menu for Casual CSS@.
-
-
-@image{images/casual-css-settings-screenshot,,,,png}
-
-
-@subheading CSS Unicode Symbol Support
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual CSS
will use Unicode symbols as appropriate in its menus.
-
-@node CSV
-@section CSV
-
-@cindex CSV
-@vindex casual-csv-tmenu
-
-Casual CSV is a user interface for @code{csv-mode}, a mode for working with
CSV files.
-
-@image{images/casual-csv-edit-screenshot,,,,png}
-
-@menu
-* CSV Install::
-* CSV Usage::
-@end menu
-
-@node CSV Install
-@subsection CSV Install
-
-@cindex CSV Install
-
-In your initialization file, bind the Transient @code{casual-csv-tmenu} to
your key binding of preference.
-
-@lisp
-(keymap-set csv-mode-map "M-m" #'casual-csv-tmenu)
-@end lisp
-
-While not required, the following configuration is recommended for working
with CSV files.
-
-@lisp
-;; disable line wrap
-(add-hook 'csv-mode-hook
- (lambda ()
- (visual-line-mode -1)
- (toggle-truncate-lines 1)))
-
-;; auto detect separator
-(add-hook 'csv-mode-hook #'csv-guess-set-separator)
-;; turn on field alignment
-(add-hook 'csv-mode-hook #'csv-align-mode)
-@end lisp
-
-@node CSV Usage
-@subsection CSV Usage
-
-@cindex CSV Usage
-
-@image{images/casual-csv-edit-screenshot,,,,png}
-
-The following sections are offered in the menu:
-
-@table @asis
-@item Navigation, Line, Buffer
-Commands for moving the point, mostly with respect to a field.
-@item Page
-Move up or down a page.
-@item Buffer/File
-Commands associated the current buffer or file, such changing the buffer state
from viewable (read-only) to editable (writeable), display alignment, or
duplicating the file for subsequent editing.
-@item Field
-Commands to mark or copy a field.
-@item Sort
-Sorting commands. This section is displayed only if the buffer is editable.
-@item Fields
-Kill and yank commands dedicated for CSV mode. Note that these commands do
@emph{not} use the default @code{kill-ring} and are marked with a bullet (•).
This section is displayed only if the buffer is editable.
-@item Misc
-Miscellaneous commands. Note if a region is selected containing multiple
complete rows, the “@kbd{C} Copy as Table” command will reformat the selected
rows as an Org table and copy them in the @code{kill-ring} for subsequent
pasting.
-@end table
-
-@subheading CVS View/Edit, Duplicate
-
-If the buffer is in view (read-only) mode, then only relevant commands are
displayed.
-
-@image{images/casual-csv-view-screenshot,,,,png}
-
-If the buffer is editable, a common to desire to instead work on a copy of the
CSV file to avoid making unwanted changes. This can be done using the “@kbd{d}
Duplicate” command.
-
-@subheading CSV Align
-@vindex casual-csv-align-tmenu
-
-The display of the CSV buffer can be controlled with this menu.
-
-@image{images/casual-csv-align-screenshot,,,,png}
-
-
-@subheading CSV Settings
-@vindex casual-csv-settings-tmenu
-
-@image{images/casual-csv-settings-screenshot,,,,png}
-
-
-@subheading CSV Unicode Symbol Support
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual CSV
will use Unicode symbols as appropriate in its menus.
-
-@image{images/casual-csv-view-unicode-screenshot,,,,png}
-
-@node Dired
-@section Dired
-
-@cindex Dired
-@vindex casual-dired-tmenu
-Casual Dired provides a user interface for Dired (@ref{Dired,,,emacs,}), the
Emacs file manager. Its top-level library is @code{casual-dired}.
-
-@image{images/casual-dired-screenshot,,,,png}
-
-@menu
-* Dired Requirements::
-* Dired Install::
-* Dired Usage::
-@end menu
-
-@node Dired Requirements
-@subsection Dired Requirements
-
-Casual Dired requires that the @code{ls} utility from GNU coreutils ≥ 8.32 be
installed.
-
-The following links provide guidance for installing GNU coreutils on different
platforms.
-
-@menu
-* macOS::
-* Windows::
-@end menu
-
-@node macOS
-@subsubsection macOS
-
-Note that the default packaged @code{ls} on macOS is BSD-flavored which is not
supported by Casual Dired. Users wishing to use Casual Dired on macOS are
recommended to install GNU coreutils and configure their Emacs to point to its
version of @code{ls} accordingly.
-
-@itemize
-@item
-@uref{https://ports.macports.org/port/coreutils/, MacPorts}
-@item
-@uref{https://formulae.brew.sh/formula/coreutils#default, Homebrew}
-@end itemize
-
-@node Windows
-@subsubsection Windows
-
-For users running on Microsoft Windows, use
@uref{https://www.gnu.org/software/emacs/manual/html_node/efaq-w32/Dired-ls.html,
this guidance} to configure Emacs to use an external install of @code{ls}.
-
-@itemize
-@item
-@uref{https://gitforwindows.org/, Git for Windows} (includes @code{ls} in Git
BASH)
-@item
-@uref{https://www.cygwin.com/, Cygwin}
-@end itemize
-
-@node Dired Install
-@subsection Dired Install
-
-@cindex Dired Install
-
-The main menu for Dired is @code{casual-dired-tmenu}. Bind this menu in the
keymap @code{dired-mode-map} as follows in your initialization file.
-
-@lisp
-(keymap-set dired-mode-map "C-o" #'casual-dired-tmenu)
-@end lisp
-
-In addition, it is convenient to have both the sort-by
(@code{casual-dired-sort-by-tmenu}) and search & replace
(@code{casual-dired-search-replace-tmenu}) menus bound. Listed below is an
example of binding the sort-by and search & replace menus to @code{s} and
@code{/} respectively.
-
-@lisp
-(keymap-set dired-mode-map "s" #'casual-dired-sort-by-tmenu)
-(keymap-set dired-mode-map "/" #'casual-dired-search-replace-tmenu)
-@end lisp
-
-Included is a standard keymap for Dired sorting commands
(@code{casual-dired-sort-menu}) which can be included in a context menu for a
mouse-driven workflow. An example of this is shown below:
-
-@lisp
-(require 'casual-dired)
-
-(defun casual-dired-context-menu-addons (menu click)
- "Customize context MENU with CLICK event."
- (easy-menu-add-item menu nil casual-dired-sort-menu)
- menu)
-
-(add-hook 'context-menu-functions #'casual-dired-context-menu-addons)
-(add-hook 'dired-mode-hook 'context-menu-mode)
-@end lisp
-
-
-@subheading Configuration
-
-As Dired has been around for a long time, the different ways of configuring it
are myriad. Described below is a configuration used by the author that is
consistent with the bindings used in Casual Dired.
-
-@lisp
-(require 'dired)
-(require 'dired-x)
-(require 'wdired)
-(require 'hl-line)
-(require 'mouse)
-(require 'image-dired)
-(require 'image-dired-dired)
-(require 'casual-dired)
-
-(keymap-set dired-mode-map "C-o" #'casual-dired-tmenu)
-(keymap-set dired-mode-map "s" #'casual-dired-sort-by-tmenu)
-(keymap-set dired-mode-map "/" #'casual-dired-search-replace-tmenu)
-
-(add-hook 'dired-mode-hook 'hl-line-mode)
-(add-hook 'dired-mode-hook 'context-menu-mode)
-(add-hook 'dired-mode-hook 'dired-async-mode)
-(add-hook
- 'dired-mode-hook
- (lambda ()
- (setq-local mouse-1-click-follows-link 'double)))
-
-(keymap-set dired-mode-map "M-o" #'dired-omit-mode)
-(keymap-set dired-mode-map "E" #'wdired-change-to-wdired-mode)
-(keymap-set dired-mode-map "M-n" #'dired-next-dirline)
-(keymap-set dired-mode-map "M-p" #'dired-prev-dirline)
-(keymap-set dired-mode-map "]" #'dired-next-subdir)
-(keymap-set dired-mode-map "[" #'dired-prev-subdir)
-(keymap-set dired-mode-map "A-M-<mouse-1>" #'browse-url-of-dired-file)
-(keymap-set dired-mode-map "<backtab>" #'dired-prev-subdir)
-(keymap-set dired-mode-map "TAB" #'dired-next-subdir)
-(keymap-set dired-mode-map "M-j" #'dired-goto-subdir)
-(keymap-set dired-mode-map ";" #'image-dired-dired-toggle-marked-thumbs)
-
-(keymap-set image-dired-thumbnail-mode-map "n" #'image-dired-display-next)
-(keymap-set image-dired-thumbnail-mode-map "p" #'image-dired-display-previous)
-@end lisp
-
-@subheading Dired Variables
-
-The Casual Dired main menu offers “@kbd{,} Settings›” to customize a set of
commonly used Dired variables.
-
-@image{images/casual-dired-settings-screenshot,,,,png}
-
-If you have GNU @code{ls} installed and configured, use the @kbd{l} key to set
the variable @code{dired-use-ls-dired} to @code{t} (“@kbd{l} Use GNU ‘ls’ with
--dired”). Otherwise this should be disabled.
-
-@node Dired Usage
-@subsection Dired Usage
-
-@cindex Dired Usage
-
-@image{images/casual-dired-screenshot,,,,png}
-
-Invoke @code{M-x dired} to launch Dired. When the point is in the Dired
window, invoke @kbd{C-o} (or a binding of your choosing) to launch the Casual
Dired menu (@code{casual-dired-tmenu}).
-
-Casual Dired organizes its main menu into the following sections:
-
-@table @asis
-@item File
-File-related commands are placed here. Most of the commands will also operate
on marked files (see @strong{Mark} item below).
-
-@item Directory
-Directory-related commands. Subdir view commands are also made available in
this section. To remove a subdir view, use the command prefix @kbd{C-u} before
pressing the binding @kbd{k} to kill a subdir view.
-
-@item Mark
-Marking operations are available here. Commands in the “@kbd{#} Utils›”
sub-menu can be used to operate on marked items. In addition, many commands
from the @strong{File} section can be operate on marked items.
-
-The “@kbd{r} Regexp›” sub-menu provides commands to mark via @ref{Regular
Expressions,regular expression,,elisp,}.
-
-@item Navigation
-Navigation commands to move the point in Dired are offered here.
-
-@item Quick
-Convenience commands for bookmarks and listing buffers are made available in
this section.
-
-@item Search
-Commands to find a filename via I-Search or to recursively search for pattern
inside files contained in a directory tree (@code{rgrep}) are made available
here.
-
-@item New
-Create a new file or directory with the commands in this section.
-@end table
-
-@menu
-* Dired Enhanced Sorting::
-* Dired Search & Replace::
-* Bulk Dired Operations::
-* Dired Link::
-* Dired Unicode Symbol Support::
-@end menu
-
-@node Dired Enhanced Sorting
-@subsubsection Dired Enhanced Sorting
-
-@cindex Dired Enhanced Sorting
-@vindex casual-dired-sort-by-tmenu
-
-Casual Dired offers enhanced sorting capabilities through GNU @code{ls}. Use
this to sort your Dired buffer to preference. Filter dot files (.*) by
disabling the @code{--all} option is available here.
-
-@image{images/casual-dired-sort-by-screenshot,,,,png}
-
-With the @strong{Sort By} menu raised, one can save the switch settings for
future use via the binding @kbd{C-x C-s} (@code{transient-save}). Note this is
a global setting and will apply to all future calls to the @strong{Sort By}
menu.
-
-@node Dired Search & Replace
-@subsubsection Dired Search & Replace
-
-@cindex Dired Search & Replace
-@vindex casual-dired-search-replace-tmenu
-
-Search and replace in multiple marked files using the “@kbd{/} Search &
Replace›” menu item in @code{casual-dired-tmenu}. This will raise a menu of
Dired commands that will work on marked files.
-
-@image{images/casual-dired-search-replace,,,,png}
-
-While most Dired commands use Emacs-style regular expression syntax
(@ref{Regular Expressions,,,elisp,}), there are two commands that instead take
instead @strong{grep}-style syntax:
-
-@itemize
-@item
-@kbd{g} Find regex… (@code{dired-do-find-regexp})
-@item
-@kbd{G} Find regex and replace… (@code{dired-do-find-regexp-and-replace})
-@end itemize
-
-The @strong{grep}-style syntax is dependent on the @code{grep} implementation
that is installed and used by Emacs.
-
-@node Bulk Dired Operations
-@subsubsection Bulk Dired Operations
-
-Casual Dired organizes a number of Dired commands that work on a set of marked
files. These commands are presented in the “@kbd{#} Utils›” menu in
@code{casual-dired-tmenu}.
-
-@image{images/casual-dired-utils-screenshot,,,,png}
-
-@node Dired Link
-@subsubsection Dired Link
-
-Create symbolic and hard links via the “@kbd{l} Link›” menu in
@code{casual-dired-tmenu}. Both absolute and relative symbolic links (symlinks)
are supported.
-
-@image{images/casual-dired-link,,,,png}
-
-@node Dired Unicode Symbol Support
-@subsubsection Dired Unicode Symbol Support
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual Dired
will use Unicode symbols as appropriate in its menus. An example is shown below.
-
-@image{images/casual-dired-screenshot-unicode,,,,png}
-
-To ensure proper layout and spacing, your default typeface should be
fixed-width or monospace and @strong{must} support the Unicode symbols used.
-
-@node Ediff
-@section Ediff
-
-@cindex Ediff
-@vindex casual-ediff-tmenu
-
-Casual Ediff is a user interface for Ediff (@ref{Top,Ediff,,ediff,}), a visual
interface for the Unix diff and patch utilities. Casual Ediff strives to
improve the usability of Ediff by simplifying the following workflows:
-
-@itemize
-@item
-Comparing a modified and uncommitted version-controlled file with its most
recent commit.
-@item
-Resolving a merge conflicted file.
-@end itemize
-
-Notable features of Casual Ediff include:
-
-@itemize
-@item
-Context aware menu items.
-@item
-Menu design tuned for side-by-side comparison.
-@item
-For a merge conflict, the ability to resolve using both the conflicting diff
versions.
-@end itemize
-
-Shown below is screenshot of the Casual Ediff in action for a
version-controlled file.
-
-@image{images/casual-ediff-screenshot,,,,png}
-
-@menu
-* Ediff Install::
-* Ediff Usage::
-@end menu
-
-@node Ediff Install
-@subsection Ediff Install
-
-@cindex Ediff Install
-
-In your initialization file, bind the Transient @code{casual-ediff-tmenu} to
your key binding of preference.
-
-@lisp
-(casual-ediff-install) ; run this to enable Casual Ediff
-(add-hook 'ediff-keymap-setup-hook
- (lambda ()
- (keymap-set ediff-mode-map "C-o" #'casual-ediff-tmenu)))
-@end lisp
-
-If the current buffer is loaded with a version-controlled file, then the
difference between that buffer's content with its most recent commit can be
seen with the command @code{casual-ediff-revision}. It is often convenient to
bind this command. Shown below is an example of such a binding.
-
-@lisp
-(keymap-global-set "<f15>" #'casual-ediff-revision)
-@end lisp
-
-Users who wish to call @code{casual-ediff-revision} via mouse can use the
command @code{casual-ediff-revision-from-menu}. An example of its use is shown
in the source example below (note this is a code fragment).
-
-@lisp
-(easy-menu-add-item
- menu nil
- ["Ediff revision…"
- casual-ediff-revision-from-menu
- :visible (and (bound-and-true-p buffer-file-name)
- (vc-registered (buffer-file-name)))
- :help "Ediff this file with revision"])
-@end lisp
-
-
-@subsubheading Ediff Variables
-
-Casual Ediff recommends the following variables be set as follows:
-
-@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaa}
-@headitem Variable
-@tab Value
-@item ediff-keep-variants
-@tab nil
-@item ediff-window-setup-function
-@tab ediff-setup-windows-plain
-@item ediff-split-window-function
-@tab split-window-horizontally
-@end multitable
-
-@node Ediff Usage
-@subsection Ediff Usage
-
-@cindex Ediff Usage
-
-@image{images/casual-ediff-basic-screenshot,,,,png}
-
-Casual Ediff (@code{casual-ediff-tmenu}) is invoked from the Ediff control
window, typically using the binding @kbd{C-o} (or your binding of preference).
-
-The menu comprises of sections laid out horizontally that correspond to source
of the diffs. The number of sections and their contents are context-dependent
on the type of content to be compared.
-
-The following sections are offered in the menu:
-
-@table @asis
-@item A
-Context-dependent commands for Ediff buffer A@.
-@item B
-Context-dependent commands for Ediff buffer B@.
-@item C
-Context-dependent commands for Ediff buffer C, if available.
-@item Diff
-Ediff commands not related to a specific buffer.
-@end table
-
-Navigation between diffs are bound to the @kbd{p} and @kbd{n} keys for
previous and next diff respectively.
-
-@menu
-* Ediff Basic Operation::
-* Comparing a Version-Controlled File::
-* Resolving a Merge Conflict::
-* Ediff Unicode Symbol Support::
-@end menu
-
-@node Ediff Basic Operation
-@subsubsection Ediff Basic Operation
-
-@image{images/casual-ediff-basic-screenshot,,,,png}
-
-If two writeable files are compared, Casual Ediff provides the ability to
write diffs from either side A or B to each other. Unwanted changes to a side
can be restored.
-
-@node Comparing a Version-Controlled File
-@subsubsection Comparing a Version-Controlled File
-
-@image{images/casual-ediff-screenshot,,,,png}
-
-Casual Ediff provides a dedicated command to compare a version-controlled file
with its latest commit: @code{casual-ediff-revision}. This command
short-circuits the prompts asked for by the command @code{ediff-revision}
which asks for the source file and the revision to compare it to. Call
@code{casual-ediff-revision} from the window of a version-controlled file,
typically by key binding of preference.
-
-The A side will hold the last committed revision of a file. The B side will
hold current source file.
-
-Users desiring a mouse-driven approach to calling @code{casual-ediff-revision}
should use the command @code{casual-ediff-revision-from-menu} invoked from
either the top-level or context menu.
-
-Note that both @code{casual-ediff-revision} and
@code{casual-ediff-revision-from-menu} will checkpoint the window configuration
before invoking the Ediff session and restore it after the session is complete.
-
-@node Resolving a Merge Conflict
-@subsubsection Resolving a Merge Conflict
-
-@image{images/casual-ediff-merge-conflict,,,,png}
-
-Magit offers a means of invoking Ediff to resolve a merge conflict via the
@kbd{e} binding from the @code{magit-status} (@ref{Status Buffer,(magit) Status
Buffer,,magit,}) window.
-
-Calling @code{casual-ediff-tmenu} will show the menu shown above. Note that in
the C section, there are commands to merge both the variant A and variant B
diffs using the bindings @kbd{mab} or @kbd{mba}, depending on the desired order
the diffs are to be merged.
-
-@node Ediff Unicode Symbol Support
-@subsubsection Ediff Unicode Symbol Support
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual Ediff
will use Unicode symbols as appropriate in its menus.
-
-@node EditKit
-@section EditKit
-
-@cindex EditKit
-@vindex casual-editkit-main-tmenu
-
-Casual EditKit provides a user interface for the numerous editing commands
offered by Emacs. Its top-level library is @code{casual-editkit}. As text
editing is a core feature of Emacs, the menus provided here are intended to be
made available in a global fashion for buffers that are intended to be edited.
-
-@image{images/casual-editkit-main-screenshot,,,,png}
-
-Casual EditKit endeavors to surface the many different editing commands
offered by Emacs via Transient menus. The main menu
(@code{casual-editkit-main-tmenu}) both demonstrates and provides a reference
to all EditKit menus. Motivated users can customize this menu to their taste.
-
-@menu
-* EditKit Install::
-* EditKit Usage::
-@end menu
-
-@node EditKit Install
-@subsection EditKit Install
-
-@cindex EditKit Install
-
-A reference menu (@code{casual-editkit-main-tmenu}) illustrating nearly all
the different menus offered by Casual EditKit is provided. This menu can be
used “as-is” with your binding of preference. For consistency with other Casual
Packages, the binding @kbd{C-o} is used in the example below. Other candidate
bindings include @kbd{M-o} and @kbd{F10}. To facilitate default access to this
menu, the configuration below sets this binding to be global which can be
overridden per mode. This is [...]
-
-@lisp
-(keymap-global-set "C-o" #'casual-editkit-main-tmenu)
-@end lisp
-
-For motivated users desiring a bespoke solution, it is recommended that they
use Casual EditKit as a library of menus to build their own workflows.
-
-@node EditKit Usage
-@subsection EditKit Usage
-
-@cindex EditKit Usage
-
-@image{images/casual-editkit-main-screenshot,,,,png}
-
-The main menu of Casual EditKit (@code{casual-editkit-main-tmenu}) is
organized into the following sections:
-
-@table @asis
-@item File
-Commands related to opening files or buffers are provided here.
-
-@item Edit
-Text editing commands are provided here.
-
-From this section, rectangle commands are made available via the “@kbd{e}
Edit›” → “@kbd{R} Rectangle›” binding combination.
-
-@item Sexp
-Text editing commands specific for a balanced expression (Sexp) are provided
here.
-
-@item Tools
-Commands for invoking different tools are provided here.
-
-@item Miscellaneous (unlabeled)
-Commands related to bookmarks, window management, project (Emacs file
organization), search & replace, and macros are found here.
-@end table
-
-Casual EditKit has numerous menus to cover a variety of edit related commands.
-
-@menu
-* Register commands::
-* Edit commands::
-* Window management::
-* Search & Replace commands::
-* Open commands::
-* Project commands::
-* Bookmark commands::
-* Emoji & Symbol Insertion::
-* Tool commands::
-* Narrow/Widen Commands::
-* Macro::
-* EditKit Settings::
-@end menu
-
-@node Register commands
-@subsubsection Register commands
-
-@cindex Registers
-@vindex casual-editkit-registers-tmenu
-
-Support for register commands (@ref{Registers,,,emacs,}) is provided by the
menu @code{casual-editkit-registers-tmenu}. It is available via the menu item
“@kbd{r} Registers›” in the navigation row at the bottom of
@code{casual-editkit-main-tmenu}.
-
-Register commands for saving and recalling text, point, window configuration,
and keyboard macros are provided by this menu.
-
-@image{images/casual-editkit-registers-screenshot,,,,png}
-
-@node Edit commands
-@subsubsection Edit commands
-
-@cindex Edit Commands
-@vindex casual-editkit-edit-tmenu
-
-This menu contains commands and sub-menus related to editing text.
-
-@image{images/casual-editkit-edit-screenshot,,,,png}
-
-Depending on the buffer mode, text can be operated on with different
granularity as words, sentences, paragraphs, balanced expressions, functions
(defuns). The following sub-menus illustrate what operations can be done on the
different text granularity.
-
-@subheading Mark›
-@cindex Mark commands
-@vindex casual-editkit-mark-tmenu
-Text can be marked with different granularity with this menu. Note that
marking functions (Defun) is only supported for modes derived from
@code{prog-mode}.
-
-@image{images/casual-editkit-mark-screenshot,,,,png}
-
-@subheading Copy›
-@cindex Copy commands
-@vindex casual-editkit-copy-tmenu
-Text can be copied with different granularity with this menu.
-
-@image{images/casual-editkit-copy-screenshot,,,,png}
-
-@subheading Kill (Cut)›
-@cindex Kill commands
-@cindex Cut commands
-@vindex casual-editkit-kill-tmenu
-Text can be cut (killed) with different granularity with this menu.
-
-@image{images/casual-editkit-kill-screenshot,,,,png}
-
-@subheading Move›
-@cindex Move commands
-@vindex casual-editkit-move-tmenu
-Text can be moved forwards or backwards with different granularity with this
menu. Note that selecting a granularity will raise another menu to allow
selection of direction (forward, backward) the text is to be moved. To enable
repeat operation, that menu is persisted and must be dismissed either with
either @code{C-q} (dismiss all) or @code{C-g} (dismiss to previous menu).
-
-@image{images/casual-editkit-move-screenshot,,,,png}
-
-@subheading Transpose›
-@cindex Transpose commands
-@vindex casual-editkit-transpose-tmenu
-Text can be transposed with different granularity with this menu.
-
-@image{images/casual-editkit-transpose-screenshot,,,,png}
-
-@subheading Transform›
-@cindex Transform commands
-@vindex casual-editkit-transform-tmenu
-Text can be transformed with different granularity with this menu. Supported
transformations are capitalization, lower and upper casing of text.
-
-@image{images/casual-editkit-transform-screenshot,,,,png}
-
-@subheading Delete›
-@cindex Delete commands
-@vindex casual-editkit-delete-tmenu
-Operations involving text deletion are included in this menu, including
joining lines and zapping to a character.
-
-@image{images/casual-editkit-delete-screenshot,,,,png}
-
-@subheading Sort›
-@cindex Sort commands
-@vindex casual-editkit-sort-tmenu
-Sorting operations on different sections of text are supported, as well as
support for sorting off a field. Press @code{?} or @code{C-h} to get help for a
specific command.
-
-@image{images/casual-editkit-sort-screenshot,,,,png}
-
-@subheading Reformat›
-@cindex Reformat commands
-@vindex casual-editkit-reformat-tmenu
-Commands to reformat text such as filling, centering, and repunctuating
sentences are provided here. Press @code{?} or @code{C-h} to get help for a
specific command.
-
-@image{images/casual-editkit-reformat-screenshot,,,,png}
-
-
-@subheading Rectangle›
-@cindex Rectangle commands
-@vindex casual-editkit-rectangle-tmenu
-
-This menu offers all the rectangle commands. It is packaged as a sub-menu of
@code{casual-editkit-edit-tmenu}.
-
-@image{images/casual-editkit-rectangle-screenshot,,,,png}
-
-@node Window management
-@subsubsection Window management
-
-@cindex Window management
-@vindex casual-editkit-window-tmenu
-This menu provides support for different Emacs window management commands.
Note that in Emacs, a window (@ref{Basic Windows,,,elisp,}) is defined
differently than its usage in contemporary graphical user interfaces.
-
-@image{images/casual-editkit-window-screenshot,,,,png}
-
-If the variable @code{casual-lib-use-unicode} is set to @code{t}, then Unicode
symbols are used in the labels.
-
-@image{images/casual-editkit-window-unicode-screenshot,,,,png}
-
-@subheading Window Deletion
-@cindex Window deletion
-@vindex casual-editkit-window-delete-tmenu
-This menu provides support for deleting windows.
-
-@image{images/casual-editkit-window-delete-screenshot,,,,png}
-
-@node Search & Replace commands
-@subsubsection Search & Replace commands
-
-@cindex Search & Replace commands
-@vindex casual-editkit-search-tmenu
-Operations related to search and replace are captured by this menu. Note that
this menu uses Transient prefix arguments (@code{--backward} and
@code{--regexp}). This is because some commands have variants involving
direction and whether to search using a regexp. Commands that support direction
will by default operate forward of the current point if @code{--backward} is
not enabled.
-
-@image{images/casual-editkit-search-screenshot,,,,png}
-
-@node Open commands
-@subsubsection Open commands
-
-@cindex Open commands
-@vindex casual-editkit-open-tmenu
-Commands related to opening a file (either for writing or read-only) are
supported here. Included are commands for visiting and renaming a file or
buffer. The @strong{Project} sub-menu is also offered here.
-
-@image{images/casual-editkit-open-screenshot,,,,png}
-
-@node Project commands
-@subsubsection Project commands
-
-@cindex Project commands
-@vindex casual-editkit-project-tmenu
-Project-related commands are listed in this menu.
-
-@image{images/casual-editkit-project-screenshot,,,,png}
-
-@node Bookmark commands
-@subsubsection Bookmark commands
-
-@cindex Bookmark commands
-@vindex casual-editkit-bookmarks-tmenu
-Commands edit, add, or jump to a bookmark are captured in this menu.
-
-@image{images/casual-editkit-bookmarks-screenshot,,,,png}
-
-@node Emoji & Symbol Insertion
-@subsubsection Emoji & Symbol Insertion
-
-@cindex Emoji & Symbols
-@vindex casual-editkit-emoji-symbol-tmenu
-
-Insert emoji and symbol characters with this menu. Smart quotes are also
supported by this menu and can be applied to a text region. This menu also
offers the command @code{electric-quote-mode} which is bound to @kbd{Q}.
-
-@image{images/casual-editkit-emoji-symbols-screenshot,,,,png}
-
-@node Tool commands
-@subsubsection Tool commands
-
-@cindex Tool commands
-@vindex casual-editkit-tools-tmenu
-This menu holds an assorted collection of different tools/utilities provided
by Emacs. Motivated users can use this Transient prefix as starting point to
create a menu customized to their needs.
-
-@image{images/casual-editkit-tools-screenshot,,,,png}
-
-@node Narrow/Widen Commands
-@subsubsection Narrow/Widen Commands
-
-@cindex Narrow/Widen Commands
-@vindex casual-editkit-narrow-tmenu
-Support for narrowing and widening (@ref{Narrowing,,,emacs,}) a buffer is
supported. Mode specific narrowing behavior is supported for Org and
@code{prog-mode} derived buffers.
-
-@image{images/casual-editkit-narrow-screenshot,,,,png}
-
-This menu can be modified (@ref{Modifying Existing Transients,,,transient,})
to support narrowing in other modes, particularly those that are packaged with
Emacs. For example, if one wanted narrowing support for Markdown
(@uref{https://jblevins.org/projects/markdown-mode/, markdown-mode}), the
following initialization code can be used.
-
-@lisp
-(transient-append-suffix 'casual-editkit-narrow-tmenu '(0 0)
- ["Markdown"
- :if (lambda () (derived-mode-p 'markdown-mode))
- ("s" "Subtree" markdown-narrow-to-subtree)
- ("b" "Block" markdown-narrow-to-block)
- ("p" "Page" markdown-narrow-to-page)])
-@end lisp
-
-@node Macro
-@subsubsection Macro
-
-@cindex Macro commands
-@vindex casual-editkit-macro-tmenu
-Commands for managing macros are provided for by this menu. Note that macro
creation commands are @emph{not} supported as they are tightly-bound to
keybindings.
-
-@image{images/casual-editkit-macro-screenshot,,,,png}
-
-@node EditKit Settings
-@subsubsection EditKit Settings
-
-@cindex EditKit Settings
-@vindex casual-editkit-settings-tmenu
-Configuration of common editing-related settings are provided here. Most all
settings are set via the @code{customize-variable} interface with the following
exceptions for:
-
-@itemize
-@item
-“Auto-fill Mode (@code{auto-fill-mode})”
-@item
-“Indent Tabs Mode (@code{indent-tabs-mode})”
-@item
-“Fill Column (@code{set-fill-column})”
-@end itemize
-
-Those commands will instead apply to the current buffer. The variables listed
above can be more permanently set via the @code{customize-variable} command.
-
-@image{images/casual-editkit-settings-screenshot,,,,png}
-
-@node Elisp
-@section Elisp
-
-@cindex Elisp
-@vindex casual-elisp-tmenu
-
-Casual Elisp is a user interface for @code{emacs-lisp-mode}. It provides a
menu for commands useful for Elisp development.
-
-@image{images/casual-elisp-screenshot,,,,png}
-
-@menu
-* Elisp Install::
-* Elisp Usage::
-@end menu
-
-@node Elisp Install
-@subsection Elisp Install
-
-@cindex Elisp Install
-
-In your initialization file, bind the Transient @code{casual-elisp-tmenu} to
your key binding of preference. Suggested bindings include @kbd{M-m} and
@kbd{C-c m}. This menu is intended to be auxiliary to @ref{EditKit, , Casual
EditKit}.
-
-@lisp
-(keymap-set emacs-lisp-mode-map "M-m" #'casual-elisp-tmenu)
-@end lisp
-
-@node Elisp Usage
-@subsection Elisp Usage
-
-@cindex Elisp Usage
-
-@image{images/casual-elisp-screenshot,,,,png}
-
-Invoke the Casual Elisp main menu @code{casual-elisp-tmenu} via the binding
@kbd{M-m} (or your binding of preference) in an Elisp window. Typically this is
whenever an @samp{.el} file is opened.
-
-The following sections are offered in the menu:
-
-@table @asis
-@item Evaluate
-Commands to evaluate or execute an Elisp expression (@ref{Eval,,,elisp,}).
-
-@item Xref
-Cross-referencing commands (@ref{Xref,,,emacs,}).
-
-@item Checkdoc
-Checks docstrings in the file.
-
-@item Byte-Compile
-Commands for byte-compilation (@ref{Byte Compilation,,,elisp,}).
-
-@item Find
-Find commands.
-
-@item Navigate
-Commands for Sexp (balanced expression) navigation.
-@end table
-
-
-@subheading Edebug Support
-@cindex Edebug
-
-Using the command prefix @kbd{C-u} when @code{casual-elisp-tmenu} is raised
will change the “@kbd{d} Defun✦” menu item to “@kbd{d} Edebug” to support
instrumenting a function for Edebug (@ref{Edebug,,,elisp,}).
-
-@image{images/casual-elisp-edebug-screenshot,,,,png}
-
-@subheading Elisp Unicode Symbol Support
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual Elisp
will use Unicode symbols as appropriate in its menus.
-
-@image{images/casual-elisp-unicode-screenshot,,,,png}
-
-@node Eshell
-@section Eshell
-
-@cindex Eshell
-@vindex casual-eshell-tmenu
-
-Casual Eshell is a user interface for @code{Eshell}, a shell-like command
interpreter implemented in Emacs Lisp.
-
-@image{images/casual-eshell-screenshot,,,,png}
-
-@menu
-* Eshell Install::
-* Eshell Usage::
-@end menu
-
-@node Eshell Install
-@subsection Eshell Install
-
-@cindex Eshell Install
-
-In your initialization file, bind the Transient @code{casual-eshell-tmenu} to
your key binding of preference.
-
-@lisp
-(keymap-set eshell-mode-map "C-o" #'casual-eshell-tmenu)
-@end lisp
-
-@node Eshell Usage
-@subsection Eshell Usage
-
-@cindex Eshell Usage
-
-Eshell can be invoked via @code{M-x eshell}. In the Eshell window, press
@kbd{C-o} (or your binding of preference) to raise the menu
@code{casual-eshell-tmenu}.
-
-The following sections are offered in the menu:
-
-@table @asis
-@item Input
-Commands supporting input to the current prompt.
-@item Argument
-Commands supporting arguments in the current prompt.
-@item Prompt
-Navigation of previous prompt commands.
-@item Output
-Commands related to display of prompt. Commands marked with the glyph ✦
support an optional prefix (@kbd{C-u}) value.
-@item Misc
-Miscellaneous commands.
-@item Process
-Signal commands to send to the process. This section is only visible when a
process is running.
-@end table
-
-
-@image{images/casual-eshell-process-screenshot,,,,png}
-
-
-@subheading Eshell Unicode Symbol Support
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual
Eshell will use Unicode symbols as appropriate in its menus.
-
-
-@image{images/casual-eshell-unicode-screenshot,,,,png}
-
-@node Help
-@section Help
-
-@cindex Help
-@vindex casual-help-tmenu
-
-Casual Help is a user interface for @code{help-mode}, a major mode for viewing
help text and navigating references in it.
-
-@image{images/casual-help-screenshot,,,,png}
-
-@menu
-* Help Install::
-* Help Usage::
-@end menu
-
-@node Help Install
-@subsection Help Install
-
-@cindex Help Install
-
-In your initialization file, bind the Transient @code{casual-help-tmenu} to
your key binding of preference.
-
-@lisp
-(keymap-set help-mode-map "C-o" #'casual-help-tmenu)
-@end lisp
-
-@code{casual-help-tmenu} deviates from the default bindings of
@code{help-mode-map} as shown in the table below.
-
-@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaa}
{aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
{aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
-@headitem Default Binding
-@tab Casual Binding
-@tab Command
-@tab Notes
-@item l
-@tab M-[
-@tab help-go-back
-@tab Make consistent with Casual Info behavior.
-@item r
-@tab M-]
-@tab help-go-forward
-@tab Make consistent with Casual Info behavior.
-@item n
-@tab N
-@tab help-goto-next-page
-@tab Use to navigate to next page.
-@item p
-@tab P
-@tab help-goto-previous-page
-@tab Use to navigate to previous page.
-@item
-@tab n
-@tab casual-lib-browser-forward-paragraph
-@tab Use to navigate paragraph forward.
-@item
-@tab p
-@tab casual-lib-browser-backward-paragraph
-@tab Use to navigate paragraph backward.
-@end multitable
-
-The following keybindings are recommended to support consistent behavior
between @code{help-mode} and @code{casual-help-tmenu}.
-
-@lisp
-(keymap-set help-mode-map "M-[" #'help-go-back)
-(keymap-set help-mode-map "M-]" #'help-go-forward)
-(keymap-set help-mode-map "p" #'casual-lib-browse-backward-paragraph)
-(keymap-set help-mode-map "n" #'casual-lib-browse-forward-paragraph)
-(keymap-set help-mode-map "P" #'help-goto-previous-page)
-(keymap-set help-mode-map "N" #'help-goto-next-page)
-(keymap-set help-mode-map "j" #'forward-button)
-(keymap-set help-mode-map "k" #'backward-button)
-@end lisp
-
-@node Help Usage
-@subsection Help Usage
-
-@cindex Help Usage
-
-After invoking help via a @code{describe-} command, invoke
@code{casual-help-tmenu} using the binding @code{C-o} (or your binding of
preference).
-
-The following sections are offered in the menu:
-
-@table @asis
-@item Navigation
-Navigation commands with the document.
-@item History
-Navigate history of help invocations.
-@item Link
-Navigate to different references in the help buffer.
-@item Describe
-Get help for different Elisp types.
-@item Info
-If available, then open this help topic in @uref{info.org, Info}.
-@item Source
-Show the Elisp source. If the help displayed is for a customizable variable,
then show a customize menu item.
-@end table
-
-@subheading Help Mode Unicode Symbol Support
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual Man
will use Unicode symbols as appropriate in its menus.
-
-@node HTML
-@section HTML
-
-@cindex HTML
-@vindex casual-html-tmenu
-
-Casual HTML is a user interface for @code{html-mode} (@ref{HTML
Mode,html-mode,,emacs,}).
-
-@image{images/casual-html-screenshot,,,,png}
-Casual also has support for CSS editing (@ref{CSS}).
-
-@menu
-* HTML Install::
-* HTML Usage::
-@end menu
-
-@node HTML Install
-@subsection HTML Install
-
-@cindex HTML Install
-
-In your initialization file, bind the Transient @code{casual-html-tmenu} to
your key binding of preference.
-
-@lisp
-(keymap-set html-mode-map "M-m" #'casual-html-tmenu)
-@end lisp
-
-A different binding (@kbd{M-m}) is used as @code{casual-html-tmenu} is
intended to work alongside with @ref{EditKit Install, , Casual EditKit}.
-
-It is convenient to also bind @code{casual-html-tag-tmenu} as well.
-
-@lisp
-(keymap-set html-mode-map "M-m" #'casual-html-tags-tmenu)
-@end lisp
-
-If HTML Tree-sitter support is enabled, set the keymap @code{html-ts-mode-map}
instead of @code{html-mode-map}.
-
-@node HTML Usage
-@subsection HTML Usage
-
-@cindex HTML Usage
-
-@image{images/casual-html-screenshot,,,,png}
-
-The following sections are offered in the menu:
-
-@table @asis
-@item </>
-SGML tag-related commands.
-@item HTML
-HTML tag-related commands.
-@item Misc
-Miscellaneous commands.
-@item Navigation
-Navigation commands.
-@end table
-
-Note that the item “@kbd{d} Delete” (bound to @code{sgml-delete-tag}) is not
available when HTML Tree-sitter support is enabled.
-
-
-@subheading HTML Tags
-@vindex casual-html-tags-tmenu
-
-This menu provides support for HTML tag-related commands provided by
@code{html-mode}.
-
-@image{images/casual-html-tags-screenshot,,,,png}
-
-@subheading HTML Settings
-@vindex casual-html-settings-tmenu
-
-SGML/HTML mode related settings can be customized here.
-
-@image{images/casual-html-settings-screenshot,,,,png}
-
-@subheading HTML Unicode Symbol Support
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual html
will use Unicode symbols as appropriate in its menus.
-
-@node IBuffer
-@section IBuffer
-
-@cindex IBuffer
-@vindex casual-ibuffer-tmenu
-Casual IBuffer provides a user interface to Emacs IBuffer (@ref{Buffer
Menus,emacs#Buffer Menus,,emacs,}), a mode designed for managing buffers. Its
top-level library is @code{casual-ibuffer}.
-
-IBuffer is a powerful tool for managing Emacs workflows. As Emacs is often
compared to an operating system, through that lens one could compare IBuffer to
being a task manager interface, managing instantiated buffers as opposed to
processes.
-
-@image{images/casual-ibuffer-screenshot,,,,png}
-
-@menu
-* IBuffer Install::
-* IBuffer Usage::
-@end menu
-
-@node IBuffer Install
-@subsection IBuffer Install
-
-@cindex IBuffer Install
-
-In your initialization file, bind the Transinent @code{casual-ibuffer-tmenu}
to your key binding of preference.
-
-@lisp
-(keymap-set ibuffer-mode-map "C-o" #'casual-ibuffer-tmenu)
-@end lisp
-
-Like with Casual Dired, it is convenient to have the menus for filtering and
sorting bound as well. Listed below shows an example of binding
@code{casual-ibuffer-filter-tmenu} and @code{casual-ibuffer-sortby-tmenu} to
@code{F} and @code{s} respectively.
-
-@lisp
-(keymap-set ibuffer-mode-map "F" #'casual-ibuffer-filter-tmenu)
-(keymap-set ibuffer-mode-map "s" #'casual-ibuffer-sortby-tmenu)
-@end lisp
-
-Use these keybindings to configure IBuffer to be consistent with keybindings
used by Casual IBuffer.
-
-@lisp
-(keymap-set ibuffer-mode-map "@{" #'ibuffer-backwards-next-marked)
-(keymap-set ibuffer-mode-map "@}" #'ibuffer-forward-next-marked)
-(keymap-set ibuffer-mode-map "[" #'ibuffer-backward-filter-group)
-(keymap-set ibuffer-mode-map "]" #'ibuffer-forward-filter-group)
-(keymap-set ibuffer-mode-map "$" #'ibuffer-toggle-filter-group)
-@end lisp
-
-While not necessary for Casual IBuffer, enabling @code{hl-line-mode} and
binding mouse clicks in IBuffer adds to a more comfortable IBuffer experience.
Also, adding @code{ibuffer-auto-mode} to @code{ibuffer-mode-hook} will enable
auto-updating.
-
-@lisp
-(require 'hl-line)
-(require 'mouse)
-(add-hook 'ibuffer-mode-hook #'hl-line-mode)
-(add-hook 'ibuffer-mode-hook #'ibuffer-auto-mode)
-(keymap-set ibuffer-mode-map "<double-mouse-1>" #'ibuffer-visit-buffer)
-(keymap-set ibuffer-mode-map "M-<double-mouse-1>"
#'ibuffer-visit-buffer-other-window)
-@end lisp
-
-@node IBuffer Usage
-@subsection IBuffer Usage
-
-@cindex IBuffer Usage
-
-@image{images/casual-ibuffer-screenshot,,,,png}
-
-
-The main menu of Casual IBuffer (@code{casual-ibuffer-tmenu}) is organized
into the following sections:
-
-@table @asis
-@item Operations
-Commands to operate either on the buffer at point or on marked buffers.
-
-@item Mark
-Commands to support the marking of buffers.
-
-@item Display
-Commands to control the display of buffers. Buffers can be sorted by different
criteria.
-
-@item Navigation
-Commands to navigate the buffer list.
-
-@item Filter
-Commands related to filtering/organizing buffers. Support for defining
@emph{Filter Groups} is provided here.
-
-@item Find/Replace in Marked
-Commands to search & replace text in marked buffers are provided here. Note
that commands in this section that modify buffers do @emph{not} save said
buffers.
-
-@item Quick
-Command to jump to a bookmark.
-@end table
-
-@menu
-* IBuffer Marking and Operating::
-* IBuffer Filtering::
-* IBuffer Sorting::
-* IBuffer Unicode Symbol Support::
-@end menu
-
-@node IBuffer Marking and Operating
-@subsubsection IBuffer Marking and Operating
-
-@image{images/casual-ibuffer-main-screenshot,,,,png}
-
-Buffers can be marked using different criteria. Marked buffers can be operated
on. Common operations include saving and deleting buffers. Note that deleting a
buffer populated with a visited file is @emph{not the same} as deleting the
visited file.
-
-From the main menu shown above, control of the display and find/replace
operations are offered.
-
-Note that the menu item “@kbd{@key{RET}} Visit/Toggle” has ``do what I mean''
(DWIM) behavior. If the point is currently on a filter group (described below)
then pressing the @kbd{@key{RET}} key will toggle the visibility of items
matching that filter group. Otherwise, it will visit (open) the buffer.
-
-As with other Casual user interfaces, the ability to jump to a bookmark is
available.
-
-@node IBuffer Filtering
-@subsubsection IBuffer Filtering
-
-@vindex casual-ibuffer-filter-tmenu
-
-@image{images/casual-ibuffer-filter-screenshot,,,,png}
-
-
-IBuffer is embarrasingly rich in the ways it can filter buffers. Once
mastered, IBuffer filtering offers a way to create different views on your
buffer list, enabling you to tailor bespoke views for different workflows. Such
capability comes with a price though: you'll need to understand how IBuffer
wants to organize filters.
-
-Key is the concept of a @emph{Filter Group} which is IBuffer's analog to a
Dired subdirectory (@ref{Subdirectories in Dired,,,emacs,}). But whereas a
subdirectory only maps to a file system directory, a filter group can be
constructed from a diverse set of rules to categorize a buffer.
-
-IBuffer organizes filtering with the following taxonomy:
-
-@enumerate
-@item
-@strong{Filter rule}
-
-The smallest unit of filtering. There are many types of filter rules:
-@itemize
-@item
-filter by major mode
-@item
-filter by derived mode
-@item
-filter by buffer name
-@item
-filter by buffer content
-@item
-filter by basename
-@item
-filter by directory name
-@item
-filter by filename
-@item
-filter by file extension
-@item
-filter by modified buffers
-@item
-filter by an arbitrary Lisp predicate
-@item
-filter by buffer size
-@item
-filter by special buffers
-@item
-filter by buffers visiting files
-
-Casual IBuffer makes the design decision to @strong{not} enumerate the above
in a menu, delegating the work of filter selection to the command
@code{ibuffer-filter-chosen-by-completion}.
-@end itemize
-
-@item
-@strong{Filter}
-
-A @emph{filter} is a logical combination of filter rules. Logic operators such
as AND (&), OR (|) and NOT (!) are used to compose rules into a @emph{filter}.
A single filter rule can also be construed as a filter.
-
-Properties of filters:
-
-@itemize
-@item
-A filter can be defined and saved for subsequent use.
-@itemize
-@item
-Filters are saved in the customizable variable @samp{ibuffer-saved-filters}.
-@item
-Multiple filters can be applied at the same time to a set of buffers.
-@end itemize
-@item
-Multiple filters are applied in LIFO order. Removing a filter is a ``pop''
operation.
-@itemize
-@item
-Rules that are combined with a logic operator are treated as a single element
of the LIFO stack.
-@item
-To individually edit the combination, use the @emph{Decompose} command to
remove the logic operator first.
-@end itemize
-@end itemize
-
-@item
-@strong{Filter Group}
-
-A filter group is set of filters. The set itself is named with an identifier
that is user-defined.
-
-Properties of filter groups:
-
-@itemize
-@item
-A filter group can be defined and saved for subsequent use but with a special
qualifier:
-@itemize
-@item
-Filter groups are only saved as a collection (more below) in the customizable
variable @samp{ibuffer-saved-filter-groups}. A filter group can not be saved
individually.
-@end itemize
-@item
-Multiple filter groups can be applied to partition the buffer list.
-@item
-Multiple filter groups are applied in LIFO order. Removing a filter group is a
``pop'' operation.
-@itemize
-@item
-Similar LIFO and decompose behavior applicable to a filter group is supported.
-@end itemize
-@end itemize
-
-@item
-@strong{Filter Group Collection}
-
-A @emph{collection} is a set of filter groups that can be named with a
user-defined identifier. Only one collection can be applied to a buffer list at
a time. However, many different collections can be defined, allowing for
different views of the same buffer list.
-@end enumerate
-
-@strong{Creating Filters}
-
-The basic procedure for making a filter that applies to the entire buffer list
is as follows:
-
-@enumerate
-@item
-From the @strong{Filter} menu, create a filter via @emph{(SPC) Rule@dots{}}
and some desired combination of operators.
-@item
-Save the filter via @emph{(s) Save@dots{}}. You will be prompted to provide a
name for the filter. This filter will be saved in the variable
@samp{ibuffer-saved-filters}.
-@item
-To recall this filter at a subsequent time, use @emph{(r) Switch to@dots{}} in
the @strong{Add} section of the @strong{Filter} menu.
-@end enumerate
-
-@strong{Creating a Collection of Filter Groups}
-
-Here is where the taxonomy becomes significant as the IBuffer command set
unfortunately does not provide much observability on edit operations to filters.
-
-@enumerate
-@item
-Create a filter as described above.
-@item
-In the @strong{Add} section of the @strong{Filter} menu, select @emph{(g)
Create Filter Group@dots{}} to convert the filter into a filter group. You will
be prompted to name the filter group. This group name will be enclosed by
square brackets [].
-@item
-Multiple filter groups can be created by repeating steps 1 and 2 above. Note
that when constructing a filter group, the IBuffer window will @emph{not}
provide observability of existing filter groups on the buffer list.
-@item
-You can save the set of filter groups as a @emph{collection} in the
@strong{Collection} section with the command @emph{(S) Save@dots{}}. You will
be prompted to name the collection. Note that only one collection can be used
at a time in IBuffer.
-@end enumerate
-
-Out of the box, it is best to think of the IBuffer commands for editing buffer
filters as a kit of parts and an arguably incomplete one at that. The Casual
IBuffer filter menu (@samp{casual-ibuffer-filter-tmenu}) is my attempt to build
a comprehensible filter editor UI from this kit. Whether it succeeds in being
comprehensible is left to user feedback.
-
-@node IBuffer Sorting
-@subsubsection IBuffer Sorting
-
-@vindex casual-ibuffer-sortby-tmenu
-
-@image{images/casual-ibuffer-sortby-screenshot,,,,png}
-
-The buffer list can be sorted using different criteria as shown in the
screenshot above.
-
-Sort ordering can be reversed via the @emph{Invert} command.
-
-@node IBuffer Unicode Symbol Support
-@subsubsection IBuffer Unicode Symbol Support
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual
IBuffer will use Unicode symbols as appropriate in its menus. The following
mapping is shown in the table below:
-
-@multitable {aaaaaaaaa} {aaaaaaaa} {aaaaaaa}
-@headitem Name
-@tab Plain
-@tab Unicode
-@item :previous
-@tab Previous
-@tab ↑
-@item :next
-@tab Next
-@tab ↓
-@item :marked
-@tab Marked
-@tab ❯
-@item :group
-@tab Group
-@tab []
-@item :jump
-@tab Jump
-@tab 🚀
-@end multitable
-
-@node Image
-@section Image
-
-@cindex Image
-@vindex casual-image-tmenu
-
-Casual Image is a user interface for Image Mode (@ref{Image Mode,,,emacs,}).
Its top level library is @code{casual-image}.
-
-Resizing an image is supported if ImageMagick 6 or 7 is installed. This
interface deviates significantly with naming conventions used by
@code{image-mode} to be more in alignment with conventional image editing tools.
-
-@image{images/casual-image-main-screenshot,,,,png}
-
-@menu
-* Image Install::
-* Image Usage::
-@end menu
-
-@node Image Install
-@subsection Image Install
-
-@cindex Image Install
-
-The main menu for Casual Image is @code{casual-image-tmenu}. Bind this menu in
the keymap @code{image-mode-map} as follows in your initialization file.
-
-@lisp
-(keymap-set image-mode-map "C-o" #'casual-image-tmenu)
-@end lisp
-
-@node Image Usage
-@subsection Image Usage
-
-@cindex Image Usage
-
-@image{images/casual-image-main-screenshot,,,,png}
-
-The main menu for Casual Image (@code{casual-image-tmenu}) is organized into
the following sections:
-
-@table @asis
-@item View
-Commands to control the display of the image. None of these commands will
mutate the image file.
-
-@item Edit
-Commands to edit the image file.
-
-@item Scroll
-Commands to scroll an image view that is larger than its window size.
-
-@item Edge
-Commands to navigate to the edges of an image view that is larger than its
window size.
-
-@item Traverse
-Commands to navigate to other image files in the same directory as the current
image.
-
-@item Mark
-Commands to mark in Dired the current image.
-
-@item Misc
-Miscellaneous commands.
-@end table
-
-@menu
-* Image Resize::
-* Image Unicode Symbol Support::
-* Image Mode Command Naming::
-@end menu
-
-@node Image Resize
-@subsubsection Image Resize
-
-@cindex Image Resize
-
-If ImageMagick (version 6 or 7) is installed, Casual Image can resize an image
using it. The Transient @code{casual-image-resize-tmenu} is a streamlined
interface to the ImageMagick @code{-resize} function.
-
-Note that if the image file has been modified, the resize interface will be
disabled. Save the image file before resizing.
-
-@image{images/casual-image-resize-screenshot,,,,png}
-
-@subheading Image Resize Options
-@itemize
-@item
-(g) Geometry -
@uref{https://imagemagick.org/script/command-line-processing.php#geometry,
ImageMagick specifier} for the resize geometry.
-@item
-(o) Output to another file - If enabled, then the user will be prompted for a
different output file, else it will @emph{irreversibly} update the current
image file.
-@item
-(t) Type - Specify if @emph{adaptive} or @emph{interpolative} resizing should
be used. If nothing is specified then @emph{standard} resizing is used.
-@end itemize
-
-@node Image Unicode Symbol Support
-@subsubsection Image Unicode Symbol Support
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual Image
will use Unicode symbols as appropriate in its menus.
-
-@node Image Mode Command Naming
-@subsubsection Image Mode Command Naming
-
-Casual Image makes a number of opinionated changes to the naming of commands
provided by @code{image-mode}.
-
-The table below shows the mapping between names used by Casual to commands
provided by @code{image-mode}.
-
-@multitable {aaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
{aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
-@headitem Casual Name
-@tab Image Mode Name
-@tab Notes
-@item Zoom In
-@tab @code{image-increase-size}
-@tab “Zoom” is more commonly used.
-@item Zoom Out
-@tab @code{image-decrease-size}
-@tab “Zoom” is more commonly used.
-@item Original Size
-@tab @code{image-transform-reset-to-original}
-@tab Using a more concise name.
-@item Fit to Window
-@tab @code{image-transform-fit-to-window}
-@tab Using a more concise name.
-@item Rotate Clockwise 90°x
-@tab @code{image-transform-set-rotation}
-@tab Rotation command is absolute and only works in increments of 90°.
-@item % of Original
-@tab @code{image-transform-set-percent}
-@tab Percent command is absolute in that it computes from the original image
size.
-@item Crop
-@tab @code{image-crop}
-@tab Command modifies image.
-@item Fill
-@tab @code{image-cut}
-@tab Command modifies image. This command is primarily a fill operation, so is
renamed appropriately.
-@item Set Fill Color
-@tab @code{image-cut-color}
-@tab This variable supports a fill operation, so is renamed appropriately.
-@item Save
-@tab @code{save-buffer}
-@tab Saves modified image file.
-@item Save as
-@tab @code{image-save}
-@tab Command to save mutated image as another file via a mini-buffer prompt.
-@item Rename
-@tab @code{rename-visited-file}
-@tab Renames the current image file.
-@item Revert
-@tab @code{revert-buffer}
-@tab Reverts the current image file.
-@item Scroll Up
-@tab @code{image-previous-line}
-@tab Rename to use arrow key direction.
-@item Scroll Down
-@tab @code{image-next-line}
-@tab Rename to use arrow key direction.
-@item Scroll Left
-@tab @code{image-backward-hscroll}
-@tab Rename to use arrow key direction.
-@item Scroll Right
-@tab @code{image-forward-hscroll}
-@tab Rename to use arrow key direction.
-@item Left Edge
-@tab @code{image-bol}
-@tab Rename to use better descriptive term.
-@item Right Edge
-@tab @code{image-eol}
-@tab Rename to use better descriptive term.
-@item Top-left
-@tab @code{image-bob}
-@tab Rename to use better descriptive term.
-@item Bottom-right
-@tab @code{image-eob}
-@tab Rename to use better descriptive term.
-@item Previous Image
-@tab @code{image-previous-file}
-@tab Visit the preceding image in the same directory as the current file.
-@item Next Image
-@tab @code{image-next-file}
-@tab Visit the next image in the same directory as the current file.
-@item Mark Image
-@tab @code{image-mode-mark-file}
-@tab Mark the current file in the appropriate Dired buffer(s).
-@item Unmark Image
-@tab @code{image-mode-unmark-file}
-@tab Unmark the current file in the appropriate Dired buffer(s).
-@item Copy filename
-@tab @code{image-mode-copy-file-name-as-kill}
-@tab Push the currently visited file name onto the kill ring.
-@end multitable
-
-@node Info
-@section Info
-
-@cindex Info
-@vindex casual-info-tmenu
-
-Casual Info is a user interface for the Emacs Info Reader. Its top level
library is @code{casual-info}.
-
-@image{images/casual-info-screenshot,,,,png}
-
-@menu
-* Info Install::
-* Info Usage::
-@end menu
-
-@node Info Install
-@subsection Info Install
-
-@cindex Info Install
-The main menu for Casual Info is @code{casual-info-tmenu}. Bind this menu in
the keymap @code{Info-mode-map} as follows in your initialization file.
-
-@lisp
-(keymap-set Info-mode-map "C-o" #'casual-info-tmenu)
-@end lisp
-
-While not required, adding this configuration to your Emacs initialization
file will synchronize keybindings between Casual Info and the Info reader. A
nice visual improvement is to use @code{hl-line-mode} to highlight the line
where the cursor is at. Enabling @code{scroll-lock-mode} will enable scrolling
the buffer for content that is larger than its window size with the navigation
keys.
-
-@lisp
-;; # Info
-;; Use web-browser history navigation bindings
-(keymap-set Info-mode-map "M-[" #'Info-history-back)
-(keymap-set Info-mode-map "M-]" #'Info-history-forward)
-;; Bind p and n to paragraph navigation
-(keymap-set Info-mode-map "p" #'casual-info-browse-backward-paragraph)
-(keymap-set Info-mode-map "n" #'casual-info-browse-forward-paragraph)
-;; Bind h and l to navigate to previous and next nodes
-;; Bind j and k to navigate to next and previous references
-(keymap-set Info-mode-map "h" #'Info-prev)
-(keymap-set Info-mode-map "j" #'Info-next-reference)
-(keymap-set Info-mode-map "k" #'Info-prev-reference)
-(keymap-set Info-mode-map "l" #'Info-next)
-;; Bind / to search
-(keymap-set Info-mode-map "/" #'Info-search)
-;; Set Bookmark
-(keymap-set Info-mode-map "B" #'bookmark-set)
-
-(add-hook 'Info-mode-hook #'hl-line-mode)
-(add-hook 'Info-mode-hook #'scroll-lock-mode)
-@end lisp
-
-@node Info Usage
-@subsection Info Usage
-
-@cindex Info Usage
-
-@image{images/casual-info-screenshot,,,,png}
-
-Invoke @code{M-x info} to launch the Info reader. Move the point inside the
Info window and invoke @kbd{C-o} (or a binding of your choosing) to launch the
Casual Info menu.
-
-The main menu for Casual Info is organized into the following sections:
-
-@table @asis
-@item Overview
-Commands that navigate you to a starting point in the info documentation.
-
-@item Goto
-Commands that have you specify where to goto in the structure of an Info
document.
-
-@item Search
-Commands for searching Info.
-
-@item History
-Commands related to the history of pages (nodes) navigated to in Info. Note
that these commands should not be confused with structural navigation.
-
-@item Scroll
-Commands to scroll down or up the current Info page.
-
-@item Navigation
-Command related to structurally navigating an Info document. Note that these
commands should not be confused with historical navigation.
-
-@item Quick
-Miscellaneous commands for working with an Info document. Included are
commands for bookmarks, copying the current node name, and cloning the buffer.
-@end table
-
-@subheading Info Unicode Symbol Support
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual Info
will use Unicode symbols as appropriate in its menus.
-
-@node I-Search
-@section I-Search
-
-@cindex isearch
-@cindex I-Search
-@vindex casual-isearch-tmenu
-
-Casual I-Search is a user interface for Emacs Incremental Search
(@ref{Incremental Search,emacs#Incremental Search),,emacs,}. Its top level
library is @code{casual-isearch}.
-
-@image{images/casual-isearch-tmenu,,,,png}
-
-@menu
-* I-Search Install::
-* I-Search Usage::
-@end menu
-
-@node I-Search Install
-@subsection I-Search Install
-
-@cindex I-Search Install
-
-The main menu for Casual I-Search is @code{casual-isearch-tmenu}. Bind this
menu to @kbd{C-o} (or your binding of preference) in the keymap
@code{isearch-mode-map} as follows in your initialization file.
-
-@lisp
-(keymap-set isearch-mode-map "C-o" #'casual-isearch-tmenu)
-@end lisp
-
-@node I-Search Usage
-@subsection I-Search Usage
-
-@cindex I-Search Usage
-
-@image{images/casual-isearch-tmenu,,,,png}
-
-The main menu for Casual I-Search is organized into the following sections:
-
-@table @asis
-@item Edit Search String
-Commands to edit the search string. The type/extent of the string (word,
symbol, line, thing) can be specified here.
-
-@item Replace
-Invoke @code{query-replace} or @code{query-replace-regexp} on matched strings.
-
-@item Toggle
-Commands to configure the type of search. Toggling any menu item in this
section will dismiss the Transient menu and return you back to the I-Search
minibuffer prompt.
-
-@item Misc
-Miscellaneous commands. From here the search string can be fed into
@code{occur} or be highlighted.
-
-@item Navigation
-Navigation commands for matched strings.
-@end table
-
-When in search mode (typically via the keybinding @kbd{C-s} or @kbd{C-r}),
pressing the keybinding @kbd{C-o} (or binding of your preference) will raise
the Transient menu @code{casual-isearch-tmenu}. Once raised, only the
@emph{I-Search} commands in the @strong{Toggle}, @strong{Replace}, and
@strong{Misc} sections will automatically dismiss the menu when selected. All
other @emph{I-Search} commands will @emph{not} dismiss the menu.
-
-Use @kbd{C-g} to dismiss this Transient menu.
-
-@node Make
-@section Make
-
-@cindex Make
-@vindex casual-make-tmenu
-
-Casual Make is a user interface for @code{make-mode}, a mode tailored for
editing a Makefile.
-
-@image{images/casual-make-screenshot,,,,png}
-
-@menu
-* Make Install::
-* Make Usage::
-@end menu
-
-@node Make Install
-@subsection Make Install
-
-@cindex Make Install
-
-In your initialization file, bind the Transient @code{casual-make-tmenu} to
your key binding of preference. Two suggested bindings are @kbd{M-m} or
@kbd{C-c m}.
-
-@lisp
-(keymap-set makefile-mode-map "M-m" #'casual-make-tmenu)
-@end lisp
-
-@node Make Usage
-@subsection Make Usage
-
-@cindex Make Usage
-
-@image{images/casual-make-screenshot,,,,png}
-
-It is recommended that some basic knowledge of the @strong{make} command is
known before using Casual Make.
-
-When in a Makefile buffer, use @kbd{M-m} (or your binding of choice) to raise
the menu @code{casual-make-tmenu}. You will be presented with a menu with the
following sections:
-
-@table @asis
-@item Edit
-Commands for editing the makefile. Note that the backslash and comment
commands require a region to be selected.
-
-@item Pickup as targets
-Commands for synchronizing @code{make-mode} with the target definitions in the
makefile. Use these commands to refresh the known list of targets.
-
-@item Misc
-Miscellaneous commands related to working with a makefile.
-
-@item Navigate
-Commands to support navigation within the makefile.
-@end table
-
-Unless you edit makefiles frequently, it is unlikely to recall what an
automatic variable declaration means. Casual Make provides the command
@code{casual-make-identify-autovar-region} to identify a region-selected
automatic variable via the menu item “@kbd{.} Identify Auto Var” in
@code{casual-make-tmenu}. A short description of the automatic variable is
shown in the mini-buffer.
-
-@menu
-* Makefile Type Selection::
-* Automatic Variables::
-* Make Unicode Symbol Support::
-@end menu
-
-@node Makefile Type Selection
-@subsubsection Makefile Type Selection
-
-@cindex Makefile Type Selection
-@vindex casual-make-mode-select-tmenu
-
-As there are different variants of @strong{make} and makefile formats, you can
configure the mode for different specific makefile types. This can be done by
selecting “@kbd{t} Makefile Type›” in @code{casual-make-tmenu}.
-
-@image{images/casual-make-mode-select-screenshot,,,,png}
-
-@node Automatic Variables
-@subsubsection Automatic Variables
-
-@cindex Automatic Variables
-@vindex casual-make-automatic-variables-tmenu
-
-Casual Make provides a menu to enter GNU Make-style @ref{Automatic
Variables,automatic variables,,make,}. Note that each keybinding is identical
to the automatic variable it represents to both reinforce its declaration and
to avoid making another mapping. This menu is available from the menu item
“@kbd{a} Automatic Variables›” in @code{casual-make-tmenu}.
-
-@image{images/casual-make-automatic-variables-screenshot,,,,png}
-
-@node Make Unicode Symbol Support
-@subsubsection Make Unicode Symbol Support
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual Make
will use Unicode symbols as appropriate in its menus.
-
-@node Man
-@section Man
-
-@cindex Man
-@vindex casual-man-tmenu
-
-Casual Man is a user interface for @code{Man-mode}, a Man page reader.
-
-@image{images/casual-man-screenshot,,,,png}
-
-@menu
-* Man Install::
-* Man Usage::
-@end menu
-
-@node Man Install
-@subsection Man Install
-
-@cindex Man Install
-
-In your initialization file, bind the Transient @code{casual-man-tmenu} to
your key binding of preference.
-
-@lisp
-(keymap-set Man-mode-map "C-o" #'casual-man-tmenu)
-@end lisp
-
-@code{casual-man-tmenu} deviates from the default bindings of
@code{Man-mode-map} as shown in the table below.
-
-@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaa}
{aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
{aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
-@headitem Default Binding
-@tab Casual Binding
-@tab Command
-@tab Notes
-@item n
-@tab [
-@tab Man-previous-section
-@tab Make consistent with Casual Dired and IBuffer behavior.
-@item p
-@tab ]
-@tab Man-next-section
-@tab Make consistent with Casual Dired and IBuffer behavior.
-@item k
-@tab K
-@tab Man-kill
-@tab Reserve k for navigation.
-@item
-@tab k
-@tab previous-line
-@tab
-@item
-@tab j
-@tab next-line
-@tab
-@item
-@tab n
-@tab casual-lib-browser-forward-paragraph
-@tab Use to navigate paragraph forward.
-@item
-@tab p
-@tab casual-lib-browser-backward-paragraph
-@tab Use to navigate paragraph backward.
-@end multitable
-
-The following keybindings are recommended to support consistent behavior
between @code{Man-mode} and @code{casual-man-tmenu}.
-
-@lisp
-(keymap-set Man-mode-map "n" #'casual-lib-browse-forward-paragraph)
-(keymap-set Man-mode-map "p" #'casual-lib-browse-backward-paragraph)
-(keymap-set Man-mode-map "[" #'Man-previous-section)
-(keymap-set Man-mode-map "]" #'Man-next-section)
-(keymap-set Man-mode-map "j" #'next-line)
-(keymap-set Man-mode-map "k" #'previous-line)
-(keymap-set Man-mode-map "K" #'Man-kill)
-(keymap-set Man-mode-map "o" #'casual-man-occur-options)
-@end lisp
-
-@node Man Usage
-@subsection Man Usage
-
-@cindex Man Usage
-
-@image{images/casual-man-screenshot,,,,png}
-
-The Man page reader can be invoked via @code{M-x man}, where the user is
prompted for a search key. This search key is typically the name of a command
that has an associated Man page. In the Man page window, pressing @kbd{C-o} (or
your binding of preference) will raise the menu @code{casual-man-tmenu}.
-
-The following sections are offered in the menu:
-
-@table @asis
-@item Navigation
-Navigation commands with the document.
-@item Paragraph
-Navigation commands by paragraph.
-@item Section
-Navigation commands by section.
-@item Link
-Jump to other Man pages referenced in the current Man page.
-@item Page
-If the Man page reader is configured to display all manual pages for a given
search key, navigation commands for multiple pages is provided.
-@end table
-
-@subheading Options Navigation
-
-@code{casual-man-tmenu} provides the menu item @kbd{o} which runs the command
@code{casual-man-occur-options}. This will invoke @code{occur} with a regexp
that searches for command line options (for example, ``--foo'', ``-a'') that
can be navigated via the @code{occur} interface.
-
-@subheading Man Settings
-
-By default, the Man page reader will @emph{not} display all manual pages for
given search key. This can be changed in the Settings menu
@code{casual-man-settings-tmenu} that can be invoked by pressing @kbd{,} in
@code{casual-man-tmenu}.
-
-Press ‘s’ and configure @code{Man-switches} to have the value ``-a'' to get
all manual pages.
-
-
-@image{images/casual-man-settings,,,,png}
-
-
-@subheading Man Unicode Symbol Support
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual Man
will use Unicode symbols as appropriate in its menus.
-
-@node RE-Builder
-@section RE-Builder
-
-@cindex RE-Builder
-@vindex casual-re-builder-tmenu
-
-Casual RE-Builder is a user interface for RE-Builder. Its top level library is
@code{casual-re-builder}.
-
-@image{images/casual-re-builder-screenshot,,,,png}
-
-@menu
-* RE-Builder Install::
-* RE-Builder Usage::
-@end menu
-
-@node RE-Builder Install
-@subsection RE-Builder Install
-
-@cindex RE-Builder Install
-
-The main menu for Casual RE-Builder is @code{casual-re-builder-tmenu}. Bind
this menu to your preference in the keymaps @code{reb-mode-map} and
@code{reb-lisp-mode-map} as follows in your initialization file.
-
-@lisp
-(keymap-set reb-mode-map "C-o" #'casual-re-builder-tmenu)
-(keymap-set reb-lisp-mode-map "C-o" #'casual-re-builder-tmenu)
-@end lisp
-
-@node RE-Builder Usage
-@subsection RE-Builder Usage
-
-@cindex RE-Builder Usage
-
-@image{images/casual-re-builder-screenshot,,,,png}
-
-When the command @code{re-builder} is invoked, a buffer named
``✳︎RE-Builder✳︎'' is created. Activate Casual RE-Builder with the binding
@{@{@{kbd(C-o@}@}@} (or one of your preference).
-
-At the top of the menu shows the title ``RE-Builder'' with the target buffer
enclosed in parenthesis. The regexp pattern will be applied to the target
buffer. The target buffer can be changed with the “@kbd{b} Target buffer” menu
item.
-
-Emacs supports three different regexp syntax: 1) read, 2) string, 3) Rx. Use
the “@kbd{x} Syntax” menu item to alter it. The current syntax is shown in
parenthesis.
-
-If multiple sub-expressions are in the regexp pattern, then they can be
observed via the “@kbd{s} Subexp mode” menu item.
-
-If the regexp pattern entered in ``✳︎RE-Builder✳︎'' finds multiple matches, a
match can be navigated to via the “@kbd{p} Previous” and “@kbd{n} Next” menu
items.
-
-@subheading Exporting the Regexp Pattern
-Once a desired regexp pattern is defined, there are two menu items that can be
used to export (copy) it to the kill-ring for further use.
-
-@itemize
-@item
-“@kbd{w} Interactive” will copy the regexp to the kill-ring so that it can be
yanked in an interactive command that requires a regexp (e.g.
@code{query-replace-regexp}).
-@itemize
-@item
-This can only be used when the regexp syntax is set to @code{string}.
-@item
-❗️When yanking (typically @kbd{C-y}) a regexp into an interactive prompt, you
@emph{must} have the point/focus in the minibuffer prompt (typically via
mouse). Otherwise the desired content can be altered with extra escaping.
-@end itemize
-@item
-“@kbd{c} Code” will copy the regexp to the kill-ring so that it can be yanked
into a Elisp code that requires a regexp argument.
-@item
-“@kbd{g} Interactive grep” will copy the regexp so that it can be used with
command that take a GNU grep regex argument.
-@itemize
-@item
-Example commands that do this are @code{dired-do-find-regexp} and
@code{dired-do-find-regexp-and-replace}.
-@item
-This command presumes that you have GNU grep installed and configured for use
by Emacs.
-@item
-❗️At current this is an experimental feature. The regexp exported from
RE-Builder may not work. If so please report an
@uref{https://github.com/kickingvegas/casual-re-builder/issues, issue}
describing the desired regexp and the target text.
-@item
-This can only be used when the regexp syntax is set to @code{string}.
-@end itemize
-@end itemize
-
-@subheading Regexp Syntax Help
-The menu item @kbd{i} will invoke the Info page for regexp syntax with respect
to the current syntax type.
-
-@subheading Quitting RE-Builder
-Select “@kbd{q} Quit” to exit the RE-Builder tool.
-
-@subheading RE-Builder Unicode Symbol Support
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual
RE-Builder will use Unicode symbols as appropriate in its menus. The following
mapping is shown in the table below:
-
-@multitable {aaaaaaaaa} {aaaaaaaa} {aaaaaaa}
-@headitem Name
-@tab Plain
-@tab Unicode
-@item :previous
-@tab Previous
-@tab ↑
-@item :next
-@tab Next
-@tab ↓
-@end multitable
-
-@node Timezone
-@section Timezone
-
-@cindex Timezone
-@vindex casual-timezone-tmenu
-
-Casual Timezone is a library of commands to work with different time zones.
Answer the questions ``what time is it over there?'' or conversely ``what is
the time over there, here?'' with ease using this. Its top level library is
@code{casual-timezone}. Commands from Casual Timezone are found in the menu
@code{casual-timezone-tmenu}, which itself is integrated into the menu
@code{casual-editkit-tools-tmenu}.
-
-Casual Timezone only supports systems that have a
@uref{https://en.wikipedia.org/wiki/Tz_database, tz database}.
-
-Casual Timezone supports viewing multiple time zones in a tabular view with
the command @code{casual-timezone-planner} as shown below:
-
-@image{images/casual-timezone-planner-screenshot,,,,png}
-
-@menu
-* Timezone Install::
-* Timezone Usage::
-@end menu
-
-@node Timezone Install
-@subsection Timezone Install
-
-@cindex Timezone Install
-
-Casual Timezone is configured as part of Casual EditKit in the Tools menu
(@code{casual-editkit-tools-tmenu}). Refer to the @ref{EditKit Install} section
for instructions on how to install it.
-
-The main menu for Casual Timezone can be invoked directly using @code{M-x}
@code{casual-timezone-tmenu}.
-
-@node Timezone Usage
-@subsection Timezone Usage
-
-@cindex Timezone Usage
-
-@image{images/casual-timezone-tmenu-screenshot,,,,png}
-
-The main menu for Casual Timezone (@code{casual-timezone-tmenu}) offers the
following commands:
-
-@itemize
-@item
-@code{casual-timezone-local-time-to-remote} (menu binding: @code{l}) will
convert a local date to its equivalent in remote time zone.
-
-@item
-@code{casual-timezone-remote-time-to-local} (menu binding: @code{r}) will
convert a date in a remote time zone to its local equivalent.
-
-@item
-@code{casual-timezone-planner} (menu binding: @code{z}) will generate a table
comparing hours between the local and a remote time zone on a certain date.
Multiple remote time zones can be specified.
-@end itemize
-
-
-@subheading Timezone Planner
-
-@image{images/casual-timezone-planner-screenshot,,,,png}
-
-The command @code{casual-timezone-planner} will prompt the user for one or
more time zones and a date to compare in tabular form the local time with the
zones selected. Multiple time zones are comma-separated.
-
-In this table, the point can be navigated using the @kbd{p}, @kbd{n},
@kbd{@key{TAB}}, and @kbd{S-@key{TAB}} bindings.
-
-Use the @kbd{T} binding to copy the timestamp under the current point to the
@code{kill-ring}. The @kbd{t} binding will copy all timestamps on the current
line to the @code{kill-ring}.
-
-@menu
-* Timezone Formatting::
-* Planner Configuration::
-* Zoneinfo Database::
-* Timezone Unicode Symbol Support::
-@end menu
-
-@node Timezone Formatting
-@subsubsection Timezone Formatting
-
-@vindex casual-timezone-datestamp-format
-@vindex casual-timezone-convert-datestamp-format
-
-The formatted representation of time in Casual Timezone is set by the
following customizable variables:
-
-@itemize
-@item
-@code{casual-timezone-datestamp-format}
-@item
-@code{casual-timezone-convert-datestamp-format}
-@end itemize
-
-The format specification of these variables conforms to the specification
defined in @ref{Time Parsing,format-time-string,,elisp,}.
-
-The following table shows which format variable applies to which command.
-
-@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
{aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
-@headitem Command
-@tab Format
-@item @code{casual-timezone-planner}
-@tab @code{casual-timezone-datestamp-format}
-@item @code{casual-timezone-local-time-to-remote}
-@tab @code{casual-timezone-convert-datestamp-format}
-@item @code{casual-timezone-remote-time-to-local}
-@tab @code{casual-timezone-convert-datestamp-format}
-@end multitable
-
-These variables can be customized via the Transient menu
@code{casual-timezone-settings-tmenu}.
-
-@node Planner Configuration
-@subsubsection Planner Configuration
-
-@vindex casual-timezone-working-hours-range
-@vindex casual-timezone-working-hour-glyph
-@vindex casual-timezone-planner-working-highlight
-
-The following variables can control how working hours are displayed in the
timezone planner.
-
-@itemize
-@item
-@code{casual-timezone-working-hours-range} will set the range (start, stop)
of working hours. The values are integers that map to 24-hour time (0..23).
-@item
-@code{casual-timezone-working-hour-glyph} will set the glyph used to denote a
working hour (default is ☼).
-@item
-@code{casual-timezone-planner-working-highlight} will set the face used to
highlight a working hour.
-@end itemize
-
-These variables can be customized via the Transient menu
@code{casual-timezone-settings-tmenu}.
-
-@node Zoneinfo Database
-@subsubsection Zoneinfo Database
-
-@vindex casual-timezone-zone-info-database
-
-The variable @code{casual-timezone-zone-info-database} is default set to the
path ``/usr/share/zoneinfo/tzdata.zi''. Customize this variable if the zoneinfo
database is located at a different path.
-
-@node Timezone Unicode Symbol Support
-@subsubsection Timezone Unicode Symbol Support
-
-By enabling “@kbd{u} Use Unicode Symbols” from the Settings menu, Casual
Timezone will use Unicode symbols as appropriate in its menus.
-
-@node Customization
-@chapter Customization
-
-@cindex Customization
-
-Users who wish to extend or alter existing Casual menus can do so via the
mechanisms offered by the Transient package.
-
-@itemize
-@item
-@ref{Modifying Existing Transients,,,transient,}
-@end itemize
-
-@node Feedback & Discussion
-@chapter Feedback & Discussion
-
-@cindex Feedback
-Please report any feedback about Casual to the
@uref{https://github.com/kickingvegas/casual/issues, issue tracker on GitHub}.
-
-@cindex Discussion
-To participate in general discussion about using Casual, please join the
@uref{https://github.com/kickingvegas/casual/discussions, discussion group}.
-
-@node Sponsorship
-@chapter Sponsorship
-
-@cindex Sponsorship
-
-It costs money to make, enhance, and maintain Casual as ideologically free
software. If you enjoy using Casual, please buy me a coffee to help support its
development and maintenance.
-
-@image{images/default-yellow,,,,png}
-
-@uref{https://www.buymeacoffee.com/kickingvegas, buymeacoffee.com/kickingvegas}
-
-@node About Casual
-@chapter About Casual
-
-@cindex About Casual
-
-@uref{https://github.com/kickingvegas/casual, Casual} was conceived and
crafted by Charles Choi in San Francisco, California.
-
-Thank you for using Casual.
-
-Always choose love.
-
-@node Acknowledgments
-@chapter Acknowledgments
-
-@cindex Acknowledgments
-
-A heartfelt thanks to all the contributors to
@uref{https://github.com/magit/transient, Transient}, @uref{https://magit.vc,
Magit}, @uref{https://orgmode.org, Org Mode}, and
@uref{https://www.gnu.org/software/emacs/, Emacs}.
-
-This package would not be possible without your efforts.
-
-@node Main Index
-@chapter Main Index
-
-Index for this user guide.
-
-@printindex cp
-
-@node Variable Index
-@chapter Variable Index
-
-Variables, functions, commands, and menus referenced by this user guide.
-
-@printindex vr
-
-@bye
diff --git a/docs/casualdocs.el b/docs/casualdocs.el
new file mode 100644
index 0000000000..cb0a356017
--- /dev/null
+++ b/docs/casualdocs.el
@@ -0,0 +1,138 @@
+;;; casualdocs.el --- Casual Documentation Configuration -*- lexical-binding:
t; -*-
+
+;; Copyright (C) 2026 Charles Choi
+
+;; Author: Charles Choi <[email protected]>
+;; Keywords: tools
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;;
+
+;;; Code:
+
+(require 'org)
+(require 'ox)
+(require 'ox-texinfo)
+
+(defun cc/reconfig-org-smart-quotes-lang (lang)
+ "Reconfigure Org smart quotes to use utf-8 per LANG."
+ (let* ((db-entry (assoc-string lang org-export-smart-quotes-alist))
+ (utf8-primary-opening (plist-get (assoc-default 'primary-opening
db-entry) :utf-8))
+ (utf8-primary-closing (plist-get (assoc-default 'primary-closing
db-entry) :utf-8))
+ (utf8-secondary-opening (plist-get (assoc-default 'secondary-opening
db-entry) :utf-8))
+ (utf8-secondary-closing (plist-get (assoc-default 'secondary-closing
db-entry) :utf-8))
+ (utf8-apostrophe (plist-get (assoc-default 'apostrophe db-entry)
:utf-8))
+ )
+
+ (setf (plist-get
+ (assoc-default 'primary-opening
+ (assoc-string lang org-export-smart-quotes-alist))
+ :html)
+ utf8-primary-opening)
+
+ (setf (plist-get
+ (assoc-default 'primary-closing
+ (assoc-string lang org-export-smart-quotes-alist))
+ :html)
+ utf8-primary-closing)
+
+ (setf (plist-get
+ (assoc-default 'secondary-opening
+ (assoc-string lang org-export-smart-quotes-alist))
+ :html)
+ utf8-secondary-opening)
+
+ (setf (plist-get
+ (assoc-default 'secondary-closing
+ (assoc-string lang org-export-smart-quotes-alist))
+ :html)
+ utf8-secondary-closing)
+
+ (setf (plist-get
+ (assoc-default 'apostrophe
+ (assoc-string lang org-export-smart-quotes-alist))
+ :html)
+ utf8-apostrophe)))
+
+
+(add-hook 'org-mode-hook (lambda ()
+ (cc/reconfig-org-smart-quotes-lang "en")))
+
+
+(setopt org-latex-classes
+ '(("article" "\\documentclass[11pt]{article}"
+ ("\\section{%s}" . "\\section*{%s}")
+ ("\\subsection{%s}" . "\\subsection*{%s}")
+ ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
+ ("\\paragraph{%s}" . "\\paragraph*{%s}")
+ ("\\subparagraph{%s}" . "\\subparagraph*{%s}"))
+ ("report" "\\documentclass[11pt]{report}" ("\\part{%s}" .
"\\part*{%s}")
+ ("\\chapter{%s}" . "\\chapter*{%s}") ("\\section{%s}" .
"\\section*{%s}")
+ ("\\subsection{%s}" . "\\subsection*{%s}")
+ ("\\subsubsection{%s}" . "\\subsubsection*{%s}"))
+ ("book" "\\documentclass[11pt]{book}" ("\\part{%s}" . "\\part*{%s}")
+ ("\\chapter{%s}" . "\\chapter*{%s}") ("\\section{%s}" .
"\\section*{%s}")
+ ("\\subsection{%s}" . "\\subsection*{%s}")
+ ("\\subsubsection{%s}" . "\\subsubsection*{%s}"))
+ ("simpleresumecv" "\\documentclass[11pt]{simpleresumecv}"
+ ("\\section{%s}" . "\\section*{%s}")
+ ("\\subsection{%s}" . "\\subsection*{%s}")
+ ("\\subsubsection{%s}" . "\\subsubsection*{%s}"))
+ ("letter" "\\documentclass[11pt]{letter}"
+ ("\\section{%s}" . "\\section*{%s}")
+ ("\\\\subsection{%s}" . "\\\\subsection*{%s}")
+ ("\\\\subsubsection{%s}" . "\\\\subsubsection{*%s}"))))
+
+(setopt org-latex-compiler "xelatex")
+(setopt org-export-allow-bind-keywords t)
+(setopt org-export-backends '(ascii html icalendar latex md odt texinfo))
+(setopt org-export-with-smart-quotes t)
+(setopt org-export-with-sub-superscripts '{})
+(setopt org-export-with-toc nil)
+(setopt org-latex-pdf-process
+ '("%latex -interaction nonstopmode --shell-escape -output-directory %o
%f"
+ "%latex -interaction nonstopmode --shell-escape -output-directory %o
%f"
+ "%latex -interaction nonstopmode --shell-escape -output-directory %o
%f"))
+
+(setopt org-texinfo-classes
+ '(("info" "@documentencoding AUTO\12@documentlanguage AUTO"
+ ("@chapter %s" "@unnumbered %s" "@chapheading %s" "@appendix %s")
+ ("@section %s" "@unnumberedsec %s" "@heading %s" "@appendixsec %s")
+ ("@subsection %s" "@unnumberedsubsec %s" "@subheading %s"
+ "@appendixsubsec %s")
+ ("@subsubsection %s" "@unnumberedsubsubsec %s" "@subsubheading %s"
+ "@appendixsubsubsec %s"))
+ ("casual" "@documentencoding AUTO\12@documentlanguage AUTO"
+ ("@chapter %s" "@unnumbered %s" "@chapheading %s" "@appendix %s")
+ ("@section %s" "@unnumberedsec %s" "@subheading %s" "@appendixsec
%s")
+ ("@subsection %s" "@unnumberedsubsec %s" "@subheading %s"
+ "@appendixsubsec %s")
+ ("@subsubsection %s" "@unnumberedsubsubsec %s" "@subsubheading %s"
+ "@appendixsubsubsec %s"))))
+
+(setopt org-src-lang-modes
+ '(("ocaml" . tuareg) ("elisp" . emacs-lisp) ("ditaa" . artist)
+ ("asymptote" . asy) ("dot" . graphviz-dot) ("sqlite" . sql)
+ ("calc" . fundamental) ("C" . c) ("cpp" . c++) ("C++" . c++)
+ ("screen" . shell-script) ("shell" . sh) ("bash" . sh)
+ ("plantuml" . plantuml) ("swift" . swift) ("swiftui" . swift)
+ ("graphviz" . graphviz) ("mscgen" . mscgen)))
+
+(setopt org-latex-prefer-user-labels t)
+
+(provide 'casualdocs)
+;;; casualdocs.el ends here
