Library <tt>[[info+.el]]</tt> extends the standard Emacs library ##info.el## in many ways.  '''[::Info+]''' provides:




[:bookmarking-enhancements]
* Association of additional information (metadata) with Info
nodes.  You do this by ''[[bookmark|bookmarking]]'' the nodes.  Library '''[[Bookmark+]]'''
gives you the following features in combination with <tt>[[info+.el]]</tt>.
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 '''[[BookmarkPlus#BookmarkTags|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|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-TOCs]
* ''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 '''`<tt>[[#Info-persist-history-mode]]</tt>'''',
command '''`<tt>[[#Info-change-visited-status]]</tt>'''' ('''`C-x DEL''''), and
the '''Info+''' [[#bookmarking-enhancements|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.










[:highlighting]
* 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, [[command]]s, functions, [[macro]]s, special forms, syntax classes, [[user option]]s, and other [[variable]]s.

** 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.)

[:GlossaryEnhancements]
** 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'''

:: [[image:DrewsEmacsInfoGlossLinksFace+Def]]

:: '''Links hidden; mouseover with definitions'''

:: [[image:DrewsEmacsInfoGlossLinksNOFace+Def]]



** 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 <code>*Info*</code> buffer, showing some of the highlighting:

:: [[image:DrewsEmacsInfoImage]]






* 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):

:: [[image:DrewsEmacsInfoCrumbsInHeaderImage]]







*  Optional automatic renaming of Info [[buffers]] to include the
manual (file) and node names, using [[minor mode]]
'''<tt>`info-manual+node-buffer-name-mode'</tt>'''.  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 [[http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=3312|#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]
** '''`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', [[bookmark]]ed Info nodes are also included.  See also `<tt>[[Icicles - Info Enhancements#VirtualInfoBooks|icicle-Info-virtual-book]]</tt>'.




[:Info-persist-history-mode]
[:Info-saved-history-file]
** '''`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 [[BookmarkPlus#AutomaticInfoBookmarking|automatically]].  This records how many times you have visited each node and when you last did so.)


[:Info-change-visited-status]
** '''`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]
** '''`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]
** '''`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.

:: [[image:DrewsEmacsInfoMerged]]

:: 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]].









----

[:SpacemacsUseOfInfo+]
== Spacemacs Use of Info+ ==

[new:DrewAdams:2021-08-25 16:32 UTC]
From user [[emacs18]], 2021-08-25 00:07 UTC:

[new]
Spacemacs uses Info+ by default for all users.  Aside from loading <tt>[[info+.el]]</tt>, 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














----

[:DiscussionAndIssues]
== Discussion and Issues ==

[new]
Your recognition of info-quoted-name seems like is not right, e.g.
<code>
 `(a list of (+ 2 3) elements)
</code>
info-quoted-name highlight it. -- [[ahei]]


[new:DrewAdams:2009-11-06 18:40 UTC]
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

[new]
OK, I see -- [[ahei]]


----
[new]
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]]

[new:DrewAdams:2011-08-23 17:48 UTC]
Should be OK now.  I had some hard-coded cruft leftover from 1999.  Thx -- DrewAdams

----
[new]
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]]

[new:DrewAdams:2013-08-14 14:30 UTC]
Hi [[Marcin]].  It is correct as is.  I don't use version information for <tt>[[info+.el]]</tt> (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

----
[new]
Typo introduced in latest mod at line 3145 results in unbalanced parens, so lib won't compile. -- PhilHudson
[new:DrewAdams:2020-05-20 18:46 UTC]
Thanks, Phil. Corrected. - DrewAdams


---
[new:Thaodan 2024-07-14 03:45:52 EEST]

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

[new:DrewAdams:2024-07-14 01:46 UTC]

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
[new]




----
Lisp:info+.el

CategoryDocumentation CategoryHelp CategoryHypermedia CategoryModes