From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.help Subject: Re: I'd like to request a change to the Emacs Info documentation Date: Fri, 21 Jan 2022 09:35:46 +0200 Message-ID: <83a6fppmlp.fsf@gnu.org> References: Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="18355"; mail-complaints-to="usenet@ciao.gmane.io" To: help-gnu-emacs@gnu.org Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org Fri Jan 21 10:59:14 2022 Return-path: Envelope-to: geh-help-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nAqhN-0004f4-Ul for geh-help-gnu-emacs@m.gmane-mx.org; Fri, 21 Jan 2022 10:59:14 +0100 Original-Received: from localhost ([::1]:44984 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nAqhM-00011f-Qv for geh-help-gnu-emacs@m.gmane-mx.org; Fri, 21 Jan 2022 04:59:13 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:39532) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nAoSZ-0001NS-8L for help-gnu-emacs@gnu.org; Fri, 21 Jan 2022 02:35:47 -0500 Original-Received: from [2001:470:142:3::e] (port=35062 helo=fencepost.gnu.org) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nAoSY-00042f-TR for help-gnu-emacs@gnu.org; Fri, 21 Jan 2022 02:35:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=o2sWCEvdFyyprA5Jrib3olM6EIDiiLrDHCBskdSxQXw=; b=f6/+wZnmA7V1 BFX9SlX26wa9g8B7Dz5oO0csoGmOK/E1Gr8NxV2zTaA+0U4I2v36K+2Io1Cb2y6D2oI3OyAVRU2ih axdgD5ghKre7rVtf/3xCnCGvud87z7nYAZrDOhxwGicHgl0aGPdree664MP4QS2X7HOEOVEe39pCX yMt8CVrthbtPX2834A8Bn9cQt1OwA8NimG+TEEwXGjY+Ww1IlHIL7qNk1mPFYqTOOtVgB4Ietatpc SE4Jn7nS5xWPqB8hNSaQbgvJtpNaH7YW6pzQGoadIesjL+nYOZonIjSNjj5/9uIKdygfxfFn0eG21 NEuTPU7B6FIRGPB5E0u66Q==; Original-Received: from [87.69.77.57] (port=3912 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nAoSX-0008Qu-Hy for help-gnu-emacs@gnu.org; Fri, 21 Jan 2022 02:35:45 -0500 In-Reply-To: (message from Ramin Honary on Fri, 21 Jan 2022 12:38:36 +0900) X-BeenThere: help-gnu-emacs@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Users list for the GNU Emacs text editor List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "help-gnu-emacs" Xref: news.gmane.io gmane.emacs.help:135466 Archived-At: > From: Ramin Honary > Date: Fri, 21 Jan 2022 12:38:36 +0900 > > Hello, everyone. I thought it would be better to ask my question here > first, so I don't end up adding noise to the emacs-devel@gnu.org > mailing list. Thank you for your interest in Emacs. > I would like to change the top-level node of the Info document for > Emacs so that it displays in prominent lettering how to do index > search (bound to the "i" key) and full text search (bound to the "s" > key) at the top of the document. I would like it to read: > > SEARCH IN THIS MANUAL: > - Press `i` to enter an index search term > - Press `m` to search this "menu" (the table of contents) > - Press `s` to do a full text search. > -------------------------------------------- > - Press `q` to quit (close this screen) > - Press `H` for more help with keyboard shortcuts. I don't think it's a good idea to add this to the Emacs manual, because it's just one manual. We'd need to add it to every Info manual, if we want to go that way. The comprehensive information about using Info is displayed if you press '?' in Info mode. That includes the search commands. Why isn't that enough for people who are not yet proficient with Info? > The justification is that search is considered essential functionality > in documentation nowadays, if people do not find search functionality > *immediately* they go to Google to search instead. Ideally, the > documentation would present an interactive search at the very top, as > most modern documentation browsers do. But failing that, the next best > thing is to put up an easy-to-read sign about how to do search. I think you are exaggerating. The search commands are indeed important, but so are the commands to move between nodes, go to a cross-reference and come back, etc. Info is a sophisticated mode, so it is impossible to squeeze its main capabilities into just a couple of commands. > As it is now, if you follow the instructions at the top of the Emacs > manual, it merely tells you to press "h" to learn more about how to > use the Info documentation browser, and pressing "h" only takes you to > section 1.2 of the Info manual. That is inaccurate. Here's what Info presents upon entry: This (the Directory node) gives a menu of major topics. Typing "q" exits, "?" lists all Info commands, "d" returns here, "h" gives a primer for first-timers, "mEmacs" visits the Emacs manual, etc. In Emacs, you can click mouse button 2 on a menu item or cross reference to select it. So it does say quite a bit more in addition to 'h', and it does mention '?', which describes all the important commands, including search. We could add there a couple more lines, but not too many, I think. (And this text is not from the Emacs manual, it's the "greeting" displayed by the Info mode in general.)