This is annalist.info, produced by makeinfo version 7.2 from annalist.texi. INFO-DIR-SECTION Emacs START-INFO-DIR-ENTRY * Annalist: (annalist). Record and display information such as keybindings. END-INFO-DIR-ENTRY  File: annalist.info, Node: Top, Next: Usage, Up: (dir) Annalist User Manual ******************** file:https://melpa.org/packages/annalist-badge.svg (https://melpa.org/#/annalist) https://travis-ci.org/noctuid/annalist.el.svg?branch=master (https://travis-ci.org/noctuid/annalist.el) Incessant wind sweeps the plain. It murmurs on across grey stone, carrying dust from far climes to nibble eternally at the memorial pillars. There are a few shadows out there still but they are the weak and the timid and the hopelessly lost. It is immortality of a sort. Memory is immortality of a sort. In the night, when the wind dies and silence rules the place of glittering stone, I remember. And they all live again. ‘annalist.el’ is a library that can be used to record information and later print that information using ‘org-mode’ headings and tables. It allows defining different types of things that can be recorded (e.g. keybindings, settings, hooks, and advice) and supports custom filtering, sorting, and formatting. ‘annalist’ is primarily intended for use in other packages like ‘general’ and ‘evil-collection’, but it can also be used directly in a user's configuration. [https://user-images.githubusercontent.com/4250696/63480582-64e2cb00-c460-11e9-9571-706b5b96992c] * Menu: * Usage:: -- The Detailed Node Listing -- Usage * Disabling Annalist:: * Terminology:: * Settings:: * Defining New Types:: * Defining Views:: * Recording:: * Describing:: * Helper Functions:: * Builtin Types:: Defining New Types * Type Top-level Settings:: * Type Item Settings:: * ‘:record-update’, ‘:preprocess’, and ‘:postprocess’ Settings Argument: record-update preprocess and postprocess Settings Argument. Defining Views * View Top-level Settings:: * View Item Settings:: Helper Functions * List Helpers:: * Formatting Helpers:: * Sorting Helpers:: Builtin Types * Keybindings Type::  File: annalist.info, Node: Usage, Prev: Top, Up: Top 1 Usage ******* * Menu: * Disabling Annalist:: * Terminology:: * Settings:: * Defining New Types:: * Defining Views:: * Recording:: * Describing:: * Helper Functions:: * Builtin Types::  File: annalist.info, Node: Disabling Annalist, Next: Terminology, Up: Usage 1.1 Disabling Annalist ====================== What fool always has his nose in everywhere because he thinks he has to know so he can record it in his precious Annals? If you use a library that uses ‘annalist’ (e.g. ‘evil-collection’ or ‘general’) but don't need it's functionality during init or at all, you can set ‘annalist-record’ to nil to shave some milliseconds off of your init time (especially if you have a lot of keybindings). Alternatively, if you only want to prevent ‘annalist’ from recording certain things or have it only record certain things, you can configure ‘annalist-record-blacklist’ or ‘annalist-record-whitelist’ respectively.  File: annalist.info, Node: Terminology, Next: Settings, Prev: Disabling Annalist, Up: Usage 1.2 Terminology =============== • item - and individual recorded item; may be displayed as a heading or as a table column entry (e.g. a key such as ‘C-c’) • record - a list of related, printable items corresponding to one piece of information (e.g. a single keybinding: a list of a keymap, key, and definition) • metadata - a plist of information about a data list that should not be printed; appears as the last item in a record • tome - a collection of records of a specific type  File: annalist.info, Node: Settings, Next: Defining New Types, Prev: Terminology, Up: Usage 1.3 Settings ============ Annalist provides ‘annalist-describe-hook’ which is run in annalist description buffers after they have been populated but before they are marked read-only: (add-hook 'annalist-describe-hook (lambda () (visual-fill-column-mode -1)))  File: annalist.info, Node: Defining New Types, Next: Defining Views, Prev: Settings, Up: Usage 1.4 Defining New Types ====================== Three huge tomes bound in worn, cracked dark leather rested on a large, long stone lectern, as though waiting for three speakers to step up and read at the same time. Annalist provides the function ‘annalist-define-tome’ for defining new types of tomes: (annalist-define-tome 'battles '(:primary-key (year name) :table-start-index 1 year name casualties ...)) At minimum, a type definition must include ‘:primary-key’, ‘:table-start-index’, and a symbol for each item records should store. Items should be defined in the order they should appear in org headings and then in the table. * Menu: * Type Top-level Settings:: * Type Item Settings:: * ‘:record-update’, ‘:preprocess’, and ‘:postprocess’ Settings Argument: record-update preprocess and postprocess Settings Argument.  File: annalist.info, Node: Type Top-level Settings, Next: Type Item Settings, Up: Defining New Types 1.4.1 Type Top-level Settings ----------------------------- These settings apply to the entirety of the recorded information. • ‘:table-start-index’ - the index of the first item to be printed in an org table; previous items are printed as headings (default: none) • ‘:primary-key’ - the item or list of items that uniquely identifies the record; used with the ‘:test’ values for those items to check for an old record that should be replaced/updated (default: none) • ‘:record-update’ - a function used to update a record before recording it; this can be used to, for example, set the value of an item to store the previous value of another item; the function is called with ‘old-record’ (nil if none), ‘new-record’, and ‘settings’; see ‘annalist--update-keybindings’ for an example of how to create such a function (default: none) • ‘:preprocess’ - a function used to alter a record before doing anything with it; it is passed ‘record’ and ‘settings’ and should return the altered record; see the default keybindings type for an example (default: none) • ‘:test’ - test function used for comparing the primary key (as a list of each item in the order it appears in the definition); you will need to create the test with ‘define-hash-table-test’ if it does not exist (default: ‘equal’; generally should be unnecessary to change) • ‘:defaults’ - a plist of default item settings; see below for valid item settings (default: none)  File: annalist.info, Node: Type Item Settings, Next: record-update preprocess and postprocess Settings Argument, Prev: Type Top-level Settings, Up: Defining New Types 1.4.2 Type Item Settings ------------------------ Item settings only apply to a specific item. Defaults for items that don't explicitly specify a setting can be set using the top-level ‘:defaults’ keyword. • ‘:test’ - test function used for comparing items; only applicable to heading items; you will need to create the test with ‘define-hash-table-test’ if it does not exist (default: ‘equal’; generally should be unnecessary to change)  File: annalist.info, Node: record-update preprocess and postprocess Settings Argument, Prev: Type Item Settings, Up: Defining New Types 1.4.3 ‘:record-update’, ‘:preprocess’, and ‘:postprocess’ Settings Argument --------------------------------------------------------------------------- The settings plist past to the ‘:record-update’ function contains all information for both the tome type and view. The information is converted into a valid plist and some extra keywords are added. Here is an example: '(:table-start-index 2 :primary-key (keymap state key) ;; the following keywords are generated for convenience :type keybindings :key-indices (2 1 0) :final-index 4 :metadata-index 5 ;; item settings can be accessed by their symbol or their index keymap (:name keymap :index 0 :format annalist-code) 0 (:name keymap :index 0 :format annalist-code) ...)  File: annalist.info, Node: Defining Views, Next: Recording, Prev: Defining New Types, Up: Usage 1.5 Defining Views ================== In those days the company was in service to… Views contain settings for formatting and displaying recorded information. Settings from the type definition cannot be changed later. On the other hand, views are for all settings that a user may want to change for a particular ‘annalist-describe’ call. They are defined using the same format as tome types: (annalist-define-view 'battles 'default '(:defaults (:format capitalize) year name (casualties :title "Deaths") ...)) The ‘default’ view is what ‘annalist-describe’ will use if no view name is explicitly specified. To prevent naming conflicts, external packages that create views should prefix the views with their symbol (e.g. ‘general-alternate-view’). * Menu: * View Top-level Settings:: * View Item Settings::  File: annalist.info, Node: View Top-level Settings, Next: View Item Settings, Up: Defining Views 1.5.1 View Top-level Settings ----------------------------- These settings apply to the entirety of the recorded information. • ‘:predicate’ - a function that is passed the entire record and returns non-nil if the record should be printed (default: none) • ‘:sort’ - a function used to sort records in each printed table; the function is passed two records and and should return non-nil if the first record should come first (default: none; tables are printed in recorded order) • ‘:hooks’ - a function or a list of functions to run in the describe buffer after printing all headings and tables before making the buffer readonly; these run before ‘annalist-describe-hook’ (default: none) • ‘:postprocess’ - a function used to alter a record just before printing it; it is passed ‘record’ and ‘settings’ and should return the altered record; an example use case would be to alter the record using its metadata (e.g. by replacing a keybinding definition with a which-key description, if one exists) (default: none) • ‘:defaults’ - a plist of default item settings; see below for valid item settings (default: none) There is also a special ‘:inherit’ keyword that can be used to create a new type of tome that is based on another type: (annalist-define-view 'keybindings 'alternate ;; override title for key column '((key :title "Keybinding") ...) :inherit 'keybindings)  File: annalist.info, Node: View Item Settings, Prev: View Top-level Settings, Up: Defining Views 1.5.2 View Item Settings ------------------------ Item settings only apply to a specific item. Defaults for items that don't explicitly specify a setting can be set using the top-level ‘:defaults’ keyword. (annalist-define-view 'keybindings 'my-view '(:defaults (:format #'capitalize) ;; surround key with = instead of capitalizing (key :format #'annalist-verbatim) ;; perform no formatting on definition (definition :format nil))) Sorting/filtering (only for items displayed in headings): • ‘:predicate’ - a function that is passed the item and returns non-nil if it should be printed; only applicable to heading items (default: none) • ‘:prioritize’ - list of items that should be printed before any others; only applicable to heading items (default: none) • ‘:sort’ - a function used to sort records; only applicable to heading items; the function is passed two items and and should return non-nil if the first item should come first (default: none; printed in recorded order) Formatting: • ‘:title’ - a description of the item; used as the column title (default: capitalize the symbol name; local only) • ‘:format’ - function to run on the item value before it is printed (e.g. ‘#'capitalize’, ‘#'annalist-code’, ‘#'annalist-verbatim’, etc.); note that this is run on the item as-is if it has not been truncated, so the function may need to convert the item to a string first; has no effect if the item is extracted to a footnote/source block (default: none) • ‘:max-width’ - the max character width for an item; note that this is compared to the item as-is before any formatting (default: 50) • ‘:extractp’ - function to determine whether to extract longer entries into footnotes instead of truncating them; (default: ‘listp’) • ‘:src-block-p’ function to determine whether to extract to a source block when the ‘:extractp’ function returns non-nil (default: ‘listp’)  File: annalist.info, Node: Recording, Next: Describing, Prev: Defining Views, Up: Usage 1.6 Recording ============= The Lady said, “I wanted you to see this, Annalist.” […] “What is about to transpire. So that it is properly recorded in at least one place.” ‘annalist-record’ is used to record information. It requires three arguments: ‘annalist’ ‘type’ ‘record’. The ‘annalist’ argument will usually be the same as the package prefix that is recording the data. ‘annalist’ and any other names prefixed by ‘annalist’ are reserved for this package. ‘type’ is the type of data to record, and ‘record’ is the actual data. Optionally, the user can also specify metadata that won't be printed after the final item. Buffer-local records should additionally specify ‘:local t’. Here is an example: (annalist-record 'me 'keybindings (list ;; keymap state key definition previous-definition 'global-map nil (kbd "C-+") #'text-scale-increase nil ;; metadata can be specified after final item (list :zoom-related-binding t))) ;; alternatively, record using plist instead of ordered list (annalist-record 'me 'keybindings (list 'keymap 'global-map 'state nil 'key (kbd "C-+") 'definition #'text-scale-increase ;; metadata can be specified with `t' key t (list :zoom-related-binding t)) :plist t) Some items can potentially be recorded as nil. In the previous example, the evil ‘state’ is recorded as nil (which will always be the case for non-evil users). When a heading item is nil, the heading at that level will just be skipped/not printed.  File: annalist.info, Node: Describing, Next: Helper Functions, Prev: Recording, Up: Usage 1.7 Describing ============== Once each month, in the evening, the entire Company assembles so the Annalist can read from his predecessors. ‘annalist-describe’ is used to describe information. It takes three arguments: ‘name’ ‘type view’. ‘view’ is optional (defaults to ‘default’). For example: (annalist-describe 'me 'keybindings) It is possible to have custom filtering/sorting behavior by using a custom view: (annalist-define-view 'keybindings 'active-keybindings-only '((keymap ;; only show keys bound in active keymaps :predicate #'annalist--active-keymap ;; sort keymaps alphabetically :sort #'annalist--string-<))) (annalist-describe 'my 'keybindings 'active-keybindings-only) ‘annalist-org-startup-folded’ will determine what ‘org-startup-folded’ setting to use (defaults to nil; all headings will be unfolded).  File: annalist.info, Node: Helper Functions, Next: Builtin Types, Prev: Describing, Up: Usage 1.8 Helper Functions ==================== * Menu: * List Helpers:: * Formatting Helpers:: * Sorting Helpers::  File: annalist.info, Node: List Helpers, Next: Formatting Helpers, Up: Helper Functions 1.8.1 List Helpers ------------------ ‘annalist-plistify-record’ can be used to convert a record that is an ordered list to a plist. ‘annalist-listify-record’ can be used to do the opposite. This is what the ‘:plist’ argument for ‘annalist-record’ uses internally. These functions can be useful, for example, inside a ‘:record-update’ function, so that you can get record items by their name instead of by their index. However, if there will be a lot of data recorded for a type during Emacs initialization time, the extra time to convert between list types can add up, so it's recommended that you don't use these functions or ‘:plist’ in such cases.  File: annalist.info, Node: Formatting Helpers, Next: Sorting Helpers, Prev: List Helpers, Up: Helper Functions 1.8.2 Formatting Helpers ------------------------ 1. ‘:format’ Helpers Annalist provides ‘annalist-verbatim’ (e.g. ‘=verbatim text=’), ‘annalist-code’ (e.g. ‘~my-function~’), and ‘annalist-capitalize’. There is also an ‘annalist-compose’ helper for combining different formatting functions. 2. Formatting Emacs Lisp Source Blocks By default, Emacs Lisp extracted into source blocks will just be one long line. You can add ‘annalist-multiline-source-blocks’ to a view's ‘:hooks’ keyword or to ‘annalist-describe-hook’ to autoformat org source blocks if lispy is installed. By default, it uses ‘lispy-alt-multiline’. To use ‘lispy-multiline’ instead, customize ‘annalist-multiline-function’. The builtin types have ‘annlist-multiline-source-blocks’ in their ‘:hooks’ setting by default. Here is an example of what this looks like: [https://user-images.githubusercontent.com/4250696/62338313-1025e300-b4a6-11e9-845f-179c02abef35]  File: annalist.info, Node: Sorting Helpers, Prev: Formatting Helpers, Up: Helper Functions 1.8.3 Sorting Helpers --------------------- Annalist provides ‘annalist-string-<’ and ‘annalist-key-<’ (e.g. ‘(kbd "C-c a")’ vs ‘(kbd "C-c b")’).  File: annalist.info, Node: Builtin Types, Prev: Helper Functions, Up: Usage 1.9 Builtin Types ================= * Menu: * Keybindings Type::  File: annalist.info, Node: Keybindings Type, Up: Builtin Types 1.9.1 Keybindings Type ---------------------- Annalist provides a type for recording keybindings that is used by ‘evil-collection’ and ‘general’. When recording a keybinding, the keymap must be provided as a symbol. Here is an example: (annalist-record 'annalist 'keybindings (list 'org-mode-map nil (kbd "C-c g") #'counsel-org-goto)) In addition to the default view, it has a ‘valid’ to only show keybindings for keymaps/states that exist (since some keybindings may be in a ‘with-eval-after-load’). It also has an ‘active’ view to only show keybindings that are currently active.  Tag Table: Node: Top217 Node: Usage2193 Node: Disabling Annalist2441 Node: Terminology3220 Node: Settings3849 Node: Defining New Types4233 Node: Type Top-level Settings5268 Node: Type Item Settings6983 Node: record-update preprocess and postprocess Settings Argument7635 Node: Defining Views8595 Node: View Top-level Settings9590 Node: View Item Settings11230 Node: Recording13451 Node: Describing15390 Node: Helper Functions16427 Node: List Helpers16641 Node: Formatting Helpers17417 Node: Sorting Helpers18604 Node: Builtin Types18866 Node: Keybindings Type19016  End Tag Table  Local Variables: coding: utf-8 Info-documentlanguage: en End: