From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id sM+hFTt932LqVAAAbAwnHQ (envelope-from ) for ; Tue, 26 Jul 2022 07:35:55 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id uK1hFTt932JLBwEAauVa8A (envelope-from ) for ; Tue, 26 Jul 2022 07:35:55 +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 E1AAE3E66D for ; Tue, 26 Jul 2022 07:35:54 +0200 (CEST) Received: from localhost ([::1]:53700 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oGDEX-0000r5-Ig for larch@yhetil.org; Tue, 26 Jul 2022 01:35:53 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:53118) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oGDDl-0000qx-Jf for emacs-orgmode@gnu.org; Tue, 26 Jul 2022 01:35:07 -0400 Received: from mail-pj1-x102b.google.com ([2607:f8b0:4864:20::102b]:36518) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oGDDg-0006up-Lw for emacs-orgmode@gnu.org; Tue, 26 Jul 2022 01:35:05 -0400 Received: by mail-pj1-x102b.google.com with SMTP id t3-20020a17090a3b4300b001f21eb7e8b0so15721102pjf.1 for ; Mon, 25 Jul 2022 22:34:57 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:in-reply-to:references:date:message-id :mime-version:content-transfer-encoding; bh=KuuOhMz91OqyjmFKgzSGTzXESpDArGMvBqlv9J5MhcM=; b=Z7yGTRXEWO4soGBldef17BpxtcT1JgWboYDy8qJrxy30WIGZozUUsUQ4/Hdfvhb/dE lLxaoFsd4EUrefGmX6A5s9wwxKy99V51LPHEU5+T7rwkACNUAPvP+wZf7n7crQIRcHgq pE3GS8TZkLhqcfVu72GUjq+se+ehvZVg4nk4+KQm+tGxNXrhvfLWRdUMB1x0rLqrABcj JdEyDb3IZIxeyPt8UBBpIb0CAz8UBuCUNwgyqaBKgvX2b1MNqz/bfhDj5U68ZCpMTUOv 8WJBAsOtcCT8cyVn40mupcKzDpDHV+39bEUziKRhLvQpRfMqTcCrRDpJSCdrw5yj8fdw TheA== 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:in-reply-to:references:date :message-id:mime-version:content-transfer-encoding; bh=KuuOhMz91OqyjmFKgzSGTzXESpDArGMvBqlv9J5MhcM=; b=XUbQxhtLIvrd2F+MP3m2u5lbNY20zWNJ7H3hgrHP6j7Kex+MundB1ZoJSzi9etvTaI o2x8o8bcLg+SHGpm+gD+6XS1D/V9z+1Po4XqOuC4PRxcUpl4ls27sX7qtMr1kwOa1nN+ iEEeU40SzzYDzg2v9LF3IFVQm18ThCSBDK20VQ5TJJL2KL4IygdkzthIGb67Hl7MHg26 s8um1EYbVHBN0WYUDkeG5xi/DxHXuPWZvByflzX0A+miXtDaB19eNJIK80FLa6H/CYXs Ojm7gADdhdUi25qQyxE2jVL70Xo7FVk3H6TRmYD4v7ksHaVFzKbBcenozZst479PCeSX mweg== X-Gm-Message-State: AJIora+Pf8vg5sakeJAFGXvDUNidmw03VX2vTSiBbWNRawntU++Q0EPI J2wHTR5+ObfoS/SwCGcEuWA= X-Google-Smtp-Source: AGRyM1t8t3BtQ8+CZAqMADgvX8VZgM1v1ck4lMvchUjLDSS+h5gMTxitMKq9+MBRzqe6qnvfTp/usw== X-Received: by 2002:a17:90a:2a0d:b0:1f2:aed:ce18 with SMTP id i13-20020a17090a2a0d00b001f20aedce18mr17527516pjd.91.1658813695419; Mon, 25 Jul 2022 22:34:55 -0700 (PDT) Received: from localhost ([115.154.175.57]) by smtp.gmail.com with ESMTPSA id l9-20020a170903120900b0016d1bee1519sm10346266plh.102.2022.07.25.22.34.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 25 Jul 2022 22:34:54 -0700 (PDT) From: Ihor Radchenko To: Juan Manuel =?utf-8?Q?Mac=C3=ADas?= Cc: orgmode Subject: Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments' In-Reply-To: <87czdt3yk3.fsf@posteo.net> References: <87o7z0tltj.fsf@posteo.net> <87bkuzdahc.fsf@localhost> <87wndna1lp.fsf@posteo.net> <87y1xzq4k9.fsf@localhost> <87o7yvlctx.fsf@posteo.net> <87y1xzwjar.fsf@localhost> <87k086h96l.fsf@posteo.net> <878rohuxij.fsf@localhost> <87czdt3yk3.fsf@posteo.net> Date: Tue, 26 Jul 2022 13:35:59 +0800 Message-ID: <87czdscu68.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=2607:f8b0:4864:20::102b; envelope-from=yantar92@gmail.com; helo=mail-pj1-x102b.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=1658813755; 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=KuuOhMz91OqyjmFKgzSGTzXESpDArGMvBqlv9J5MhcM=; b=q0XazEG/o9Blzi0+r3S5RN5dZzUtZh5eYLW5sVl8abKU7O2qqVNsiVCuCax5MVZwoPDXpZ 50cNfo4x0jkTwmsIUm2lta63ApJNfSBTb3KSCu+Mmhupbc15AmAdY8m0fn4OQOKKXBcEcO bqJm4LNJw5JCAP51uVy+NyziKn2G5bdYHlgDQhUXWdtp+MvIb4GDC9NILNFbgiAQ3dU4Ox Dzvhyb2ens96Kqbki8BV1E/uCJ9wF3QGMN4pS2EueKPHHJymtiOsuYNfnk9fxAYSl9daRq dup8muvbeaHJd7N3fLDNhURJ4gRwEk0FgqQ27ho76tG1Ux98rBKmXrE97GjCkQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1658813755; a=rsa-sha256; cv=none; b=CNiwRivjQNXw+aMj2Sj2kKywXBmgV4S9SRqnCzAAvY03O7T2H9L2yqDBrMzD7MN33tnR/1 0yTZrEOLIGGTpqChFhcPo3Y0g3VXGD4M242igjkg2jl7M8U2UGfA8KihrLKXdHMzgbZvdU MWul6YT6dpwjkNyTP0wMaf2aCmt1vBk3ZhNID7fMaU2yT8jBqmozY60tuylF7KylRyAZxA WeeIm7oKIbwZ5VrpJbGUIf7Y602XyHo8WmzFAHa1iPWg0sB0SaguQ9t6a8NKe4XBxfF3U6 HL5fsAssY8v6ez+k4xZPwjJ6QRcR+dcabC9i6t6RzK/42p7VBqz5qY+6l2oOGA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=Z7yGTRXE; 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: -4.93 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=Z7yGTRXE; 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: E1AAE3E66D X-Spam-Score: -4.93 X-Migadu-Scanner: scn0.migadu.com X-TUID: VrbHO31jQgkx Juan Manuel Mac=C3=ADas writes: > Ihor Radchenko writes: > >>> - (org-back-to-heading t) ; Sets match data >>> - (match-end 0)) >>> + (re-search-backward org-heading-regexp) ; Sets match data >>> + (match-beginning 0)) >> >> This will err when the source block is before the first headline in the >> document. > > I've reverted the first line to (org-back-to-heading t), keeping the > (match-beginning 0), otherwise you don't get the full headline and all > property drawers would be exported. But it's strange, it doesn't give me > any error when the source block is before the first headline in the > document. Isn't that error prevented with this: > > (condition-case nil > ...=09=09=20=20=20 > (error (point-min))) > > ? Hmm. You are indeed right. I missed the condition-case part. In any case, re-search-backward is not reliable when you have inlinetasks. > By the way, I've noticed that it's not convenient to export numbered > headers, so I've modified org-babel-export-comment-text-as-plain-text so > that it removes header numbering. I don't know if it's ok to do it this > way... The path you took is indeed a bit awkward. You may need to use the approach similar to orgtbl-to-latex. Also, things to watch are org-export-exclude-tags, org-export-with-section-numbers, org-export-with-archived-trees, org-export-with-broken-links (we don't want tangle to fail because of broken links), org-export-with-inlinetasks, org-export-with-toc, and org-export-with-tasks. > +(defun org-babel-export-comment-text-as-plain-text (text) > + "Function to process raw Org TEXT collected to be inserted as > +comments in tangled source-code files. This function is the > +default value for `org-babel-process-comment-text'." > + ;; Ensure that if TEXT is a header it is not numbered. > + (let ((text-nonum (with-temp-buffer > + (insert text) > + (when (not (org-entry-get nil "UNNUMBERED")) > + (org-entry-put nil "UNNUMBERED" "t")) > + (buffer-string)))) > + (org-export-string-as text-nonum 'ascii t))) "Function to" can be safely dropped. See D.6 Tips for Documentation Strings in Elisp manual: =E2=80=A2 The first line of the documentation string should consist of o= ne or two complete sentences that stand on their own as a summary. =E2=80= =98M-x apropos=E2=80=99 displays just the first line, and if that line=E2=80= =99s contents don=E2=80=99t stand on their own, the result looks bad. In particular, start the first line with a capital letter and end it with a period. For a function, the first line should briefly answer the question, =E2=80=9CWhat does this function do?=E2=80=9D For a variable, the firs= t line should briefly answer the question, =E2=80=9CWhat does this value mean?=E2=80= =9D Don=E2=80=99t limit the documentation string to one line; use as many = lines as you need to explain the details of how to use the function or variable. Please use complete sentences for the rest of the text too. =E2=80=A2 The first line should mention all the important arguments of t= he function, and should mention them in the order that they are written in a function call. If the function has many arguments, then it is not feasible to mention them all in the first line; in that case, the first line should mention the first few arguments, including the most important arguments. =E2=80=A2 For consistency, phrase the verb in the first sentence of a function=E2=80=99s documentation string as an imperative=E2=80=94for i= nstance, use =E2=80=9CReturn the cons of A and B.=E2=80=9D in preference to =E2=80= =9CReturns the cons of A and B.=E2=80=9D Usually it looks good to do likewise for the rest of= the first paragraph. Subsequent paragraphs usually look better if each sentence is indicative and has a proper subject. Best, Ihor