Hi Arsen, On 1/7/23 21:33, Arsen Arsenović wrote:
Hi Alex,Alejandro Colomar <[email protected]> writes:Hello, As someone with zero knowledge of how info(1) works, but considerable knowledge of how to read a manual page (well, there's little to it; less(1) is really simple), I'd like to recommend something for the info(1) manual page.Check out ``info "(info)Help"''.
That brings me to the same as `man info`.
This page is also linked through the info viewer welcome message: "Welcome to Info version 7.0.1. Type H for help, h for tutorial". Pressing h at any point in the info viewer takes you to that page.
Oh, in the front page of `info info`, I saw that 'H' is for help, and read the basic command keys:
[ Next: Stand-alone Info, Up: (dir) Stand-alone GNU Info ******************** This documentation describes the stand-alone Info reader which you can use to read Info documentation. If you are new to the Info reader, then you can get started by typing 'H' for a list of basic key bindings. You can read through the rest of this manual by typing <SPC> and <DEL> (or <Space> and <Backspace>) to move forwards and backwards in it. ]However, help that explains how to navigate is of little help if I first don't know how documentation is organized. In a manual page, it is simple: documentation for something is in a single page. In Texinfo, there is a nodes a dir, a pointer, a file, a tree, ... and I don't know what they mean.
For someone who has never used emacs, learning all this from scratch is... not easy. It's a bit of a chicken-and-egg problem. I can't say I didn't have this problem with less(1) and vim(1), but at least a man page doesn't need that one knows everything about less(1); even a novice can use the arrows, and that's enough for starting; search and other features can come with learning.
This message seems to often be missed by users, in my experience. I don't know why - perhaps because it's on the bottom of the screen, below the interesting stuff.The info(1) manual page seems to be little more than just a link pointing readers to the actual documentation, accessed through info(1) itself: SEE ALSO The full documentation for info is maintained as a Texinfo manual. If the info program is properly installed at your site, the command info info should give you access to the complete manual. (Or, if you have Emacs, M‐x info will lead to the manual.)This is pretty common with many pages, as manuals generally serve as a short summary of a full documentation suite in info pages, where that exists.
Yeah, I guess that's normal; I don't expect you to write twice your docs, once for man(1) and again for info(1).
It might be useful to lessen the learning curve of info(1), and recommend to habitual readers of manual pages to pipe info(1) to less(1), so that the manual is in a more familiar format. Who knows? Maybe after reading without much friction the entire info(1) manual you convert some of us. And if not, at least we were able to read manuals only available through info(1) :) How about adding the following: For readers more familiar with manual pages, it might be interesting to pipe info(1) through less(1): info info | lessThis suffers from decreased navigability, though, as links (xrefs and menu entries especially) become non-clickable.
We have the same issue in the manual pages. less(1) seems to not be very friendly to hyperlinks. Maybe we could add a disclaimer that piping through less(1) would disable links (and maybe other stuff).
That said, that could be done, if others agree, but I believe a better experience can be created by making the info format viewers themselves more accessible for people more used to pagers, or otherwise un-adapted to EMACS.
:)If you could add an alternative mode where it would behave somewhat like less(1)/vim(1), that would be great.
I've been brewing thoughts of how to make the standalone info viewer (or an alternative one) more useful to newcomers to GNU. I'd value your feedback, given your background. I think (Tex)info has a lot to offer already, and has large potential for generating new high-quality documentation, on top of the large volumes of existing documents.
Maybe vinfo(1) would be a good name for a vi-like info.However, navigation is only one issue; understanding how the documentation is organized is another, which I guess could be better detailed in `info info`.
Maybe before the '5 Selecting a Node' section, you could add one that explains what is a node, and all other subdivisions of info documentation, and maybe show some visual example (an ascii-art tree or something).
A suggestion I got already (and I'll see if I can implement it soon) is generating a HTML version of the ``(dir)'' node, and probably providing a link to it, or a shortcut to jump from info to a HTML view, or something like that, so that an end user can make use of the HTML view, which is potentially more alike what they'd be adjusted to.
HTML is probably good for some. However, others prefer the terminal (yes, there are terminal HTML browsers, but for some reason I don't find them very useful).
A vi-like info viewer would be interesting (and as a temporary workaround, `info x | less` does the job).
I'm very much looking forward to hearing your thoughts on this, as I believe it's quite important. I must apologize in advance for a lack of initiative in the coming few weeks (at least up to FOSDEM), I've a lot of work to do right now.
Oh, don't worry at all. As I said, |less does the trick for me :)
Thanks in advance, have a great night.
Have a great night :) Cheers, Alex -- <http://www.alejandro-colomar.es/>
OpenPGP_signature
Description: OpenPGP digital signature
