LWN: Comments on "Emacs and changing documentation formats"

man > info

mpr22 — Wed, 21 Jan 2015 11:55:41 +0000

I am curious how info ends the ls manual so hit space a few more times. Before I know it, I'm in the middle of the "cp" info page. ls is gone.

This is because GNU ls is a component of the GNU coreutils suite, and whoever wrote the documentation for GNU coreutils made the IMO completely misguided decision that there should be a single info document covering all the disparate components of coreutils. I'd never noticed this before because I've never used the info documentation for coreutils because every Linux distribution I've ever used has a man page for the programs in coreutils.

Some other info documents (such as the manuals for GCC, Flex, and Bison; if you tell me any of those should be a single man page each, or even a farm of man pages, I will laugh like a hyena and refer you to the reply in the case of Arkell v. Pressdram (1971)) are more sensible.

man > info

bmur — Wed, 21 Jan 2015 11:38:51 +0000

I am also someone who is utterly frustrated by info and I hope all info documents die a horrible firey death.

For comparison, I just did a "man ls" and "info ls".

The man page gives me a nice short description of the command, a synopsis of the syntax, and jumps into the options. Very unix.

Info tells me that ls lists directory content and quickly sends me down a rabbithole. It gets pedantic about files vs directories, locales, and gives me a full paragraph telling me this command has a lot of options. (duh) Maybe all of these details are important. But for me, seeing the command line options are my goal and the edge cases about ls output sorting behavior can be put at the end of the manual.

Pressing the arrow key to scroll down doesn't move the page down. I have to take my focus off of the document and figure out why the down key didn't work. Oh, there is a cursor moving in-page on a read-only document... that seems useless. So I hold the down key to get a page full of keystrokes hoping to find the command line options. At such point the command description disappears and the options start like a new document. My expected behavior was to see it as a continuation of the documentation.

But oh wait, my down key isn't moving the page down anymore. The cursor starts moving from the top and needs another 30 presses to get to the bottom.

If you want to review something you read a few seconds ago, you need 30 up keypresses to move the page up a single line.

This is the hell of using the info command.

If I decide I want to skip a full page ahead, I press the space bar because that is what most standard unix utilities use. Sometimes it was moving me down a page and sometimes I get a blank screen (I have no idea why).

I am curious how info ends the ls manual so hit space a few more times. Before I know it, I'm in the middle of the "cp" info page. ls is gone.

All of these minor things add up to a horrible experience. Imagine if instead of ls, I was trying to get info about a command I was less familiar with. The frustration would be immense.

source format vs info/html

benbadge72 — Tue, 13 Jan 2015 17:44:04 +0000

*chuckling* Man, oh man. :-) "If it works, fix it. If it's broke, leave it alone." *grinning and chuckling*

source format vs info/html

benbadge72 — Tue, 13 Jan 2015 17:40:14 +0000

As you describe this *issue*, it seems imho that really all that is needed is perhaps yet another Emacs mode. Also from mho, had thought muse mode fairly well did the *trick* aptly enough. Excuse me, whilst I sit going, "hm ...".

Emacs and changing documentation formats

vonbrand — Thu, 25 Dec 2014 16:48:57 +0000

"Keep screenshots in documentation and code in sync automatically" is just a very tiny part of the job of structuring and writing said doumentation. And mostly science fiction.

There are several objectives to documentation. One is "answer somebody's specific question, who has already a pretty good idea what they are looking for", where short man pages excel. Another, almost opposite, is "get an overview of what <foo> is all about", which is typically covered by textbooks and such. The info system tries to do both in a book-style format, no wonder it isn't too good at delivering the first. Some of the info documentation I've used is excellent in the second aspect, for example the bison manual. And the info format isn't at all a hindrance in its use, making it navigable is much better than having it as a printout. You can even pilfer the code examples, but that takes a bit too much effort.

Redoing the extant texinfo format documentation in some other format won't solve the problem that it isn't easy to extract answers to narrow questions out of broad descriptions. Perhaps complementing texinfo manuals with narrow man pages (or something equivalent) would be a step forward, but that requires knowledegable brains to write the missing pieces, not just a format change or some vaporware extraction tool.

Emacs and changing documentation formats

job — Thu, 25 Dec 2014 15:19:34 +0000

So... Imagine you're doing the thankless work of maintaining documentation. It's hard, hardly anyone notices, but it has to be done. You're proud you what you've achieved considering the circumstances.

