From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.devel Subject: Re: master 72b1379f079: Increase `emacs-lisp-docstring-fill-column` to 72 Date: Sat, 3 Feb 2024 16:47:54 -0500 Message-ID: References: <170687730547.552.9673193819426474611@vcs2.savannah.gnu.org> <20240202123506.0CEC7C0EFF5@vcs2.savannah.gnu.org> <87mssjm0ac.fsf@yahoo.com> <87il36mevf.fsf@yahoo.com> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="23984"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Po Lu Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Feb 03 22:48:57 2024 Return-path: Envelope-to: ged-emacs-devel@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 1rWNsf-00064K-Dl for ged-emacs-devel@m.gmane-mx.org; Sat, 03 Feb 2024 22:48:57 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWNrk-0005sO-Bt; Sat, 03 Feb 2024 16:48:00 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rWNrj-0005sF-39 for emacs-devel@gnu.org; Sat, 03 Feb 2024 16:47:59 -0500 Original-Received: from mail-lj1-x235.google.com ([2a00:1450:4864:20::235]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rWNrh-0002az-Dn for emacs-devel@gnu.org; Sat, 03 Feb 2024 16:47:58 -0500 Original-Received: by mail-lj1-x235.google.com with SMTP id 38308e7fff4ca-2d09cf00214so7386411fa.0 for ; Sat, 03 Feb 2024 13:47:56 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1706996875; x=1707601675; darn=gnu.org; h=cc:to:subject:message-id:date:mime-version:references:in-reply-to :from:from:to:cc:subject:date:message-id:reply-to; bh=nNuh4IH0mlZS33hlf3hWq7bhdXX+9ZeRmnE7dgrNXjA=; b=YOYPrvJGdUot6XPGDatFkJQIoLeDZqLcvHAcRGkcFvFBGHrx53uC5JpxCbTjEdcDZn +sCZ4olLUtPAHLiMOV6TuN3Y7C98Bf1iUkccZBEWeD7HxL9kar9nlaSAtFo6+uJjLdhl N6hhfIYQB1JM9ww8m1BiUDO2oZA/UlpexKNxpLVHQ4hvTOdRU1hAMK21aDJuIGU6U7o2 zfP2YwigjwXbdGkVf+oHV1ct3EzoPpBOM/RVqhGAH1i/ngE4PMmJ1SaXwVhTVKjjQFpe MBB2MxDdrvI7aUfnPsrVVIRBp1VA0TbnY2/WCkfHWAc5tK6oHW42pWglTHrz0kp2+RlT A0/Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1706996875; x=1707601675; h=cc:to:subject:message-id:date:mime-version:references:in-reply-to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=nNuh4IH0mlZS33hlf3hWq7bhdXX+9ZeRmnE7dgrNXjA=; b=ilblGP/9NSQQGrXAOnVg3icpb6xVIEda01zCiBHOCQCLLa6+kWZmswkJ/hi5jWZGzX XKxH6t0fz0+8C0jcKWSqzrjXD7ncd6iNyKH+omNh+zMqtpWgeV911jZ6XluYog6kXp30 hm2Yvibh3Dosgg/H5R8BpsRDvKYEcCxJPJHMSJLrBGL/Xii3BwDtyAP0TZbPEvozXO2c Fr8ncCgGoFvI0MjsUDDxu6KrWti1PWQ/p3KByBWdJxis7hRuQOMPz+nQrFvX6CmlLca1 olGJ0fA1Lxzx7+isk1bEE0ZqkNOGGWKuQAdG6LOcljRZCwan0W+KctFL1DfMTVZI9XtN o+UQ== X-Gm-Message-State: AOJu0Yw3AY6o+hlO62QdvDXDu/QdLoQF2EYr0LR3tStNwHBgGCxVC9Td 4i4jRH1499eUMhg8Ts4wieLwuErkbsqWrmRYWbVdcEs1bLTrJRXbMuHJBvU54cxRjHwLDGptEs0 ZIuowyKaW7EvgSuvQXDSv4cOVnHQ= X-Google-Smtp-Source: AGHT+IGb+ii97LJ3QL/zfykOU/YBZu2p/kVfMf7EzmbZ9yEbVoY0ufoLaMDCTw/7tcitGnImO7QbDoNBN6XBvdOTt5w= X-Received: by 2002:a2e:9cd3:0:b0:2d0:89d4:59a1 with SMTP id g19-20020a2e9cd3000000b002d089d459a1mr3277593ljj.21.1706996874858; Sat, 03 Feb 2024 13:47:54 -0800 (PST) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Sat, 3 Feb 2024 16:47:54 -0500 In-Reply-To: <87il36mevf.fsf@yahoo.com> Received-SPF: pass client-ip=2a00:1450:4864:20::235; envelope-from=stefankangas@gmail.com; helo=mail-lj1-x235.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:315837 Archived-At: Po Lu writes: > of which criticism is met by an ultimatum to either complete a > task that stands little chance of success (designing and securing the > universal adoption of a new doc string format), It seems like you think I didn't mean what I said, or in other words that I wasn't replying honestly. That's not the case. IIUC, the problem you seem to be concerned about is that Emacs doesn't wrap docstrings on narrow displays (mobile phones). We seem to agree that this is not currently supported. The claim that wrapping docstrings to 65 characters in any way solves that problem is just wrong. It is the same as ignoring the problem, perhaps simply because it happened to work on the one screen we bothered to test with (using some font and font size, letter spacing, etc.). I described the only solution I see, which is a new docstring format. Designing a new docstring format is obviously not a small task, but it would have many important benefits. It's quite a big blemish that for an editor that prides itself on its high quality documentation to have such a limited markup for docstrings. Our docstring format does have one important upside: its relative simplicity. But IME it's only simple for the simple cases. It was probably not too bad at some point in the past, but the world in 2024 looks very different, and users expect more. The markup itself is more like a bunch of cobbled together hacks that have amassed organically over years than a proper markup language. It doesn't only lack important features like word wrapping, but also: - bold, italic, etc. - lists (numbers and bullets) - variable width text - tables - semantically marking arguments - proper hyperlinks - an actually good way to markup keybindings and commands - maybe dividers and subheaders - etc. This project has the potential to make our help system better for users and developers, more consistent, easier to navigate, and so on and so forth. I think it's a very worthy endeavor. > In truth, there has been _nothing_ to suggest that the > width of doc strings has inconvenienced our users in any manner, Increasing the fill column for docstrings will not inconvenience users more than the current default does. Also, knowing Emacs, the overwhelming majority of docstrings are likely to continue being wrapped to 65 characters for years to come. I expect that we will have a new docstring format long before they are all rewrapped.