Amy's Emacs Packages

A boxy layout framework

project website

Boxy provides an interface to create a 3D representation of boxes.
Each box has a relationship with one other box.  Multiple boxes can
be related to one box.  The relationship can be any of the
following:

- in
- on
- behind
- on top of
- in front of
- above
- below
- to the right of
- to the left of

The relationship determines the ordering and structure of the
resulting boxy diagram.

Only boxes which have their :name slot set will be drawn to the
buffer.  Boxes without names still take up space and can have
children, so can be used for grouping.  All diagrams have one top
level unnamed box called a `world'.

Each box should have either a list of markers or an action
function.  When viewing a box that has a list of markers, the
following keybindings are available:

RET/mouse-1   - Jump to the first marker
o             - Open next marker in other window.
                  Pressed multiple times, cycle through markers.
M-RET         - Open all markers as separate buffers.
                  This will split the current window as needed.

When viewing a box with an action function, RET and <mouse-1> will
be bound to that function.

Additionally, all boxes have the following keybindings defined:

r     - Jump to the box directly related to the current box.
          Repeated presses will eventually take you to the
          top level box.
TAB   - Cycle visibility of box's children

See the class definition for `boxy-box' for all other available
properties.

To start, create an empty box named `world'.

  (let ((world (boxy-box)))

Use the method `boxy-add-next' to add top-level boxes to the world,
without relationships:

  (let ((cyprus (boxy-box :name "Cyprus"))
        (greece (boxy-box :name "Greece")))
    (boxy-add-next cyprus world)
    (boxy-add-next greece world)

To ease the boxy renderer, use the :expand-siblings and
:expand-children slots.  These should be list of functions which
take the current box as an argument and call `boxy-add-next' to add
sibling boxes and children boxes respectively.  Children boxes are
defined as any box with a relationship of in, on, behind, in front
of, or on top of.  Sibling boxes are defined as any box with a
relationship of above, below, to the left of, or to the right of.

   (push '(lambda (box)
            (boxy-add-next
             (boxy-box :name "Lebanon" :rel "below")
             box))
         (boxy-box-expand-siblings cyprus))

The expansion slots will be called when the user toggles the box's
visibility.

To display a box in a popup buffer, use the function `boxy-pp'.

The methods `boxy-merge' and `boxy-merge-into' should be used to
merge boxes together.  `boxy-merge' takes a list of boxes and
merges them into one box.  `boxy-merge-into' takes two boxes and
merges the first into the second.

View org files in a boxy diagram

project website

The command `boxy-headings' will display all headings in the
current org file as a boxy diagram.  The relationship between
a heading and its parent can be set by using a REL property on the
child heading.  Valid values for REL are:

  - on-top
  - in-front
  - behind
  - above
  - below
  - right
  - left

The tooltip in `boxy-headings' shows the values for each row in
`org-columns' and can be customized the same way as org columns
view.

View imenu in a boxy diagram

project website

The command `boxy-imenu' will display `imenu' in a boxy diagram.

Standard Emacs movement commands will navigate by boxes instead of
words or characters.  Clicking on a box or pressing RET will take
you to that item.  The 'o' command will open the item in the other
window.

View info manuals in a boxy diagram

project website

The command `boxy-info' will display the current Info manual as a
boxy diagram.  If not looking at an Info manual, boxy-info will
prompt for a manual to display.

Standard Emacs movement commands will navigate by boxes instead of
words or characters.  Clicking on a box or pressing RET will take
you to that node in the manual.  If a box has a double outline, it
can be expanded by hovering over it with the cursor and pressing
TAB.

Alternate archive for Org

project website

Chive provides an alternative archive style for Org mode files.
Each heading's direct ancestors will be recreated in the archive
file.  The subtree itself will be merged into whatever exists
already in the archive file.  In essence, the archive file will
look like the same Org file it came from.

To enable chive-mode, add this to your init file:

  (add-hook 'org-mode-hook 'chive-mode)

An overview of when things were archived can be seen by pressing [
from an agenda buffer limited to the archive file.

The archive file and parent heading is determined by the variable
`org-archive-location'.  However, using the keyword `datetree' in
the archive location is not supported.

Control your chromecast

project website

chromecast.el provides commands for interacting with a chromecast.

Requires the python package `pychromecast' which can be found in
apt and pip.

Usage:

`chromecast': Select a device (if not already selected) and control
it through a transient interface.

Use clang-format to determine indentation

project website

`clang-format-indent-mode' advises the existing indentation
function using the `clang-format-executable'.  This can be turned
on automatically using a mode hook:

  (add-hook 'c-mode-common-hook 'clang-format-indent-mode)

Share events in real time

project website

This package sends updates to a server whenever you clock in or out
or add a log entry to an org headline.

Org blogging helper

project website

Blogging tools for ox-publish based projects.

Retrieve passwords from KeePass

project website

This package provides the command `keepass-picker' to quickly
retrieve selected KeePass passwords from within Emacs using
`keepassxc-cli'.

------------------------------------------------------------------
                             Setup
------------------------------------------------------------------

This package uses the command keepassxc-cli, which must located on
the path.  Install KeePassXC in order to get this program.

Set the absolute path to your KeePass database file:

 (setq keepass-db "/absolute/path/to/my-passwords.kdbx")

If you use a key file to unlock the database, set it as
`keepass-key-file'.

A password can be retrieved by using the command `keepass-picker'.
In order to create a global keybinding for `keepass-picker', use
the utility function `keepass-global' in your config.

 (keepass-global "C-c p")

OR

 (keepass-global (kbd "C-c p"))


------------------------------------------------------------------
                     Registering passwords
------------------------------------------------------------------

In order to register a password for the password manager, use the
function `keepass-register':

 (keepass-register "m" "My Pass" :name "Email/Yahoo Email")

This will register a password entry named "My Pass" which can be
retrieved by calling `keepass-picker' and entering the letter "m".

`keepass-register' can also be used to register a category of
passwords by omitting the KeePass name:

 (keepass-register "e" "Email category")

After a category has been registered, passwords can be registered
under the category by prepending the key of the category to the key
of the password:

 (keepass-register "el" "Laura's email" :name "Laura Gmail")

Categories can be nested arbitrarily deep:

 (keepass-register "s" "Social")
 (keepass-register "sr"  "Reddit")
 (keepass-register "srp"   "Personal" :name "Reddit/Personal")
 (keepass-register "sra"   "Anon"     :name "Reddit/Anon")

------------------------------------------------------------------
                           Security
------------------------------------------------------------------

The master password for the KeePass database will be cached for
`password-cache-expiry' seconds.

By default, keepass.el will copy the password to the kill ring for
`keepass-timeout' seconds, then remove it.  During this time, the
clipboard feature of Emacs will be disabled.  Set
`keepass-clipboard' to `t' to allow other applications to access
the password through the clipboard.

------------------------------------------------------------------
                       Multiple databases
------------------------------------------------------------------

When registering a password entry or category, you can specify the
database file and/or key file:

 (keepass-register "w" "Work Database"
   :db "/absolute/path/to/work-passwords.kdbx"
   :key-file "/absolute/path/to/key-file")

These settings will be applied to all children of the category "w"
(unless overriden by the child).

To unset the key file for a particular password entry or category,
use -1 (setting `nil' will use inheritance).

 (keepass-register "w" "Work Database"
   :db "/absolute/path/to/work-passwords.kdbx"
   :key-file -1)

Create key-based tutorial games

project website

Create a tutorial game for your Emacs package.  Start by defining a
game with the `key-game' macro.  The DOC-STRING and TITLE keyword
are required parameters.  This will define a `NAME-level' macro,
where NAME is the name of the `key-game'.  Use this macro to define
levels for the game.

For example, for a `key-game' named "example":

  (key-game example
    "An example game."
    :title "example")

The macro to define levels for this game will be named
`example-level':

  (example-level level-1
    "Level 1: intro")

Within the level creation macro, define `frame's and, optionally,
an `intro':

  (example-level level-1
    "Level 1: intro"
    (intro
     "This is an intro.")
    (frame
     :keys ("x")
     "Press the `x' key: "
     (goto-char (point-max)))
    (frame
     :commands (next-line)
     "Go to the next line\n"))

See the documentation for `key-game-frame' for all options for
both `intro's and `frame's.

Example key-based tutorial games

project website

An example tutorial game based on key-game.el

Navigate and edit text objects

project website

A global minor-mode to navigate and edit text objects.  Objed enables modal
editing and composition of commands, too.  It combines ideas of other
Editors like Vim or Kakoune and tries to align them with regular Emacs
conventions.

For more information also see:

- My Blog: https://www.with-emacs.com/categories/objed/
- Project Readme: https://github.com/clemera/objed/blob/master/README.asc
- Project News: https://github.com/clemera/objed/blob/master/News.asc.

Text objects are textual patterns like a line, a top level definition, a
word, a sentence or any other unit of text.  When `objed-mode' is enabled,
certain editing commands (configurable) will activate `objed' and enable
its modal editing features.  When active, keys which would usually insert a
character are mapped to objed commands.  Other keys and commands will
continue to work as they normally would and exit this editing state again.

By default important self inserting keys like Space or Return are not bound
to modal commands and will exit `objed' on insertion.  This makes it
convenient to move around and continue adding new text.

With activation `objed' shows the current object type in the mode-line.  The
textual content of the object is highlighted visually in the buffer and the
cursor color is changed, too.  The user can now navigate by units of this
object, change the object state or switch to other object types.

The object state is either "inner" or "whole" and is indicated in the
modeline by (i) or (w) after the object type.  With inner state, anything
that would be considered delimiters or padding around an object is
excluded.

The user can apply operations to objects.  By marking objects before
applying an operation, s?he can even operate on multiple objects at once.
This works similar to the way you interact with files in `dired'.  When
marking an object the point moves on to the next object of this type.

The object type used for initialization is determined by the mapping of the
entry command (see `objed-cmd-alist').  For example using
`beginning-of-defun' will activate `objed' using the `defun' object as
initial object type.  With command `next-line', `objed' would initialize
with the `line' object.

Objeds modal state provides basic movement commands which move by line,
word or character.  Those switch automatically to the corresponding object
type, otherwise they work the same as the regular Emacs movement commands.
Other commands only activate the part between the initial position and the
new position moved to.  By repeating commands you can often expand/proceed
to other objects.  This way you can compose movement and editing operations
very efficiently.

The expansion commands distinguish between block objects (objects built out
of lines of text) and context objects (programming constructs like strings,
brackets or textual components like sentences).  This way you can quickly
expand to the desired objects.

For example to move to the end of the paragraph, the user would first move
to the end of the line with "e".  This would activate the text between the
starting position and the end of the line.  The user can now continue to the
end of the paragraph by by pressing "e" again.  Now s?he is able to proceed
even further by pressing "e" again OR to continue by adding new text to the
end of the paragraph OR to continue by acting on the text moved over, for
example killing it by pressing "k".

As often with text editing, the explanation sounds more complicated than
using it.  To get a better impression of the editing workflow with `objed'
have look at https://github.com/clemera/objed where you can find some
animated demos.

To learn more about available features and commands have a look at the
descriptions below or the Docstrings and bindings defined in `objed-map'.
To define your own operations and text objects see `objed-define-op' and
`objed-define-object'.

Although some features are still experimental the basic user interface will
stay the same.


CONTRIBUTE:

I'm happy to receive pull requests or ideas to improve this package.  Some
parts suffer from the bottom up approach of developing it, but this also
allowed me to experiment a lot and try ideas while working on them,
something that Emacs is especially good at.  Most of the features are tested
using `emacs-lisp-mode' but hopefully there aren't to many problems using
modes for other languages, I tried my best to write text objects in a
language agnostic way.  Testing this and writing more tests in general would
be an important next step.

This package would never been possible without the helpful community around
Emacs.  Thank you all and see you in parendise...Share the software!

Keep track of real things as org-mode links

project website

This package adds a 'real' type link to org mode to create links to
real things.

The function `org-real-world' will display all real links in the
current buffer.

When in a boxy mode diagram, the standard movement keys will move
by boxes rather than characters.  S-TAB will cycle the visibility
of all children.  Each box has the following keys:

  TAB   - Cycle visibility of box's children
  RET   - Jump to first occurrence of link.
  o     - Open next occurrence of link in other window.
            Pressed multiple times, cycle through occurrences.
  M-RET - Open all occurrences as separate buffers.
            This will split the current window as needed.
  r     - Jump to the box directly related to the current box.
            Repeated presses will eventually take you to the
            top level box.

Server side rendering in the current directory

project website

The command `org-ssr' will start a server-side renderer in the
current directory.  If called with a prefix argument, files will be
served recursively.  The ip address and port will be displayed in
the minibuffer.  Navigating to this address in the browser will
list all available export formats for all available org files (as
well as all subdirectories if served recursively).

A cache of exported files is saved in the hash table
`org-ssr--cache'.  To clear this cache, use the command
`org-ssr-clear-cache'.

Use the built-in command `list-processes' to manage instances of
`org-ssr' servers and view their listening ports.

This package is an extension of an example created Eric Schulte for
web-server.el available here:

https://github.com/eschulte/emacs-web-server/blob/master/examples/007-org-mode-file-server.el

Show status of any linked todo item

project website

Activate the global mode `org-todo-link-mode' in order to display
the todo keyword before any `file' link where the target is a todo
item.

With point inside such a link, use C-c C-t (`org-todo-link-todo')
to set the todo keyword on the target heading, and C-c C-c
(`org-todo-link-recalculate') to recalculate the todo keyword.

The keyword is displayed as a clickable button, which will allow
you to set the todo keyword on the target heading via the mouse.

Yet another alert package for org

project website

Yet another alert package for org mode.  Synchronously checks all
headings for alerts to send.

This package also has the ability to show a persistent notification
for clocking in and out, send a notification for daily events
without a specified time, and repeat notifications for old events
which have not been completed yet.

Enable it with "M-x org-yaap-mode" or by adding

    (org-yaap-mode)

To your init file.

If you are using termux, to allow notification clicks to launch
Emacs, add `allow-external-apps' to ~/.termux/termux.properties:

    allow-external-apps = true

(you may have to create the file and/or directory)

Then install and configure the Termux:API addon package, and
install termux-api from the pkg manager:

    pkg install termux-api

***********
* SUMMARY *
***********

Customize the "org-yaap" group in order to see all available
options.  By default, you will be notified for all scheduled
headings (`org-yaap-include-scheduled') and headings with a
deadline (`org-yaap-include-deadline') within your agenda files.
If a heading only includes the date, you will be notified at 09:00
on that date (`org-yaap-daily-alert').  If you don't mark a heading
as done, you will be repeatedly notified every 30 minutes after the
heading was due (`org-yaap-overdue-alerts').

*******************************
* DATE and TIME SPECIFICATION *
*******************************

The time and date can be specified together in either a `SCHEDULED'
or `DEADLINE' cookie:

    * Some event
      SCHEDULED: <2022-09-08 Thu 15:00>
    * Some deadline
      DEADLINE: <2022-09-08 Thu 08:30>

If a date is given without a time, the alert will be sent according
to `org-yaap-daily-alert' or the "ALERT_TIME" property of a
heading, which is 09:00 by default.  For example:

    * TODO Something due on Wednesday
      DEADLINE: <2022-09-07 Wed>

Will be alerted once a day from Sep 7 onward at 9am until it is
marked `DONE'.

`SCHEDULED' and `DEADLINE' headings can also use the diary format
to specify which days they should be alerted:

   * Diary sexp alert
     SCHEDULED: <%%(diary-cyclic 7 9 7 2022)>

In this case the heading will be alerted every Wednesday from Sep 7
onward.  Note that overdue alerts cannot occur for diary headings,
so marking an diary heading as `DONE' will prevent all future
alerts.

The time can also be specified plainly in the heading itself.  For
example:

   * TODO Dentist at 3pm with Dr.  Gates
     SCHEDULED: <2022-09-07 Wed>

Will be alerted at 15:00 on Sep 7.

You can turn off plain style time specifications, in which case the
entry will be treated as a daily alert, by setting
`org-agenda-search-headline-for-time' to nil.

Plain style time specifications are useful for diary-style
headings.  For a complete example, consider a workout schedule from
7:30am-8am everyday consisting of walking on Mondays, Wednesdays,
and Fridays, stretching on Tuesdays Thursdays and Saturdays, and a
core workout on Sundays.

    * Go for a walk 7:30am-8am
      SCHEDULED: <%%(or (diary-cyclic 7 9 5 2022) (diary-cyclic 7 9 7 2022) (diary-cyclic 7 9 9 2022)>

    * Stretch 7:30am-8am
      SCHEDULED: <%%(or (diary-cyclic 7 9 6 2022) (diary-cyclic 7 9 8 2022) (diary-cyclic 7 9 10 2022)>

    * Core workout 7:30am-8am
      SCHEDULED: <%%(diary-cyclic 7 9 4 2022)>

Every day you will be alerted at 7:30am (depending on
`org-yaap-alert-before' or "ALERT_BEFORE") with the type of workout
to do that day.

***************************
* AS a BACKGROUND PROCESS *
***************************

Look at the file `org-yaap-script' for a demonstration of how to
run `org-yaap' in a separate Emacs instance.  For example, to run
your script as a user systemd service, create a service file at
`~/.config/systemd/user/org-yaap.service':

    [Unit]
    Description=Org Yaap

    [Service]
    ExecStart=<abolute path to org-yaap script>
    Restart=on-failure

    [Install]
    WantedBy=default.target

Launch this service with the commands:

    systemctl --user enable --now org-yaap

Edit beancount files using transient menus

project website

Edit beancount files using transient menus.

Use the command `trans-bean-txn' within a valid beancount
transaction to edit it using a transient menu.

From the transient menu for a transaction, you can move to a
posting within the transaction by pressing `e'. You can also launch
the transient menu for an individual posting by using the command
`trans-bean-posting' within a valid beancount posting within a
transaction.

To create a new transaction, use the command
`trans-bean-insert-transaction', which will walk through all of the
necessary metadata.

When selecting an account for a posting, a boxy menu will be
displayed that you can use to see the hierarchy of accounts and
choose one that fits best. To see this boxy menu outside of the
posting transient menu, use the command `trans-bean-boxy-accounts'.