One day a clown pops up: "I'm here to take all your tools away! But don't worry, I will get you new and different ones!" It's not hard to imagine the outcome. Especially if the said person was widely known to let others pick up the pieces.

The ONLY way to manage such a change is to do it in manageable chunks. First create new html templates with all the functionality of the current info pages. Then, change the internal viewer to show the nice html documents instead. THEN, change the file formats for documentation maintainers, because this time there'll be benefits to it.

If it is at all a welcome change, that is. I know neither Sphinx (which I regard as much nicer to write than asciidoc) nor html directly would solve any of the real problems I see with documentation. The most obvious one is that neither has any support for figures and screenshots. It's all delegated to external tooling, and at best stored hierarchically together with the documentation source.

But an integrated figure system could solve so much more. It could update screenshots when the underlying software is updated and make sure figures don't look out of place graphically. Just look at Lilypond which is rightly pointed out as well done. No offense meant, but while it's absolutely good, it doesn't look remotely modern. Text as pictures, bad aliasing, strange positioning, colors out of place, and no visible connect to the actual software in use. There's no doubt even better is possible.

Scrolling

DigitalBrains — Thu, 25 Dec 2014 13:47:02 +0000

While reading a text, I don't scroll with PgUp/PgDn; I scroll with the arrow keys. The more fluid motion of one line at a time helps me keep my orientation, I think. I only use PgUp/PgDn for skipping text, as a poor man's search for the next piece I'm interested in when I can't be bothered to think of a search term or genuinely don't know one.

I think the biggest problem with info I had quite some years ago before I discovered 'pinfo' was simply related to scrolling. Using the arrow keys to scroll is so much in my muscle memory that I felt like a stranger in an unfamiliar, not very friendly environment when it did not work. I was focusing my attention on the text, and kept getting drawn back to having to think about navigation halfway through a paragraph.

Trying info for the first time in years just now, it does indeed support one-line scrolling with the arrow keys, and there's the very helpful "Press 'h' for help" message. It would be nice if scrolling from one chapter to the next were fluid, though. Now it behaves like PgUp/PgDn at the boundaries. And it does so before I have finished reading the last chapter, whisking away the text I'm reading. The scroll-behaviour=Page Only option mentioned by mchapman is preferable to me now.

By the way, my 'less' does not have Del for PgUp; its help mentions b, ^B, Esc-v and w. The unmentioned PgUp works as well.

source format vs info/html

madscientist — Wed, 24 Dec 2014 13:46:27 +0000

We can't make you use something better if you simply refuse to.

If you'd prefer to go to your browser, search for the location of the manual on the web, search around to find the index, then search to find "foo" (remembering that the version of the documentation on the website is always the latest version which may not match the version of software you have installed), rather than typing "info gcc <RET> i foo <RET>" and getting the exact correct documentation for your software version...

Well, that's up to you.

source format vs info/html

arafel — Wed, 24 Dec 2014 12:29:31 +0000

Why would I bother to go back to it, though? If I want to look up a glibc function there are man pages; if I want to look up make or gcc then I use the web versions of the manuals. I have no interest in fighting with info, and if that's the only format documentation is in then I probably won't read it.

Emacs and changing documentation formats

bjartur — Wed, 24 Dec 2014 01:46:01 +0000

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

blujay — Tue, 23 Dec 2014 06:56:44 +0000

That is really fantastic! Thanks for sharing.

man > info

madscientist — Sun, 21 Dec 2014 06:50:38 +0000

The main drawback to info format is that it can only be read by the info program with its own nonsensical (to me) key bindings.

I really cannot understand this. I've seen many posts similar to this in this thread and I'm still stumped. Hardly any of the criticisms seem accurate to me.

You want to page through the entire manual as a single document? SPC/DEL (like less/more) will page down and back, and at the end of the page they automatically go to the next/previous page, just as you'd expect. Also PgUp/PgDown work the same way. Also arrow keys work the same way.

You want to search the entire document? "s" does that. So does "/" (a la less or vi).

You can't remember a key? "h" gives a quick key reference. So does "?".

These are all the common keys that I would try in any reader program, that work just as I'd expect them to work, and for which I wouldn't need to read any documentation first. I see lots of generic expressions of frustration, but no one is saying exactly what is missing.

