branch: scratch/hyperbole-lexbind commit d56c8c07764724ece380d2d3215bd0f743bbd1b1 Author: Bob Weiner <r...@gnu.org> Commit: Bob Weiner <r...@gnu.org>
Most changes for 7.0.3a release --- Changes | 16 ++++- HY-NEWS | 8 +-- README.md.html | 2 +- hargs.el | 2 + hbut.el | 71 ++++++++++++++++++---- hui-menu.el | 2 +- hui-mini.el | 4 +- hui.el | 27 +++++++-- man/hyperbole.html | 160 ++++++++++++++++++++++++++++---------------------- man/hyperbole.info | Bin 511871 -> 512812 bytes man/hyperbole.pdf | Bin 1266697 -> 1270678 bytes man/hyperbole.texi | 168 ++++++++++++++++++++++++++++------------------------- 12 files changed, 287 insertions(+), 173 deletions(-) diff --git a/Changes b/Changes index d2b9934..fcf7199 100644 --- a/Changes +++ b/Changes @@ -1,3 +1,17 @@ +2019-07-23 Bob Weiner <r...@gnu.org> + +* man/hyperbole.texi (Referent Display): Rewrote and added details on how the 4 types + of referents are processed. + +2019-07-22 Bob Weiner <r...@gnu.org> + +* hargs.el (hargs:at-p): Added hbut support (ebut or ibut). + +* hui.el (hui:hbut-act): Generalized to handle both explicit and labeled implicit buttons. + (hui:ebut-act): Added and replaced use of hui:hbut-act in menus. + +* hbut.el (ebut:to, gbut:to, hbut:get): Added. + 2019-07-21 Bob Weiner <r...@gnu.org> * man/hyperbole.texi (Implicit Button Types): Split off type descriptions to this new @@ -380,7 +394,7 @@ V7.0.3a changes ^^^^: * man/hyperbole.texi (Keyboard Drags): Added doc of {M-o r <window-id>}, replace selected window's buffer with that of another window. -* man/hyperbole.texi (Keyboard Drags): +* man/hyperbole.texi (Keyboard Drags): DEMO (Displaying File and Buffer Items and Moving Buffers): Added doc of {M-o m <window-id>}, swap selected window's buffer with that of <window-id>'s. diff --git a/HY-NEWS b/HY-NEWS index 8bd1f18..1c966c2 100644 --- a/HY-NEWS +++ b/HY-NEWS @@ -75,11 +75,11 @@ to allow selection of labeled Hyperbole buttons in currrent buffer by name. - gbut:get, hbut:map, ibut:label-map, ibut:key-src, ibut:key-to-label, ibut:label-to-key, - ibut:summarize, ibut:label-start, ibut:label-end, ibut:label-p, ibut:get, + hui:ebut-act, ibut:summarize, ibut:label-start, ibut:label-end, ibut:label-p, ibut:get, hui:ibut-label-create, hui:ibut-rename, hui:ibut-message, ibut:alist, ibut:list, ibut:map, - ibut:next-occurrence, ibut:label-regexp, gbut:ibut-key-list, ibut:to: Added to support - ibut:label-separator, hbut:label-regexp, ibut:rename: Added to support labeled implicit - buttons too. + ibut:next-occurrence, ibut:label-regexp, gbut:ibut-key-list, ebut:to, gbut:to, ibut:to, + ibut:label-separator, hbut:label-regexp, ibut:rename, hbut:get: Added to support labeled + implicit buttons and links to buttons. hbut:label-p: Updated to handle implicit button labels. ibut:label-separator-regexp, hbut:outside-comment-p: Added. diff --git a/README.md.html b/README.md.html index 0ed4301..b183d0f 100644 --- a/README.md.html +++ b/README.md.html @@ -1,5 +1,5 @@ <h1> -<a id="user-content-gnu-hyperbole-703---the-everyday-hypertextual-information-manager" class="anchor" href="#gnu-hyperbole-703---the-everyday-hypertextual-information-manager" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>GNU Hyperbole 7.0.3 - The Everyday Hypertextual Information Manager</h1> +<a id="user-content-gnu-hyperbole-703a---the-everyday-hypertextual-information-manager" class="anchor" href="#gnu-hyperbole-703a---the-everyday-hypertextual-information-manager" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>GNU Hyperbole 7.0.3a - The Everyday Hypertextual Information Manager</h1> <p>[Say thanks if you like Hyperbole.(<a href="https://saythanks.io/to/rswgnu" rel="nofollow">https://saythanks.io/to/rswgnu</a>)]</p> <p><strong>Table of Contents</strong></p> diff --git a/hargs.el b/hargs.el index 5abccfb..39d1635 100644 --- a/hargs.el +++ b/hargs.el @@ -324,6 +324,8 @@ Handles all of the interactive argument types that `hargs:iform-read' does." ((eq hargs:reading-p 'gbut) (when (eq (current-buffer) (get-file-buffer gbut:file)) (hbut:label-p 'as-label))) + ((eq hargs:reading-p 'hbut) (or (ebut:label-p 'as-label) + (ibut:label-p 'as-label))) ((hbut:label-p) nil) ((eq hargs:reading-p 'file) (cond ((derived-mode-p 'dired-mode) diff --git a/hbut.el b/hbut.el index ce5c78a..cb4816b 100644 --- a/hbut.el +++ b/hbut.el @@ -434,6 +434,32 @@ enables partial matches." (if kill-buf (kill-buffer currbuf))))))))))) total)) +(defun ebut:to (lbl-key) + "Finds the nearest explicit button with LBL-KEY (a label or label key) within the visible portion of the current buffer. +Leaves point inside the button label. Returns the symbol for the button, else nil." + ;; Handle a label given rather than a label key + (if (string-match-p "\\s-" lbl-key) + (setq lbl-key (ebut:label-to-key lbl-key))) + (let ((regexp (hbut:label-regexp lbl-key t)) + pos + found) + (save-excursion + ;; Since point might be in the middle of the matching button, + ;; move to the start of line to ensure don't miss it when + ;; searching forward. + (forward-line 0) + ;; re-search forward + (while (and (not found) (re-search-forward regexp nil t)) + (setq pos (match-beginning 0) + found (equal (ebut:label-p nil nil nil nil t) lbl-key))) + ;; re-search backward + (while (and (not found) (re-search-backward regexp nil t)) + (setq pos (match-beginning 0) + found (equal (ebut:label-p nil nil nil nil t) lbl-key)))) + (when found + (goto-char pos) + (ebut:at-p)))) + ;;; ------------------------------------------------------------------------ (defun ebut:delimit (start end instance-str) "Delimits button label spanning region START to END in current buffer. @@ -526,6 +552,23 @@ the button that point is within or nil." "Returns list of global button labels." (mapcar 'hbut:key-to-label (gbut:key-list))) + +(defun gbut:to (lbl-key) + "Finds the global button with LBL-KEY (a label or label key) within the visible portion of the global button file. +Leaves point inside the button label, if it has one. +Returns the symbol for the button, else nil." + (when (file-readable-p gbut:file) + (let ((obuf (current-buffer)) + (opoint (point)) + found) + (set-buffer (find-file-noselect gbut:file)) + (setq found (or (ebut:to lbl-key) (ibut:to lbl-key))) + (if found + (hpath:display-buffer (current-buffer) 'this-window) + (set-buffer obuf) + (goto-char opoint)) + found))) + ;;; ------------------------------------------------------------------------ (defun gbut:key-list () "Returns list of global button label keys." @@ -772,9 +815,20 @@ Ignores email-related buffers." hbut:fill-prefix-regexps)) label) +(defun hbut:get (&optional lbl-key buffer key-src) + "Returns explicit or labeled implicit Hyperbole button symbol given by LBL-KEY and BUFFER. +KEY-SRC is given when retrieving global buttons and is the full source pathname. + +Returns a symbol which references the button. + +All arguments are optional. When none are given, returns a +symbol for the button or button label that point is within or +nil. BUFFER defaults to the current buffer." + (or (ebut:get lbl-key buffer key-src) (ibut:get lbl-key buffer key-src))) + (defun hbut:is-p (object) "Returns non-nil if object denotes a Hyperbole button." - (and (symbolp object) (hattr:get object 'categ))) + (and (symbolp object) (hattr:get object 'categ))) (defun hbut:key-src (&optional full) "Returns key source (usually unqualified) for current Hyperbole button. @@ -888,10 +942,8 @@ button delimiters. With POS-FLAG non-nil, returns list of label-or-key, but-start-position, but-end-position. Positions include delimiters. With TWO-LINES-FLAG non-nil, constrains label search to two lines." - (if (and start-delim end-delim) - (ebut:label-p as-label start-delim end-delim pos-flag two-lines-flag) - (or (ebut:label-p as-label start-delim end-delim pos-flag two-lines-flag) - (ibut:label-p as-label start-delim end-delim pos-flag two-lines-flag)))) + (or (ebut:label-p as-label start-delim end-delim pos-flag two-lines-flag) + (ibut:label-p as-label start-delim end-delim pos-flag two-lines-flag))) (defun hbut:label-regexp (lbl-key &optional no-delim start-delim end-delim) "Unnormalizes LBL-KEY. Returns regular expr matching delimited button label. @@ -1363,14 +1415,13 @@ move to the first occurrence of the button." (defun ibut:to (lbl-key) "Finds the nearest implicit button with LBL-KEY (a label or label key) within the visible portion of the current buffer. Leaves point inside the button text or its optional label, if it has one. -Returns the button symbol for it, else nil." +Returns the symbol for the button, else nil." ;; Handle a label given rather than a label key (if (string-match-p "\\s-" lbl-key) (setq lbl-key (ibut:label-to-key lbl-key))) (let ((regexp (hbut:label-regexp lbl-key t)) pos - found - reverse) + found) (save-excursion ;; Since point might be in the middle of the matching button, ;; move to the start of line to ensure don't miss it when @@ -1379,11 +1430,11 @@ Returns the button symbol for it, else nil." ;; re-search forward (while (and (not found) (re-search-forward regexp nil t)) (setq pos (match-beginning 0) - found (equal (ibut:at-p t) lbl-key))) + found (equal (ibut:label-p nil nil nil nil t) lbl-key))) ;; re-search backward (while (and (not found) (re-search-backward regexp nil t)) (setq pos (match-beginning 0) - found (equal (ibut:at-p t) lbl-key)))) + found (equal (ibut:label-p nil nil nil nil t) lbl-key)))) (when found (goto-char pos) (ibut:at-p)))) diff --git a/hui-menu.el b/hui-menu.el index efc2daa..d8335fb 100644 --- a/hui-menu.el +++ b/hui-menu.el @@ -358,7 +358,7 @@ REBUILD-FLAG is non-nil, in which case the menu is rebuilt." )) '("Explicit-Button" :filter hui-menu-explicit-buttons - ["Activate" hui:hbut-act t] + ["Activate" hui:ebut-act t] ["Create" hui:ebut-create t] ["Delete" hui:ebut-delete t] ["Edit" hui:ebut-modify t] diff --git a/hui-mini.el b/hui-mini.el index dfaf7d7..70b626a 100644 --- a/hui-mini.el +++ b/hui-mini.el @@ -527,8 +527,8 @@ constructs. If not given, the top-level Hyperbole menu is used." )) '(ebut . (("EButton>") - ("Act" hui:hbut-act - "Activates button at point or prompts for explicit button.") + ("Act" hui:ebut-act + "Activates explicit button at point or prompts for explicit button to activate.") ("Create" hui:ebut-create) ("Delete" hui:ebut-delete) ("Edit" hui:ebut-modify "Modifies any desired button attributes.") diff --git a/hui.el b/hui.el index 4cebff3..12f2680 100644 --- a/hui.el +++ b/hui.el @@ -65,6 +65,25 @@ (message "{%s} now runs `%s'; prior {%s} binding removed" new-key-text cmd old-key-text)) (message "{%s} now runs `%s'" new-key-text cmd)))) +(defun hui:ebut-act (&optional but) + "Executes action for optional explicit button symbol BUT in current buffer. +Default is the current button." + (interactive + (let ((but (ebut:at-p)) (lst)) + (list + (cond (but) + ((setq lst (ebut:alist)) + (ebut:get (ebut:label-to-key + (hargs:read-match "Button to execute: " lst nil t + (ebut:label-p 'as-label) 'ebut)))) + (t (hypb:error "(ebut-act): No explicit buttons in buffer.")))))) + (cond ((and (called-interactively-p 'interactive) (null but)) + (hypb:error "(ebut-act): No current explicit button to activate.")) + ((not (hbut:is-p but)) + (hypb:error "(ebut-act): Explicit button is invalid; it has no attributes.")) + (t (or but (setq but 'hbut:current)) + (hui:but-flash) (hbut:act but)))) + (defun hui:ebut-create (&optional start end) "Creates an explicit Hyperbole button starting from label between optional START and END. Indicates by delimiting and adding any necessary instance number of the button @@ -365,11 +384,11 @@ Default is the current button." (let ((but (hbut:at-p)) (lst)) (list (cond (but) - ((setq lst (ebut:alist)) - (ebut:get (ebut:label-to-key + ((setq lst (nconc (ebut:alist) (ibut:alist))) + (hbut:get (hbut:label-to-key (hargs:read-match "Button to execute: " lst nil t - (ebut:label-p 'as-label) 'ebut)))) - (t (hypb:error "(hbut-act): No explicit buttons in buffer.")))))) + (hbut:label-p 'as-label) 'hbut)))) + (t (hypb:error "(hbut-act): No labeled buttons in buffer.")))))) (cond ((and (called-interactively-p 'interactive) (null but)) (hypb:error "(hbut-act): No current button to activate.")) ((not (hbut:is-p but)) diff --git a/man/hyperbole.html b/man/hyperbole.html index e7110c6..0fb35b5 100644 --- a/man/hyperbole.html +++ b/man/hyperbole.html @@ -841,16 +841,17 @@ Next: <a href="#Motivation" accesskey="n" rel="next">Motivation</a>, Previous: < you prefer a simpler, more interactive introduction to Hyperbole, the <samp>DEMO</samp> file included in the Hyperbole distribution demonstrates many of Hyperbole’s standard facilities without the need to read through -this reference manual. It is a good way to rapidly understand some of what -Hyperbole can do for you. Once Hyperbole is installed, (see <a href="#Setup">Setup</a>), -you can access the DEMO with the key sequence <kbd>{C-h h d d}</kbd>. +this reference manual. The DEMO is a good way to rapidly understand some +of what Hyperbole can do for you. Once Hyperbole is installed, +(see <a href="#Setup">Setup</a>), you can access the DEMO with the key sequence <kbd>{C-h h +d d}</kbd>. </p> <p>See <a href="#Glossary">Glossary</a>, for definitions of Hyperbole terms. In some cases, -terms are not precisely defined within the body of this manual since -they are defined within the glossary. Be sure to reference the -glossary if a term is unclear to you. Although you need not have a keen -understanding of all of these terms, a quick scan of the glossary should -help throughout Hyperbole use. +terms are not precisely defined within the body of this manual since they +are defined within the glossary. Be sure to reference the glossary if a +term is unclear to you. Although you need not have a keen understanding of +all of these terms, a quick scan of the glossary helps throughout Hyperbole +use. </p> <p>See <a href="#Setup">Setup</a>, for explanations of how to obtain, install, configure and load Hyperbole for use. This appendix includes information on @@ -926,19 +927,19 @@ its use as the prime means of organizing and interlinking the constant flows of daily information. </p> <p>GNU Hyperbole takes a distinctly different approach. It has its own -hypertext technology that can interface perfectly with web links but -which are much easier to create (simply drag from the source to the -destination of a link to create a new hyperlink). Hyperbole -hyperbuttons can link not only to static information but can perform -arbitrary actions through the use of button types written in a single, -highly interactive language, Emacs Lisp. Hyperbole adds all of this -power to your written documents, e-mail, news articles, contact -management, outlines, directory listings, and much more. Hyperbole -works well with the very latest versions of GNU Emacs. +hypertext technology that can interface perfectly with web links but which +are much easier to create (simply drag from the source to the destination +of a link to create a new hyperlink). Hyperbole hyperbuttons can link not +only to static information but can perform arbitrary actions (through the +use of button types written in a single, highly interactive language, Emacs +Lisp). Hyperbole adds all of this power to your written documents, e-mail, +news articles, contact management, outlines, directory listings, and much +more. Hyperbole works well with the very latest versions of GNU Emacs +across every editing and viewing mode in Emacs. </p> -<p>Unlock the power of GNU Hyperbole to make your information work for -you. One system. One language. One manual. One solution. Learn GNU -Hyperbole and start moving further, faster. +<p>Unlock the power of GNU Hyperbole to make your information work for you. +One system. One language. One manual. One solution. Learn Hyperbole and +start moving further, faster. </p> <hr> <a name="Hyperbole-Overview"></a> @@ -955,7 +956,7 @@ Next: <a href="#Mail-Lists" accesskey="n" rel="next">Mail Lists</a>, Previous: < <a name="index-Emacs-Lisp"></a> <a name="index-Emacs"></a> <p>GNU Hyperbole (pronounced Ga-new Hi-per-bo-lee), or just Hyperbole, is -an efficient and programmable hypertextual information management +an efficient, programmable hypertextual information management system. It is intended for everyday work on any GNU Emacs platform. Hyperbole allows hypertext buttons to be embedded within unstructured and structured files, mail messages and news articles. It offers @@ -969,9 +970,12 @@ archives, and the World-Wide Web (WWW). <dt><em>Buttons and Smart Keys</em></dt> <dd><p>Hyperbole hyperlink and other kinds of buttons (explicit buttons) may be added to documents with a simple drag between windows, no markup language -needed. Implicit buttons are patterns automatically recognized within text -that perform actions, e.g. bug#24568 displays the bug status information -for that bug number. See <a href="#Buttons">Buttons</a>. +needed. Implicit buttons are patterns automatically recognized within +existing text that perform actions, e.g. bug#24568 displays the bug status +information for that bug number, without the need for any additional +markup. Global buttons are buttons that are activated by name from +anywhere within Emacs. +See <a href="#Buttons">Buttons</a>. </p> <p>Buttons are accessed by clicking on them or referenced by name (global buttons), so they can be activated regardless of what is on screen. @@ -2632,7 +2636,7 @@ as {^x^b} will not be recognized. </dd> <dt><code>dir-summary</code></dt> <dd><p>Detects filename buttons in files named "MANIFEST" or "DIR". -Displays selected files. Each file name must be at the beginning of the +Displays selected files. Each filename must be at the beginning of the line and must be followed by one or more spaces and then another non-space, non-parenthesis, non-brace character. </p> @@ -2642,7 +2646,7 @@ non-space, non-parenthesis, non-brace character. </dd> <dt><code>text-toc</code></dt> <dd><p>Jumps to the text file section referenced by a table of contents entry -at point. The file name of the current buffer must contain +at point. The filename of the current buffer must contain <samp>README</samp> and there must be a ‘Table of Contents’ or ‘Contents’ label on a line by itself (it may begin with an asterisk), preceding the table of contents. Each toc entry must begin with some whitespace @@ -3470,7 +3474,7 @@ Info Index Item link-to-Info-index-item Info Node link-to-Info-node Mail Reader Message link-to-mail Directory Name link-to-directory -File Name link-to-file +Filename link-to-file Koutline Cell link-to-kcell Outline Heading link-to-string-match Buffer attached to File link-to-file @@ -5332,8 +5336,8 @@ Next: <a href="#Exporting" accesskey="n" rel="next">Exporting</a>, Previous: <a <a name="index-outline_002c-foreign-file"></a> <p>The paragraphs of another buffer or file may be inserted into a koutline as a set of cells by using the <kbd>{C-x i}</kbd> command. When prompted, -you may use a buffer name or file name from which to insert; -completion is provided for file names only. +you may use a buffer name or filename from which to insert; +completion is provided for filenames only. </p> <a name="index-koutliner_002c-C_002du-C_002dx-i"></a> <p>The elements from the original buffer are converted into kcells and @@ -5365,7 +5369,7 @@ entire file into the current cell following point. files. You can import a file into an existing koutline, following the tree at point, or can create a new koutline from the imported file contents. <kbd>{M-x kimport:file <span class="key">RET</span>}</kbd> selects the -importation type based on the buffer or file name suffix of the file to +importation type based on the buffer or filename suffix of the file to import. </p> <a name="index-kotl_002dmode-1"></a> @@ -5426,7 +5430,7 @@ World-Wide Web. </p> <p><kbd>{M-x kexport:html <span class="key">RET</span>}</kbd> prompts for the koutline buffer or file to export, the HTML file or buffer to which to output, and the -title to use for the HTML file. Completion of file names is provided. +title to use for the HTML file. Completion of filenames is provided. The conversion will then be done and the output file or buffer will be written; the output file will not be displayed. </p> @@ -6292,7 +6296,7 @@ list. In general, you should leave your personal rolo file as the first entry in the list, since this is the only file to which the Add command on the rolo menu adds entries. </p> -<p>Hyperbole releases earlier than 4.17 used a different file name for the +<p>Hyperbole releases earlier than 4.17 used a different filename for the personal rolo. If such a file exists, you will be prompted to rename it whenever the HyRolo system is loaded. </p> @@ -6861,7 +6865,7 @@ identifier or a permanent idstamp. <a name="index-argument_002c-mail-message"></a> </dd> <dt><code>+M</code></dt> -<dd><p>Prompts for a mail message date and the file name in which it resides. +<dd><p>Prompts for a mail message date and the filename in which it resides. The mail parameters prompted for by this character code may change in the future. </p> @@ -7459,7 +7463,20 @@ to documents created and managed by tools other than Hyperbole, for example, programming documentation. <b>Ibtype</b> is a synonym for implicit button type. See also <b>system encapsulation</b>. </p> - +<a name="index-InfoDock"></a> +</dd> +<dt><b>InfoDock</b></dt> +<dd><p>InfoDock was an integrated productivity toolset for software engineers +and knowledge workers built atop XEmacs; it is no longer maintained or +updated. An older version from 1999 may be found at +infodock.sf.net. +</p> +<p>InfoDock has much of the power of GNU Emacs, but with an +easier to use and more comprehensive menu-based user interface. Most +objections people raise to using emacs have already been addressed in +InfoDock. InfoDock was meant for people who wanted a complete, +pre-customized environment in one package. +</p> </dd> <dt><b>Instance Number</b></dt> <dd><p>A colon prefaced number appended to the label of a newly created button @@ -7724,12 +7741,11 @@ Next: <a href="#Invocation" accesskey="n" rel="next">Invocation</a>, Previous: < installed by using the Emacs Package Manager. If you are not familiar with it, see <a href="http://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Packages">Packages</a> in <cite>the GNU Emacs Manual</cite>. </p> -<p>If you have Hyperbole 5.10 or higher installed and simply want to -upgrade it, invoke the Emacs Package Manager with <kbd>{M-x -list-packages <span class="key">RET</span>}</kbd>, then use the <kbd>{U}</kbd> key followed by -the <kbd>{x}</kbd> key to upgrade all out-of-date packages, Hyperbole among -them. Then skip the text below and move on to the next -section, see <a href="#Invocation">Invocation</a>. +<p>If you have Hyperbole installed and simply want to upgrade it, invoke +the Emacs Package Manager with <kbd>{M-x list-packages <span class="key">RET</span>}</kbd>, +then use the <kbd>{U}</kbd> key followed by the <kbd>{x}</kbd> key to upgrade all +out-of-date packages, Hyperbole among them. Then skip the text below +and move on to the next section, see <a href="#Invocation">Invocation</a>. </p> <p>Otherwise, to download and install the Hyperbole package, you should add several lines to your personal Emacs initialization file, <samp>~/.emacs</samp>. @@ -7926,7 +7942,8 @@ Next: <a href="#Internal-Viewers" accesskey="n" rel="next">Internal Viewers</a>, <p>Hyperbole lets you control where link referents are displayed. It also permits setting a specific Emacs function or external program to display them. There are four categories of referents, each with -its own display setting, listed in decreasing order of priority. +its own display setting, listed in decreasing order of priority. All +of these variables are defined within <samp>hpath.el</samp>. </p> <div class="example"> <pre class="example">Referent Category Variable Setting @@ -7961,21 +7978,23 @@ Next: <a href="#External-Viewers" accesskey="n" rel="next">External Viewers</a>, <a name="index-hpath_003ainternal_002ddisplay_002dalist-1"></a> <a name="index-internal-standard-display"></a> <a name="index-hpath_003adisplay_002dwhere-1"></a> -<p>When given a file name, Hyperbole will by default display the file for -editing within an Emacs buffer. The <code>hpath:internal-display-alist</code> -variable can be used to specify file name patterns, such as matching -suffixes, which will invoke a special Emacs Lisp function to display -any matching files within Emacs. This can be used to format raw data -files for convenient display. -</p> -<p>This variable, <code>hpath:internal-display-alist</code> is defined in -<samp>hpath.el</samp>. Its value is an association list whose elements are -(<file-name-regular-expression> . <function-of-one-arg>) pairs. Any -path whose name matches a <file-name-regular-expression> will be -displayed by calling the associated <function-of-one-arg> with the -file name as the argument. -</p> -<p>By default, this variable handles the following types of files: +<p>When given a filename to display, Hyperbole first checks if its suffix +is matched by <code>hpath:native-image-suffixes</code>. If so and if the +function <code>image-mode</code> is defined, it uses that mode together with +the value of <code>hpath:display-where</code> to display the image within an +Emacs buffer. +</p> +<p>If no match is found, the <code>hpath:internal-display-alist</code> variable +is checked for a filename match. Its value is an association list +whose elements are (<file-name-regular-expression> +. <function-of-one-arg>) pairs. Any path whose name matches +a <file-name-regular-expression> will be displayed by calling the +associated <function-of-one-arg> with the filename as the argument. +The first regular expression that matches each filename is the one +used. This can be used to format raw data files for convenient +display. +</p> +<p>By default, this setting handles the following types of files: </p><dl compact="compact"> <dt><em>Audio Files</em></dt> <dd><p>Major audio format files are played with the <code>play-sound-file</code> command. @@ -7992,9 +8011,9 @@ available with InfoDock. <a name="index-menu_002c-Cust_002fReferents"></a> <a name="index-C_002dh-h-c-r"></a> <p>Links to standard files, those which don’t match any special referent -category, are displayed in an Emacs window specified by the -<code>hpath:display-where</code> setting. It may be changed with the Cust/Referents -<kbd>{C-h h c r}</kbd> menu. +category handled by any described earlier, are displayed in an Emacs +window specified by the <code>hpath:display-where</code> setting. It may be changed with the +Cust/Referents <kbd>{C-h h c r}</kbd> menu. </p> <p>Available options are: </p> @@ -8016,7 +8035,7 @@ category, are displayed in an Emacs window specified by the the default) </p></dd> <dt><em>• Single-Win</em></dt> -<dd><p>Display in a window of the selected frame and delete its other windows +<dd><p>Display in a window of the selected frame and delete its other windows </p></dd> </dl> @@ -8027,7 +8046,7 @@ the default) <img src="im/menu-display-referents.png" alt="Display Referents Menu"> <div class="float-caption"><p><strong>Image B.2: </strong>Display Referents Menu</p></div></div><br> -<p>See <a href="#External-Viewers">External Viewers</a>, for instructions on associating file names with +<p>See <a href="#External-Viewers">External Viewers</a>, for instructions on associating filenames with external, window-system specific viewers. </p> <hr> @@ -8049,10 +8068,10 @@ Next: <a href="#Link-Variable-Substitution" accesskey="n" rel="next">Link Variab <a name="index-external-display-1"></a> <a name="index-hpath_003aexternal_002ddisplay_002dalist"></a> -<p>If you will be using Hyperbole under a window system, -the <code>hpath:get-external-display-alist</code> function -in <samp>hpath.el</samp> supports hyperlinks that open files using external, non-Emacs -tools, e.g. a pdf reader or a vector graphic viewer. +<p>If you use Hyperbole under a window system, +the <code>hpath:get-external-display-alist</code> function in <samp>hpath.el</samp> +supports hyperlinks that open files using external, non-Emacs tools, e.g. +a pdf reader or a vector graphics viewer. </p> <p>The value returned by <code>hpath:get-external-display-alist</code> is determined based on the window system supported by the current frame and the version @@ -8062,13 +8081,13 @@ path whose name matches a <file-name-regular-expression> will be displayed using the corresponding viewer-program or the first viewer-program found on the system from a list of programs. If a <viewer-program> entry contains a ‘<samp>%s</samp>’ string, the filename to -display will be substituted at that point within the string. -Otherwise, the filename will be appended to the <viewer-program> +display is substituted at that point within the string. +Otherwise, the filename is appended to the <viewer-program> entry. Alternatively, the viewer-program may be a Lisp function that takes a single filename argument. </p> <p>The association lists used by this function are stored in variables -for each available window system: <code>hpath:external-display-alist-macos</code>, +vfor each available window system: <code>hpath:external-display-alist-macos</code>, <code>hpath:external-display-alist-mswindows</code>, and <code>hpath:external-display-alist-x</code>. Examine and modify these values to suit your needs. @@ -8185,7 +8204,7 @@ Hyperbole: <code>(hpath:find-file-urls-mode 1)</code>. <a name="index-URLs_002c-abbreviated"></a> <a name="index-Tramp-1"></a> <p>Both full URLs and abbreviated ones, like <samp>www.gnu.org</samp>, are -recognized. File name completion does not work with URLs; you +recognized. filename completion does not work with URLs; you have to type or paste in the entire URL. This feature will work only if you have the builtin Tramp Emacs Lisp package; if you don’t have Tramp, an error message will be displayed when you try to enable @@ -8841,7 +8860,7 @@ Called from a program, takes three args: START, END and COLUMN. <dt><code>kimport:insert-file <kbd>{C-x i}</kbd></code></dt> <dd><p>Insert each paragraph in IMPORT-FROM as a separate cell in the current view. Insert as sibling cells following the current cell. IMPORT-FROM may be a -buffer name or file name (file name completion is provided). +buffer name or filename (filename completion is provided). </p> <a name="index-kimport_003ainsert_002dregister"></a> </dd> @@ -13039,6 +13058,7 @@ Previous: <a href="#Function" accesskey="p" rel="prev">Function</a>, Up: <a href <tr><td></td><td valign="top"><a href="#index-Info-browsing">Info browsing</a>:</td><td> </td><td valign="top"><a href="#Smart-Key-_002d-Info-Manuals">Smart Key - Info Manuals</a></td></tr> <tr><td></td><td valign="top"><a href="#index-Info-manual">Info manual</a>:</td><td> </td><td valign="top"><a href="#Invocation">Invocation</a></td></tr> <tr><td></td><td valign="top"><a href="#index-Info-node">Info node</a>:</td><td> </td><td valign="top"><a href="#Implicit-Button-Type-Summaries">Implicit Button Type Summaries</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-InfoDock">InfoDock</a>:</td><td> </td><td valign="top"><a href="#Glossary">Glossary</a></td></tr> <tr><td></td><td valign="top"><a href="#index-initialization-file">initialization file</a>:</td><td> </td><td valign="top"><a href="#Autonumbering">Autonumbering</a></td></tr> <tr><td></td><td valign="top"><a href="#index-inserting-tabs">inserting tabs</a>:</td><td> </td><td valign="top"><a href="#Relocating-and-Copying">Relocating and Copying</a></td></tr> <tr><td></td><td valign="top"><a href="#index-insertion">insertion</a>:</td><td> </td><td valign="top"><a href="#Inserting-and-Importing">Inserting and Importing</a></td></tr> diff --git a/man/hyperbole.info b/man/hyperbole.info index f39d786..78fe934 100644 Binary files a/man/hyperbole.info and b/man/hyperbole.info differ diff --git a/man/hyperbole.pdf b/man/hyperbole.pdf index a6fdfee..8b3ec58 100644 Binary files a/man/hyperbole.pdf and b/man/hyperbole.pdf differ diff --git a/man/hyperbole.texi b/man/hyperbole.texi index 7329552..1f59b75 100644 --- a/man/hyperbole.texi +++ b/man/hyperbole.texi @@ -501,16 +501,17 @@ This is a reference manual with extensive details about Hyperbole use. If you prefer a simpler, more interactive introduction to Hyperbole, the @file{DEMO} file included in the Hyperbole distribution demonstrates many of Hyperbole's standard facilities without the need to read through -this reference manual. It is a good way to rapidly understand some of what -Hyperbole can do for you. Once Hyperbole is installed, (@pxref{Setup}), -you can access the DEMO with the key sequence @bkbd{C-h h d d}. +this reference manual. The DEMO is a good way to rapidly understand some +of what Hyperbole can do for you. Once Hyperbole is installed, +(@pxref{Setup}), you can access the DEMO with the key sequence @bkbd{C-h h +d d}. @xref{Glossary}, for definitions of Hyperbole terms. In some cases, -terms are not precisely defined within the body of this manual since -they are defined within the glossary. Be sure to reference the -glossary if a term is unclear to you. Although you need not have a keen -understanding of all of these terms, a quick scan of the glossary should -help throughout Hyperbole use. +terms are not precisely defined within the body of this manual since they +are defined within the glossary. Be sure to reference the glossary if a +term is unclear to you. Although you need not have a keen understanding of +all of these terms, a quick scan of the glossary helps throughout Hyperbole +use. @xref{Setup}, for explanations of how to obtain, install, configure and load Hyperbole for use. This appendix includes information on @@ -581,19 +582,19 @@ its use as the prime means of organizing and interlinking the constant flows of daily information. GNU Hyperbole takes a distinctly different approach. It has its own -hypertext technology that can interface perfectly with web links but -which are much easier to create (simply drag from the source to the -destination of a link to create a new hyperlink). Hyperbole -hyperbuttons can link not only to static information but can perform -arbitrary actions through the use of button types written in a single, -highly interactive language, Emacs Lisp. Hyperbole adds all of this -power to your written documents, e-mail, news articles, contact -management, outlines, directory listings, and much more. Hyperbole -works well with the very latest versions of GNU Emacs. - -Unlock the power of GNU Hyperbole to make your information work for -you. One system. One language. One manual. One solution. Learn GNU -Hyperbole and start moving further, faster. +hypertext technology that can interface perfectly with web links but which +are much easier to create (simply drag from the source to the destination +of a link to create a new hyperlink). Hyperbole hyperbuttons can link not +only to static information but can perform arbitrary actions (through the +use of button types written in a single, highly interactive language, Emacs +Lisp). Hyperbole adds all of this power to your written documents, e-mail, +news articles, contact management, outlines, directory listings, and much +more. Hyperbole works well with the very latest versions of GNU Emacs +across every editing and viewing mode in Emacs. + +Unlock the power of GNU Hyperbole to make your information work for you. +One system. One language. One manual. One solution. Learn Hyperbole and +start moving further, faster. @node Hyperbole Overview, Mail Lists, Motivation, Introduction @section Hyperbole Overview @@ -604,7 +605,7 @@ Hyperbole and start moving further, faster. @cindex Emacs Lisp @cindex Emacs GNU Hyperbole (pronounced Ga-new Hi-per-bo-lee), or just Hyperbole, is -an efficient and programmable hypertextual information management +an efficient, programmable hypertextual information management system. It is intended for everyday work on any GNU Emacs platform. Hyperbole allows hypertext buttons to be embedded within unstructured and structured files, mail messages and news articles. It offers @@ -620,9 +621,12 @@ Hyperbole consists of five parts: @item Buttons and Smart Keys Hyperbole hyperlink and other kinds of buttons (explicit buttons) may be added to documents with a simple drag between windows, no markup language -needed. Implicit buttons are patterns automatically recognized within text -that perform actions, e.g. bug#24568 displays the bug status information -for that bug number. @xref{Buttons}. +needed. Implicit buttons are patterns automatically recognized within +existing text that perform actions, e.g. bug#24568 displays the bug status +information for that bug number, without the need for any additional +markup. Global buttons are buttons that are activated by name from +anywhere within Emacs. +@xref{Buttons}. Buttons are accessed by clicking on them or referenced by name (global buttons), so they can be activated regardless of what is on screen. @@ -2032,7 +2036,7 @@ Any key sequence must be a string of one of the following: @vindex file, DIR @item dir-summary Detects filename buttons in files named "MANIFEST" or "DIR". -Displays selected files. Each file name must be at the beginning of the +Displays selected files. Each filename must be at the beginning of the line and must be followed by one or more spaces and then another non-space, non-parenthesis, non-brace character. @@ -2041,7 +2045,7 @@ non-space, non-parenthesis, non-brace character. @cindex toc implicit button type @item text-toc Jumps to the text file section referenced by a table of contents entry -at point. The file name of the current buffer must contain +at point. The filename of the current buffer must contain @file{README} and there must be a `Table of Contents' or `Contents' label on a line by itself (it may begin with an asterisk), preceding the table of contents. Each toc entry must begin with some whitespace @@ -2769,7 +2773,7 @@ Info Index Item link-to-Info-index-item Info Node link-to-Info-node Mail Reader Message link-to-mail Directory Name link-to-directory -File Name link-to-file +Filename link-to-file Koutline Cell link-to-kcell Outline Heading link-to-string-match Buffer attached to File link-to-file @@ -4351,8 +4355,8 @@ This helps maintain any special formatting the appended text may have. @cindex outline, foreign file The paragraphs of another buffer or file may be inserted into a koutline as a set of cells by using the @bkbd{C-x i} command. When prompted, -you may use a buffer name or file name from which to insert; -completion is provided for file names only. +you may use a buffer name or filename from which to insert; +completion is provided for filenames only. @kindex koutliner, C-u C-x i The elements from the original buffer are converted into kcells and @@ -4384,7 +4388,7 @@ The outliner supports conversion of three types of files into koutline files. You can import a file into an existing koutline, following the tree at point, or can create a new koutline from the imported file contents. @bkbd{M-x kimport:file @key{RET}} selects the -importation type based on the buffer or file name suffix of the file to +importation type based on the buffer or filename suffix of the file to import. @findex kotl-mode @@ -4439,7 +4443,7 @@ World-Wide Web. @bkbd{M-x kexport:html @key{RET}} prompts for the koutline buffer or file to export, the HTML file or buffer to which to output, and the -title to use for the HTML file. Completion of file names is provided. +title to use for the HTML file. Completion of filenames is provided. The conversion will then be done and the output file or buffer will be written; the output file will not be displayed. @@ -5208,7 +5212,7 @@ list. In general, you should leave your personal rolo file as the first entry in the list, since this is the only file to which the Add command on the rolo menu adds entries. -Hyperbole releases earlier than 4.17 used a different file name for the +Hyperbole releases earlier than 4.17 used a different filename for the personal rolo. If such a file exists, you will be prompted to rename it whenever the HyRolo system is loaded. @@ -5665,7 +5669,7 @@ Prompts for a klink specification. See the documentation for the function @cindex interactive cmd char, +M @cindex argument, mail message @item +M -Prompts for a mail message date and the file name in which it resides. +Prompts for a mail message date and the filename in which it resides. The mail parameters prompted for by this character code may change in the future. @@ -6179,16 +6183,18 @@ to documents created and managed by tools other than Hyperbole, for example, programming documentation. @b{Ibtype} is a synonym for implicit button type. See also @b{system encapsulation}. -@c @cindex InfoDock -@c @item InfoDock -@c InfoDock is an integrated productivity toolset for software engineers -@c and knowledge workers. It is presently built atop XEmacs and is no -@c longer maintained. An older version from 1999 may be found at -@c infodock.sf.net. InfoDock has all the power of emacs, but with an -@c easier to use and more comprehensive menu-based user interface. Most -@c objections people raise to using emacs have already been addressed in -@c InfoDock. InfoDock was meant for people who wanted a complete, -@c pre-customized environment in one package. +@cindex InfoDock +@item InfoDock +InfoDock was an integrated productivity toolset for software engineers +and knowledge workers built atop XEmacs; it is no longer maintained or +updated. An older version from 1999 may be found at +infodock.sf.net. + +InfoDock has much of the power of GNU Emacs, but with an +easier to use and more comprehensive menu-based user interface. Most +objections people raise to using emacs have already been addressed in +InfoDock. InfoDock was meant for people who wanted a complete, +pre-customized environment in one package. @item Instance Number A colon prefaced number appended to the label of a newly created button @@ -6403,12 +6409,11 @@ Once you have Emacs set up at your site, GNU Hyperbole may be installed by using the Emacs Package Manager. If you are not familiar with it, @pxref{Packages,,,emacs,the GNU Emacs Manual}. -If you have Hyperbole 5.10 or higher installed and simply want to -upgrade it, invoke the Emacs Package Manager with @bkbd{M-x -list-packages @key{RET}}, then use the @bkbd{U} key followed by -the @bkbd{x} key to upgrade all out-of-date packages, Hyperbole among -them. Then skip the text below and move on to the next -section, @pxref{Invocation}. +If you have Hyperbole installed and simply want to upgrade it, invoke +the Emacs Package Manager with @bkbd{M-x list-packages @key{RET}}, +then use the @bkbd{U} key followed by the @bkbd{x} key to upgrade all +out-of-date packages, Hyperbole among them. Then skip the text below +and move on to the next section, @pxref{Invocation}. Otherwise, to download and install the Hyperbole package, you should add several lines to your personal Emacs initialization file, @file{~/.emacs}. @@ -6588,7 +6593,8 @@ be of interest to users. Hyperbole lets you control where link referents are displayed. It also permits setting a specific Emacs function or external program to display them. There are four categories of referents, each with -its own display setting, listed in decreasing order of priority. +its own display setting, listed in decreasing order of priority. All +of these variables are defined within @file{hpath.el}. @example Referent Category Variable Setting @@ -6618,21 +6624,23 @@ are displayed internally and externally. @vindex hpath:internal-display-alist @cindex internal standard display @vindex hpath:display-where -When given a file name, Hyperbole will by default display the file for -editing within an Emacs buffer. The @code{hpath:internal-display-alist} -variable can be used to specify file name patterns, such as matching -suffixes, which will invoke a special Emacs Lisp function to display -any matching files within Emacs. This can be used to format raw data -files for convenient display. - -This variable, @code{hpath:internal-display-alist} is defined in -@file{hpath.el}. Its value is an association list whose elements are -(<file-name-regular-expression> . <function-of-one-arg>) pairs. Any -path whose name matches a <file-name-regular-expression> will be -displayed by calling the associated <function-of-one-arg> with the -file name as the argument. - -By default, this variable handles the following types of files: +When given a filename to display, Hyperbole first checks if its suffix +is matched by @code{hpath:native-image-suffixes}. If so and if the +function @code{image-mode} is defined, it uses that mode together with +the value of @code{hpath:display-where} to display the image within an +Emacs buffer. + +If no match is found, the @code{hpath:internal-display-alist} variable +is checked for a filename match. Its value is an association list +whose elements are (<file-name-regular-expression> +. <function-of-one-arg>) pairs. Any path whose name matches +a <file-name-regular-expression> will be displayed by calling the +associated <function-of-one-arg> with the filename as the argument. +The first regular expression that matches each filename is the one +used. This can be used to format raw data files for convenient +display. + +By default, this setting handles the following types of files: @table @emph @item Audio Files Major audio format files are played with the @code{play-sound-file} command. @@ -6646,9 +6654,9 @@ available with InfoDock. @cindex menu, Cust/Referents @kindex C-h h c r Links to standard files, those which don't match any special referent -category, are displayed in an Emacs window specified by the -@code{hpath:display-where} setting. It may be changed with the Cust/Referents -@bkbd{C-h h c r} menu. +category handled by any described earlier, are displayed in an Emacs +window specified by the @code{hpath:display-where} setting. It may be changed with the +Cust/Referents @bkbd{C-h h c r} menu. @noindent Available options are: @@ -6666,7 +6674,7 @@ Display in a new single window frame Display in another, possibly new window of the selected frame (this is the default) @item @bullet{} Single-Win -Display in a window of the selected frame and delete its other windows +Display in a window of the selected frame and delete its other windows @end table @page @@ -6679,7 +6687,7 @@ Alternatively, you can use the Hyperbole menubar menu as shown here: @end float @sp 1 -@xref{External Viewers}, for instructions on associating file names with +@xref{External Viewers}, for instructions on associating filenames with external, window-system specific viewers. @node External Viewers, Link Variable Substitution, Internal Viewers, Customization @@ -6695,10 +6703,10 @@ external, window-system specific viewers. @cindex external display @vindex hpath:external-display-alist -If you will be using Hyperbole under a window system, -the @code{hpath:get-external-display-alist} function -in @file{hpath.el} supports hyperlinks that open files using external, non-Emacs -tools, e.g.@: a pdf reader or a vector graphic viewer. +If you use Hyperbole under a window system, +the @code{hpath:get-external-display-alist} function in @file{hpath.el} +supports hyperlinks that open files using external, non-Emacs tools, e.g.@: +a pdf reader or a vector graphics viewer. The value returned by @code{hpath:get-external-display-alist} is determined based on the window system supported by the current frame and the version @@ -6708,13 +6716,13 @@ path whose name matches a <file-name-regular-expression> will be displayed using the corresponding viewer-program or the first viewer-program found on the system from a list of programs. If a <viewer-program> entry contains a @samp{%s} string, the filename to -display will be substituted at that point within the string. -Otherwise, the filename will be appended to the <viewer-program> +display is substituted at that point within the string. +Otherwise, the filename is appended to the <viewer-program> entry. Alternatively, the viewer-program may be a Lisp function that takes a single filename argument. The association lists used by this function are stored in variables -for each available window system: @code{hpath:external-display-alist-macos}, +vfor each available window system: @code{hpath:external-display-alist-macos}, @code{hpath:external-display-alist-mswindows}, and @code{hpath:external-display-alist-x}. Examine and modify these values to suit your needs. @@ -6822,7 +6830,7 @@ Hyperbole: @code{(hpath:find-file-urls-mode 1)}. @cindex URLs, abbreviated @cindex Tramp Both full URLs and abbreviated ones, like @file{www.gnu.org}, are -recognized. File name completion does not work with URLs; you +recognized. filename completion does not work with URLs; you have to type or paste in the entire URL. This feature will work only if you have the builtin Tramp Emacs Lisp package; if you don't have Tramp, an error message will be displayed when you try to enable @@ -7379,7 +7387,7 @@ Called from a program, takes three args: START, END and COLUMN. @item kimport:insert-file @bkbd{C-x i} Insert each paragraph in IMPORT-FROM as a separate cell in the current view. Insert as sibling cells following the current cell. IMPORT-FROM may be a -buffer name or file name (file name completion is provided). +buffer name or filename (filename completion is provided). @findex kimport:insert-register @item kimport:insert-register @bkbd{C-x r i}