EmacsWiki: Info Plus (original) (raw)

Library info+.el extends the standard Emacs library info.el in many ways. Info+ provides:

• Association of additional information (metadata) with Info nodes. You do this by bookmarking the nodes. Library Bookmark+ gives you the following features in combination with info+.el. In many ways an Info node and its default bookmark can be thought of as the same animal.
  • Rich node metadata. In particular, you can tag nodes with any number of arbitrary tags, to classify them in different and overlapping ways. You can also annotate them (in Org mode, by default).
  • You can use ‘C-h C-b’ to show the metadata for a (bookmarked) node. This is all of the associated bookmark information, including the annotation and tags for that node and the number of times you have visited it. If invoked with point on a link, the targeted node is described; otherwise, you are prompted for the node name.
  • Links for bookmarked nodes can have a different face, to let you know that those nodes have associated metadata. Option ‘Info-fontify-bookmarked-xrefs-flag’ controls whether this is done.
  • The face for this is ‘info-xref-bookmarked’ by default, but you can set the face to use for a given Info bookmark using ‘C-x f’ (command ‘Info-set-face-for-bookmarked-xref’). This gives you an easy way to classify nodes and show the class of a node by its links. Uses faces to make clear which nodes are most important to you, or which are related to this or that general topic.
  • You can use command ‘Info-make-node-unvisited’ to make a node be considered unvisited. By default the node at point is used. For a node that is not bookmarked this also gives links to the node face ‘info-xref’, which indicates that their targets are unvisited. If for some reason you want to make links to a bookmarked node also have this face then just use command ‘Info-set-face-for-bookmarked-xref’, specifying face ‘info-xref’.
  • If option ‘Info-node-access-invokes-bookmark-flag’ is non-‘nil’ then going to a bookmarked Info node invokes its bookmark, so that the node metadata (such as number of visits) gets updated. Command ‘Info-toggle-node-access-invokes-bookmark’ toggles the option value.
  • You can automatically bookmark nodes you visit, by enabling mode ‘bmkp-info-auto-bookmark-mode’. Toggle the mode off anytime you do not want to record Info visits.
  • In the bookmark-list display (from ‘C-x r l’) you can sort bookmarks by the time of last visit (‘s d’) or by the number of visits (‘s v’). This gives you an easy way to see which parts of which Info manuals you have visited most recently and how much you have visited them.