Of course there are more advanced operations which don't have direct analogs in other programs... because info has more capabilities than those programs. Things like "i" for searching the index, or "n" (next section), "p" (previous section), "u" (up to parent section), "m" (choose menu item), "t" (top of manual), or "d" (directory of manuals). But if you don't know about these you don't have to use them.

Just about the only common navigation keys not supported by info are vi's hjkl.

So what, pray tell, are these magical keys that everyone expects info to support and are so frustrated when it doesn't, and take ten times as long to discover as it does to read the documentation?

Regarding man pages vs. texinfo manuals; I will definitely agree that man pages are better for some sorts of documentation and that in general, the GNU project does a disservice when they produce anemic man pages that say little more than "read the texinfo manual". Some things are better documented via man pages. However, man pages are reference documentation: that is, they work best when you already have a basic idea of what command you want to use and more or less how it works, but need a refresher on the details. Texinfo documentation is user documentation. Reworking the GNU Emacs manual, for example, into a man page (or even a huge set of man pages) would be excruciating and ridiculous.

As I said in my first reply, I won't pretend texinfo is the greatest markup ever but anyone wanting to move to something else should first ensure that the something else has at least all the capabilities of info. My suspicion is it would take less effort overall to keep texinfo as a markup and fix up the problematic output formats... the HTML output for example could be significantly improved: maybe having a floating menu that followed as you scroll and contained next/previous/up/top/directory buttons and search and index search boxes, plus providing info-like keybindings for keyboard control.

source format vs info/html

Wol — Sat, 20 Dec 2014 16:22:28 +0000

Don't forget - some people do still only have a 9600 baud modem - that's if they're lucky ...

Sneakernet is still the best available if you're in the back of beyond (although what was that quote - never underestimate the bandwidth of a truck full of 9-track tapes ... ?)

Cheers,
Wol

source format vs info/html

bronson — Fri, 19 Dec 2014 19:55:28 +0000

This is absolutely true, and I think it comes from the days of 9600 baud and 8 MB RAM. Any document over 10 pages got painful (especially if it had so much as a single image in it).

It's time for us to get over it. It's perfectly fine for a single HTML document to be 300 pages long, complete with a table of contents, index, and deep linking.

source format vs info/html

Wol — Fri, 19 Dec 2014 15:41:21 +0000

Exactly. Any document of any size is usually split across multiple pages and I invariably get lost in a maze of twisty little web pages, all different.

Cheers,
Wol

source format vs info/html

fb — Fri, 19 Dec 2014 14:36:32 +0000

I'm well aware that Apple is not updating anything re-released as GPLv3. No, I don't think this is in my interest as an Apple _user_ (the Apple customer in question is my employer).

[...]

I am seriously /not/ an Apple fan. But from my experience working for large IT companies, I don't think it has much to do with a former CEO's wrath or not. My **guess** is that something like this took place:

1. when the GPLv3 came out, folks in charge of updating utilities knew they had to get Legal to approve the new license. They asked Legal. Legal said "nope".

2. the (GPLv3 inclusion) request won't ever get reevaluated without pressure coming from product managers, and I suppose Apple product managers really do not have that anywhere in their priority list.

[...]

Bash's shell-shock back and forth of fix-attempts was, in my understanding, embarrassing for everyone.

source format vs info/html

oldtomas — Fri, 19 Dec 2014 14:10:07 +0000

> It seems OSX ships a version of info which is from Dec 2004

This could be an instance of "Steve's wrath": AFAIK Apple hates GPLV3 and prefers treating its customers to outdated Gnu software before even coming close to this license (Bash's another typical case: watch Apple's strange dance in the shellshock drama).

Whether that's in your (as Apple's customer) interest is quite another thing...

source format vs info/html

cortana — Fri, 19 Dec 2014 13:11:18 +0000

FYI, Debian policy recommends that documentation in text, HTML, PDF, etc. format be registered with doc-base, so that documentation browsers such as dhelp/dwww/yelp can locate it.

source format vs info/html

sorpigal — Fri, 19 Dec 2014 11:00:02 +0000

HTML also does hyperlinks, just like info, and encourages this kind of split document.

source format vs info/html

fb — Fri, 19 Dec 2014 10:53:32 +0000

@mbunkus sorry, but the version of the info manual present in my computer does not contain that string.

It seems OSX ships a version of info which is from Dec 2004 (Info version 4.8). (at work I pretty much sit the whole day inside OSX).

