> From: Dave Kemper <[email protected]> > Date: Mon, 9 Jan 2023 15:36:44 -0600 > Cc: [email protected], [email protected], [email protected], > [email protected] > > On 1/9/23, Eli Zaretskii <[email protected]> wrote: > > It is not a coincidence that the GNU project deprecated man pages in > > favor of Info manuals. > > A decision that, decades on, still does not garner universal acclaim.
There are people who weren't yet exposed to the superior power of Info, because no one could be bothered telling them the main points and punch lines. And then there are old habits that die hard. The GNU project has as its _policy_ to prefer Info documentation. We are executing this policy because we fully agree with it, but even if we didn't agree, when we accept the nomination of maintainers of some GNU package, we promise to uphold these policies. > But it's easy to understand the source of this difference. I'm > writing in an Info forum, so it's natural that you and others here are > predisposed to prefer the Info way of doing things. But bring this up > over on the groff forum, where man pages are a central topic, and > you'll get a rather different viewpoint. This is not Texinfo preference, this is the preference of the GNU project as a whole. You are supposed to hear about this policy being upheld in any GNU forum. And Groff is itself documented in an Info manual, btw. Don't get me wrong: I _love_ Less. I use it every day, and at the time contributed to its development. I just prefer not to use it for reading documentation when an Info manual is available, that's all. And I always explain to the uninitiated the most important and powerful commands of Info, with some success. > All I'm saying is, don't confuse YOUR (collective help-texinfo) > worldview with THE worldview. See above: it's not our view, it's a policy that we must uphold. > The main points are: (a) the info program can accommodate both types > of users; and (b) two small additions to the info man page will let > users see both paths available to them. But we don't _want_ users to use Info like that. > Piping and redirecting are CENTRAL to Unix's power, and the fact that > the "info" command allows this is an important piece of information to > communicate to users (as I mentioned before, it's not intuitive, as it > is with a lot of Unix commands, because the default interface is > interactive), even if the recipient of that knowledge never once pipes > it through "less." I disagree that it's an important piece of information. > > An Info manual is much more than the sum total of the text in it. The > > cross-references and the index commands make finding stuff in an Info > > much more efficient and fast, and the ability to jump to a > > cross-referenced material and then come back allows to consult the > > details without losing the context and the main subject you are > > reading on. > > True, and I'm not arguing against the advantages of the info interface. > > What I'm saying is that users come to tools from vastly different > contexts and backgrounds. A user who regularly uses "less" on other > enormous files or output streams will have a toolkit of keystrokes for > doing this, will know how use marks and regular-expression searches, > replicating some of that ability (and in some cases improving on it: > by setting marks at places throughout the document, the user can jump > between them in arbitrary order rather than having to navigate forward > and back among existing links). Let users see their options for > browsing Info manuals, and they can decide what works best for THEM. All of these capabilities have direct equivalences in Info. Users are better off learning how to use an Info reader, and use it efficiently, than learning about piping from Info. > > It's an obscure capability > > But that's circular: it's obscure because it's not well documented, > and now you're saying it shouldn't be better documented because it's > obscure. No. It isn't documented well because we consider it obscure and not worthy of more detailed documentation. There's no circle. A circle would mean that it's obscure because the Texinfo maintainers aren't familiar with it, and they aren't familiar because it isn't documented. That is not the case: I personally know about this capability since very long ago, and used it once or twice during the 3 decades I'm using Texinfo and help developing it. > It's also a testament to the power of "less" that it's usable on huge > man pages like bash(1). And if someone has learned how to use "less" > effectively to navigate and search such a page, why shouldn't they at > least be informed they can use that knowledge on Info documents? Because there are much better ways. For example, any large Info manual should never be (and usually isn't) read in its entirety more then once. Thereafter, people should use index-searching commands to quickly and efficiently find the subject of their current interest. There's nothing even approaching this capability in the "pipe-to-Less" method. How do you read even the Groff's manual, let alone something like Emacs or ELisp (or even Texinfo) using this method? what do you search for to skip irrelevant stuff, without the help of a well-thought index? Our efforts to improve the Texinfo documentation are better spent on making these aspects of Info more easily discoverable and more widely known, than on advertising obscure options that keep users from discovering and using Info. > Additionally, as Alex pointed out when starting this thread, if you > give users a familiar toehold into the expansive information Info > documentation provides, they'll be more likely to explore other ways > of accessing it. That's why the Info reader has the vi-keys option. (You are talking to the person who suggested adding that option to Info and implemented its first version, back in 1999. If you examine the key bindings under that option, you will discover that quite a few of them mimic Less, and that is also not a coincidence.) I consider _that_ to be the proper way of reaching out to users of Less and helping them open up and eventually migrate to Info. > That's getting a lot of mileage out of adding one sentence and one > example usage to info(1). Thank you for considering this. I don't mind a single sentence (and it's Gavin's call after all), I'm just saying that the issue at hand is not a sentence, the issue is the clash of two different philosophies.
