undefined | Better HN

0 pointsclarry12y ago0 comments

My problem with info is the document structure. The manual for each application seems to be structured so differently with topics under specific titles and subtitles, I always get lost and it takes me a while to find the thing I'm looking for. And it really is frustrating to stumble in the dark looking for that one command line flag or input format that you've found and used many times before.

For me the consistent reference-like structure and terse language of man pages is ideal. The whole document is shorter than a bunch of info pages will be, and because of the structure, I always know where to expect specific things to be. Some man pages do not quite fit the traditional model so there is a bit of compromise, but I still find it easier to scan through such pages and remember the location of things than I do with info pages.

The difference between (Open)BSD and GNU/Linux world man pages is that the former group spend plenty of effort on polishing the language & structure to make the text clean, short and to-the-point, as well as consistent. So exactly the qualities I prefer man for are taken as far as possible. And because we love well written man pages, there's a man page for damn well near anything in the base system; whereas on other systems you're sometimes looking at info pages, sometimes html documentation installed where-ever or nowhere, READMEs, comments in config files, howtos and tutorials via Google, or at the source because nobody bothered write real documentation. If the source isn't at hand or you don't have the time for it, you try imitate what you see in use already, and pray..

0 comments

teddyh12y ago

> My problem with info is the document structure. The manual for each application seems to be structured so differently with topics under specific titles and subtitles, I always get lost and it takes me a while to find the thing I'm looking for.

Use the index – it’s what it’s there for. In the usual Info readers, it’s the “i” key. This is what I use when, for instance, reading the GNU C Library manual and wanting the documentation for a specific function, struct or macro. If you want the command-line switches for the “foo” command, the node to go to in the manual you find yourself when invoking “info foo” is called “foo invocation”; you go to a specified node using the “g” key. Then you simply use the space key to navigate serially through all the following nodes. There are only three more keys that I use when reading Info documentation.¹

I think it’s mostly a question of habit. Man pages has taught you to read mostly the whole document quickly, while scanning for the information you need. These are habits unsuitable to both to reading a book of printed documentation or Info documentation. If you have a specific idea of what you want to find, you use the index.

1) The “l” key – “l” for “last” – corresponds to a web browser’s back button, the “u” key goes “up” in the document tree, and the “t” key goes to the top of the current document. These five keys are all the keys I use for Info navigation, except for normal searching with C-s, but that’s Emacs. This should not be difficult, but it is. I suspect, as I wrote previously, that it’s not Unix-y enough.

clarryOP12y ago

The index is the problem. The index for each application and library looks different. There are headings and subheadings and subheadings.. sometimes they're descriptive enough to help you find what you need, but in my experience, they often are not. But in either case you still need to read through them and interpret them. And reading through tens of headings is a pain, especially if after reading them you navigate to the seemingly most relevant page and find it doesn't have the information you need. ("Where the hell was it?!" is something I've said more than once, trying to battle info documents.) This is what I mean when I complain about structure; it's not consistent, it's not predictable. I don't want it to read like book, I want it to be useful and being consistent in such a manner that I can always find my answer quick helps there. Good man pages more or less have this consistency. And because they're terse, it's still quite easy to scan even when the structure for some reason does not conform to the tradition.

teddyh12y ago

I think you misunderstood me; the Index is not the table of contents or the list of headings. The index is what you access with the “i” key, and can also be read directly using the “g” key to go directly to the “Index” node.

I agree, reading headings and navigating that way is mostly a waste of time when trying to find something specific. Which is why I never do it; I use the Index.

j / k navigate · click thread line to collapse

0 pointsclarry12y ago0 comments

0 comments

teddyh12y ago

clarryOP12y ago

teddyh12y ago

I agree, reading headings and navigating that way is mostly a waste of time when trying to find something specific. Which is why I never do it; I use the Index.

j / k navigate · click thread line to collapse