• Editable, outline-enabled tables of contents (TOCs). Command ‘Info-toc-outline’ (bound to ‘O’) opens a separate Info buffer showing the table of contents (TOC). This is similar to the standard command ‘Info-toc’ (bound to ‘T’), but the buffer is cloned from the manual and is in ‘outline-minor-mode’. Also, there is no redundancy, by default: each TOC entry is listed only once, not multiple times. (This is controlled by option ‘Info-toc-outline-no-redundancy-flag’.)
  • You can have any number of such TOCs, for the same manual or for different manuals.
  • Outline minor mode lets you hide and show, and promote and demote, various parts of the TOC tree for a manual. And since the TOC is editable you can make other changes to it: sort parts of it, delete parts of it, duplicate parts of it, move parts around in an ad hoc way, and so on. Info+ makes the outlining commands behave, so that hidden Info text (e.g. markup text such as ‘*note’ … **`::**’ surrounding links) is kept hidden.
  • Especially when combined with `Info-persist-history-mode**’, command **`Info-change-visited-status’ (‘C-x DEL’), and the Info+ bookmarking enhancements (e.g., special link highlighting and persistently tracking the number of visits per node), ‘Info-toc-outline’ gives you a way to organize access and visibility of a manual’s nodes, to reflect how you use it.
• Additional, finer-grained Info highlighting. This can make a big difference in readability.
  • In the Emacs Lisp manual, reference items are highlighted, so they stand out. This means: constants, commands, functions, macros, special forms, syntax classes, user options, and other variables.
  • Single-quoted text, like `text' or ‘text’, and double-quoted names, like "text" or “text”, is highlighted if **‘Info-fontify-quotations’** is non-‘nil’. If the non-‘nil’ value is ‘t’ (the default) then, for the case of `...', only text quoted on the same line is highlighted. If the non-‘nil’ value is ‘multiline’ then even multiline text quoted with `...' is highlighted.
  • Angle-bracketed names, like <tab>, are highlighted if ‘Info-fontify-angle-bracketed-flag’ and ‘Info-fontify-quotations-flag’ are non-‘nil’.
  • Isolated single quotes and backquote characters, as in 'foobar and `foobar, are highlighted if **‘Info-fontify-isolated-quote-flag’** and ‘Info-fontify-quotations’ are both non-‘nil’.
  • Emphasized text, that is, text enclosed in underscore characters, like _this is emphasized text_ ,is highlighted if ‘Info-fontify-emphasis-flag’ is non-‘nil’. (But if internal variable ‘info-fontify-emphasis’ is ‘nil’ then there is no such highlighting, and that option has no effect.)
  • Glossary words, that is, words that are defined in a manual’s ‘Glossary’ node, are highlighted and linked to their glossary entries, if option ‘Info-fontify-glossary-words’ is non-‘nil’. Only the first occurrence of a given glossary word is ever linked in a given node. Several alternative behaviors are available using this option, including (1) whether to hide the link (showing it only on mouseover), (2) whether to show the definition in a mouseover tooltip (if ‘tooltip-mode’ is on), and (3) whether to show the link always or only until you’ve visited its word in the Glossary. Here are two screenshots.

Links shown; mouseover with definitions

Links hidden; mouseover with definitions

• Be aware that any such highlighting is not 100% foolproof. Especially for a manual such as Emacs or Elisp, where arbitrary keys and characters can be present anywhere, the highlighting can be thrown off.
• You can cycle or toggle the ‘Info-fontify-*’ options from the ‘Info’ menu, or using command ‘Info-cycle-fontify-quotations’ or an ‘Info-toggle-fontify-*’ command. For example, command ‘Info-toggle-fontify-emphasis’ toggles option ‘Info-fontify-emphasis-flag’.
• Minor mode ‘Info-variable-pitch-text-mode’ uses a variable-pitch font for Info text. If you enable this then you might also want to customize option ‘Info-fontify-indented-text-chars’, so indented text such as code uses a fixed-pitch font (face ‘info-indented-text’).
• Non-nil option ‘Info-fontify-indented-text-chars’ means fontify text that is indented at least that many characters (default 10). In the Elisp manual this often means blocks of code and ASCII-art diagrams. But in general there’s no telling what is indented at any given level, so caveat emptor. Think of this as an experimental feature.
• Option ‘Info-fontify-indented-text-manuals’ is a list of manuals that should use ‘Info-fontify-indented-text-chars’. By default this is just the Elisp manual: (elisp).
• You can define specific highlighting for individual manuals. To do this, you ‘put’ the regexp you want for a given regexp variable on the manual symbol. For example, if MY-REGEXP is a regexp string then this defines the regexp to use for a quotation as being MY-REGEXP, but only for the Elisp manual: (put 'elisp 'info-quotation-regexp MY-REGEXP). Then you can toggle that highlighting separately, using command ‘Info-toggle-fontify-local-quotation’. There’s such a command for each regexp variable. When you toggle a particular kind of manual-local highlighting off in the current manual, the global highlighting for that kind takes over there. Instead of explicitly setting the variable value for a manual using ‘put’, you can just use the local toggle command (such as ‘Info-toggle-fontify-local-quotation’) with a prefix argument. That prompts you for the regexp to use locally, for the current manual. You can also use such local highlighting to just turn OFF the global highlighting for a given regexp variable. To do that, use a prefix argument with the toggle command, and when prompted for the regexp, type **` $-**’. That’s a regexp that _cannot match anything_. When using Lisp, use the value of constant **‘info-nomatch’** – that prevents even trying to match. For example: (put 'some-manual 'info-isolated-quote-regexp info-nomatch). This is already done by default for the isolated-quote regexp variables, for several manuals that don’t involve (much) Elisp code with such chars: ‘ada’, ‘bovine’, ‘calc’, ‘emacs-gnutls’, ‘epa’, ‘eshell’, ‘eww’, ‘info’, ‘nxml’, ‘pcl-cvs’, ‘smtpmail’, ‘srecode’, ‘todo-mode’, ‘wisent’. The manuals you have may well be different from those Emacs provides by default, and you might want to add or remove such highlighting.
• Here is a screenshot of the *Info* buffer, showing some of the highlighting:

• Optionally showing breadcrumbs in the mode line or the header line, or both. See where you are in the Info hierarchy, and access higher nodes directly.
  • In the mode line. Turned on by default. See ‘Toggle Breadcrumbs’ in ‘mouse-3’ mode-line menu and ‘Toggle Breadcrumbs in Mode Line’ in ‘Info’ menu (e.g. in the minor-mode indicator). You can customize option ‘Info-breadcrumbs-in-mode-line-mode’ if you want to turn it off by default. (Available for Emacs 23+ only.)
  • In the header (just below the header line). I added this to vanilla Emacs 23. Turned off by default in Info+. See ‘Toggle Breadcrumbs in Header Line’ in ‘Info’ menu. Be aware that unlike breadcrumbs in the mode line, this can occasionally throw off the destination accuracy of cross references and searches slightly. Here is a screenshot showing breadcrumbs in the header line (only):

• Optional automatic renaming of Info buffers to include the manual (file) and node names, using minor mode `info-manual+node-buffer-name-mode’**. You can use option **‘info-buffer-name-function’ to customize the format of the buffer names.
• New key bindings, commands, and menus.
• Improved standard commands. For example:
  • ‘info-display-manual’: Completion for manual name.
  • ‘Info-goto-emacs-key-command-node’: If the key’s command is not found, then it searches for the key sequence in the text.
• Syntax table that respects EmacsLisp: apostrophe (') and non-breaking space have punctuation syntax, not word syntax. So for example, you can easily use ‘C-s C-w’ to select text between `…' without also grabbing the ' at the end. (I reported this as Emacs bug #3312, which was fixed a couple years later in Emacs 24.)
• Redefinitions of some standard Emacs functions
  • An Info frame is dynamically shrink-wrapped to fit each node individually (if ‘Info-fit-frame-flag’ is non-‘nil’).
  • Searching highlights the found regexp (if ‘search-highlight’ is non-‘nil’).
  • Searching does not deactivate the region if search stays within the same node. If you also use library IsearchPlus then option ‘isearchp-deactivate-region-flag’ controls whether it’s deactivated when search stays within the node. You can toggle that option anytime while searching, with ` M-= C-SPC’.
  • Better default values for input.
  • More informative messages – e.g. how many additional matches found.
• ‘*info*’ has been removed from ‘same-window-buffer-names’, so that a separate window can be used if you so choose.
• Some of the commands defined in Info+:
  • ‘Info-virtual-book’ (bound to ‘v’) – Open a virtual Info manual of saved nodes from any number of manuals. The nodes are those saved in option ‘Info-virtual-book’. With ‘C-u’, bookmarked Info nodes are also included. See also `icicle-Info-virtual-book’.
  • ‘Info-persist-history-mode’ – Enabling this minor mode saves the list of your visited Info nodes between Emacs sessions. Together with command ‘Info-history’ (bound to ‘L’ by default), this gives you a persistent virtual manual of the nodes you have visited in the past. If the mode is enabled then the list of visited nodes is saved to the file named by option ‘Info-saved-history-file’ when you quit Emacs (not Info) or when you kill an Info buffer. (If you also use library Bookmark+ then you can also bookmark Info nodes, including automatically. This records how many times you have visited each node and when you last did so.)
  • ‘Info-change-visited-status’ (bound to ‘C-x DEL’) – Toggle or set the visited status of the node at point or the nodes in the active region. Useful if you use ‘Info-fontify-visited-nodes’ to show you which nodes you have visited. No prefix arg: toggle. Non-negative prefix arg: set to visited. Negative prefix arg: set to unvisited.
  • ‘Info-save-current-node’ (bound to **` .**’) – Save name of current node to list ‘Info-saved-nodes’, for use by ‘v’ (‘Info-virtual-book’).
  • ‘Info-merge-subnodes’ – Integrate the current Info node with its subnodes (the nodes in its Menu), perhaps recursively.

Use ‘Info-merge-subnodes’ to extract a self-contained report (possibly the whole manual) from an Info manual. The report is itself an Info buffer, with hyperlinks and normal Info behavior.

There are various prefix-argument options that govern just how subnodes are treated (recursively or not, for instance). There are a few user variables that let you customize the report appearance.

Here is a screenshot of a report. I removed most of the text in each node (replacing it by a narrow band of white with “**. . .**”) so that I could show more than one node in the screenshot; the real report is a buffer 322 lines long.

You can convert such a report to HTML using menu Tools > HTMLize Buffer (‘mkhtml-any-buffer’) from library Lisp:mkhtml.el. For more information, see SaveAsHtml. (That code is quite old, however.)

See Also: Icicles - Info Enhancements.

Spacemacs Use of Info+

From user emacs18, 2021-08-25 00:07 UTC:

Spacemacs uses Info+ by default for all users. Aside from loading info+.el, Spacemacs has these two lines to configure it:

  (spacemacs/set-leader-keys "hj" 'info-display-manual)
  (setq Info-fontify-angle-bracketed-flag nil)

First line binds ‘SPC h j’ and/or ‘M-m h j’ key sequences to info-display-manual.

Following are the key sequences that follow ‘SPC h’ or ‘M-m h’ prefix keys. If you can suggest other commands in Info+ that we can add key bindings for, then please do. I can submit pull request to have the bindings added. Whether my PR request is approved or not is not up to me to say.

RET → helm-enable-minor-mode SPC → helm-spacemacs-help . → helm-spacemacs-help-dotspacemacs f → helm-spacemacs-help-faq i → helm-info-at-point j → info-display-manual k → which-key-show-top-level l → helm-spacemacs-help-layers m → helm-man-woman n → view-emacs-news p → helm-spacemacs-help-packages r → helm-spacemacs-help-docs t → helm-spacemacs-help-toggles I → report-issue M → helm-switch-major-mode b → +prefix d → browse-docs-online-at-point d → +help-describe a → helm-apropos b → describe-bindings c → describe-char f → describe-function k → describe-key l → describe-last-keys m → describe-mode p → describe-package s → describe-system-info t → describe-theme v → describe-variable x → describe-ex-command F → helm-faces K → describe-keymap P → configuration-layer/describe-pac.. T → describe-theme P → +profiler k → profiler-stop r → profiler-report s → profiler-start w → profiler-report-write-profile T → +tutorials e → emacs-tutorial v → evil-tutor-start

– emacs18 2021-08-25 06:51 UTC

Discussion and Issues

Your recognition of info-quoted-name seems like is not right, e.g. `(a list of (+ 2 3) elements) info-quoted-name highlight it. – ahei

Only if it is followed (by default on the same line) by a normal single-quote char: '. But yes, otherwise, you are correct.

Highlighting ‘...’ or `...', and "..." strings is problematic. In general, the results are good, but there are several things that can throw it off. Fortunately, these things do not occur that commonly in manuals – but they do occur. The more typical problem is an isolated " character referred to as such in the manual (e.g. ?"). You’ll just have to live with it or, if you think it’s not worth it, customize ‘Info-fontify-quotations’ to nil. – DrewAdams

Hi! A quick question: how to prevent info+ to split my window. I want the original info behavior, if i type M-x info, i want a full window to read. Thanks! --PasJa

Should be OK now. I had some hard-coded cruft leftover from 1999. Thx – DrewAdams

Hi! Version info in current update is inconsistent with previous one. We had Version 21.1 Update #: 4855 while currently Version is 0 with Update #: 4857 Could you correct this? Thanks! --Marcin

Hi Marcin. It is correct as is. I don’t use version information for info+.el (or for most of my other libraries either). package.el needs header field ‘Package-Requires’ to include a version number, however. (Pseudo) version ‘0’ allows any package requiring the given package to use any version of the required one.

Each of my library files has a ‘Last-Updated’ field that has the date and last ` Update #’ (which is incremented each time I save the file). This is the best info to use for reporting/communicating (e.g. about bugs). Users can ignore the ‘Version’ field for most of my libraries.

Thx – DrewAdams

Typo introduced in latest mod at line 3145 results in unbalanced parens, so lib won’t compile. – PhilHudson

Hey would it be possible that the format that Info-breadcrumbs-in-mode-line-mode uses? I don’t like that it removes the * around the mode-line-buffer-identification similar as info has by default and what other modes uses which contain buffers that are not backend by plain files. I also noticed that using nfo-breadcrumbs-in-mode-line-mode breaks doom-modeline-mode.

Thaodan – Björn

It sounds like you don’t want to put the breadcrumbs in the mode line, and you want to see the buffer name (as usual) instead.

For that, just turn off minor mode ‘Info-breadcrumbs-in-mode-line-mode’ or customize that user option.

If you still want to see and use breadcrumbs, you can customize option ‘Info-breadcrumbs-in-header-flag’ to non-‘nil’.

You can easily toggle the use of breadcrumbs in either location interactively, using the Info menubar menu, submenu Toggle/Cycle, items Breadcrumbs in Mode Line and Breadcrumbs in Node Header.

HTH. – DrewAdams

Lisp:info+.el

CategoryDocumentation CategoryHelp CategoryHypermedia CategoryModes