From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Nikolay Kudryavtsev Newsgroups: gmane.emacs.bugs Subject: bug#50903: Checkdoc recommendation for docstring subsitutions is inconsistent with other documentation Date: Wed, 29 Sep 2021 22:46:14 +0300 Message-ID: <70d5f8e1-0131-c0e2-1033-03911377e856@gmail.com> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="------------84E9C52A6F40CA61713E1F64" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="6832"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Thunderbird/78.14.0 To: 50903@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Sep 29 21:51:58 2021 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 1mVfcT-0001aP-MQ for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 29 Sep 2021 21:51:57 +0200 Original-Received: from localhost ([::1]:34560 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mVfcS-0002Ul-JU for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 29 Sep 2021 15:51:56 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:47436) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mVfXi-00014V-Iq for bug-gnu-emacs@gnu.org; Wed, 29 Sep 2021 15:47:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:38771) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mVfXi-0007mo-89 for bug-gnu-emacs@gnu.org; Wed, 29 Sep 2021 15:47:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1mVfXi-00053W-1U for bug-gnu-emacs@gnu.org; Wed, 29 Sep 2021 15:47:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Nikolay Kudryavtsev Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 29 Sep 2021 19:47:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 50903 X-GNU-PR-Package: emacs X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.163294478519380 (code B ref -1); Wed, 29 Sep 2021 19:47:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 29 Sep 2021 19:46:25 +0000 Original-Received: from localhost ([127.0.0.1]:50316 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mVfX7-00052W-0L for submit@debbugs.gnu.org; Wed, 29 Sep 2021 15:46:25 -0400 Original-Received: from lists.gnu.org ([209.51.188.17]:50194) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mVfX5-00052N-0s for submit@debbugs.gnu.org; Wed, 29 Sep 2021 15:46:23 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:47376) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mVfX3-00007n-Br for bug-gnu-emacs@gnu.org; Wed, 29 Sep 2021 15:46:21 -0400 Original-Received: from mail-lf1-x130.google.com ([2a00:1450:4864:20::130]:45960) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mVfX1-00079B-HJ for bug-gnu-emacs@gnu.org; Wed, 29 Sep 2021 15:46:21 -0400 Original-Received: by mail-lf1-x130.google.com with SMTP id u18so15354566lfd.12 for ; Wed, 29 Sep 2021 12:46:18 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:subject:message-id:date:user-agent:mime-version :content-language; bh=ZCbDiIX4h9/94HVhGhu8sEBSuZRpTYGm3mswJP2ajvg=; b=W84aQ5Ndo7z/r6k3oTwNLw972N0P0K2+GieNqESS8RiWlIeLTLUIy0Kibu9qBi1f7u 2il13OU/f0R/Ebhqjq2g3HjOKzZdS8dg3lhpQWvVdY78xS1Hv5xw7TRI49cew9AwM1Zz pkihlpSl2jfmzIWH1buVfCEtjSiQGHwb1Mf9i4RUWI1bgo/HnhSOD5tB0Gl9OV87LBeJ AX1cxAbzqjQj5P3w+gpPUFUcjaSFQz8wVcqwdkBCKZnMedGp6DIvbK+oYJKy3a1fy5E5 n/+6Hcy4H1h/MXnKOHPFKuB8rRJkFFxuDA4vW9G3tJNCJihaIZId8bDlws+EnDloAMOf Dfzg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:subject:message-id:date:user-agent :mime-version:content-language; bh=ZCbDiIX4h9/94HVhGhu8sEBSuZRpTYGm3mswJP2ajvg=; b=WYWweQx/vHVKerriaM6ibaYOtR2JqLxtZwf0BYezvKxfabbGzF6ni7OZ1qOulK8xwX oboBITMAlAwePgPAzmyiADpG9O8DeRVWaUfknDJ1M0h0x5LAsYSasS8/qTUPj8gsL7ew tO3kRmravKDJDsp/qgXpRc1OFXt3vkHEd+s3ZQmBnXpXptdsHBjIdfEBIYlZAFzTk8hv H7DfmJmkNHaE7GDj9R9Gh9NDTJOIDZ/EsS2pwauLLeTPs5TAG9LscDa8KOFastLtMKeG 18COQmSRQL3ITmr05queJwIeJX841SFdu8n+rh8XyuUuZ7ZLItypXuP6am4hqj/BGZqP 0wbA== X-Gm-Message-State: AOAM531sgA6RafpnaxvLwV1U/A5XPl5e75kW+4rNf1xHM9MAul6VjNaZ kwEHbDccfZmJSdKTiEI4kpbU9yHzk9c= X-Google-Smtp-Source: ABdhPJxbLy83OXRr4sLj1GjjWhkSxK2iANN+cfLhisZ8Nkf/+uddmpFCR8BJqPQ0NlSEltxS9I5ZpQ== X-Received: by 2002:a05:6512:214e:: with SMTP id s14mr1538755lfr.588.1632944776929; Wed, 29 Sep 2021 12:46:16 -0700 (PDT) Original-Received: from ?IPv6:2a02:2168:b115:9d00:5256:21d3:d9bf:ccde? ([2a02:2168:b115:9d00:5256:21d3:d9bf:ccde]) by smtp.gmail.com with ESMTPSA id g2sm92029lfe.266.2021.09.29.12.46.16 for (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 29 Sep 2021 12:46:16 -0700 (PDT) X-Google-Original-From: Nikolay Kudryavtsev Content-Language: en-US Received-SPF: pass client-ip=2a00:1450:4864:20::130; envelope-from=nikolay.kudryavtsev@gmail.com; helo=mail-lf1-x130.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 autolearn=ham autolearn_force=no X-Spam_action: no action 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:215911 Archived-At: This is a multi-part message in MIME format. --------------84E9C52A6F40CA61713E1F64 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit I had a docstring containing "C-c". Checkdoc gave me this suggestion: "Keycode C-c embedded in doc string.  Use \\ & \\[function] instead" Ok, but how? The relevant page of Elisp reference is (info "(elisp) Keys in Documentation"). But there they're called ‘\’ and ‘\[COMMAND]’. So someone searching by the checkdoc names would never find them there. The docstring for substitute-command-keys is also consistent with the Elisp reference. A trivial patch is included, since Elisp reference names seem more reasonable. I'm not sure whether MAPVAR and COMMAND should be capitalized in the docstring, so someone else should decide on that. --------------84E9C52A6F40CA61713E1F64 Content-Type: text/plain; charset=UTF-8; name="0001-checkdoc-Docstring-substitution-consistent-with-othe.patch" Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename*0="0001-checkdoc-Docstring-substitution-consistent-with-othe.pa"; filename*1="tch" RnJvbSA4NjE4ZTg2YWNkOTNhMGQ2ZmMwMmNjYjJkZTQ5M2MyYmUxYWM3OTVhIE1vbiBTZXAg MTcgMDA6MDA6MDAgMjAwMQpGcm9tOiBOaWtvbGF5IEt1ZHJ5YXZ0c2V2IDxuaWtvbGF5Lmt1 ZHJ5YXZ0c2V2QGdtYWlsLmNvbT4KRGF0ZTogV2VkLCAyOSBTZXAgMjAyMSAyMjozMzo0OSAr MDMwMApTdWJqZWN0OiBbUEFUQ0hdIGNoZWNrZG9jOiBEb2NzdHJpbmcgc3Vic3RpdHV0aW9u IGNvbnNpc3RlbnQgd2l0aCBvdGhlciBkb2NzLgoKKiBsaXNwL2VtYWNzLWxpc3AvY2hlY2tk b2MuZWwgKGNoZWNrZG9jLXRoaXMtc3RyaW5nLXZhbGlkLWVuZ2luZSk6CkluIGVycm9yIHRl eHQgcmV0dXJuICJNQVBWQVIiIGluc3RlYWQgb2YgImtleW1hcCIgYW5kICJDT01NQU5EIgpp bnN0ZWFkIG9mICJmdW5jdGlvbiIuCi0tLQogbGlzcC9lbWFjcy1saXNwL2NoZWNrZG9jLmVs IHwgNiArKystLS0KIDEgZmlsZSBjaGFuZ2VkLCAzIGluc2VydGlvbnMoKyksIDMgZGVsZXRp b25zKC0pCgpkaWZmIC0tZ2l0IGEvbGlzcC9lbWFjcy1saXNwL2NoZWNrZG9jLmVsIGIvbGlz cC9lbWFjcy1saXNwL2NoZWNrZG9jLmVsCmluZGV4IDVlYTJmNTllZTYuLjE2OTE4NzQ2Y2Eg MTAwNjQ0Ci0tLSBhL2xpc3AvZW1hY3MtbGlzcC9jaGVja2RvYy5lbAorKysgYi9saXNwL2Vt YWNzLWxpc3AvY2hlY2tkb2MuZWwKQEAgLTI1NCw3ICsyNTQsNyBAQCBjaGVja2RvYy1pc3Bl bGwtbGlzcC13b3JkcwogKGRlZmN1c3RvbSBjaGVja2RvYy1tYXgta2V5cmVmLWJlZm9yZS13 YXJuIG5pbAogICAiSWYgbm9uLW5pbCwgbnVtYmVyIG9mIFxcXFw9W2NvbW1hbmQtdG8ta2V5 c3Ryb2tlXSB0b2tlbnMgYWxsb3dlZCBpbiBhIGRvYyBzdHJpbmcuCiBBbnkgbW9yZSB0aGFu IHRoaXMgYW5kIGEgd2FybmluZyBpcyBnZW5lcmF0ZWQgc3VnZ2VzdGluZyB0aGF0IHRoZSBj b25zdHJ1Y3QKLVxcXFw9e2tleW1hcH0gYmUgdXNlZCBpbnN0ZWFkLiAgSWYgdGhlIHZhbHVl IGlzIG5pbCwgbmV2ZXIgd2Fybi4KK1xcXFw9e01BUFZBUn0gYmUgdXNlZCBpbnN0ZWFkLiAg SWYgdGhlIHZhbHVlIGlzIG5pbCwgbmV2ZXIgd2Fybi4KIAogSXQgdXNlZCB0byBub3QgYmUg cHJhY3RpY2FsIHRvIHVzZSBgXFxcXD1bLi4uXScgdmVyeSBtYW55IHRpbWVzLAogYmVjYXVz ZSBkaXNwbGF5IG9mIHRoZSBkb2N1bWVudGF0aW9uIHN0cmluZyB3b3VsZCBiZWNvbWUgc2xv dy4KQEAgLTE2MjYsNyArMTYyNiw3IEBAIGNoZWNrZG9jLXRoaXMtc3RyaW5nLXZhbGlkLWVu Z2luZQogCSAgICAgKGNoZWNrZG9jLWNyZWF0ZS1lcnJvcgogCSAgICAgIChjb25jYXQKIAkg ICAgICAgIktleWNvZGUgIiAobWF0Y2gtc3RyaW5nIDEpCi0JICAgICAgICIgZW1iZWRkZWQg aW4gZG9jIHN0cmluZy4gIFVzZSBcXFxcPGtleW1hcD4gJiBcXFxcW2Z1bmN0aW9uXSAiCisJ ICAgICAgICIgZW1iZWRkZWQgaW4gZG9jIHN0cmluZy4gIFVzZSBcXFxcPE1BUFZBUj4gJiBc XFxcW0NPTU1BTkRdICIKIAkgICAgICAgImluc3RlYWQiKQogCSAgICAgIChtYXRjaC1iZWdp bm5pbmcgMSkgKG1hdGNoLWVuZCAxKSB0KSkpKQogICAgICA7OyBPcHRpb25hbGx5IHdhcm4g YWJvdXQgdG9vIG1hbnkgY29tbWFuZCBzdWJzdGl0dXRpb25zLgpAQCAtMTYzNiw3ICsxNjM2 LDcgQEAgY2hlY2tkb2MtdGhpcy1zdHJpbmctdmFsaWQtZW5naW5lCiAgICAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgKDErIGNoZWNrZG9jLW1heC1rZXlyZWYtYmVmb3Jl LXdhcm4pKQogICAgICAgICAgICAgICAgICAgKG5vdCAocmUtc2VhcmNoLWZvcndhcmQgIlxc XFxcXFxce1xcdyt9IiBlIHQpKSkKICAgICAgICAgICAgICAoY2hlY2tkb2MtY3JlYXRlLWVy cm9yCi0gICAgICAgICAgICAgICJUb28gbWFueSBvY2N1cnJlbmNlcyBvZiBcXFtmdW5jdGlv bl0uICBVc2UgXFx7a2V5bWFwfSBpbnN0ZWFkIgorICAgICAgICAgICAgICAiVG9vIG1hbnkg b2NjdXJyZW5jZXMgb2YgXFxbQ09NTUFORF0uICBVc2UgXFx7TUFQVkFSfSBpbnN0ZWFkIgog ICAgICAgICAgICAgICBzIChtYXJrZXItcG9zaXRpb24gZSkpKSkpCiAgICAgIDs7IEFtYmln dW91cyBxdW90ZWQgc3ltYm9sLiAgV2hlbiBhIHN5bWJvbCBpcyBib3RoIGJvdW5kIGFuZCBm Ym91bmQsCiAgICAgIDs7IGFuZCBpcyByZWZlcnJlZCB0byBpbiBkb2N1bWVudGF0aW9uLCBp dCBzaG91bGQgYmUgcHJlZml4ZWQgd2l0aAotLSAKMi4zMi4wLndpbmRvd3MuMQoK --------------84E9C52A6F40CA61713E1F64--