From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0 ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id wMlRLiqsVWGwJwAAgWs5BA (envelope-from ) for ; Thu, 30 Sep 2021 14:23:06 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0 with LMTPS id qDwZKiqsVWEpXAAA1q6Kng (envelope-from ) for ; Thu, 30 Sep 2021 12:23:06 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 1159F1F771 for ; Thu, 30 Sep 2021 14:23:06 +0200 (CEST) Received: from localhost ([::1]:45166 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mVv5d-0006oM-2f for larch@yhetil.org; Thu, 30 Sep 2021 08:23:05 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:46950) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mVv4b-0006n9-8i for emacs-orgmode@gnu.org; Thu, 30 Sep 2021 08:22:01 -0400 Received: from mail-lf1-x133.google.com ([2a00:1450:4864:20::133]:34415) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mVv4W-0003wH-1e; Thu, 30 Sep 2021 08:22:00 -0400 Received: by mail-lf1-x133.google.com with SMTP id g41so24465751lfv.1; Thu, 30 Sep 2021 05:21:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=jKpvHBuVV7x+P2bYeTNK8qnRi//bpTheorR8npJIAlU=; b=emgH3nr0b96Mdyg+K8bRc2vJWig8vYdxMqQnSm2EizatSr8yebqDQkBy+ft+bbGNWd BZ6nu50fjZ5cvbmlBj60ZO8v5qb86AuMLdOZxYTVH+Gv06x3gMdBdKtMRMbHVGMKPEiA ZpnlxGlKN3sNYgYB+wts4tEFzhBAB/GlSYCCbH86mrhbi6kWoBGwXd3aq2RAt9qCoMsd Y4Vwb2brgTl7zSU7benEgzIYg8ce/hjnY5SH1xiSdxZmhbtYO3Pnb4NFFN7UdERKFqZ9 72ltZlrBOmNsol9QqsK+83BgDkjrXe7cXT8I9JF5oHm6lgBvj8T/ZBA2gT24O+E9vVnB M6DA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=jKpvHBuVV7x+P2bYeTNK8qnRi//bpTheorR8npJIAlU=; b=ReBEWQBNxXXSHTPahe37l7OT+ugI1bp7SzcUdTzczlGox8mClWKwKVs5UKwj9E9INr JLMQeupcryTZ/7rAprUR1LtoyM52eAScT8CfQbOfXcvR5Txk5EIbrZYHDPzkMD/dH7vr eN/cJ2awE/wBbbsS/L+SRdAZ9/aPoisFe8PAykvVkj6Ydy11StvmtoMNCo0QHejyiW29 AX2nMGpA5hI8xRSjfU3kx9UGbN+B7ORxRNpGBvR+Q4pKxlES3SBaFLLwiLcoBtGF+dPL xjOlxGJKyHb8t3pGO4oQdovgyB87vhOQz59HAG0NG0WqmpL6c0m/V4jx9AC7ctODH01L baYQ== X-Gm-Message-State: AOAM533If3UU95aNFCV+pCKHTSjeL3xWR7bZU5JWoiZk6rYVy1g70+M9 mm66Q8Ot3vFjm4eIPx/w4z9QBITuFrM= X-Google-Smtp-Source: ABdhPJznQZCA2cOckg+AGWqBxU/8UWqWv2KnYwODILW0+SaSY62j5RB+QqhM+XPNAj2rPvUNyaYyCA== X-Received: by 2002:a05:6512:16a7:: with SMTP id bu39mr5964345lfb.578.1633004512470; Thu, 30 Sep 2021 05:21:52 -0700 (PDT) Received: from guix-xps13 (95-29-46-69.broadband.corbina.ru. [95.29.46.69]) by smtp.gmail.com with ESMTPSA id j24sm351197lfh.302.2021.09.30.05.21.51 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 30 Sep 2021 05:21:52 -0700 (PDT) From: =?utf-8?Q?Andr=C3=A9_A=2E_Gomes?= To: Bastien Subject: Re: [PATCH] Rename headline to heading References: <871r786qfe.fsf@gmail.com> <87pmsv4rfy.fsf@bzg.fr> Date: Thu, 30 Sep 2021 15:21:50 +0300 In-Reply-To: <87pmsv4rfy.fsf@bzg.fr> (Bastien's message of "Sun, 26 Sep 2021 11:27:45 +0200") Message-ID: <87zgruw8wx.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=2a00:1450:4864:20::133; envelope-from=andremegafone@gmail.com; helo=mail-lf1-x133.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: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: emacs-orgmode@gnu.org Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: "Emacs-orgmode" X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1633004586; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=jKpvHBuVV7x+P2bYeTNK8qnRi//bpTheorR8npJIAlU=; b=O1osP/W9XJM+oiOED6nFcCmSTV/syeJOQY+n11Cy4+qr1PY5BzCiAN48vmAvm/S9L4iL9f NpUhKrLef6xyxgTaCjmBbC+SWTmBeMmBbdebiYo41ZZSwhnw2YZm6990QwtyjvSRd7En1L hHD0+g8aXSK4wj9Z82xIDEqz5iXvdy8xmbxyS/pw6EuB572EGyMLNP2Vyvlj7jyjb2wFZt J9gjv3cuUx1K+QeSel5J+Je3Ld8lCuGy/G4TDDEgbsbErUahjwAoOGUeCX3bW27wv6qaVb NJzygzirZD60rlDfvXOWFZclr2Ql0NiYJ498oCut1BC/gFqdd98wC9Xpl1Rtug== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1633004586; a=rsa-sha256; cv=none; b=p1hyA+pPX3SEmZu0oIElsk0ZuPn2sRQGBhDlo7Q1vd9UnUxyt6dOaegnWzO/OKeVTOJ+jw dNdjHbRp/RqAwI0Xd466VjIfQDerAVlsaW7AAwdzDqzI2SHS5Tzrw/1glXMMn3cBhb7GoR q8ABbaFIejZf6a1ZvzRsmx9h9bBbt5NgghKZt9nng7dfiv0ystdWu7L4l+qr3xG4C2oHHS 6z5v5KmWVy2W6WSkBb/MhjZGxhLkNbDY68uRXURFi396ZbZ5heNec9l7RwOQJoh7J3j7MG 6xXm4AKtXd5yUqhyU7PliAbTFJU/WjKXuG6bRkXLmKEPsHZD7a1RJSWd0nV5vQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=emgH3nr0; spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Migadu-Spam-Score: -3.10 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=emgH3nr0; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Migadu-Queue-Id: 1159F1F771 X-Spam-Score: -3.10 X-Migadu-Scanner: scn0.migadu.com X-TUID: 2oF/nzMWcLLD Bastien writes: > Hi Andr=C3=A9, > > I agree this change is a welcome improvement: thanks a lot for working > on this patch. I would like to suggest a step by step approach: > > 1. Updating occurrences in the documentation: manual, guide, > docstrings, worg occurences, etc. > > 2. Updating Org internals without impacting users' configuration > (i.e. update the functions and variables name, but don't update > the "file+headline" config string.) > > 3. If the "file+headline" config string is the only part of a config > that can be impacted by this change, support both the new and old > strings for backward compatibility. > > We don't need a transition period for the first two changes, and we > don't need one either for the third one if we implement the backward > compatible solution. We need a transition period if we remove it, but > I'm not convinced removing it is really needed now. > > What do you think? Hi Bastien, Sorry for my late reply. Overall, I agree with the suggested approach. Here's something I wasn't sure about when I worked on it. How should I distribute the changes commit-wise? Tom Gillespie, for instance, suggested separating documentation and docstring from internals. I think it's ok to separate internals from documentation (manuals). But when it comes to docstrings, it feels a bit odd. Say there's a function named foo-headline whose docstring contains the string headline. Then there would be a commit where the function continues to have headline in its definition, but the docstring contains heading. Shouldn't we avoid such a "grey area" snapshot? I could create a bunch of small and well documented patches, that in the end would be squashed before merging into master. Perhaps it would even make sense to have a branch for a while so that people would test it. This way everyone gets a fine grain for inspection, while in the end we get a huge "/s/headline/heading" commit. If someone has better ideas, please share. I will take a look at this perhaps next week. Thank you. --=20 Andr=C3=A9 A. Gomes "Free Thought, Free World"