* GNU Hyperbole Full Demo/Tutorial by Bob Weiner Send an email or a testimonial if you like Hyperbole to . Table of Contents ----------------- * Introduction * Smart Keys * Koutliner * HyControl * HyRolo * History * Implicit Buttons * Explicit Buttons * Button Files * Global Buttons * Smart Mouse Keys * Epilog * References * Introduction Welcome to GNU Hyperbole. Hyperbole will super-charge your GNU Emacs experience, allowing you to work faster, utilize fewer key bindings, recall more information and link it all together by learning just a few concepts and keys. Invest an hour learning Hyperbole now and speed your daily information management for years to come. If you simply want to know what Hyperbole is, see the file "HY-ABOUT". Hyperbole displays that file when you press {C-h h d a}. Hyperbole assumes you know how to use Emacs. Otherwise, run the Emacs tutorial by pressing {C-h t} first. You should be looking at this file within Emacs and Hyperbole should already be installed within your copy of Emacs. To be sure, press 'C-h h' and you should see the Hyperbole menu in your minibuffer window at the bottom of your current Emacs frame. Press 'q' to quit out of this menu and we can begin. If Hyperbole is not installed, see the "INSTALL" file, in the same directory as this file, for instructions on installing it. This demo illustrates simple usage of the basic Hyperbole button-action-type model and shows how Hyperbole can support a style of self-documenting, interactive files. See the glossary in the Hyperbole Manual, "(hyperbole)Glossary", if terms used here are unfamiliar to you. Once you read the next section on "#Smart Keys", you can then browse any other sections individually as you like. Many people initially use Hyperbole for its "#Implicit Buttons" capabilities, so you may want to jump to that section. * Smart Keys Hyperbole provides two context-sensitive keys, the Action Key and the Assist Key, jointly referred to as Smart Keys. Each do dozens of things, essentially whatever is most helpful in any given textual context where they are pressed. The Action Key is {M-RET} (ESC RETURN if you are unsure) on the keyboard and the shift-middle mouse button on a 3-button mouse or the shift-left button on a two button mouse. The Assist Key is {C-u M-RET} and the shift-right mouse button. Memorize these keys; you will use them a lot. To distinguish the mouse buttons from the keyboard keys, we will often refer to the Action Mouse Key or Assist Mouse Key. (It is possible to rebind these keys to the unshifted middle and right mouse buttons, if desired. See the Smart Key Bindings section of the Hyperbole Manual, "(hyperbole)Smart Key Bindings") simply by pressing the Action Key on that reference. The Action Key selects entities, creates links and activates buttons. The Assist Key provides help, such as reporting on a button's attributes, or serves a complementary function to whatever the Action Key does within a context. Press the Action Key within this <(button)> to see all of the contexts and operations of the Smart Keys. SPACE scrolls forward and BACKWARDS DELETE scrolls backward within the Smart Key summary; {q} quits and returns here. See also the later section, <(Smart Mouse Keys)>. Now let's look at some of the things you can do with the Smart Keys. ** Table of Contents Browsing In DEMO, README and TUTORIAL files, Hyperbole recognizes table of contents entries and jumps to their associated sections (by default, in another window) with a press of the Action Key. Go back to the table of contents at the start of this file and try navigating to different sections. ** Smart Scrolling By default, the variable `smart-scroll-proportional' is set to t (TRUE). This makes a press of the Action Key at the end of a line scroll forward, so that the current line is placed at the top of the window; the Assist Key does the reverse when pressed at the end of line; it places the current line at the bottom of the window. This is called proportional scrolling because the amount of scrolling is relative to the point's position in the window. Try it with this DEMO buffer to see how you can precisely control what is displayed in a window and then come back here. Alternatively, if this variable is set to nil (FALSE), the Smart Keys scroll forward or backward a windowful when at the end of a line, regardless of which line point is on, just as {C-v} and {M-v} do. Let's try windowful scrolling a bit. Press the Action Key within the following button and then practice scrolling: <(toggle-scroll-proportional)>. If you prefer the default proportional scrolling, press on the previous button again to restore it. If you always want windowful (non-proportional) scrolling, use the Emacs customize system to set it permanently. Otherwise, you can set it manually by adding a setting of smart-scroll-proportional to your "~/.emacs" file after the point at which you load Hyperbole or else set it as part of hyperbole-init-hook, which executes whenever Hyperbole is loaded, e.g.: (add-to-list 'hyperbole-init-hook (lambda () (setq smart-scroll-proportional nil))) ** Hyperbole Menus Once Hyperbole is loaded into your Emacs, a Hyperbole menu will be added to the Emacs menubar, if you have one. This menu is mostly the same as the minibuffer menu you saw at the beginning; one is for use from the keyboard (the minibuffer menu) and one is for use with the mouse (the menubar menu). In this demo, we will use the minibuffer menu. To display the top-level Hyperbole menu again use 'C-h h' or click the Action Mouse Key within the blank/inactive minibuffer window. You will see a single line (possibly wrapped around) with submenus that end with a forward slash (/) and non-menu items. Type the first capitalized letter of any menu item (you can type it as lower or upper case, it does not matter) or click on it with the Action Mouse Key to select and activate it. You may also move forward an item with 'TAB' or 'M-f' or backward an item with 'Shift-TAB' or 'M-b' and then use 'RET' to select the item. Also, notice at the left of this menu is your Hyperbole release version number for easy reference. A press/click of the Assist Key on a menu item pops up a window displaying help for it while keeping the current menu on screen. 'C-t' or an Action Key press/click on the menu prefix (before the '>' character) returns you to the top Hyperbole menu if you are in a submenu. A press of 'q' or 'C-g' will quit from the current menu without invoking any further commands. Let's try a menu item that displays the Hyperbole Glossary of terms. Use {C-h h d g} to display the glossary. Use {q} in the glossary to return here. {C-h h d RET} would simply exit the menu and {C-h h d C-t q} would redisplay the top Hyperbole menu and then quit it. What if we want to do a web search for GNU Hyperbole? Then we use the Find/Web menu, typically bound to 'C-c /' or if not, then use {C-h h f w g "GNU Hyperbole" RET} to search Google, including the quote marks so that it is searched for as a phrase. Your standard web browser will be used to return the search results. You can change which browser is used with 'C-h h c w', the Cust/Web-Search menu. Advanced users can change the search engines listed by editing the option, <(hyperbole-web-search-alist)>. ** Help Buffers Since the Smart Keys do so many things, it is helpful to see what they will do in any given context before pressing them, especially when you are first learning Hyperbole. {C-h A} shows you what the Action Key will do in the current context; {C-u C-h A} displays the same kind of help for the Assist Key. Only a capital A will work, so be sure to press shift. Try these help commands. You can also see what mouse-only events like modeline clicks and drags across frames will do. Depress the Smart Mouse Key you are interested in at a location, then while holding it down, depress the other Smart Mouse Key, move to any release point and then release both keys. The help displayed will show you exactly what will happen in that context. Try this for the Action Mouse Key by dragging horizontally at least 10 characters in this buffer and depressing the Assist Mouse Key before you finish the drag. Any buffer whose name ends in `Help*' is presumed to be a temporary buffer that you want to inspect and then remove from view. If you press either the Action or Assist Key at the end of a help buffer, the buffer is buried from view and your window configuration is restored to its state prior to displaying the help (same as what {q} does). If you have removed the Smart Key help buffer, bring it back. Then press one of the Smart Keys at its end to remove it. Note how your window configuration is restored. Remember that this works for any help buffer, whether or not Hyperbole generated it. * Koutliner A unique feature of Hyperbole is the Koutliner; it is for outlining thoughts, developing requirements or listing tasks and hyperlinking them to other documents. The Hyperbole Koutliner produces multi-level, autonumbered hierarchies of cells. Each cell has two identifiers, a relative autonumber indicating its present position within the outline and a permanent identifier suitable for use within hyperlink references to the cell. A demonstration of the Koutliner is found on the Hyperbole Kotl/Example menu entry. {C-h h k e}, gives you an editable copy of Hyperbole's example Koutliner file. This explains the Koutliner commands and lets you try them out as you learn. Additional documentation can be found in "(hyperbole)Koutliner". "(hyperbole)Koutliner Keys" summarizes, in alphabetical order, the Koutliner commands which are bound to keys. * HyControl Hyperbole includes the fastest, easiest-to-use Emacs window and frame management system available, HyControl, found under the Hyperbole Screen menu, {C-h h s}. If you use a lot of Emacs windows or frames (native window system windows), then this tool is for you. A long video demonstrating most of HyControl's features is available at https://youtu.be/M3-aMh1ccJk. HyControl interactively adjusts the layout of your windows and frames down to the pixel-level, if desired. You adjust the location, size and display elements of your windows and frames until they look as you like and then simply quit HyControl and go back to work. It has smart features for laying out large grids of windows, avoiding having frames cover graphical toolbars anchored at the edges of your screen, and allows you to quickly set numeric arguments to apply to operations, like resizing a frame to a percentage of your screen size. There are two submodes of HyControl: one for controlling windows and one for controlling frames, although a number of commands are available in both modes where they are useful. Hyperbole binds {C-c \ } to invoke HyControl windows control; otherwise, the Hyperbole minibuffer menu item, Screen/WindowsControl {C-h h s w}, will do the same thing. Once in HyControl, your minibuffer window at the bottom of the selected frame will display a summary of keys you may use to adjust your windows until you press {Q} (or {q} once or twice) to quit from HyControl. If you don't see it, press {?} to turn on this help display. The key {t} will always switch you between controlling frames and windows, the minor modes of HyControl, with a modeline indicator of either "HyFrm" or "HyWin" depending on which type of control is active. See "(hyperbole)HyControl" for full usage information. ** Frame Commands Let's try some of the more interesting commands. You can either type the following key sequences (ignoring the braces) for practice or simply press the Action Key within them to see what they look like. {C-h h s f} - enter HyControl Frames mode {.50 %} - make frame 50% of screen size { c } - use this multiple times to move frame around screen edges { a } - use this multiple times to adjust frame width { A } - use this multiple times to adjust frame height The following 4 commands use the prefix argument as a percentage of the screen height, except that no argument or an argument of 1 mean 50% since the argument is used to adjust one dimension of the frame. { i } - move to top edge, next press cuts height by ARG % { m } - move to bottom edge, next press cuts height by ARG % { j } - move to left edge, next press cuts width by ARG % { k } - move to right edge, next press cuts width by ARG % { f } - clone the selected window to a new frame { F } - tear off the selected window (if more than one window) into a new frame ** Windows Grid The @ command splits a frame into a grid of up to 9 rows by 9 columns of windows, showing a different buffer in each window, if available. Outside of HyControl, you can invoke the grid of windows command with {C-c @} in most buffers. By default, this command shows buffers with attached files only and prompts for the size of the grid to display. With a negative prefix argument, the @ command prompts for a shell glob-type pattern of files to match, e.g. *hypb*.el, and then chooses the smallest square grid patterns that can accommodate the number of files matched, e.g. 3x3 or 4x4, etc. With a zero prefix argument, the @ command prompts for a major mode name, e.g. emacs-lisp-mode, then the size of the grid and then displays the existing buffers with that major mode. Let's try this unique command. First we will expand our frame to full screen with the {C-h h s f .1 % Q} command and then show a 2 x 3 grid. We can do the whole thing in one 'key series'. Press the action key within the braces: {C-h h s f .1 % .23 @ Q}. Using the global key binding in any buffer is even simpler: {C-23 C-c @}. Pretty amazing, right? You can separate each command by any number of spaces or even jam them all together: {C-hhsf.1%.23@Q}. Use SPC (separated by spaces) to include a space as part of the key series. Now let's display a 2x2 grid of windows preferring Emacs Lisp buffers. First let's add a few Emacs Lisp files to the bottom of our buffer list. Press the Action Key anywhere within the first line of the code of this action button: To display the grid, activate this key series button: {C-0 C-c @ emacs-lisp-mode RET 22 RET} Or how about we display a bunch of matching files in a directory, say Elisp files with 'hypb' in their names: {C--1 C-c @ *hypb*.el RET} If you ever need to experiment with different sized window grids, use {M-x hycontrol-window-grid-repeatedly RET}. It will repeatedly prompt you for a grid size and then display it. When you are done, simply press RET to exit. There is lots more to discover in HyControl as you explore. * HyRolo HyRolo is an advanced hierarchical, record-oriented retrieval system that uses text files for storing its records. Most often this is used for contact management but it can quickly be adapted to most any record-oriented lookup task requiring fast retrieval. HyRolo manages and searches rolo files which consist of an optional header that starts and ends with a line of equal signs (at least three equal signs starting at the beginning of a line), followed by zero or more rolo records. You must manually add a header to any rolo file if you want it to have one. We call rolo records, entries. Entries begin with a delimiter of one or more `*' characters at the beginning of a line. Entries may be arranged in a hierarchy, where child entries start with one more `*' character than do their parents. Top-level entries begin with a single `*'. Beyond this initial delimiter, entries are completely free-form text. It is best to use a "lastname, firstname" format, however, when adding contact entries into a rolo. Then HyRolo will automatically keep your entries alphabetized as you enter them. Then you can sort the entries if you ever need. HyRolo commands are invoked from the Hyperbole Rolo menu. See "(hyperbole)HyRolo" for a full reference on commands including adding entries, regular expression searches and manipulating the HyRolo search results buffer. For demonstration purposes, we discuss only the most common searches and use a global key binding for quick access to HyRolo searches of existing entries. Below is a sample rolo file (indented 3 spaces) that we will work with in this DEMO. The date at the end of each record is automatically added by HyRolo whenever a new record is added. ================================================================== DEMO ROLO ================================================================== * HiHo Industries ** Strong, Hugo W708-555-9821 Manager 04/12/2017 *** Smith, John W708-555-2001 Chief Ether Maintainer 05/24/2017 * Work Industries ** Hansen, Dan W218-555-2311 Manager 02/18/2017 *** Dunn, John W218-555-3233 Media Maker 11/2/2017 ** String Searches Any search done on the rolo scans the full text of each entry and ignores the case of the text. During a search, the rolo file header separator lines and anything in between are appended to the buffer of matched entries before any entries are retrieved from the file. Whenever an entry is matched, it and all of its descendant entries are retrieved. If your emacs version supports textual highlighting, each search match is highlighted for quick, visual location. Let's try the HyRolo. First load the HyRolo demo commands with an Action Key press on "-hyrolo-demo.el". Now C-x 4 r will search the DEMO ROLO file. Action Key press on {C-x4r work RET} to search for all entries from Work Industries; then type {q} to quit from the HyRolo search results buffer. {C-x4r manager RET} finds all managers plus their staff across companies. {C-x4r Dunn,\ J RET} finds just that staffer. Notice that you must quote the space with a backslash when including it in a key series search string or else the space will be removed (or you could type SPC); when just typing the same string interactively, don't add the backslash. A prefix argument used with any of the find commands listed above limits the search to a maximum number of matches given by the argument. For example {C-u 1 C-x4r John RET}, finds only the John Smith entry and ignores John Dunn. ** Logical Searches The same search command can be used to perform logical searches of the HyRolo files. A simple parenthesis delimited prefix format is used with the following logical operators. Operator Name Number of Arguments Description ===================================================================== and two or more Match entries with all args or two or more Match entries with any args xor two or more Match entries with 1 arg only not one Match entries without the arg ===================================================================== So for example, {C-x4r (or smith dunn) RET} finds both the Smith and Dunn entries. (Note that you do not need to quote spaces with backslashes within parentheses, square brackets, angle brackets or double quotes when used in key series). To find any Managers and their staffers at HiHo Industries, use: {C-x4r (and manager hiho) RET}. To find managers anywhere but at HiHo: {C-x4r (and manager (not hiho)) RET}. Finally, this will find all people who are not managers at HiHo: {C-x4r (not (and manager hiho)) RET}. See "(hyperbole)HyRolo Keys" for how to navigate the HyRolo Matches buffer when many entries are found or how to edit a matched entry. We are now finished with the HyRolo section of the demo. Activate this to remove the HyRolo demo code and restore any prior key binding: {M-x hyrolo-demo-quit RET}. * History Hyperbole provides a history command that returns you to previous button locations in the reverse order of the way you traverse them. It actually restores your complete frame and window configuration at the time of the button press. You access it by selecting the Hist command from the top-level Hyperbole menu, {C-h h h}. Remember this because you will want to use that command to return to this DEMO later. * Implicit Buttons Table of Contents ----------------- ** Key Series Buttons ** Org Mode ** Implicit Path Links *** Paths with Line and Column Numbers *** HTML Markdown and Emacs Outline Hash Links *** Path Suffixes and Variables *** Path Prefixes *** Info Paths *** Remote Paths *** POSIX and MSWindows Paths ** Internet Request For Comments (RFC) Document Browsing ** MANIFEST Files and Tables of Contents ** World Wide Web URL Buttons ** Email Addresses ** Action Buttons *** Using Action Buttons *** Defining New Action Button Types ** Github (Remote) References ** Gitlab (Remote) References ** Git (Local) References ** Grep, Occurrence, Debugger and Compiler Error Buttons, and Cscope Analyzer Lines ** Annotated Bibliography Buttons ** Completion Selection ** Hyperbole Source Buttons ** UNIX Man Apropos Buttons ** Site-specific Online Library Document IDs Hyperbole can recognize a wide variety of links embedded within Emacs buffers, turning your unmodified text files into hypertexts via its incredibly powerful feature: implicit buttons. An implicit button is a span of text within a buffer that Hyperbole recognizes as a button and lets you activate. Hyperbole recognizes these buttons using its predefined implicit button types that specify how to recognize a particular type of button and what action it performs. For example, an Action Key press on a double-quoted pathname displays it. (This is because an implicit button type of 'pathname' is recognized and it has an associated action type of 'hpath:find' which displays the path in a window specified by the setting of 'hpath:display-where'). You can simply type implicit buttons into a buffer or you can use {C-h h i c} to create them and give them names. To create an implicit link button from a buffer in one window to another, simply depress the Assist Mouse Key where you want the new button (but not within a draggable item), drag to a point in another Emacs window and release. An implicit link button of an appropriate type for the release context will be inserted at the original depress point. Hyperbole has many built-in implicit button types, a number of which you will see here. You may also create your own types through the use of regular expressions or via Emacs Lisp, see "(hyperbole)Creating Implicit Button Types". Once a type is known, you can embed an infinite number of buttons of that type within your text documents simply by typing them. Let's look at some of these button types and how you can use them. Note that you must press a Smart Key on the first line of an implicit button to utilize it if it spans multiple lines and always press on a regular character, not a delimiter like ( or ) since these are treated specially and used to select groups of text. Individual implicit buttons may be labeled so that they can be activated by name or linked to by other buttons. Here is a pathname button with a label of 'My Emacs Files': <[My Emacs Files]>: "~/.emacs.d" You see that the label is delimited by '<[' and ']>'. It must be at least 2 characters in length and can be followed by any number of :, - or = characters, including none, and then a whitespace character. You can activate the button either from its label or its pattern text. With point on an implicit button, you can label it by using C-h h i l. Now let's explore some implicit button types. ** Key Series Buttons Any series of Emacs key sequences (or 'key series') delimited by curly braces is an implicit button. Press the Action Key within {C-u C-p C-n C-e} for example and the point should move three lines upward and to the end of line. An Assist Key press on the key series either displays the documentation for its command binding (if a single key sequence) or displays help for the implicit button, i.e. what it does. Key series together with the arguments their commands prompt for, may also be given, e.g. {M-x apropos RET hyperbole RET}. Click with the Action Mouse Key within the first line of this button to try it out. Hyperbole minibuffer menu items may also be activated as key series. For example, {C-h h d i} displays the online browsable Info version of the Hyperbole Manual. Press your Action Key between the braces to see it. Another press here: {C-x o m implicit\ buttons RET} should jump to the Implicit Buttons section of the manual. Now when you write notes about particular global key sequences you want to remember, just surround them with curly braces and you'll always be able to try them out with a simple click or press. You can even create your own demonstrations and tours with this and other implicit button types. ** Org Mode For users of Emacs Org mode, Hyperbole does quite a few things when the Action Key is pressed. 1. If on an Org todo keyword, cycle through the keywords in that set or if final done keyword, remove it. 2. If on an Org agenda view item, jump to the item for editing. 3. Within a radio or internal target or a link to it, jump between the target and the first link to it, allowing two-way navigation. 4. Follow other internal links in Org mode files. 5. Follow Org mode external links. 6. When on a Hyperbole button, activate the button. 7. With point on the :dir path of a code block definition, display the directory given by the path. 8. With point on any #+BEGIN_SRC, #+END_SRC, #+RESULTS, #+begin_example or #+end_example header, execute the code block via the Org mode standard binding of {C-c C-c}, (org-ctrl-c-ctrl-c). 9. When point is on an Org mode heading, cycle the view of the subtree at point. 10. In any other context besides the end of a line, invoke the Org mode standard binding of {M-RET}, (org-meta-return). To disable ALL Hyperbole support within Org major and minor modes, set the custom option `hsys-org-enable-smart-keys' to nil. Then the Action Key will simply invoke the Org mode standard binding of {M-RET}, (org-meta-return). ** Implicit Path Links Any existing absolute or relative pathname (whether doubly quoted or not) acts as an implicit button that either displays the referenced path within a buffer, passes it to an external viewer program, or runs a function that operates upon the path. These are `pathname' implicit buttons. For example, activate "HY-ABOUT". HY-ABOUT or `HY-ABOUT' would work as well. Or try "~/.emacs". Pathname implicit buttons provide one example of how Hyperbole can improve your working environment without requiring any work from you. *** Paths with Line and Column Numbers If you want to display a path at a specific line number and optionally column number, then add each number preceded by a colon at the end of the path. For example, "HY-ABOUT:10" displays HY-ABOUT at line 10, the second paragraph, with point at the start of the line. "HY-ABOUT:17:7" shows the first numbered item on line 17 at column 7, where the text starts. *** HTML Markdown and Emacs Outline Hash Links Often links to HTML and Markdown files use a hash mark (#) plus an identifier to refer to a section of such files. When the Action Key is pressed on any such reference, it jumps to the section referenced by the link. For example, "man/hyperbole.html#Smart-Keys" will take you to the Smart Keys description in the HTML version of the Hyperbole manual. Inside that manual in HTML form, "#Smart-Keys" would do the same thing. Similarly, "README.md#why-was-hyperbole-developed" jumps to the referenced section of that Markdown file, while accounting for the difference in case, whitespace and trailing punctuation between the identifier and the section header. (Inline Markdown links surrounded by parentheses and square bracketed reference links work similarly but are handled specifically as Markdown links, not as pathnames). Hyperbole allows hash-style links to Emacs outline files (including Org-mode files); they work just like the Markdown section links but match to section headings preceded by asterisks rather than hash marks. So to jump back to the Org Mode section in this file, press the Action Key on "#Org-Mode". HTML hash-links are case-sensitive; other hash-links are not. Hash links typically use dashes in place of the spaces that referents may contain, but if the link is enclosed in quotes, Hyperbole allows spaces to be used as well. In fact, it is best practice to always enclose hash-style links in quotes so Hyperbole can distinguish them from other similar looking constructs, such as social media hashtags (see "#Social Media Hashtags and Usernames"). *** Path Suffixes and Variables Most file path buttons directly name their associated files in full, but Hyperbole can also add file name suffixes and resolve Emacs and environment variables within path buttons. If you have the source code for your Emacs installation, then there is a Lisp library, simple.el.gz, stored in compressed form within a directory listed in the variable, load-path. An Action Key press on "${load-path}/simple.el" will dynamically locate the file within load-path, uncompress it and display it for editing. There is no need to know whether the file is compressed or not or what values are set for load-path at your particular location. Thus, you can provide path links that vary from site to site, especially handy if you email Hyperbole buttons to your associates. Shell environment variables also work. To see your home directory, try "${HOME}". Press the Action Key within the quoted text of "(hyperbole)Link Variable Substitution" for a bit more on this topic. For the special cases of Emacs Lisp files and Info manual files, you can omit the variable of directories to search since Hyperbole knows them already. Thus an Action Key press on "simple.el", "hyperbole.info" or even "(hyperbole)" will display these properly as well. Some file types require external programs to view them, such as pdf files. The function (hpath:get-external-display-alist) determines the file suffixes which should be viewed externally, together with their associated viewer programs, on a per-frame, per window-system basis. See its documentation for more details. The association lists used by this function are stored in variables for each available window system: hpath:external-display-alist-macos, hpath:external-display-alist-mswindows, and hpath:external-display-alist-x. Examine and modify these values to suit your needs. Under the X Window System, if you have the `xv' program, all of the following file formats may be displayed externally as images: gif, tiff, xbm, pm, pbm, and jpeg. Under X or Mac OS, try a press of the Action Key on "man/hyperbole.pdf" to browse the printable version of the Hyperbole Manual. *** Path Prefixes Several prefix characters may be attached to pathnames to indicate that a different action should be taken when the button is activated. An exclamation point prefix indicates that the full pathname should be run as a non-windowed shell program. For example, try "!${PATH}/date" on a POSIX system. This will run the program in a subshell within Emacs. An ampersand prefix means run the full pathname as a windowed program, outside of Emacs. Under the X window system, try "&${PATH}/xeyes". Finally, a hyphen indicates that the filename should be executed as an Emacs Lisp library, e.g. "-subr.elc", rather than displayed. *** Info Paths Double quoted GNU Info manual references of the form "(filename)refname" work as implicit buttons that display the associated referent in the Emacs Info Browser. Thus, Action Key presses on "(hyperbole)Glossary" or "(emacs)Glossary", take you right there. Typically, you exclude any path and file suffix from the filename. Refname can be an Info node name or any Info index item (an item listed in any of a manual's indices). Index items let you jump to a specific, referenced point within an Info node. As an example, suppose you want quick access to a summary of Hyperbole's key bindings. Store "(hyperbole)key binding list" in your personal file of buttons (accessed with {C-h h b p}) and you will always have quick access to a list of Hyperbole's key bindings. Press the Action Key on the Info reference and try it. Press the Action Key on the key binding of your personal button file and then store the implicit link there if you like. Since Emacs and most GNU programs include Info manuals, you now have a simple way to link to and jump to any named item within a manual. *** Remote Paths If you use the standard Emacs library "tramp.el" for working with remote files and directories, then remote pathnames of the form: /protocol:user@host.domain:/path will be recognized by Hyperbole. Once you have Tramp configured for loading and are on the Internet, you can press on any of the following to jump to the ftp site of Hyperbole tarball distributions: /ftp:anonymous@ftp.gnu.org:/pub/gnu/hyperbole/ For Tramp pathnames, Hyperbole recognizes them with or without double quote delimiters. If you enable the Hyperbole option to use URLs when finding files with the {C-x C-f} (find-file) command via the {C-h h c f} key sequence, then you can also use paths of the form: ftp://ftp.gnu.org/pub/ *** POSIX and MSWindows Paths Hyperbole recognizes standard POSIX paths as well as typical MSWindows paths (both local and network shares) and can convert an in-buffer path between POSIX and MSWindows formats multiple times, even paths involving mount points. Hyperbole even recognizes the different ways paths are accessed when using Windows for GNU/Linux (WSL) atop MSWindows, where all of these reference the same directory: "c:/Users", "c:\Users", "/C/Users", "/c/Users", and "/mnt/c/Users". MSWindows paths may be used within links and implicit path buttons just like POSIX paths, whether running Emacs under a POSIX system or MSWindows. If under POSIX, a remote MSWindows path must be accessed through a mount point to the network share. Hyperbole caches such mount points when it is first loaded. Use {M-x hpath:cache-mswindows-mount-points RET} to update them if more mounts are made later. {M-x hpath:substitute-posix-or-mswindows-at-point RET} toggles any path at point between POSIX and MSWindows styles. Bind it to a key for rapid path transformations. The function, `hpath:substitute-posix-or-mswindows', does the same thing for properly quoted path strings, for example: (hpath:substitute-posix-or-mswindows "C:\\Users") yields "/mnt/c/Users" and (hpath:substitute-posix-or-mswindows "/c/Users") yields "c:\\Users". To convert pathnames in one direction only, use the `hpath:mswindows-to-posix' or `hpath:posix-to-mswindows' functions. ** Internet Request For Comments (RFC) Document Browsing With Tramp, you can also retrieve and browse RFC documents used in Internet standard-making. Simply use the Action Key on an RFC document identifier, like RFC-822 or rfc 822, and the RFC will be retrieved and displayed for browsing. The `rfc' implicit button type provides this service. The `hpath:rfc' variable specifies the location from which to retrieve RFCs. Once you have retrieved an RFC, an Action Key press most anywhere within a line typically will produce a table of contents summary of the RFC (via the `rfc-toc' implicit button type). An Action Key press on any of the table of contents lines then displays that section, for easy sectional browsing. ** MANIFEST Files and Tables of Contents Now suppose you want to browse through a number of files within the Hyperbole distribution. You could use the Emacs dired subsystem, "(emacs)Dired", but a faster way is to note that files named MANIFEST and DIR are used to summarize the files in a directory, so we can use each of their entries as an implicit button (of type `dir-summary') to take us to the file. Let's look at "MANIFEST". Now press anywhere within a line in the MANIFEST file and you see that it is displayed as expected. (Remember to use the Hyperbole history command to return here.) You can get help on these buttons just like any others. In README files, such as Hyperbole's "README.md", table of contents entries act similarly. Press on "README.md" to view that file and then press on a table of contents entry to jump to the associated section in the "README.md" file. Or "README.md#User Quotes" goes directly to that section. ** World Wide Web URL Buttons You can browse URLs (universal resource locators) from within any buffer once Hyperbole is loaded. Hyperbole's Cust (Customization) menu allows you to set the web browser used for display (this is turn sets the standard Emacs "browse-url.el" library settings). Try using the Action Key on: "http://www.gnu.org". Full and abbreviated web and ftp URLs, e.g. www.gnu.org, are recognized with or without quotes. ** Email Addresses An Action Key press on an email address of any common domain name will start composing an email message to that name within Emacs. This is limited to major modes listed in the variable, hypb:mail-address-mode-list. If that variable is nil, then email addresses are active in every buffer. Try composing a message to and tell us what you think of Hyperbole. Even better, a press of or on {C-h h m c} composes mail to the list that includes your system information. ** Action Buttons *** Using Action Buttons A new feature of Hyperbole is a universal syntax for creating implicit buttons known as Action Buttons. These buttons execute any existing action types or Emacs Lisp symbols. They are delimited by angle brackets, < >, and come in three types: 1. action type invocations - these begin with an action type name (from the list displayed by {C-h h d t a RET}) and are followed by any needed arguments to form the action, e.g. 2. function calls - these are similar to action type invocations but begin with an Elisp function name rather than an action type name. They may contain any number of levels of embedded Lisp s-expressions, e.g. 3. variable displays - these consist of an Elisp variable name only and display a message with the variable name and value, e.g. If there is a function binding with the same name as the variable you wish to display, to prevent interpretation as a function call action button, precede the name with a '$', e.g. <$hbut:max-len> 4. ert-deftest tests - these consist of the test name only as tests take no arguments, e.g. This runs one of the Hyperbole regression tests. An Action Button is recognized only if the first name within the angle brackets is an existing action type or Emacs Lisp symbol. Otherwise, other implicit button types will be tested and may activate instead. With Action Buttons you need not remember any special syntax for each type of implicit button. You can freely embed them in any type of text and use the Action and Assist keys on them as you do with any other type of implicit button. *** Defining New Action Button Types You can do many things with existing Action Button types but sometimes you may want to define your own types for more advanced usage. Hyperbole lets you easily create your own Action Button link types without knowing Elisp, if you understand basic regular expression-based pattern replacement. In your Emacs initialization file, e.g. ~/.emacs, you will add a line of the form: (defal TYPE LINK-EXPR &optional DOC) where: TYPE is the name of the new type you want to create; LINK-EXPR is a regular expression containing a %s replacement string into which Hyperbole will substitute the button text following the TYPE from each button activated of this type; alternatively, LINK-EXPR may be the name of a function of one argument, the button text sans the function name; Hyperbole automatically creates a doc string for the type but you can override this by providing an optional DOC string. When a button of this new type is activated, the button text following the type is substituted into LINK-EXPR. After which, the button is activated as one of these 4 kinds: (1) a brace-delimited key series; (2) a URL/web link; (3) a path (possibly with trailing colon-separated line and column numbers); (4) or a function or action type of one argument, the button text sans the function name. Let's try an example. If you use Python and have a PYTHONLIBPATH environment variable, then pressing {C-x C-e} after this expression: (defal pylib "${PYTHONLIBPATH}/%s") defines a new action button link type called 'pylib’ whose buttons take the form of: and display the associated Python libraries (typically Python source files). Optional colon separated line and column numbers may be given as well. Now press the Action Key press within: This will display the source for "string.py" (wherever it is installed on your system) from the Python standard library with point on the fifth line at the seventh character. ---- As another example, suppose you want to do a web search for Emacs Lisp libraries whose names may be very generic, like hyperbole. For this, you can use a Google filetype-specific search. Define an action link type with: (defal elsearch "https://www.google.com/search?q=%s+filetype:el" "Find Elisp libraries via a Google file type search") Then, an Action Key press on: will find major links to that library which makes window configurations and framesets persistent across Emacs sessions. This search is actually built in to the Hyperbole menus, so you could have defined it more simply (and sans docstring) with a key series definition: (defal elsearch "{C-hhfwe %s RET}") as well. ---- For more advanced and flexible regular expression-based link type creation, see the 'defil' expression in "(hyperbole)Implicit Button Link Types". For any type of implicit button type creation using ELisp, see 'defib' in "(hyperbole)Programmatic Implicit Button Types". ** Social Media Hashtags and Usernames An Action Key press on a social media hashtag or username reference at point displays the web page associated with the reference at the associated service. References are of the form: [facebook|instagram|twitter][#@] or [fb|in|tw][#@]. If the service is omitted and there is no other usage of a hash reference without a prefix in the buffer, then the service defaults to the value of `hibtypes-social-default-service', which is initially "twitter". For example, these make the same hashtag reference: twitter#gnu or tw#gnu and display the page for tweets with that hashtag. Similarly, in@lostart or instagram@lostart would display the page for the user lostart at instagram. Try pressing the Action Key on these if you like. The file "hib-social.el" has more details on this. ** Github (Remote) References For software developers who use Github for publishing and version control, Github links are similar to social media links but reference specific Github web pages. Press the Action Key on github@rswgnu to go to RSW's gihub home page. gh@rswgnu works too. References to project home pages look like this (the / is required): github#/hyperbole (uses user default setting) github#/rswgnu/hyperbole References to specific commits use the # hash symbol and short versions of the git commit hash code: gh#rswgnu/hyperbole/5ae3550 (if include user, must include project) github#hyperbole/5ae3550 (project can be given with user default) gh#5ae3550 (user and project defaults are used) An Action Key press on the first commit reference above works because user, project and commit hash code are all included. The second and third versions require the setup of default values, as explained in the commentary near the top of "hib-social.el". Similarly, the same file above explains how to link to pull requests, issues, branches and tags. ** Gitlab (Remote) References For software developers who use Gitlab for publishing and version control, Gitlab links are similar to social media links but reference specific Gitlab web pages. See "#Github (Remote) References" for the basic syntax of such links but substitute 'gl' instead of 'gh'. Gitlab offers many more types of reference links than Github, here they are: gl#gitlab-org/gitlab-ce/activity Summarize user's project activity gl#gitlab-org/gitlab-ce/analytics Display user project's cycle_analytics gl#gitlab-org/gitlab-ce/boards Display user project's kanban-type issue boards Once you set the default user and project variables, you can leave them off any reference links: (setq hibtypes-gitlab-default-user "gitlab-org") (setq hibtypes-gitlab-default-project "gitlab-ce") gl#jobs Display default project's computing jobs gl#labels Display default project's issue categories gl#members Display default project's staff list gl#contributors Show contributor push frequency charts gl#merge_requests or gl#pulls Display default project's pull requests gl#milestones Display default project's milestones status gl#pages Display default project's web pages gl#pipelines List build and test sequences gl#pipeline_charts Graphical view of pipeline run results across time gl#schedules Display schedules for project pipelines gl#snippets Project snippets, diffs and text with discussion gl#groups List all available groups of projects gl#projects List all available projects gl#milestone=38 Show a specific project milestone gl#snippet/1689487 Show a specific project snippet ** Git (Local) References Similarly, again for software developers, git references work on local git repositories. If you have a clone of the Hyperbole git repository on your local system, then you can activate all of the following buttons. git#/hyperbole (displays the top directory of the hyperbole repository) git#/hyperbole/55a1f0 (displays hyperbole git commit diff) git#=hactypes.el (displays a git-versioned file regardless of directory) git#=master:kotl/kview.el (displays file in subdirectory from master branch) gt#55a1f0 (when within a git repo, displays its commit diff) The first four examples work anywhere regardless of the buffer since Hyperbole locates all git repositories for you by repository/project name. If you set a default project, then the last example will work anywhere as well. ** Grep, Occurrence, Debugger and Compiler Error Buttons, and Cscope Analyzer Lines The output of `grep -n', the UNIX line pattern matcher, can be activated as buttons that jump to each matched line within its source file; use {M-x grep RET} or even better, the Hyperbole recursive directory grep, {C-h h f g}. Compiler error messages also serve as implicit buttons that jump to associated source lines; use {M-x compile RET}. GDB, DBX or XDB stack frames along with GDB breakpoint listing lines also link to source lines. {C-h h f o} or {M-x occur RET} (find matches in a single buffer) and {C-h h f m} or {M-x moccur RET} (find matches across multiple buffers and files) also produce implicit button output that display associated source lines. If you have the Cscope C/C++ code analyzer from the AT&T Toolchest and have loaded the cscope.el library add-on for GNU Emacs, then the output lines from a cscope query serve as implicit buttons which jump to associated source lines. Cscope goes beyond the basic Emacs tags facility to allow you to see the callers of a function and the functions called by a specific routine. Many of these find-a-line features exist in the Hyperbole Find/ menu, {C-h h f}. Give it a try for fast access to complex file line filters, e.g. filter a file to just lines that don't match a pattern (RemoveLines). ** Completion Selection Often when Emacs or Hyperbole prompts for an argument in the minibuffer, a list of possible argument completions is available by pressing {?} or automatically displayed. A single Action Key press on any of these completions inserts it into the minibuffer for your inspection. A second press on the same completion uses it as the argument value and moves on to any next minibuffer argument prompt. Test this technique with a {C-x C-f} (find-file) and then a {?}. Within the minibuffer itself, the Smart Keys are also context-sensitive. A press of the Action Key at the end of the argument line tries to accept the argument and when successful, exits the minibuffer. A press of the Assist Key at the end of the argument line displays matching completions for times when they are not automatically displayed or need updating. A press of the Action or Assist Key on part of the argument, deletes from point to the end of the line, expanding the set of available completions and redisplaying them. ** Hyperbole Source Buttons If you ask for a report on all the explicit buttons in this buffer with {C-h h e h b}, the first line of the resulting help buffer will look like this: @loc> "DEMO" except it will contain the full pathname of the file. If the buttons were embedded within a buffer without an attached file, the first line of the help buffer might look like: @loc> # If you press the Action Key on the buffer name, the buffer will be displayed just as a file buffer would. This type of implicit button is called a `hyp-source' button. You can also activate any explicit buttons (see "#Explicit Buttons") shown in help buffers thanks to hyp-source buttons. ** UNIX Man Apropos Buttons Below are some lines output by the UNIX `apropos' command (with a little touchup for display purposes). A button activation anywhere within such a line recognizes the line as an apropos entry and displays the man page for the entry. Try it. grep, egrep, fgrep (1) - search a file for a string or regular expression rm (1) - remove (unlink) files or directories touch (1) - update the access and modification times of a file cat (1) - concatenate and display ** Site-specific Online Library Document IDs Hyperbole offers a powerful, yet easy to use facility for building online libraries through the use of the `doc-id' implicit button type. A document id is used just like a reference citation in traditional publications but it actually links to the document that it references and the card catalog (index) entry for the document. One can easily pass around doc ids to point people to appropriate documents. For example, a mail message in response to a question might say, "See [Emacs-001] for examples of what Emacs can do." Since the format and handling of document identifiers and their index entries is site-specific, document id handling is not completely configured in a default Hyperbole configuration. If you wish to setup this facility for site or personal use, see the DESCRIPTION section in "hib-doc-id.el" for installation and use information. * Explicit Buttons Beyond implicit buttons recognized in-context by Hyperbole, Hyperbole also offers `explicit buttons' that you create and embed within documents. As you have seen, explicit buttons look like this `<(fake button)>'. They are quickly recognizable, yet relatively non-distracting as one scans the text in which they are embedded. Explicit buttons can link to local and remote files or to a section within a document; they can calculate things or query databases or show different views of bodies of information. Unlike HTML hyperbuttons, there is no markup language to learn nor specific document format required. You can create explicit buttons with simple keyboard presses or mouse drags from one window to another (when not depressed on a draggable item). This button prints the <(factorial)> of 5 in the minibuffer when activated with the Action Key. If you instead press the Assist Key, you get help for the preceding button. The help offered is a summary report of the button. You will see that it utilizes the `eval-elisp' action type. You can also see who created it. Try it. {q} will quit the summary report display. Note that the create-time and mod-time are displayed using your own timezone but they are stored as universal times. So if you work with people at other sites, you can mix their buttons with your own within the same document and see one unified view of the modification times on each button. Every explicit button utilizes an `action type', many of which are predefined by Hyperbole. {C-h h e t RET} lists all Hyperbole action types but Emacs Lisp commands may be utilized as well. Hyperbole is pretty forgiving about the format of explicit buttons. For example, all of the following represent the same button, as long as you press on the *first* line of the button, within the button delimiters: <(factorial button)> <( factorial button)> Pam> <(factorial Pam> button)> ;; <(factorial ;; button)> /* <( factorial */ /* button )> */ ** Creating and Editing Explicit Buttons Creating explicit buttons is fun and easy. You can always try them out immediately after creating them or can utilize the Assist Key to verify what buttons do. There are two ways to create them: by dragging between windows with the Assist Mouse Key or by using the Hyperbole menus. *** Creation via Dragging An efficient way to create an explicit button interactively is to use the Assist Mouse Key to drag from a window where you want the button created (button source window) to a window showing its link referent. The drag must start outside of a draggable item which includes Hyperbole buttons, dired items and buffer menu items. More specifically, you should split your current Emacs frame into two windows: one which contains the point at which you want a button to be inserted and another which shows the point to which you want to link, the referent. Depress the Assist Mouse Key at the source point for the button (anywhere but on a paired delimiter such as double quotes or parentheses). Then drag to the other window and release the Assist Mouse Key at the start point of the link referent. The process becomes quite simple with a little practice. Hyperbole uses the link referent context to determine the type of link to make. If there are a few different types of links which are applicable from the context, you will be prompted with a list of the types. Simply use the Action Key or the first letter of the link type to select one of the type names and to finish the link creation. Hyperbole will then insert explicit button delimiters around the button label and display a message in the minibuffer indicating both the button name and its action/link type. When a link is created, if its path contains a match for any of the variable values listed in hpath:variables, then the variable's name surrounded by ${ } delimiters is substituted for the literal value. Hyperbole then replaces the variable with a matching value when the link is later resolved. This allows the sharing of links over wide areas, where links contain variables whose values differ between link creator and link activator. If you do the same thing with the Action Mouse Key instead of the Assist Mouse Key, Hyperbole will create an implicit link button instead of an explicit one. Such buttons are created without names but you can add a name preceding such buttons by using {C-u C-h h i l} instead. *** Creation via Ace Window For the fastest link button creation, use the Emacs package 'ace-window' (see "(hyperbole)Keyboard Drags" for setup). Once this is configured, then {M-o w`j } may be used to quickly create an unnamed implicit link button in the selected window that links to any other window chosen via the Ace Window. Use a M-1 prefix argument to create a named implicit link button. If you want to create an explicit button instead, use the C-u prefix argument. *** Creation via Menu You may instead use the Hyperbole menus to create explicit buttons. First, mark/highlight a short region of text in any fashion allowed by Emacs and then select the Hyperbole menu item sequence, Ebut/Create {C-h h e c}. You will be prompted for the button's label with the marked region as the default. If you accept the default and enter the rest of the information you are prompted for, the button will be created within the current buffer and Hyperbole will surround the marked region with explicit button delimiters to indicate success. If you do not mark a region before invoking the button create command, you will be prompted for both a label and a target buffer for the button and the delimited label text will be inserted into the target buffer after a successful button creation. After Hyperbole has the button label and its target buffer, it will prompt you for an action type for the button. Use the {?} completion list key to see all of the available types. The type selected determines any following values for which you are prompted. If a previous button with the same label exists in the same buffer, Hyperbole will add an instance number to the label when it adds the delimiters so that the name is unique. Thus, you don't have to worry about accidental button name conflicts. If you want the same button to appear in multiple places within the buffer, just copy and paste the button with its delimiters. Hyperbole will interpret all occurrences of the same delimited label within a buffer as the same button. If you create link buttons using the Hyperbole menus, the best technique is to place on screen both the source buffer for the button and the buffer to which it will link (referent buffer). Leave point where you want to link to in the referent buffer, switch to the source buffer and put point where you want to insert the link button. If the button name is already there in the buffer, mark it as the region to use for your button label. Then press {C-h h e l} and that will figure out the proper link type, prompt for any needed arguments and then insert the button. You can use the direct selection techniques mentioned in "(hyperbole)Smart Key Argument Selection", to select any arguments. See "(hyperbole)Utilizing Explicit Buttons" for much more detail on how to work with explicit buttons. ** Sample Explicit Buttons and Types Below we demonstrate some uses and types of explicit buttons. Activation of the next button will tell you about <(keyboard macros)>. Can't remember a Hyperbole term? Check out the Hyperbole Manual <(glossary)>. Here is a <(keyboard macro)> button. It displays documentation for the first Emacs Lisp function that follows it, e.g. (hbut:report). You can see that a button label may consist of many characters, up to a set <(maximum length)>. A <(shell command)> button can do many things, such as display the length of this file. While such commands are executing, you can perform other operations. If you create a button that runs a shell command which displays its own window system window, i.e. a window outside of Emacs, use `exec-window-cmd' rather than `exec-shell-cmd' as its action type. You can link to files such as your <(.emacs)> file. Or directories, like the <(tmp directory)>. When creating file links, if the file you are linking to is loaded in a buffer, you are prompted as to whether you want the link to jump to the present point in that buffer. If so, the link will always jump there, so position point within the referent file to take advantage of this feature. Note how a separate window is used when you activate file link buttons. Most basic Hyperbole action types display their results in this manner. You can create buttons that run specific web searches such as a Wikipedia query on an <(electric car)> with the `link-to-web-search' action type. You can make a button an alias for another by using the `link-to-ebut' action type. This <(factorial alias)> button does whatever the earlier <(factorial)> button does. * Button Files It is often convenient to create files filled with buttons as a means of navigating distributed information pools or for other purposes. These files can also serve as useful roadmaps that guide you through both unfamiliar and highly familiar information spaces. Files that are created specifically for this purpose are called "Hyperbole button files". Hyperbole's ButFile menu provides quick access to two types of these button files. Your personal button file is stored in "${hbmap:dir-user}/HYPB" and accessed with {C-h h b p}. Per-directory button files are stored in the respective directories and are also named "HYPB". Access the current one with {C-h h b d}. If you want group and site-specific button files, simply place links to such files at the top of your personal button file and do so for your colleagues. This provides a flexible means of connecting to such resources. * Global Buttons Global buttons are labeled Hyperbole buttons in your personal button file. All global buttons are activated by name with completion provided, independent of which buffers are on-screen. Global buttons may be explicit buttons or labeled/named implicit buttons. The Hyperbole Gbut menu, C-h h g, creates, modifies and activates global buttons by name. Each button created by this menu is stored as an explicit button near the end of your personal button file. But any buttons you create in other ways within this file also become global buttons, for example labeled/named implicit buttons. Since implicit buttons can be labeled with a name and placed in the global button file for invocation by name, you can give short names to any such buttons you want to invoke frequently. For example, to create a labeled implicit global button that displays a personal todo file maintained with the Koutliner, activate the following key series by pressing M-RET within the first few characters: {C-h h b p M-> <[td]>: RET} From then on, you can jump to your todos with: {C-h h g a td RET} Or bind the global button activation command, hui:gbut-act, to a key of your choice for even faster access to all of your global buttons. Let's create a global button that counts the lines in the current buffer and displays the count in the minibuffer. Press the Action Key on the first line of this key series to create the global button named "line-count": {C-h h g c line-count RET eval-elisp RET (message "Lines in %s = %s" (buffer-name) (count-lines (point-min) (point-max))) RET} Then activate it with {C-h h g a line-count RET}. Try it out in different buffers. To avoid embedding such code in the button itself, just define a function in your Emacs initialization file and then activate that: (defun line-count () (interactive) (message "Lines in %s = %s" (buffer-name) (count-lines (point-min) (point-max)))) Then button creation would be: {C-h h g c line-count RET eval-elisp RET (line-count) RET} and activation would be the same as above. Defining a link to a file section is even easier, say to the section below here: {C-h h g c smk RET link-to-file RET "DEMO#Smart Mouse Keys" RET} Then from anywhere: {C-h h g a smk RET} will activate it. * Smart Mouse Keys If you use Emacs with mouse support under the macOS window system, the X Window System or MS Windows, Hyperbole automatically configures your mouse keys for use as Smart Keys and provides additional display-oriented operations as demonstrated here. See the Hyperbole menu item, Doc/SmartKeys {C-h h d s}, for a summary of all Smart Key operations. For extensive details on Smart Key operation, see the Hyperbole manual section, "(hyperbole)Smart Key Reference". If you ever want to disable Hyperbole key and mouse bindings, simply toggle Hyperbole minor mode off with {M-x hyperbole-mode RET}. Alternatively, you may select a key and bind it as part of any setting of `hyperbole-init-hook' within your personal .emacs file. For example: (add-hook 'hyperbole-init-hook (lambda () (global-set-key 'hyperbole-mode))) ** Thing Selection Hyperbole has some radically cool ways to select, copy and move regions of structured text or source code that we call `things'. You can copy or move things between buffers with a single mouse drag or two key presses. A great deal of smarts are built-in so that it does the right thing most of the time. Things are structured entities that Hyperbole can select and manipulate. These include: delimited pairs of (), {}, <>, [] and quote marks, source code functions, source code comments and matching tag pairs in HTML and SGML modes. Delimited things are those things that contain a selectable delimiter such as an opening parenthesis. The best way to mark a delimited thing is to move your cursor to the starting delimiter of the thing and then press the Action Key. Typically, you will see the thing highlight. You can then operate upon it as you would any Emacs region. An Action Key press on the start of an HTML or SGML tag pair marks the entire region span of the pair. If you use the Assist Key instead, it will mark and kill (delete) the thing. Even better are Smart Mouse Key drags which let you copy or move delimited things in one operation without even highlighting them. To copy, simply drag with the Action Key from a thing's opening delimiter and release somewhere outside of the thing, either within the same window or within another window. The thing will be copied to the point of release. If you want to move a thing, simply perform the same drag but with the Assist Mouse Key. Ensure that you do not move any explicit buttons from one buffer to another as that does not work. Try out some of these operations in HTML or source code files to see how they can speed your editing. Hyperbole also binds two convenience keys for working with things. {C-c RET} selects bigger and bigger syntactic regions with each successive use. Double or triple clicks of the Selection Key (left mouse key) do the same thing. The first press selects a region based upon the character at point. For example, with point over an opening or closing grouping character, such as { or }, the whole grouping is selected, e.g. a C function. When on an _ or - within a programming language variable name, the whole name is selected. The type of selection is displayed in the minibuffer as feedback. When using a language based mainly on indenting, like Bourne shell, a double click on the first alpha character of a line, such as an if statement, selects the whole statement. Use {C-g} to unmark the region when done. The second convenience key is bound only in HTML/web mode. {C-c .} jumps between the opening and closing tag of a pair. It moves point to the start of the tag paired with the closest tag that point is within or which it precedes. A second press moves point to the matching tag of the pair, allowing you to quickly jump back and forth between opening and closing tags. ** Context-sensitive Help Since the Smart Keys perform different operations in different contexts, it is important to have context-sensitive help available. The earlier section on Help Buffers explained how to display such help from the keyboard. The same help can be displayed using the mouse by depressing the Smart Key for which you want help, performing any action necessary to register a context, such as a drag motion, and then pressing the other Smart Key and releasing both. Here is an example. Depress the Action Mouse Key somewhere within this paragraph and while holding it down, depress the Assist Mouse Key. Then release the keys in any order and the help display will pop up. It explains the context in which the Action Mouse Key was pressed and what it does in that context. Try it. Basically, you just depress the Smart Mouse Key you want help for and while holding it down, depress the other Smart Mouse Key to get help. If you use the mouse a lot, this is a great key combination to master as it will let you explore the many different contextual actions that Hyperbole offers without having to trigger any of them. ** Creating and Deleting Windows Horizontal and vertical drags of the Smart Mouse Keys are used to split and delete Emacs windows. An Action Mouse Key horizontal drag of five or more characters in either direction within a single window creates a new window by splitting the current window into two windows, one on top of the other. An Action Mouse Key vertical drag in either direction splits the current window into two side-by-side windows. A horizontal or vertical drag of the Assist Mouse Key within a single window, deletes that window. Let's try these. You need only move your mouse pointer a few characters to register a drag. First, split this window with an Action Key horizontal drag. Then click the Assist Key on the buffer name in the modeline of one of the windows to change the buffer that it displays, so you can tell the windows apart. Then delete either one of the windows with a horizontal drag of the Assist Key within the window. If you split windows many times and then delete a number of the windows, you'll be left with windows of differing heights. Use {C-x +} to re-balance the sizes of the remaining windows, so they are fairly even. Now try a side-by-side window split. Drag vertically with the Action Key by three or more lines to split the window. Again, change the buffer of one of the windows. Then use a vertical Assist Key drag within either one of the side-by-side windows to delete it. ** Resizing Windows You can easily resize Emacs windows by dragging their window separators (modelines or vertical side lines) within a frame. Simply depress either Smart Key on a modeline or near a window side, hold it down while you drag to a new location and then release. The window separator will move to the location of release. Basically, just drag the window separator to where you want it. Nowadays a better version of Emacs window resizing exists on the left mouse key. Drags from a blank area of a modeline show visible feedback as the window is resized. Did you follow all that? Let's try it to be sure. First, you need at least two windows, so create a new one with the drag techniques you just learned. Now drag with either Smart Key from the shared window edge to a new location. See how both windows change size? For side-by-side windows, you drag from just to the left of any window border controls and drag within this same window. Try to drag the bottom modeline. You see that you can't; you would have to resize the frame to move the bottom up. ** Moving Frames Drags of either Smart Key from a bottommost modeline can be configured to drag Emacs frames to new locations on screen. See "(hyperbole)Moving Frames" for how to configure this behavior. ** Dragging Buffers, Windows and Items *** Swapping Buffers Swapping buffer locations is quick and easy with Hyperbole. Simply drag from one window to another with the Assist Key (not the Action Key). Split the current window into two, one above the other. Drag the upper modeline so that one window is clearly bigger than the other. Now switch to another buffer in one of the windows. Then depress your Assist (not Action) Mouse Key within one window, drag to the other window and release the key. Boom, the buffers are swapped. This works across frames as well. If you have just two windows in an Emacs frame, you can swap their buffers from the keyboard. Use this Hyperbole minibuffer menu key sequence to swap the buffers and quit from the Hyperbole minibuffer menu: {C-h h s w ~ Q}. Similarly, if you have two single window frames, you can swap buffers between them with {C-h h s f ~ Q}. *** Displaying Buffers What if you want to display the same buffer in another window and not swap buffers? Depress the Action Key in the open area of the modeline of the source window and drag to the text area of the destination window. Voila, the buffer appears in the new location as well as the old one. If you want a new window where you release (so the original destination window's buffer stays onscreen), just drag to a window's modeline; that window will be split before the buffer is displayed. *** Displaying Items via Drags and Moving Buffers You can do the same thing with items in dired, buffer menu and ibuffer menu listing buffers as well as with Hyperbole button referents. Drag with the Action Mouse Key from the item and the selected item/referent will be displayed in the Emacs window in which you release. To display the last item you want, press the Action Key on it and it will display within the listing window itself. (If you use the Treemacs file viewer package, item dragging works there as well). Under the MacOS window manager, you can also drag outside of an Emacs frame and the item will be displayed in a newly created and selected frame. So now you can rapidly put a bunch of buffers and files on your screen wherever you like. Typically, a brief visual pulse is shown first at the source item and then in the destination window, to help you see that the transfer has been made. An Assist Key Drag will move the item list buffer to the destination (swapping buffers), just as it does with other buffers. Practice these drags as they will prove very beneficial across time. For even faster keyboard-based drag emulation, use the Emacs package 'ace-window' (see "(hyperbole)Keyboard Drags" for setup). Once this is configured and the suggested M-o key binding is made, the leftmost character or two of each window's modeline will show the to type to use that window as the drag destination. Then whenever point is on an item you want displayed in another window, use M-o i to display it there and select the window. If you want to display multiple items in different windows, instead use the M-o t key sequence to @emph{throw} each item to a different window, without changing the selected window. To replace the selected window's buffer with that of another window, use M-o r . To instead swap the selected window's buffer with that of another window, use M-o m . Try these commands out and they will speed your work. You can also throw the active (highlighted) region of text to another window. Simply activate a region and then use M-o t just like before. If you don't use region highlighting, i.e. transient-mark-mode, then use C-u M-o t for the same effect. The buffer in the target window must differ from the one in the source window. With no region active, this command throws the source buffer to the target window. *** Cloning Windows To clone a window with its buffer to a new frame, simply drag the Action Mouse Key from the window to outside of Emacs and release the key. A new frame will be created, selected and sized according to the original window. Do the same thing with the Assist Mouse Key and the original window will be deleted as well, unless it is the only window in that frame. Create a few windows and try these actions. ** Window Configuration Drags A window configuration consists of the set of windows within a single Emacs frame. This includes their locations, buffers, and scrolled positions of their buffers. Hyperbole allows you to save and restore window configurations with simple diagonal mouse drags within a single window. A diagonal drag in any direction of the Action Key saves the current window configuration to a ring of window configurations, just like the Emacs text kill ring. (See "(Emacs)Kill Ring".) Each diagonal drag in any direction of the Assist Key restores a prior saved window configuration from the ring. Window configurations are restored in reverse order of the way they were saved. Since a ring is circular, after the oldest element is restored, the newest element will again be restored and so on. If these operations are unclear to you, just forget about them and move on. They are not necessary to enjoy the rest of Hyperbole. Otherwise, give them a try by creating various window configurations and then saving and restoring them. ** Modeline Mouse Clicks Smart Mouse Key clicks on window modelines are treated specially by Hyperbole. They are broken up into separate regions, each with their own Smart Mouse Key operations. The regions are: the left edge, the buffer ID, the blank middle portion (the non-edge part of the modeline), and the right edge. The edge regions are the left first character and the rightmost three characters of the modeline, by default. *** Switching to Another Buffer An Action Key click in the left edge of a modeline buries the current buffer, i.e. puts it on the bottom of the buffer list and removes it from view, if it is not the only available buffer. An Assist Key click in the left edge of a modeline unburies the bottom buffer. Repeated clicks of either key allow you to cycle through buffers to get to the one you want. Try this out. A similar thing can be accomplished by using the left mouse key and the Assist Mouse Key on the modeline buffer name if you need a wider space as a target. *** Running Dired on the Current Directory An Action Key click on the modeline buffer name runs dired on the current directory. An Action key click on an item in the dired buffer, displays the item. An Action Key click on part of the directory name in the first line of the dired buffer runs dired on the ancestor directory given by the text to the left of the click location. A click at the end of the first line quits the dired session. *** Displaying Documentation An Action Key click in the right edge of a modeline displays the Info manual browsing system, see "(info)". Once in Info, you can click with your Action Key to follow menu items, cross references, or to jump to Info nodes referenced within the top header line of a node. Try browsing a bit and while in Info, display context-sensitive help for both the Action and Assist Keys to see all that they can do. If you click again with the Action Key on the right edge of the window displaying Info, it will hide the Info buffer. Thus, it works as a toggle to display or to hide the Info buffer. Isn't that easy? A click of the Assist Key at the right edge of a modeline toggles between display and removal of the Smart Key operation summary. To remove the summary, you must click on the modeline of the window displaying the summary. *** Buffer Menu and Screen Control An Action Key click in the blank center portion of a modeline displays a buffer menu, a summary of available buffers. An Action Key click on any buffer menu line then displays that buffer and closes the buffer menu. If you want to display several buffers, first create some new windows, then display the buffer menu and drag from each buffer name to the window in which you want it displayed. This works across frames and also works in ibuffer and dired modes too! Try it now. Alternatively, you may display the buffer menu, use its {m} command to mark buffers and then use the {@} command to display the marked buffers in a grid of popup windows whose number of rows and columns you specify at the prompt or via a prefix argument. This also works in ibuffer-menu and dired modes. An Assist Key click in the blank center portion of a modeline pops up a menu of convenient screen commands that lets you select buffers grouped by major mode, use HyControl, or jump to specific windows, window configurations or frames. See "(hyperbole)action-key-modeline-function" for how to adjust this behavior. * Epilog We hope you have enjoyed this introduction to Hyperbole. It can be your ever-ready sidekick in your daily knowledge work. Explore the Hyperbole menus to learn more interactively. For reference, the Hyperbole Manual, has extensive detail about the many things that Hyperbole does when you are ready to dive deeper. Read it online with the GNU Info reader at "(hyperbole)Top". * THE END