So while the documentation may have been fixed recently to address many usability issues. This old man page shows (as far as I am concerned) why so many people that made an honest attempt to use info 'back in day' did not succeed and pretty much learned ways to avoid using it.

source format vs info/html

epa — Fri, 19 Dec 2014 10:19:41 +0000

I don't see how that ties in with hating HTML? Since you can clearly read an HTML document from beginning to end. Do you mean that you dislike the practice of splitting an article into multiple Web pages?

Emacs and changing documentation formats

flussence — Thu, 18 Dec 2014 23:38:58 +0000

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.

source format vs info/html

bronson — Thu, 18 Dec 2014 22:29:33 +0000

Quite the opposite -- it's OVER documented. Using info requires reading so much documentation that I just can't be bothered. Why doesn't it behave like other Unix utilities? (Emacs doesn't count)

source format vs info/html

Wol — Thu, 18 Dec 2014 20:37:40 +0000

Unfortunately, it is. As someone who has - on several occasions - done pretty much as you suggest, I still hate the damn thing with a vengeance because I just cannot get to grips with it!!!

Cheers,
Wol

source format vs info/html

Wol — Thu, 18 Dec 2014 20:05:24 +0000

This is exactly why I hate HTML with as much venom as info.

"Start at the beginning, finish at the end" is how I learnt to read, and it's still how I prefer to read.

Cheers,
Wol

man > info

perlwolf — Thu, 18 Dec 2014 16:50:38 +0000

Exactly.

The main drawback to info format is that it can only be read by the info program with its own nonsensical (to me) key bindings. Whereas man uses whichever pager *I* chose for all of my viewing of long texts with the key bindings I already know. A learning curve of zero wins by a factor of infinity.

Every time I am forced to go to info to read documentation, I spend ten times as much time trying to figure out how to make it work than I do in reading actual documentation. So, I only use info as a absolute last resort. I've never, in all the time since the first info docs came available (yes, I've been using Unix systems that long) used info enough time to actually learn its command line. I've always considered the single fact of required a special program with its own random keystrokes to do a simple task as being an extremely arrogant act in the GNU choice of using info.

Emacs and changing documentation formats

dakas — Thu, 18 Dec 2014 16:05:59 +0000

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.

source format vs info/html

dakas — Thu, 18 Dec 2014 15:58:37 +0000

You should add i to the navigation keys you use. It's the actual navigation powerhouse of Info readers for which everything else is forgiven.

Also l for getting to the last page viewed before is nice particularly after following links.

source format vs info/html

dakas — Thu, 18 Dec 2014 15:54:17 +0000

I just installed pinfo and checked it out. It does not display images and does not appear to offer anything significantly over Emacs' info browser. Which is not all that surprising since there just isn't more in the Info format than what Emacs displays in the first place.

Yelp also is useless for browing Info files with substantial amounts of images. For example, starting it on the LilyPond notation manual (which contains thousands of images) will lock it up for some intolerable amount of time (I think the most I tried before aborting was an hour or so).

So the only competent Info reader supporting image display is Emacs. Which is a less than thrilling situation. On the other hand, Emacs' info reader knocks the pants off any other documentation viewing solution to a degree that is not even funny.

I have no good idea how to significantly improve this situation.

source format vs info/html

dakas — Thu, 18 Dec 2014 15:44:58 +0000

Shrug. Basically all GNU/Linux distributions I know have standardized tools for installing and augmenting and organizing the Info documentation database. In contrast, HTML docs are dumped in some non-standard place you have to figure out yourself.

Man pages, in contrast, are again placed in centrally managed places and indexed with keywords (man -k ...).

So "html is what the world uses to distribute documents, not info." is just not true with regard to program documentation: HTML documentation tends to get dumped without love and reference and indexing tools in some local directory with non-standard paths differing from application to application, or it gets dumped somewhere on the Internet and good luck finding a version corresponding to your installed version and written in a competent manner rather than cobbled together from bits and pieces, possibly in a Wiki-like manner.

And it's not like you cannot produce HTML from Texinfo anyway. Info is just one output format from Texinfo, the one that is really *good* to use from inside of Emacs.

Emacs and changing documentation formats

ssokolow — Thu, 18 Dec 2014 13:16:59 +0000

Seriously? Nobody mentioned that, by design, asciidoc is semantically just a human-friendly version of DocBook XML?

