From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id qJGoNk9obGa6pgAAqHPOHw:P1 (envelope-from ) for ; Fri, 14 Jun 2024 15:57:04 +0000 Received: from aspmx1.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0.migadu.com with LMTPS id qJGoNk9obGa6pgAAqHPOHw (envelope-from ) for ; Fri, 14 Jun 2024 17:57:04 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gnu.org header.s=fencepost-gnu-org header.b=kSV41uLC; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; dmarc=pass (policy=none) header.from=gnu.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1718380623; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=WqCyDwgef6H2EFBaSQxmdXXiorGBTATEuwo2XQGUdqs=; b=sDBDRmq1hvM+/L2/rA2elcNdQSPDM1FwWm5DoLO2PTsWfHe50LPVRlRzmH6VRrEK5nBVUX ufwa+WC0oFOC9hCXbVTfQ+XQw1slY8E65sIBGWMXhSGfeIe+jyn6QV8aDuYY6dwu7TcsSR IxlfxC0RI0SgglxMDowiATXKLy9TgqXv8ZRJPnn7mk0tXhOHv2/InWKfZHLfMGgj9JrM9r A+Gp+RtsS45XHhxlYXuGN9jm2pFyhApVtryWxn1Yju37ELqbqW4ghhWaDmbAIvAFBfDutt sebpW36XjcbiR0WD+C50TJsVpQv2u6rPiXToJopF0M/U6WfxDZSKrwb70hD4LA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gnu.org header.s=fencepost-gnu-org header.b=kSV41uLC; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; dmarc=pass (policy=none) header.from=gnu.org ARC-Seal: i=1; s=key1; d=yhetil.org; t=1718380623; a=rsa-sha256; cv=none; b=QuMA2GA/FrGs1/5PaKykZzhmh5TrmeEj+BBitO+s0+I1xpWZ0J9ixJfUw8ZzsjYhEk8M64 bKNmyPeds8vZTQT7/0hC61mRHwXwrclvpi9fMeJD5P0lFQRuLogYTun6YDAnlz9iPM8UpV Z7QDePn84jDOjZwKl0ohKdpYEDqh8nmS+PMQV34bGy+7Ckyvpv2jiwix0ep80vob6Pc2ZT qmg87SJO304VgyX3Y3Lgl6O+gGOGGYxiuHEKuBSGaPaR3uQwLmjLckI4BsHM8omd0uk8bp Rt7AnW7ox+Gx8mz9gEtQFDr71ynmgsjw+YYo/QpggucgHWKb8H/PkbCetvjL2w== 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 2C44F24CE5 for ; Fri, 14 Jun 2024 17:57:02 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sI9Hk-00047R-OC; Fri, 14 Jun 2024 11:56:16 -0400 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 1sI9Hh-00043q-Ks for emacs-orgmode@gnu.org; Fri, 14 Jun 2024 11:56:14 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sI9Hf-00056p-Ur; Fri, 14 Jun 2024 11:56:12 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=WqCyDwgef6H2EFBaSQxmdXXiorGBTATEuwo2XQGUdqs=; b=kSV41uLCGkse J8+iPbxiEFJJU7JuxLnjyfSbNypfXzcaogZp/uN7zapR6a5xfd45W91ZsqfBP472UCF4B98m65fE0 Az3ww2rEQgCYOypAUJ/TQggYcxAY5JQXAQrbGkGw/1tNxcHkWWUqLQSdvkvC79+ZnOAxGD0Nl8NT6 v2pnYO9EWl9yG87z+cKC8nnTnpf5f1WlVcvSiO2wkQyVu67NB4hahJuAVMjFL8HhfOC+bkAQG0irq E5PgNU7a9jXB3E1mGOnAluvPpnahDdjXbBnKNPwnxTy2BwZUX7G2oSLPNW2a11/gPwS0PzI5nbWNb 8Nooc6GjoIjiAlaNT6qNCg==; Date: Fri, 14 Jun 2024 18:56:09 +0300 Message-Id: <861q4zy0va.fsf@gnu.org> From: Eli Zaretskii To: Ihor Radchenko Cc: emacs-orgmode@gnu.org In-Reply-To: <877cerk0bz.fsf@localhost> (message from Ihor Radchenko on Fri, 14 Jun 2024 15:31:28 +0000) Subject: Re: Please document the caching and its user options References: <86ed921oxu.fsf@gnu.org> <874j9vllbp.fsf@localhost> <86a5jny72y.fsf@gnu.org> <877cerk0bz.fsf@localhost> X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Country: US X-Migadu-Flow: FLOW_IN X-Spam-Score: -11.09 X-Migadu-Queue-Id: 2C44F24CE5 X-Migadu-Scanner: mx10.migadu.com X-Migadu-Spam-Score: -11.09 X-TUID: JwwKhO+s6Nr+ > From: Ihor Radchenko > Cc: emacs-orgmode@gnu.org > Date: Fri, 14 Jun 2024 15:31:28 +0000 > > Eli Zaretskii writes: > > >> Hmm. What aspect of caching do you want us to document? > > > > First and foremost, that it exists, and is turned on by default. The > > manual is currently completely silent about it. > > > > Next, please document the user options that control this caching, and > > especially those options which can be used to turn this caching off or > > direct it to a different place. > > I am not convinced that we have to do it. That's too bad. When a user finds out about this caching, how do you propose that he/she looks for the information about it? I wanted to know what is being cached, why, and in what file/directory. It took me quite some time to find the answers, since Org is a very large package, and there's no org-cache.el file or similar to serve as the immediate suspect. Surely, such a basic functionality should be at least hinted in the documentation, so that users new which options to look at and where? > Firstly, it is not clear if you are asking to document caching parser > state specifically or all kinds of caching Org mode does. All of them. > Secondly, I am not sure if we have to document the details of caching at > all in the manual. We do not document all the custom options in the > manual; just the most important/useful. I submit that at least the options which control where the cache is and how to disable it are important enough to be in the manual. Given their names, users can use apropos or customize-group to find other relevant options. > Emacs user manual does not document `multisession-directory' - something > very close to how we implement Org caches. So, apparently, customizing > `multisession-directory' and even the very multisession feature > existence is not deemed necessary inside Emacs manual. Why would it be > different for Org mode manual? multisession is an optional package, it is neither preloaded nor turned on by default in Emacs. And even if Emacs makes a mistake of not documenting anything it is not a valid argument to make the same mistake elsewhere. > > But why do you use utf-8 there and not utf-8-unix? Come to think > > about it, why not emacs-internal? Those files are used internally by > > Org, so they should be able to encode any characters supported by > > Emacs, not just those which have UTF-8 encoding. And using native EOL > > convention is not needed, and will get in the way if the user shares > > these files between systems. > > Mostly because we chose whatever looked reasonable. I am not 100% sure > what is the practical difference between `utf-8' and `utf-8-unix' and > why the latter should be considered better. > > As for `emacs-internal', we try to make files readable if at all > possible. In particular, index.eld file is even pretty-printed for user > convenience. The idea is to keep things in plain text and not in binary > formats, following the overall spirit how Emacs usually stores data. (I > think you may recall people raising their voice about plain text > vs. binary during the discussion of multisession feature and the use of > sqlite database). The emacs-internal encoding is not binary. In almost all the cases it is indistinguishable from utf-8-unix. It differs where a buffer includes characters outside of the Unicode codespace. The usual practice in Emacs is that files holding internal data use emacs-internal to make sure all the characters are saved correctly and can be later restored correctly.