From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1.migadu.com ([2001:41d0:303:e16b::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id KBXcNhLNmGYWUwAA62LTzQ:P1 (envelope-from ) for ; Thu, 18 Jul 2024 08:06:43 +0000 Received: from aspmx1.migadu.com ([2001:41d0:303:e16b::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1.migadu.com with LMTPS id KBXcNhLNmGYWUwAA62LTzQ (envelope-from ) for ; Thu, 18 Jul 2024 10:06:42 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=G5eKk1+Y; 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=gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1721290002; 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=7Y9ZOJH7hnWBbl+ojLp0h95jyTWkM+/stiYzfSaF5BA=; b=C60eNRiJFF6tmcgJvh3oHA8opc6wy9l5xXeSBEbzcSCuNBMgbenEQqcN8gPhj7melLK/6X QA0jq++nSTDWgT9iIeBi/9sDEY225vBZVMRtzTM45xhMBTjEk/Don9A5DifwOZyIwNsaiN EQz3RJVXTBfsGVTMuY0G05AVyfJIsDXwNIovLXq4hWCQydaWWLGVsokhZsznx/bomxAcNV TYvSLXmxSMOZA9TOt90RTms31fLXh4Ey+bc/N9Ah4Yjmt6ncLuPrrSnktG+p1aEnJuj6dG 3Fcb7GIt1iiGM3ANvsc5hWR2MMlAlmVI3s9feKNqzAXamJejuPwBcsnEJcxV8g== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=G5eKk1+Y; 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=gmail.com ARC-Seal: i=1; s=key1; d=yhetil.org; t=1721290002; a=rsa-sha256; cv=none; b=RvLQ/0z7ouZsbKj6EEFeQUOJmc8wjjZhin0IhYUN/ye2JuZQIwr+Gz8+3beUeACpqQu9zs PXLbWyG1LAEpAmEjBt+c8uYrz4CxvqaNXv6hRIlz/k5B0OVCBc5A/o0//si+ybP6W2vGLt 1aahjQU4HT6/Iy09+ycBztpXxOPN6BaQ1GQvbsfCwJmwClISNB8KHWe064xkPHT7eFNGxn HyXKSN4HsF5G/sk8B4EfibpcTAaIpKrbyWNTyENxOnQtdPVDR1I0pu+GBdw1WYiVdkFDKo wX/9td9PdWH7IgKodpKqZSILiKQBEcVf/PZgt+2yBFAtQi8SI0VklEhyv1fAfg== 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 9B87F65647 for ; Thu, 18 Jul 2024 10:06:42 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sUM9B-0003xR-Tf; Thu, 18 Jul 2024 04:05:53 -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 1sUM9A-0003xA-Ep for emacs-orgmode@gnu.org; Thu, 18 Jul 2024 04:05:52 -0400 Received: from mail-wm1-x330.google.com ([2a00:1450:4864:20::330]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1sUM98-0003O5-HR for emacs-orgmode@gnu.org; Thu, 18 Jul 2024 04:05:52 -0400 Received: by mail-wm1-x330.google.com with SMTP id 5b1f17b1804b1-4266fcb311cso222605e9.1 for ; Thu, 18 Jul 2024 01:05:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1721289948; x=1721894748; darn=gnu.org; h=content-transfer-encoding:mime-version:date:references:in-reply-to :subject:cc:to:from:message-id:from:to:cc:subject:date:message-id :reply-to; bh=7Y9ZOJH7hnWBbl+ojLp0h95jyTWkM+/stiYzfSaF5BA=; b=G5eKk1+YjJSj2Lz9C7cHsOVaL/zRtYWqqaSB8eQE67Rgy8OiuK6EMaf/L+hP1Y8pRz YMQH2M07kpXDss9CoVgZxBL4lZaB2RPzRL6sVL/z4WSnnFxNydrvmu5C+a+PvHxAIDkE ia8gdk6ysslL8UDSRlU28wnYLhdjPIt26qRdCzSS570wYLGGY9lWdmr33xqDFSuufDsn 8iZ6BpPvF5gnPZtlsBcPrajYt3B+nN67gLoKuaMv0DPTv0lS2NXGj4gNU2jRgPPb41vV krUg6BKq57OlQHZaqzRHAKBsEpv+nNrUu8XuCuXk331yamDMcdWsBjvT1JYm2bhd0DXG EJpA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1721289948; x=1721894748; h=content-transfer-encoding:mime-version:date:references:in-reply-to :subject:cc:to:from:message-id:x-gm-message-state:from:to:cc:subject :date:message-id:reply-to; bh=7Y9ZOJH7hnWBbl+ojLp0h95jyTWkM+/stiYzfSaF5BA=; b=NT5emnKSlb5kQKUHBcMSoDyNVqbG6dYmqwnprcCcCAqkrifwyOH+1lNsNBZSnhKoKj 84hWPwkdFEThzY/v8WNB+rfvgXjtC8MJOmQk2YOss0EdfjR3UUPYPCUOos3UD8QfaXO/ UowHJXfGBR/UDVmDaH95vh17ZuqdyfXne3BlxjsGMQLxrnxgLkKFJ0sRtdD360U0lMKT il0Y/2jClPyrT3EBYdvVCBWQm2LOwgacf0mTh/HTP9wZmgpEoibBN6gbLSDDQr9nCQT7 UYk8zluXdsTb9aStBlAsMhvem9IGmVDUU0+1Je55hAyE5HfCK3fbJ8Q88iExb+yijF3s fKIA== X-Gm-Message-State: AOJu0YyXVhQVGDUDWSQy//jE0UGtxm0MhyibCBqcRF3gnHsV3XsmXPQv 7Jgyw1TYUPAhhK2JPVJ89bC/kPnYWhj4AEtLk/F3bgTO6Gr6ZW4O X-Google-Smtp-Source: AGHT+IFWwpEZ8MV4xKI4/55C7C8PI2e4dpSAhQJ6W9oGkefLLcOlv+G24X55l1+VEshpcRF5PgiZ3Q== X-Received: by 2002:adf:ab04:0:b0:368:48e6:5059 with SMTP id ffacd0b85a97d-36848e65136mr1199580f8f.32.1721289948186; Thu, 18 Jul 2024 01:05:48 -0700 (PDT) Received: from keynux.home.arpa. ([2a01:e0a:505:3460:1c18:688d:ece4:372e]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-3680db038f4sm13426409f8f.94.2024.07.18.01.05.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 18 Jul 2024 01:05:47 -0700 (PDT) Message-ID: <6698ccdb.050a0220.63d89.3c1c@mx.google.com> Received: by keynux.home.arpa. (sSMTP sendmail emulation); Thu, 18 Jul 2024 10:05:46 +0200 From: Bruno Barbier To: Ihor Radchenko Cc: emacs-orgmode , Jack Kamm , Matt Subject: Re: Pending contents in org documents In-Reply-To: <87msmtflhq.fsf@localhost> References: <87o7d0mm54.fsf@localhost> <65f95bf2.050a0220.6d051.c8b1@mx.google.com> <87plvpjj76.fsf@localhost> <65fc06c1.5d0a0220.0d53.efdc@mx.google.com> <87frwjlr1a.fsf@localhost> <6601b872.050a0220.31a67.5a55@mx.google.com> <87le63c3qy.fsf@localhost> <660ed63d.050a0220.36fdd.af23@mx.google.com> <87cyqwyvgw.fsf@localhost> <66225435.5d0a0220.f60e4.c590@mx.google.com> <87r0f02vq2.fsf@localhost> <664f6f54.050a0220.10342.b002@mx.google.com> <87o78vwnds.fsf@localhost> <6658cd1f.050a0220.f6605.de1a@mx.google.com> <87jzja71n7.fsf@localhost> <665abf9f.050a0220.d2a6e.ef6b@mx.google.com> <87plsyz3rn.fsf@localhost> <666d4779.050a0220.13efd.8a2d@mx.google.com> <87ed8xi688.fsf@localhost> <668a5cc4.df0a0220.11fdd.05c1@mx.google.com> <87msmtflhq.fsf@localhost> Date: Thu, 18 Jul 2024 10:05:45 +0200 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::330; envelope-from=brubar.cs@gmail.com; helo=mail-wm1-x330.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, MSGID_FROM_MTA_HEADER=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.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-Migadu-Queue-Id: 9B87F65647 X-Migadu-Scanner: mx13.migadu.com X-Migadu-Spam-Score: -9.75 X-Spam-Score: -9.75 X-TUID: okMgjtcuoV4X Hi Ihor, Ihor Radchenko writes: > Bruno Barbier writes: > >> I added a function 'org-pending-unlock-NOW!' which unlock the region >> immediately. The uppercase "NOW!" emphasizes that it's not the >> "safe" way to unlock a region. > > I expect to see this function called by some kind of button in the > details buffer, so that users can actually call it. This function should not be used, not even in code, except to work around bugs. I would prefer not to provide a button for it. > Also, a few more small comments on the commentary section: > >> ;; The library makes locks visible to the user using text properties >> ;; and/or overlays. It diplays and updates the status while the > * displays Thanks. >> ;; If the user kills a buffer, or, kills Emacs, some locks may have to >> ;; be destroyed. The library will ask the user to confirm if an >> ;; operation requires to destroy some locks. See the field >> ;; `before-destroy-function' of REGLOCK object, if you need to do >> ;; something before a lock is destroyed. > > We should provide a user option to suppress the query. Something like > what `confirm-kill-processes' does. Maybe even support something akin > `process-query-on-exit-flag', but for reglocks. IMHO, it's the package that uses org-pending that should provide such a feature: I may not care about loosing data by ignoring on-going code block executions, but, I'll probably care if Emacs aborts some money transfers. > >> ... feel free to look at the docstrings of the >> ;; cl-defstruct `org-pending-reglock' for the full documentation. > > Maybe better refer to M-x cl-describe-type org-pending-reglock. It will > look nicer. Thanks. I didn't know how to display that documentation actually :) As this library is for developpers, I've used the syntax: (cl-describe-type 'org-pending-reglock) so that the documentation is only one click away. >> (cl-defun org-pending (region >> ... >> On receiving the outcome (a :success or :failure message, sent with >> `org-pending-send-update'), remove the region protection. Call >> ON-OUTCOME with the reglock and the outcome, from the position from >> where the REGLOCK was created. If ON-OUTCOME returns a region (a >> pair (start position . end position)), use it to report the >> success/failure using visual hints on that region. If ON-OUTCOME >> returns nothing, don't display outcome marks. > > Please describe what the default value of ON-OUTCOME (when ON-OUTCOME is > not explicitly provided) does right in the docstring. Done. >> You may set/update the following fields of your reglock to customize its >> behavior: >> - Emacs may have to destroy your locks; see the field >> `before-destroy-function' if you wish to do something before your >> lock is destroyed. >> - The user may ask Emacs to cancel your lock; see the field >> `user-cancel-function' to override the default cancel function. >> - The user may request a description of the lock; see the the field >> `insert-details-function' to add custom information when your >> lock is displayed to the user. >>=20 >> You may add/update your own properties to your reglock using the field >> `properties', which is an association list. > > Here, we may also refer to cl-describe-type for more details about the fi= elds. Done. >> ( user-cancel-function nil >> :documentation >> "Function called when the user wish to cancel this REGLOCK, >> with the REGLOCK as argument. This function must return immediately; it >> may, asynchronously, stop some processing and release resources; and, >> once this is done, it should send the outcome to the REGLOCK (using >> `org-pending-send-update', so that the region is unlocked and the >> REGLOCK destroyed). The default value is >> `org-pending--user-cancel-default'" ) > > How come the default value is `org-pending--user-cancel-default' when it > is nil? The only way to build a lock is to use the function 'org-pending'; and that function was setting it to that value. I've moved the setting to the defstruct definition. >> (cl-defstruct (org-pending-reglock >> ... > > It would be nice to define slot types for each slot. I added that to my todo list: I'll have to learn how to write types in elisp (or common lisp?) to be able to do that (... the very bottom of my list :) ) >> insert-details-function nil >> When non-nil, function called to insert custom details at the end of >> =E2=80=98org-pending-describe-reglock=E2=80=99. The function is cal= led with a REGLOCK, >> a START position and an END position, it must insert details at >> point. Assuming B is a (virtual) buffer containing all detailed human >> readable information, insert at point details from START to END. Ha= ndle >> cases where START, END are nil or out of bounds without raising an >> error. The function may use text properties, overlays, etc. See >> =E2=80=98org-pending-describe-reglock=E2=80=99 > > From this description, my understanding is that the existing text > between START and END must be replaced? Or is it something else? No. That description says: "it must insert details at point." > It is > also not clear what the custom function is supposed to do when START/END > are nil. > > I looked up the docstring of `org-pending-describe-reglock', but it does > not contain anything useful wrt setting insert-details-function slot. Yeah ... that feature was smelling more and more like an overdesign :) I'm dropping that feature altogether: no more start/end; problem solved ;) For the record, the idea was to allow to insert a small view from a 10GB log; i.e. to insert *at point* in the description buffer, the text that begins at START in that log file and ends at END in that log file; the current default implementation would just display the first few lines. That API would allow: 1. to configure how much is displayed, 2. to display the tail if needed, 2. and even to implement paging. As I removed the feature, the org-pending user is now responsible to insert at point only a reasonable amount of text. I've pushed the changes to my repository. Thanks again for the review. Bruno