branch: externals/window-commander
commit 3a9848deac878a59ecfaa5bd9fd4235bef2ee9ed
Author: Daniel Semyonov <cm...@dsemy.com>
Commit: Daniel Semyonov <cm...@dsemy.com>
Add an Info node for the package
* Makefile: New Makefile for building the package archive.
* config.mk: Added configuration for the Makefile.
* swsw-pkg.el: New package definition file.
* swsw.texi: New Info node documenting most aspects of the package.
---
Makefile | 38 ++++++++++
NEWS | 4 +
README | 12 ++-
config.mk | 5 ++
swsw-pkg.el | 9 +++
swsw.texi | 240 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
6 files changed, 306 insertions(+), 2 deletions(-)
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000000..26974bc8a5
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,38 @@
+include config.mk
+
+.PHONY: info clean
+
+all: info package
+
+help:
+ $(info make all - generate info manual)
+ $(info make info - generate info manual)
+ $(info make package - generate tar file containing the package)
+ $(info make clean - remove generated files)
+ @exit
+
+info: $(PKG).info dir
+
+%.info: %.texi
+ @echo "Generating $@"
+ @$(MAKEINFO) --no-split $< -o $@
+
+dir: $(PKG).info
+ @echo "Generating $@"
+ @$(INSTALLINFO) $< $@
+
+package: $(PKG)-$(VERSION).tar
+
+%.tar: $(PKG).info dir *.el
+ @echo "Creating temporary package directory"
+ @mkdir $(PKG)-$(VERSION)
+ @echo "Copying package files to temporary directory"
+ @cp -a $^ $(PKG)-$(VERSION)/
+ @echo "Creating package archive $@"
+ @tar -cf $@ $(PKG)-$(VERSION)
+ @echo "Removing temporary package directory"
+ @rm -rf $(PKG)-$(VERSION)
+
+clean:
+ @echo "Cleaning..."
+ @rm -rf $(PKG).info dir $(PKG)-$(VERSION).tar
diff --git a/NEWS b/NEWS
index c4e9bff168..9e60a7ad01 100644
--- a/NEWS
+++ b/NEWS
@@ -10,6 +10,10 @@ C-g ('keyboard-quit') while reading a window ID.
** Bind C-x o to swsw-select in swsw-mode-map by default.
+** Add an info node.
+An info node (swsw) has been added which documents all user facing parts of the
+package in detail.
+
* 1.0
** Stable version.
diff --git a/README b/README
index 95d00e5aa5..ec889aff61 100644
--- a/README
+++ b/README
@@ -13,13 +13,19 @@ $ cd
$ git clone 'https://git.sr.ht/~dsemy/swsw'
+Build the package:
+
+$ cd swsw
+
+$ make
+
Install the package:
-M-x package-install-file RET ~/swsw.el RET
+M-x package-install-file RET ~/swsw/swsw-1.0.tar RET
Usage:
-Enable `swsw-mode' and (optionally) bind `swsw-select' to a key:
+Enable `swsw-mode':
(swsw-mode)
@@ -43,6 +49,8 @@ You can customize `swsw-mode' using the customize interface:
M-x customize-group RET swsw RET
+For more information see the swsw info node.
+
Copyright:
Copyright © 2020 Daniel Semyonov <cm...@dsemy.com>
diff --git a/config.mk b/config.mk
new file mode 100644
index 0000000000..5d955aee29
--- /dev/null
+++ b/config.mk
@@ -0,0 +1,5 @@
+PKG = swsw
+VERSION = 1.0
+
+INSTALLINFO ?= install-info
+MAKEINFO ?= makeinfo
diff --git a/swsw-pkg.el b/swsw-pkg.el
new file mode 100644
index 0000000000..ca6d453038
--- /dev/null
+++ b/swsw-pkg.el
@@ -0,0 +1,9 @@
+(define-package "swsw" "1.0" "Simple window switching"
+ '((emacs "23.1"))
+ :keywords ("convenience")
+ :authors (("Daniel Semyonov" . "cm...@dsemy.com"))
+ :maintainer ("Daniel Semyonov" . "cm...@dsemy.com")
+ :url "https://sr.ht/~dsemy/swsw";)
+;; Local Variables:
+;; no-byte-compile: t
+;; End:
diff --git a/swsw.texi b/swsw.texi
new file mode 100644
index 0000000000..49f8a766a9
--- /dev/null
+++ b/swsw.texi
@@ -0,0 +1,240 @@
+\input texinfo
+@setfilename swsw.info
+@settitle swsw User Manual
+@documentencoding UTF-8
+@documentlanguage en
+
+@copying
+@quotation
+Copyright @copyright{} 2020 Daniel Semyonov
+
+You can redistribute this document 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 document 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.
+
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* swsw: (swsw). Simple window switching.
+@end direntry
+
+@titlepage
+@title swsw User Manual
+@subtitle for version 1.0
+@author Daniel Semyonov
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top swsw User Manual
+
+swsw provides a minor mode for switching to windows using IDs assigned
+to them automatically.
+@end ifnottex
+
+@menu
+* Introduction::
+* Installation::
+* Usage::
+* Customization::
+* Keystroke Index::
+* Command Index::
+* Function Index::
+* Variable Index::
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+Installation
+
+* Installing a release::
+* Installing from the Git repository::
+
+Customization
+
+* Display functions::
+
+@end detailmenu
+@end menu
+
+@node Introduction
+@chapter Introduction
+
+swsw provides a minor mode for switching to windows using IDs assigned to them
+automatically. It's implementation is simple and extensible, providing various
+advanced customization features for users, while keeping the code base small
+and easy to hack on.
+
+@node Installation
+@chapter Installation
+
+swsw can currently only be installed manually.
+
+@menu
+* Installing a release::
+* Installing from the Git repository::
+@end menu
+
+@node Installing a release
+@section Installing a release
+
+Simply download a release (from <https://dsemy.com/software/swsw>), and install
+it:
+
+@table @asis
+@item @kbd{M-x package-install-file RET /path/to/download/swsw-VERSION.tar RET}
+@end table
+
+@node Installing from the Git repository
+@section Installing from the Git repository
+
+Clone the repository and build the package archive:
+
+@example
+$ git clone https://git.sr.ht/~dsemy/swsw
+$ cd swsw
+$ make
+@end example
+
+Install the package:
+
+@table @asis
+@item @kbd{M-x package-install-file RET /path/to/clone/swsw-VERSION.tar RET}
+@end table
+
+@node Usage
+@chapter Usage
+
+In order to use any feature of the package, @code{swsw-mode} must be enabled:
+
+@cindex swsw-mode
+@table @asis
+@item @kbd{M-x swsw-mode RET}
+@end table
+
+You can also add @code{(swsw-mode)} to your init file, instead.
+
+By default, window IDs will be shown as mode line lighters of the
+form @code{<ID>}.
+
+@kindex C-x o
+@cindex swsw-select
+@table @asis
+@item @kbd{C-x o ID}
+@end table
+Switch to the window corresponding to @code{ID} (@code{swsw-select}).
+
+@node Customization
+@chapter Customization
+
+All customization, except for defining custom display functions, can be done
+through the customize interface:
+
+@table @asis
+@item @kbd{M-x customize-group RET swsw RET}
+@end table
+
+@defopt swsw-id-chars
+Base set of character from which window IDs are constructed. This should be a
+list of characters. By default, the home row (@code{a s d f g h j k l}) is
+used.
+@end defopt
+
+@defopt swsw-minibuffer-id
+ID reserved for the minibuffer. This should be a single character. By default,
+@code{m} is used.
+@end defopt
+
+@defopt swsw-id-format
+Format string for the window ID. Display functions may use this format string
+to display the ID, but they can also ignore it. The string should contain a
+single occurrence of @code{%s}, which will be replaced by the ID. By default,
+@code{" <%s>"} is used.
+@end defopt
+
+@defopt swsw-scope
+Scope of all window operations. Used to determine on which frames to track
+windows. A value of @code{t} means consider all windows on all frames, @code{0}
+(the number zero) means consider all windows on all visible and iconified
+frames, @code{visible} means consider all windows on all visible frames and
+@code{current} means consider only the currently selected frame. By default,
+@code{t} is used.
+@end defopt
+
+@menu
+* Display functions::
+@end menu
+
+@node Display functions
+@section Display functions
+
+Display functions are used to display the ID of each window.
+
+@defopt swsw-display-function
+Function used to display the ID of each window. This should either be a
+display function or @code{lighter}, in which case window IDs are shown using
+a mode line lighter. A display function must accept a single argument, which
+will be @code{t} when enabling @code{swsw-mode} and @code{nil} when disabling
+it. By default, @code{lighter} is used.
+@end defopt
+
+@defvar swsw-before-select-hook
+Hook which runs after @code{swsw-select} is called, but before and ID has been
+read. This hook can be used display window IDs conditionally.
+@end defvar
+
+@defvar swsw-after-select-hook
+Hook which runs after reading an ID, or if the user interrupts
+@code{swsw--read-id}. This hook can be used hide window IDs conditionally.
+@end defvar
+
+@defun swsw-mode-line-display-function switch
+Reference implementation of a ``simple'' display function. Display window IDs
on
+the mode line if SWITCH isn't @code{nil}, and hide window IDs from the mode
+line if SWITCH is @code{nil}. This display function respects
+@code{swsw-id-format}.
+@end defun
+
+@defun swsw-mode-line-conditional-display-function switch
+Reference implementation of a conditional display function. Add a hook to
+@code{swsw-before-select-hook} which displays window IDs on the mode line and
+add a hook to @code{swsw-after-select-hook} which hides window IDs from the
+mode line if SWITCH isn't @code{nil}, and remove those hooks if SWITCH is
+@code{nil}. This display function respects @code{swsw-id-format}.
+@end defun
+
+@node Keystroke Index
+@appendix Keystroke Index
+
+@printindex ky
+
+@node Command Index
+@appendix Command Index
+
+@printindex cp
+
+@node Function Index
+@appendix Function Index
+
+@printindex fn
+
+@node Variable Index
+@appendix Variable Index
+
+@printindex vr
+
+@bye
+
