Improve the usability of Info pages by going from this:
to this:
Package-Version: 20160415.001
Copyright 2016 Aaron Miller <me@aaron-miller.me>
Last revision: Friday, April 15, 2016, ca. 12:30.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Emacs’ Info manuals are extremely rich in content, but the user experience isn’t all that it could be; an Emacs process contains a lot of information about the same things that Info manuals describe, but vanilla Info mode doesn’t really do much to take advantage of that. Niceify-info remedies this.
To improve a single Info page, do M-x niceify-info in that page’s buffer. If you decide you like the effect so much that you want it applied to all Info pages you visit, add the `niceify-info’ function to `Info-selection-hook’ in your init file. For example:
(add-hook 'Info-selection-hook
#'niceify-info)This function applies a set of changes I call “niceification”, because I have a longstanding fondness for terrible names. This process does the following things:
- Applies customizable faces to text surrounded by emphasis characters * and _. The default faces for these are bold and italic, respectively, because that’s what the GNU-hosted HTML versions of the Emacs manuals use, but they can be customized to suit your taste.
- Identifies Emacs Lisp code samples and fontifies them accordingly.
- Identifies references in `ticks’, and where they refer to function or variable bindings, applies the necessary text properties to link them to the relevant documentation. References without a corresponding function or variable binding will be fontified as Emacs Lisp, by the same method used for code samples.
- Identifies headers for longer-form documentation of several types of objects, such as: “– Function: find-file filename &optional wildcards” and applies text properties making them easier to identify and parse. Names for documented things are linked to their documentation in the same way as for references in `ticks’. Functions’ argument lists are additionally fontified with a customizable face, which defaults to italic.
Each kind of niceification has a corresponding customization option to enable or disable it. You can easily access these via M-x customize-group RET niceify-info RET, or as a subgroup of the Info customization group. The faces used for emphases, and for function argument lists in headers, can also be customized.
Little of this is done with perfect accuracy. Here are the known issues:
- Autoloaded libraries not currently loaded will not have references in `ticks’ linked or fontified. (But if you load such a library, and then revisit an Info page containing such references, they will be correctly niceified.)
- Code sample identification and fontification is questionable. Due
to the lack of structural information in Texinfo files, the only
reliable method I’ve found of identifying a code sample is by
looking for places where indentation is deeper than the usual for
paragraphs on this page, and checking to see whether the first
following non-whitespace character is ‘(’ or ‘;’. This will fail
on Emacs Lisp forms which do not start with those characters, and
will have unpredictable and probably ugly results on code samples
not actually in Emacs Lisp which happen to start with one of
those characters.
The former issue I’ve found to be negligible, since it only appears to affect printable forms of non-printable objects (e.g. buffers, hash tables) which wouldn’t be affected by fontification anyway.
The latter issue I actually have yet to run across; in the non-Emacs-related Texinfo manuals I have on the systems where I wrote and tested this code, an admittedly brief and unsystematic search has failed to turn up any code samples or other quotes which erroneously trigger fontification. If you find one, let me hear about it! (See below for details on how.)
- For symbols with both a function and a variable binding, the function binding is always preferred. This seems to be a fairly rare case, and handling it (by prompting for which binding’s documentation to display) is surprisingly complex, so I plan to leave it for a later version of the library. If you’re anxious to have it before I get around to implementing it, feel free to open a pull request!
- Not all kinds of headers in Info pages are niceified, because for a lot of them I couldn’t figure out how to do anything useful.
I welcome bug reports, feature requests, and proposed modifications. You can submit all of these via Github’s issue and pull request trackers at https://github.com/aaron-em/niceify-info.el, and that is the method I prefer. Should you prefer not to use Github, or if the concern you wish to raise doesn’t fit well into one of those categories, you can also contact me by email at me@aaron-miller.me.