Emacs and changing documentation formats

Posted Dec 11, 2014 7:31 UTC (Thu) by Karellen (subscriber, #67644)
Parent article: Emacs and changing documentation formats

Are indices really that useful for a computer-based display format? Computers, unlike dead-tree based documentation, have this thing called "search" or "find", commonly accessible with "/" or "[ctrl]+f". Some of them even have regex-based find capability. I don't think I've needed to use an index for online documentation in about a decade.

I do find a table of contents with per-chapter links handy on occasion. But they're still not necessary, due to the magic of [ctrl]+f,"chapter title".

(Naturally, this required that your computer-based documentation is available as one large document. If you're creating a zillion tiny documents with links between them, just stop it, please? "Flipping" through documentation is much nicer with page up/page down, or roughly dragging a scrollbar thumb, than it is with endlessly clicking "prev"/"next" links.)

Emacs and changing documentation formats

Posted Dec 11, 2014 8:39 UTC (Thu) by ibukanov (subscriber, #3942) [Link] (6 responses)

> this required that your computer-based documentation is available as one large document.

100% spot on. This is the reason that info sucks for me with its viewers showing typically one node without a possibility to quickly search the whole document. I have found that man pages for GNU utils that refer to info pages for full details are more usable then info themselves because I can quickly locate the term using search in the man page.

Emacs and changing documentation formats

Posted Dec 11, 2014 9:33 UTC (Thu) by marcH (subscriber, #57642) [Link]

> 100% spot on. This is the reason that info sucks for me with its viewers showing typically one node without a possibility to quickly search the whole document.

The default info viewer searches across multiple info nodes. 100% "off spot"?

And this is not even related to the source format.

Emacs and changing documentation formats

Posted Dec 11, 2014 9:43 UTC (Thu) by drothlis (guest, #89727) [Link] (1 responses)

Just FYI, in "info" the key for "search for next occurrence" will continue searching past the end of the current "node" until it finds another hit. (And the "scroll down" key also goes to the next node after you've reached the end of the current node).

Having said that, I really feel for non-Emacs users who try to use the "info" command-line tool. It's just so different to anything else. You already know how to search in man pages because it uses $PAGER, which in turn uses the same keybindings as vi. Info is just alien.

Emacs users don't use the "info" command-line tool either, they use Emacs's built-in info browser which uses keybindings an Emacs user is already familiar with. Sometimes I wonder why distros don't replace "info" with a script that opens up the corresponding documentation in your web browser -- after all you can generate html from texinfo sources.

Emacs and changing documentation formats

Posted Dec 11, 2014 17:44 UTC (Thu) by sjj (guest, #2020) [Link]

I always use pinfo (or emacs) to read info docs. Pinfo has less of that alien technology feel than /usr/bin/info.

Emacs and changing documentation formats

Posted Dec 18, 2014 16:05 UTC (Thu) by dakas (guest, #88146) [Link] (2 responses)

This is the reason that info sucks for me with its viewers showing typically one node without a possibility to quickly search the whole document.

Except that s does search the whole document. So does i. And much faster than any HTML search, I might add.

Having one large HTML page for a 700-page manual is a huge pain in the behind. Try to do any sensible scrolling with the scrollbar: pretty much impossible. Try getting back to the previous place when scrollbar or text search led to some uninteresting chapter: pretty much impossible. There is no "Back" button for in-page navigation.

Emacs and changing documentation formats

Posted Dec 18, 2014 23:38 UTC (Thu) by flussence (guest, #85566) [Link]

Nitpick on the last point: the back button works fine when following #url-fragment-links inside a page, and in most of these types of document there's usually a table of contents of those right at the top.

But I agree with the rest. HTML is a poor output format for technical documentation.

Emacs and changing documentation formats

Posted Dec 24, 2014 1:46 UTC (Wed) by bjartur (guest, #67801) [Link]

In the case when you searched forward one too many times, searching backwards using ^G (Cmd-G) will bring you back. But only in repeated text search, and not in scrolling. Unless you remember where you were, or can search back for a rare word close to where you were. In fact, I found this comment after logging in by searching for "in-page".

Emacs and changing documentation formats

Posted Dec 11, 2014 9:03 UTC (Thu) by marcH (subscriber, #57642) [Link] (1 responses)

> Are indices really that useful for a computer-based display format? Computers, unlike dead-tree based documentation, have this thing called "search" or "find", commonly accessible with "/" or "[ctrl]+f". Some of them even have regex-based find capability.

Yes they are. When using info I use regularly BOTH indices and search because sometimes one hits faster and sometimes it's the other.

> I don't think I've needed to use an index for online documentation in about a decade.

Before mobile phones or tablets existed most people did not think they would ever feel the need for one.

Emacs and changing documentation formats

Posted Dec 11, 2014 9:11 UTC (Thu) by marcH (subscriber, #57642) [Link]

Among other differences, indices support auto-complete suggestions.

Emacs and changing documentation formats

Posted Dec 11, 2014 9:27 UTC (Thu) by drothlis (guest, #89727) [Link] (4 responses)

> Are indices really that useful for a computer-based display format?

As an Emacs user, my use case for documentation indexes is this:

* I'm editing a Makefile.
* Hmmm what does "$*" mean again?
* Press magic Emacs key incantation ("F1 S")
* Bam the documentation for "$*" appears. Not just the right document, but with the viewpoint centred at the relevant paragraph, which is highlighted.

It's so convenient that I try to find or generate info versions of the documentation for any programming language I use frequently. So far I've managed to get bash / coreutils / awk / sed, gnu make, automake / autoconf, perl, and python manuals.

Emacs and changing documentation formats

Posted Dec 11, 2014 10:28 UTC (Thu) by dgm (subscriber, #49227) [Link] (3 responses)

I recall experiencing something similar with Turbo C, back in the 90's. It was called context help, and has been an standard feature on any IDE I have used ever since.

Emacs and changing documentation formats

Posted Dec 11, 2014 11:08 UTC (Thu) by drothlis (guest, #89727) [Link] (2 responses)

What IDE do you use at the moment, and how does its context help for Makefiles and Bash work?

Emacs and changing documentation formats

Posted Dec 11, 2014 11:24 UTC (Thu) by drothlis (guest, #89727) [Link]

To tie this back to the grandparent commenter asking "are indices really that useful?": For a language like Python the IDE can offer some degree of contextual help based on introspecting the standard library. For Bash, Make, C++, and many others, this isn't possible so you need indexed documentation.

Furthermore, indexed documentation gives you things that introspection doesn't -- I often find myself looking up the documentation for Python keywords, standard exception hierarchy, etc etc etc. None of which I can get from ipython's contextual help, at least.

Emacs and changing documentation formats

Posted Dec 11, 2014 15:11 UTC (Thu) by nix (subscriber, #2304) [Link]

I use Emacs, of course. Its context help for makefiles and bash... well, if they were usefully parsable, it would use their Info manuals (since of course they have Info manuals). They're not, so I have to open the manuals myself and hit 'i' to look in the index. The horror!

Emacs and changing documentation formats

Posted Dec 12, 2014 4:00 UTC (Fri) by sadboy (guest, #94691) [Link]

Searching is a terribly inefficient method of reading documentation. Imagine searching through a million page document with ten thousand references to 'foo', for that one definition of 'foo'.

Additionally indices have auto-completion which will give you a quick list of potentially relevant terms.