From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: jan via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#41006: 26.3; regular expressions documentation Date: Sun, 3 May 2020 11:31:52 +0100 Message-ID: References: Reply-To: jan Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="41220"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 41006@debbugs.gnu.org To: rms@gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun May 03 12:33:29 2020 Return-path: Envelope-to: geb-bug-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 1jVBw9-000Ab5-4D for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 03 May 2020 12:33:29 +0200 Original-Received: from localhost ([::1]:35132 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jVBw7-0002s4-TW for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 03 May 2020 06:33:27 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:34136) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jVBvi-0002rk-Cf for bug-gnu-emacs@gnu.org; Sun, 03 May 2020 06:33:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:43159) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jVBvi-0005IA-3P for bug-gnu-emacs@gnu.org; Sun, 03 May 2020 06:33:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jVBvh-0008ET-U0 for bug-gnu-emacs@gnu.org; Sun, 03 May 2020 06:33:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: jan Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 03 May 2020 10:33:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 41006 X-GNU-PR-Package: emacs Original-Received: via spool by 41006-submit@debbugs.gnu.org id=B41006.158850194131597 (code B ref 41006); Sun, 03 May 2020 10:33:01 +0000 Original-Received: (at 41006) by debbugs.gnu.org; 3 May 2020 10:32:21 +0000 Original-Received: from localhost ([127.0.0.1]:54705 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jVBuu-0008DP-CR for submit@debbugs.gnu.org; Sun, 03 May 2020 06:32:21 -0400 Original-Received: from mail-pf1-f179.google.com ([209.85.210.179]:39708) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jVBuh-0008Ck-4Y for 41006@debbugs.gnu.org; Sun, 03 May 2020 06:32:10 -0400 Original-Received: by mail-pf1-f179.google.com with SMTP id 18so4065463pfx.6 for <41006@debbugs.gnu.org>; Sun, 03 May 2020 03:31:59 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlemail.com; s=20161025; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc; bh=HjXvrdJkoY6eR89pK5A/7oscS4XJqpkP7bi3Y5PCxBo=; b=gzPD6Q6Qwi0E+bGyUEGUoXeXdTyWZ9BYe+ng29IMYBoCa5L4l33Owy/4hgHCC2moFs MzUvi8YYuNEPqd9xN3b2zi9H+8xgPbJZabN6IpTD/ko7hmnTnOe16v/PvmnBoTIfeWjf XVpVLVwxpPctBnQ7TvOkNqFeDDZmZPyQpnp7VfB59bZMTu3pJYWTEg77psF4/cVTMlcA O0QCWMUceJOjSYp+9/1XwLb1N9/EXcp2Qz/3cpvOlkry73zTqHutX3OThvPPq2G9aDXL pyTZs2Gc0PdLNDbHwXq5NUfae3YOtMKeMaZvA7ynjeDSlWqlnvf46hbhN2dzTy6E6m+W Msag== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to:cc; bh=HjXvrdJkoY6eR89pK5A/7oscS4XJqpkP7bi3Y5PCxBo=; b=C+FKhlvMndrDVWkxKzV+OVbHts0kOjCqqsrmhW0UJVa8p9CdNCa+/nMEZvd+U2plxz F0gu1V+9ABMEUSQFrnO4aeD5qYM5DoFah8e3U/7YfJHrSNwDa2xILTQZPgzr1HQhibGP 8a164ReoX4OBpJkgTHrtlCNz/i7L+20Ye+s6YTdVRVk4hDUqodpToBrL2AqNhuw3XVql hLGLuFL5eyJBZzmkAhrNj1Z2bg2LuykjwnYbl/2KjlLmFTGrtiRjSP118Au3hTUzNsm+ wI9gFWVQX1r2Vr7WxNy80WAkPsh+jzSuYNRLimP+NcG33E5MOrFy0Tu6ZdOCuTXdxfZy swvw== X-Gm-Message-State: AGi0Pubs4gQW5s7KUGairYhwSg7LLLEGM1VaTfL0nh7pu5Bfwar3t9Le wSOCviIRinPHQRJHoIytCVhwp+EqH4RCt1F6Eo9RgA== X-Google-Smtp-Source: APiQypIgIllwPm3R+eB3PHj79ENKtpSKETZtnSeiSl/fGVjgPBPBoEszG+piNZPYU/nWMDqtEpSsLgogDFxSMJh3g7o= X-Received: by 2002:a62:3303:: with SMTP id z3mr11625060pfz.88.1588501913210; Sun, 03 May 2020 03:31:53 -0700 (PDT) Original-Received: by 2002:a17:90a:9a86:0:0:0:0 with HTTP; Sun, 3 May 2020 03:31:52 -0700 (PDT) In-Reply-To: X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:179573 Archived-At: Well there's a name I recognise! Wasn't expecting that. Anyway, allow me to push back slightly. I have long ago training in user interfaces, but I'm no expert. To transmit info it has to be, among other things, 'evident' or 'obvious'. In this case I'd say that means visible. Section "15.6 Syntax of Regular Expressions" is very visible. It's easily navigable up and down by mouse or keyboard, also the scroll bar gives clearer indication of how much there is and where you are on the page. Great stuff. Even better it's easy to browse 'exhaustively' - if I start at the top of the page and into the bottom I know I've covered everything. I find that property very useful as I do *a lot* of technical reading. But it's only showing about half the information. There is no evident indication that there is more. I'm not the first person to get confused by this ( "The answer you seek seems to be in a separate section (Regexp Backslash), at least in the version I am currently using" - that took about 15 seconds to find). If you combine both sections together it would be visible and exhaustive. Whether it would be too long is something I can't answer, but my opinion would be it's okay (based purely on my evidence-free opinion). If you don't want to combine them then make the other half reasonably visible (it's rather odd that the top of the section points you at "(elisp)Regular Expressions" but not to backslash section). About the only evidence there is a second section, is right at the very top in the breadcrumbs (Next: Regexp Backslash) and a little hint at the end ("...since backslashes can legitimately precede these characters where they _have_ special meaning, as in..."). Specifically may have suggests that the start that currently looks like this: " 15.6 Syntax of Regular Expressions ================================== This section (and this manual in general)... " perhaps have a direct link to the next section, like this " 15.6 Syntax of Regular Expressions ================================== Non-Backslash Regular Expressions <--- dead link because you're here Backslash Regular Expressions (more regexp syntax) <--- live link This section (and this manual in general)... " And perhaps repeat that link at the end of that help page as well. Or something else. Whatever you think works, assuming you even think I have a point. regards jan On 03/05/2020, Richard Stallman wrote: > [[[ To any NSA and FBI agents reading my email: please consider ]]] > [[[ whether defending the US Constitution against all enemies, ]]] > [[[ foreign or domestic, requires you to follow Snowden's example. ]]] > > > 1. Suggest emacs' excellent documentation should not distinguish > between > > Regexps and Regexp Backslash in the manual. > > That is, these 2 should be combined: > > When a node is too long, browsing in Info becomes inconvenient. > Therefore, we look for a reading way to split up the node. > > We found that way to split up the node on regexps. > There is no logical _need_ to split the topic that way, but it is not > unreasonable, so it was a valid solution to the overlongness. > > I expect that many nodes are too long now, and we should look for > reasonable ways to split them. > > -- > Dr Richard Stallman > Chief GNUisance of the GNU Project (https://gnu.org) > Founder, Free Software Foundation (https://fsf.org) > Internet Hall-of-Famer (https://internethalloffame.org) > > >