That means perfect fidelity conversion to DocBook and easy construction of a toolchain to output anything DocBook tooling can do. (Which, when you consider that Pandoc accepts DocBook, is quite a lot.)

Heck, I don't know how well it works, but there already exists a DocBook->TexInfo converter OTHER THAN Pandoc which is mature enough to have made it into Debian as docbook2x and Ubuntu as docbook2x-texi. (It also does manpages, thus the split)

source format vs info/html

jzbiciak — Thu, 18 Dec 2014 05:31:41 +0000

Pinfo has preserved my sanity many times as compared to Info.

I'm not an Emacs user (and so have no vested interest or opinion on how Emacs distributes its documentation). That said, 'info' pages pervade the GNU project and are in practice inescapable. So having something with a more approachable interface (without having to fire up a web browser) is very nice.

So add my vote for pinfo as well.

source format vs info/html

tao — Wed, 17 Dec 2014 12:26:43 +0000

Dunno about other viewers (since I don't use them), but at least evince allows you to view PDF's in continuous mode instead of page-by-page.

source format vs info/html

mchapman — Wed, 17 Dec 2014 12:04:29 +0000

> Yes you can page through it with space - which causes the current page to vanish and be replaced by the next page.

I find the single biggest usability improvement to GNU Info is to turn this behaviour off. If the documentation is going to be split up into separate chapters (which I don't find particularly annoying, to be honest), then it's better to not have the viewer jump between chapters and completely refresh the screen when you're not expecting it to.

To change this behaviour you need to set up an ~/.infokey file containing:

#var
scroll-behaviour=Page Only

Then run infokey to compile that to ~/.info. Who said GNU Info wasn't user-friendly? :-)

source format vs info/html

epa — Wed, 17 Dec 2014 11:36:54 +0000

Yes you can page through it with space - which causes the current page to vanish and be replaced by the next page. That is not nearly as familiar as scrolling up and down where you can visually see where you are in the document.

There are still a few interfaces that work by pages - two that come to mind are PDF viewers (where you are viewing a document with hard page boundaries) and ebook readers (often with slowly-updating displays that would blur on scrolling, and attempting to reproduce the experience of reading a book). But on the whole, scrolling interfaces have driven out paginated ones, and with good reason.

I would much prefer the Info reader to show the whole document and scroll through it, a line at a time with up / down and a screenful (not a 'section') at a time with page up / page down. That doesn't stop it from accepting Space to jump to the start of the next section, but you could still visually see your position in the document.

Yes, I have sometimes used the trick of info | less to get a more usable interface...

Emacs and changing documentation formats

sjj — Tue, 16 Dec 2014 20:21:12 +0000

I have made a couple of false starts using Org as a GTD/todo/etc app over the years. I haven't gotten the habit to stick very well, but I keep returning to it because it is pretty awesome.

I just started putting our company sysadmin docs into Org documents, stored in git and rendered to web pages with this: https://github.com/fniessen/org-html-themes and I'm in love.

If Emacs wants to ditch texinfo, they could do much worse than use Orgmode instead.

source format vs info/html

hickinbottoms — Tue, 16 Dec 2014 08:17:25 +0000

Many thanks for the pinfo pointer -- worth the visit to the comments for this alone.

source format vs info/html

k8to — Tue, 16 Dec 2014 07:59:16 +0000

The arrow keys for a text viewing application should absolutely shift the text (as in scroll up/down/left/right), not switch to a different set of text.

man > info

ldo — Tue, 16 Dec 2014 02:14:33 +0000

If it comes to a choice of man pages over info pages, I would choose man every time. Even after many years of exposure to documentation in info format, I still cannot get used to how clunky it is to find things. My first instinct when looking for documentation for any command-line tool is to see if there is a man page for it.

OK, so how would you provide cross-referencing and searchability? Look at these two examples:

Perl, where the obvious perl(1) man page that users would go to helpfully provides an intro and a list of other man pages for more details.
Bash, which puts the entire user manual into one bash(1) man page. So you have all the usual searching facilities of less(1) (or whatever pager you prefer).

Either option works just fine, and lets me find stuff much quicker than info would.

Who Says AsciiDoc Tools Only Output HTML?

ldo — Tue, 16 Dec 2014 02:03:32 +0000

The asciidoc(1) man page says it can output either HTML or (shudder) DocBook.

And then there’s Pandoc, which can convert between a whole range of formats, including AsciiDoc.