From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id 2N3LGauNAGO+oAAAbAwnHQ (envelope-from ) for ; Sat, 20 Aug 2022 09:30:51 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id 8APFGauNAGNDVwEAauVa8A (envelope-from ) for ; Sat, 20 Aug 2022 09:30:51 +0200 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 EB9E22287F for ; Sat, 20 Aug 2022 09:30:50 +0200 (CEST) Received: from localhost ([::1]:39438 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oPIwT-0004Wv-6q for larch@yhetil.org; Sat, 20 Aug 2022 03:30:49 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:45088) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oPIuL-0004Ti-E8 for emacs-orgmode@gnu.org; Sat, 20 Aug 2022 03:28:37 -0400 Received: from mail-pj1-x1036.google.com ([2607:f8b0:4864:20::1036]:36457) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oPIuJ-0004c1-6P for emacs-orgmode@gnu.org; Sat, 20 Aug 2022 03:28:36 -0400 Received: by mail-pj1-x1036.google.com with SMTP id r14-20020a17090a4dce00b001faa76931beso9447855pjl.1 for ; Sat, 20 Aug 2022 00:28:34 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:from:to:cc; bh=PYf20uQrMqKL/+Rbmc7jOruuoIqpYC4vMfNCsXX4uvQ=; b=UTIgdPqGFzqDx1LLR78yVOyYsK1CxYEa7sjSHdUOyBDHqwqwvBmGwrc/duYEV2aQ1d eoC1Aifz4bKGJGqayGGoNt6CvsMa+wN3cHcdsLBeZ1uPztWezKmXJnStAk6YHpOLEgSA 8nnRPcVyHoVNw903G8CUhcXO822DMu4hW8755pIVnUdyv1+yA6IBn6mFVAb+JGsKoNDk BSitQC4Dcb23PU/lmQ8ueKuuFvVeEWVZofl9WDciOfUvN6StBOsIZqEjTr3Qq28nEmsK wq2zYopB349Sp+141RFKUdyKuC2U4lkOZcq6dzJko8LLXoWdnhJGWyCzHTGGwaHp4FzG fp3w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:x-gm-message-state:from:to:cc; bh=PYf20uQrMqKL/+Rbmc7jOruuoIqpYC4vMfNCsXX4uvQ=; b=Y5IeoaLxNsdTRSG7NQbeBJhooJVOMFoneEn5zrdwk3hK5jMtyQfegz7qvhKOW+69Vi FlWbtTYzRFGvb2qiExKPcMVMHs00JqJfl0gGci2fPqYNkAFLuMFV/okebjZpmZRxfbX8 PnSPnsvnuui67CRBhbiAYC6L/W7Vmh/fWF6B9bag5kG+N+432M3l4BiBDB9S/eZrNLsH MLQAomwgI4yOaChQshfTueGWXnRp4g5mzlUY/aNODq8W4KeTyiIN2nVNeye0lijjdEmg Lyl0yObUfqDnW8w9/8DVauSU1JI4om/mZJ1NJ1aQKfM7ow1cj2wgwZrYcxL0XvIvIWOR x6Vw== X-Gm-Message-State: ACgBeo1XFv/rl/ybQwCd3/fqyocP9fxuJEEkigYGo/VD5baOksY0ct51 kTTK4IwylbMq55+WY1TWr1M= X-Google-Smtp-Source: AA6agR49rAPVTFe8mSQgoqm+dxi+HitFwOQ5nlmPxthCnAbQvg1+mR1tpj8UREFMY8Eu+AwCSK7Edw== X-Received: by 2002:a17:90a:6001:b0:1fa:e851:3480 with SMTP id y1-20020a17090a600100b001fae8513480mr6485769pji.153.1660980513687; Sat, 20 Aug 2022 00:28:33 -0700 (PDT) Received: from localhost ([2409:8a70:2b9:1e80:8ec6:81ff:fe70:339d]) by smtp.gmail.com with ESMTPSA id x24-20020a17090a789800b001f312e7665asm4202686pjk.47.2022.08.20.00.28.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 20 Aug 2022 00:28:33 -0700 (PDT) From: Ihor Radchenko To: Max Nikulin Cc: emacs-orgmode@gnu.org Subject: Re: [PATCH v2] ol-info: Define :insert-description function In-Reply-To: References: <87zgl1npow.fsf@localhost> <87tu7gkb4l.fsf@heagren.com> <87y1ws6o0c.fsf@localhost> <87k08bjw0t.fsf@heagren.com> <47248a4f-10aa-0980-c054-563f30c05aaa@gmail.com> <87mtd0gthe.fsf@heagren.com> <78b97c9e-fced-0ee4-f3f2-3cbe81080ffa@gmail.com> <87sfms9dx7.fsf@localhost> <87v8rmd53g.fsf@localhost> <871qu9xv8q.fsf@heagren.com> <0da49392-26c6-8ba3-f657-647522d59342@gmail.com> <87zggrg2om.fsf@heagren.com> <87edy3t8o0.fsf@localhost> <87tu6zf2o1.fsf@heagren.com> <871qu3rpt9.fsf@localhost> <8bbccdb4-52f4-b9b5-eb10-252bb15108ec@gmail.com> <87a68hn9es.fsf@localhost> <87zgg0q2kz.fsf@localhost> Date: Sat, 20 Aug 2022 15:29:26 +0800 Message-ID: <877d33nzjd.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=2607:f8b0:4864:20::1036; envelope-from=yantar92@gmail.com; helo=mail-pj1-x1036.google.com X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 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_ENVFROM_END_DIGIT=0.25, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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" X-Migadu-Flow: FLOW_IN X-Migadu-To: larch@yhetil.org X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1660980651; 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:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=PYf20uQrMqKL/+Rbmc7jOruuoIqpYC4vMfNCsXX4uvQ=; b=ahOyrZRE/0TNbY+EmPs5ciiuO+AJgak0EOK8YCy35fEy+oWUYfARt9awhFQ09nxX6w0nO9 iZMmmF45VlHrCGAiYwg/5YiR+2wWDAk2aaFYkk9z7kA8t0xzRHYBCDHZptv7tdcuqaSXjv i+sMCuvQAgeH0LWUxgZU9Pnh7yDqdSNpCnwasZWmZdG2w5QUklsqED6xJ3fVjCDowxz65h 6W2tzv2jLUW301ZlSZFHJ7slyNgf5s6uyVnCyCncFDFCujB8G2pX4M97xrATYlT+jMCTSl 1kbdLTpVB7x0lXbPpPcRjNs2aDdUfFUhZoN6XfLDag5b1za7Eu6jZLQy3mivsg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1660980651; a=rsa-sha256; cv=none; b=RJhtzPMLtJnLstE5tu00zxDeMLoEfGy8/e6phcg3wuoqTczIF23+xoKGKeLvgGbv3e3ylk QuSgFzwrh2/zcY/STseYxId+zoTjrPh4+nBGmEYYUt63MhKgIh1fVUhVlA/grw0xtA/58U 6lGcl0wz08FzId3+CZPldAqCMsWJTcMRFPQG4AnqE1716+Q/L04dGLDQ2p+wYrxOdX3T6/ rtssjic+8B5oPeocS4GPgkqFl/8CPHx9ZUIzN4NvBOoSqYocPTUwJMKIw1CSoZ+IDhFXWg D2CQUu+S9XrKrjxcfMMbgBm0Nh2LXqm35smBrp/C9GoA2DLBfsYUggTgpPWG5A== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=UTIgdPqG; dmarc=pass (policy=none) header.from=gmail.com; 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" X-Migadu-Spam-Score: -5.15 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=UTIgdPqG; dmarc=pass (policy=none) header.from=gmail.com; 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" X-Migadu-Queue-Id: EB9E22287F X-Spam-Score: -5.15 X-Migadu-Scanner: scn0.migadu.com X-TUID: is4y9s3OHKLy Max Nikulin writes: > On 19/08/2022 11:28, Ihor Radchenko wrote: >> Max Nikulin writes: >> >>> +(defun org-info--link-file-node (path) >>> + "Extract file name and node from info link PATH. >>> + >>> +Return cons consisting of file name and node name or \"Top\" if node >>> +part is not specified. Components may be separated by \":\" or by \"#\"." >> >> It looks like the docstring does not match what the function actually >> returns. > > It returns a cons, doesn't it? Is it confusing that separator for > components is related to the argument? It is confusing that cons consist of _file name_ and node name. However, the function may return non-file as car of the cons. >>> + (if (not path) >>> + '("dir" . "Top") >> >> "dir" is not a file. Also, it is not very clear what "dir" is referring >> to. Maybe you can add a comment pointing to `org-info-other-documents'? > > Try M-x info RET when you do not have *info* buffer and you get "(dir) > Top" node. It is the directory of info files. If you run "info" without > argument in shell you will get the same. Sure. I know this. But see the above. Not every person reading the Org source is familiar with info conventions. >>> + (string-match "\\`\\([^#:]*\\)\\(?:[#:]:?\\(.*\\)\\)?\\'" path) >>> + (let* ((node (match-string 2 path)) >>> + ;; `string-trim' modifies match >> >> Here and is several other places, including docstrings, please make sure >> that the sentences end with "." and are separated with " ". > > It was supposed to be a brief phrase rather than complete sentence. What about other places like the docstring? Or + ;; Unlike (info "dir"), "info dir" shell command opens "(coreutils)dir invocation" (missing ".") probably some more places. (Of course, this is minor, and I could do it myself; just pointed this together with other more important comments) >>> + (cons >>> + ;; Fallback to "org" is an arbirtrary choice >>> + ;; and added because "(dir)filename" does not work as "filename". >> >> Should this be documented? Or at least mentioned that the behaviour is >> undefined. And if it is undefined you should not test it in the tests. > > The purpose of test is to check that it does not signal some obscure > error. I am unsure how to handle corner cases, so I am open to > suggestions. Some considerations > - `org-info--link-file-node' may return nil when link path is incomplete > or some value that may help to avoid error handling code paths in callers. > - does not look like a valid link but it may be handled like > shell "info" command without argument, so I chose "(dir)" node. Elisp > (info) without arguments however may display existing buffer. > - certainly should be handled as (info "(dir)") > - is invalid. Maybe (info "elisp") should be used instead. > - I am unsure in my choice to open (info "(org) Tables"). > Maybe it is better to treat it as "(dir) Tables" and so as "(dir) Top" > node since "(dir) Top" is quite reasonable for with empty path. I am not sure what would be the best here. The main point - whatever fallback mechanism you choose, please document it in the docstring. In general, I favour having a fallback more compared to not having any. -- Ihor Radchenko, Org mode contributor, Learn more about Org mode at https://orgmode.org/. Support Org development at https://liberapay.com/org-mode, or support my work at https://liberapay.com/yantar92