From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: master 1e3b0f2: Improve doc strings of project.el Date: Sat, 11 Jul 2020 14:29:04 +0300 Message-ID: References: <87bllfqj82.fsf@warpmail.net> <83h7v7xf7w.fsf@gnu.org> <831rmayj55.fsf@gnu.org> <6dc2c2ac-8e17-f044-dc78-8c109f936ad2@yandex.ru> <83wo42w83e.fsf@gnu.org> <6762abf5-71c1-aa54-1bac-d4c90c20870b@yandex.ru> <831rmavsuq.fsf@gnu.org> <83a70wv4mj.fsf@gnu.org> <5542db0c-cc0d-2743-87ae-7728a0cc94bb@yandex.ru> <83ftaf2rj2.fsf@gnu.org> <43a8f8d4-83fb-f012-8e1d-c1a618b0ef59@yandex.ru> <83mu4m0vub.fsf@gnu.org> <44f2f1f4-ae34-f0bf-b153-f33b8ee6069f@yandex.ru> <83mu4fvjh3.fsf@gnu.org> <7c2e93d4-8d86-bbbb-77a0-bf5d73051907@yandex.ru> <83imf2t4w4.fsf@gnu.org> <95fd893e-0da5-4cdc-a3e8-3c22af750aae@yandex.ru> <837dvfs6wg.fsf@gnu.org> <8bc1f381-248f-5cee-c3c6-a29d411a2f74@yandex.ru> <837dvbphs0.fsf@gnu.org> <83365zp78d.fsf@gnu.org> <831rlipmgg.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="36319"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0 Cc: philip@warpmail.net, theo@thornhill.no, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Jul 11 13:29:41 2020 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 1juDhN-0009Lq-3O for ged-emacs-devel@m.gmane-mx.org; Sat, 11 Jul 2020 13:29:41 +0200 Original-Received: from localhost ([::1]:57472 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1juDhM-0002Cr-5z for ged-emacs-devel@m.gmane-mx.org; Sat, 11 Jul 2020 07:29:40 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:55846) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1juDgt-0001nU-2k for emacs-devel@gnu.org; Sat, 11 Jul 2020 07:29:11 -0400 Original-Received: from mail-wr1-x429.google.com ([2a00:1450:4864:20::429]:38417) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1juDgr-0000Bq-AW; Sat, 11 Jul 2020 07:29:10 -0400 Original-Received: by mail-wr1-x429.google.com with SMTP id z13so8355180wrw.5; Sat, 11 Jul 2020 04:29:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:subject:to:cc:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=X/5Vc3PyJtVJFG6Azg4F4Seuc079hlhPnlvR8BlNIiI=; b=OxyAqSNCrQSrN4BbHsWaaDRTYqzkE4vadx0l7LElPDpjUwqxCHs7p+QFMLL5UiyHwZ Zc6zPF6O9h8kqMVzqRTgeCR4oh4Lj0WVAnVehJe4RmK+SP28onHpxbuxv6nm+dfJ/zao +awyMlVPQa/kviOwBE/K9gBAHN2hCEOW+7RccpYGQFEFIkcEz+gG2CElMUC0ZkAe0VLO +PApgl0DZSgUprhIPAkEUhh09DYkJK0sQ9/PCedvsixMsIBw5ILTLNLXj4oxVZx+K3Hr SxuSXfdRrzhszNmuoH3gZOYl5+fgNHUM+kRRUztHw6RAgg+dDGTb4PLZkFIorjhYRKnH AGyw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:subject:to:cc:references:from:message-id :date:user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=X/5Vc3PyJtVJFG6Azg4F4Seuc079hlhPnlvR8BlNIiI=; b=imYNFM6d+04b0F9FKN7Jpo9xTrAToHZwdwsUd3/jA/pXVHXLPKV7etI5myIh9aF2eE Xd2TVweIhVp2I9K5o/X273rQwLlgEjkr7MUQj1bJT7dlW4KZtXrrEwg4zCdpDRtfjeGI KuBbIQBdnE93yB+1F96JWZKEquC58Kk7Bq7ecvbs1lfcjXsouMLVDL1Hl8/guVXb9aTw WQ4T0fDgLGJF4pUvDz5zJuziB0te83S66DcpEYYzUu/eB6zTikmXPd9/mK7nCx34+kYp lGJPozThfDSCz08E8Qz+wp7kNcZublgzrKdAprKTYL6IrLE0ggWabMUCsW+d1PuU1qe0 USWQ== X-Gm-Message-State: AOAM532xCjqyTsH8d6npYeniCgdU+0BzFb5jxOeSTxyqlm2CDccTBKY+ ueoj7hSmxtX0DNh0JoR6kMtYxqZw X-Google-Smtp-Source: ABdhPJwY2rb5PkuARQ54uHFujrSJpAoaykH6RnmOQbJ1t7BsDjBzOgqZr+3hjo9F5tOJZM1D0YXclw== X-Received: by 2002:adf:8462:: with SMTP id 89mr70495067wrf.420.1594466947083; Sat, 11 Jul 2020 04:29:07 -0700 (PDT) Original-Received: from [192.168.0.3] ([66.205.73.129]) by smtp.googlemail.com with ESMTPSA id r8sm13929489wrp.40.2020.07.11.04.29.05 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sat, 11 Jul 2020 04:29:06 -0700 (PDT) In-Reply-To: <831rlipmgg.fsf@gnu.org> Content-Language: en-US Received-SPF: pass client-ip=2a00:1450:4864:20::429; envelope-from=raaahh@gmail.com; helo=mail-wr1-x429.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: 0 X-Spam_score: 0.0 X-Spam_bar: / X-Spam_report: (0.0 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FORGED_FROMDOMAIN=1, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 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" Xref: news.gmane.io gmane.emacs.devel:252861 Archived-At: On 11.07.2020 09:58, Eli Zaretskii wrote: >> Tramp has extra-special handling for VC. It probably wouldn't be able to >> do that for all possible project backends. > > Why assume the worse? The situation is no different from that with > VC, so I see no reason to assume Tramp will do something similar for > supporting project.el. We shall see. >> - The "current project" cache of said buffer (if it is already visited) >> needs to be invalidated. >> - The "project-files" cache (currently not cached) of said project needs >> to be invalidated as well. >> >> When a file is removed from project, the latter needs to happen. > > Having commands to add or remove files from the project would allow us > to advertise those commands as the supported means of doing so. We > could also have a command to "refresh" the project, for those who for > some reasons will prefer doing that externally. These are options, of course. But this will make Emacs project support more high-maintenance than in "other editors". Take a random modern editor, open an existing project in it (it will show up in the side panel, usually). Then create a new file in its root directory using some external means. If it's not ignored by existing configuration, it will automatically show in the project drawer as well. We should support that. > But even without such > a command, we could say that users will have to go the project.el way > to have their project always up to date with the files it consists of, > and discourage doing that by external means. What's the project.el way? I suppose we could add hooks to find-file, dired-delete-file and after-save-hook in .dir-locals.el, if we give up on this kind of feature parity. >> The exact logic of project-current depends on the configuration of >> project-find-functions. > > Exactly. Then mentioning that as well would also help. Sounds good. >>>>> . the new doc string is confusing: "if 'project-current' returns the >>>>> same (equal) value" is incomplete, because it doesn't say the same >>>>> as what >>>> >>>> Same as the current project value, if any (otherwise, same as the value >>>> returned by the project selection prompt). >>> >>> Please fix the sentence, then. >> >> I'll do my best. > > I see you simply reverted to the original wording, more or less, which > is what prompted me to improve it. If you are still working on > improving that, I will wait; I "fixed" it to match the docstring of another command which you also improved in the past. Guessing that it could be good enough. > but if this is what you think the doc > string should say, then I will fix it again to be better. That sounds threatening. Like I said, you're welcome to suggest a better phrasing, for this and the other command (as long as the descriptions remain accurate). Go ahead and commit the new versions, if you like.