From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: "Basil L. Contovounesios" Newsgroups: gmane.emacs.bugs Subject: bug#41571: 27.0.91; "(elisp) Interpolated Strings" is under "(elisp) Text" Date: Thu, 28 May 2020 11:41:54 +0100 Message-ID: <87zh9sfij1.fsf@tcd.ie> References: <877dwxexsh.fsf@tcd.ie> <83d06osfyw.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="25844"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) Cc: 41571@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu May 28 12:43:10 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 1jeG0D-0006c5-VG for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 28 May 2020 12:43:09 +0200 Original-Received: from localhost ([::1]:45648 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jeG0D-0003wI-0X for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 28 May 2020 06:43:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:47434) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jeG06-0003w8-C0 for bug-gnu-emacs@gnu.org; Thu, 28 May 2020 06:43:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:39536) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jeG06-00033S-0N for bug-gnu-emacs@gnu.org; Thu, 28 May 2020 06:43:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jeG05-0000m4-PO for bug-gnu-emacs@gnu.org; Thu, 28 May 2020 06:43:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Basil L. Contovounesios" Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 28 May 2020 10:43:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 41571 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 41571-submit@debbugs.gnu.org id=B41571.15906625242889 (code B ref 41571); Thu, 28 May 2020 10:43:01 +0000 Original-Received: (at 41571) by debbugs.gnu.org; 28 May 2020 10:42:04 +0000 Original-Received: from localhost ([127.0.0.1]:51081 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jeFzA-0000kX-Aw for submit@debbugs.gnu.org; Thu, 28 May 2020 06:42:04 -0400 Original-Received: from mail-wr1-f51.google.com ([209.85.221.51]:46542) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jeFz8-0000k2-VX for 41571@debbugs.gnu.org; Thu, 28 May 2020 06:42:03 -0400 Original-Received: by mail-wr1-f51.google.com with SMTP id x6so13715086wrm.13 for <41571@debbugs.gnu.org>; Thu, 28 May 2020 03:42:02 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tcd-ie.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=ZafJMcmciYt8qZc40fJyo1wub5EPral+PIMI1ot+aPo=; b=fCh7GLRMbacffT3myB6rXlj0AAOQd18Fu7tjylrGix6De/ay9Qd8VmlwuhQKvHYjxO 58apjTHI37T0hQup34ksSJUBuAGk3YBYIG7w0BbXANlmoFBxrsANddgy3sFaXVKe9SmI EbNsjxb7mD/UHOMswtobBrw4R9vpNSLyZjW7O5AFLsKxuqvOwasazEvxPHFCKAxAK+yC 4Rut58lDrwbmUN/Ku2H8JSWfWfcVmcuVHIXtFU8Q2hLCpgTkdEBsRVmtW5gpTz5RYfDj IBQ/v1Mpr6NiE3XY0YI/W4WkcnF4xJ8fWnw2Nj2+wqEsRlaEdDMsMRbHrAZzZBkm9lOs +nNA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version; bh=ZafJMcmciYt8qZc40fJyo1wub5EPral+PIMI1ot+aPo=; b=SYYE+EPSIXhXE/mCqpMiGSeUg/deBTngLWAzJf8uLjUpwtJ9AtDRWp5Aw8ew7IHa6z HvJh1Bxnpxqn6wd50FW9gUeLWNYx6sRSRpBhwjh8zU+1I6YaK4Dy4p1LQzTrJ3bJZjb9 zbyi4Nie7w3GtOCMoA8AynDgSsWRwR9xNDVCybWhhfObF3Hje+2Js4jbWu/4tK9ZgtW4 KuXPc4SJOTpKUQoPVXoDr/vbopcdMeKvSr/jfoj2ZxiVPrUVkgZCG7kOBAmS4EfKsrmN Zvy5DeAeVF6iUBrYR76GcOdpNhFg9rHoAqBe9EpjS/E8qoH3T0RTWHhvckujTfhToiGi EVqw== X-Gm-Message-State: AOAM532XBuK6t5XIzCw3A7sqYbjnZurHRiBrMyF72tiRzH8q2J5tgTys +xbA2QcyKFPfTSHzt/kOkVx08i/pzHs= X-Google-Smtp-Source: ABdhPJygKYmL6mkxBj3dlqZaWs8Jjk3KyrQim1g9uU8N9z8wJIZbJRp8YTZpMrY6pXPPfRe6qTtCUw== X-Received: by 2002:adf:e30e:: with SMTP id b14mr830882wrj.334.1590662516740; Thu, 28 May 2020 03:41:56 -0700 (PDT) Original-Received: from localhost ([2a02:8084:20e2:c380:1f68:7ff5:120d:64e]) by smtp.gmail.com with ESMTPSA id k21sm1068756wrd.24.2020.05.28.03.41.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 28 May 2020 03:41:56 -0700 (PDT) In-Reply-To: <83d06osfyw.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 28 May 2020 09:58:47 +0300") 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:181134 Archived-At: Eli Zaretskii writes: >> From: "Basil L. Contovounesios" >> Date: Thu, 28 May 2020 00:57:34 +0100 >> >> The Elisp manual node "(elisp) Interpolated Strings", which documents >> the function format-spec and is new in Emacs 27, is currently included >> under "(elisp) Text", which opens with: >> >> This chapter describes the functions that deal with the text in a >> buffer. Most examine, insert, or delete text in the current buffer, >> often operating at point or on text adjacent to point. Many are >> interactive. All the functions that change the text provide for undoing >> the changes (*note Undo). >> >> I think a more appropriate location would be following "(elisp) >> Formatting Strings", or at least under "(elisp) Strings and Characters". > > I agree, but can we please take this opportunity to improve that > section? First, it uses passive tense too much for no real reason > AFAICT. More importantly, the description of the feature is not clear > enough. I had trouble understanding even the "trivial example" it > shows, let alone all the rest. The very purpose of the feature is not > really obvious after reading the text. Sure, I'll give it a try, as I was already working on improving the format-spec implementation and documentation on master. While I'm at it, may I change the node name? Interpolating is the same as formatting in this context, so the difference between the two nodes is not clear to me. Perhaps something like: * Formatting Custom Strings:: Formatting custom @code{format} specifications. In fact, couldn't format-spec be documented alongside format and format-message under "(elisp) Formatting Strings"? Or does format-spec need its own node? Just to recap: format-spec is like format, except it allows custom %-sequence characters, such as %z, which are substituted in a similar way to format's %s. A common use case is to allow users to customise different output presented to them via custom format control strings. Thanks, -- Basil