[Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Juan Manuel Macías]

[-- Attachment #1: Type: text/plain, Size: 264 bytes --]

Hi,

With this new value, comments are passed to the source file as plain
text, without the org metadata (keywords, property drawers, etc.).

As usual, feedback and suggestions for this patch are greatly appreciated.

Best regards and happy weekend,

Juan Manuel


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-ob-tangle.el-add-the-ascii-value-to-the-comment.patch --]
[-- Type: text/x-patch, Size: 2671 bytes --]

From 414e0b3a18abca34bc47f07e55debec0910d4728 Mon Sep 17 00:00:00 2001
From: Juan Manuel Macias <maciaschain@posteo.net>
Date: Fri, 10 Jun 2022 20:12:37 +0200
Subject: [PATCH] lisp/ob-tangle.el: add the `ascii' value to the `comments'
 head. arg.

* (org-babel-tangle-single-block): With the value ascii the comments
are passed as plain text. This is useful for removing all org
metadata from the source file's comments.
---
 lisp/ob-tangle.el | 53 ++++++++++++++++++++++++++++++++---------------
 1 file changed, 36 insertions(+), 17 deletions(-)

diff --git a/lisp/ob-tangle.el b/lisp/ob-tangle.el
index 6685a1599..aed241416 100644
--- a/lisp/ob-tangle.el
+++ b/lisp/ob-tangle.el
@@ -525,23 +525,42 @@ non-nil, return the full association list to be used by
 	      (run-hooks 'org-babel-tangle-body-hook)
 	      (buffer-string))))
 	 (comment
-	  (when (or (string= "both" (cdr (assq :comments params)))
-		    (string= "org" (cdr (assq :comments params))))
-	    ;; From the previous heading or code-block end
-	    (funcall
-	     org-babel-process-comment-text
-	     (buffer-substring
-	      (max (condition-case nil
-		       (save-excursion
-			 (org-back-to-heading t) ; Sets match data
-			 (match-end 0))
-		     (error (point-min)))
-		   (save-excursion
-		     (if (re-search-backward
-			  org-babel-src-block-regexp nil t)
-			 (match-end 0)
-		       (point-min))))
-	      (point)))))
+	  (cond ((or (string= "both" (cdr (assq :comments params)))
+		     (string= "org" (cdr (assq :comments params))))
+		 ;; From the previous heading or code-block end
+		 (funcall
+		  org-babel-process-comment-text
+		  (buffer-substring
+		   (max (condition-case nil
+			    (save-excursion
+			      (org-back-to-heading t) ; Sets match data
+			      (match-end 0))
+			  (error (point-min)))
+			(save-excursion
+			  (if (re-search-backward
+			       org-babel-src-block-regexp nil t)
+			      (match-end 0)
+			    (point-min))))
+		   (point))))
+		((string= "ascii" (cdr (assq :comments params)))
+		 ;; From the previous heading or code-block end
+		 (let ((org-babel-process-comment-text
+			(lambda (str)
+			  (org-export-string-as str 'ascii t))))
+		   (funcall
+		    org-babel-process-comment-text
+		    (buffer-substring
+		     (max (condition-case nil
+			      (save-excursion
+				(org-back-to-heading t) ; Sets match data
+				(match-beginning 0))
+			    (error (point-min)))
+			  (save-excursion
+			    (if (re-search-backward
+				 org-babel-src-block-regexp nil t)
+				(match-beginning 0)
+			      (point-min))))
+		     (point)))))))
          (src-tfile (cdr (assq :tangle params)))
 	 (result
 	  (list start-line
-- 
2.36.1

Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

> With this new value, comments are passed to the source file as plain
> text, without the org metadata (keywords, property drawers, etc.).
>
> As usual, feedback and suggestions for this patch are greatly appreciated.
>
> Best regards and happy weekend,

Thanks for the patch!
Wouldn't it be better to supply a customization for
org-babel-process-comment-text instead?

I do not feel that per-src-block control on the comment type makes much
sense here.

Best,
Ihor

Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Juan Manuel Macías]

Hi, Ihor, thanks for your comments,

Ihor Radchenko writes:

> Wouldn't it be better to supply a customization for
> org-babel-process-comment-text instead?
>
> I do not feel that per-src-block control on the comment type makes much
> sense here.

My first approach was actually to define some options for
org-babel-process-comment. But I noticed that a header with properties,
for example:

* Header
  :PROPERTIES:
  :FOO:      var
  :END:

is interpreted as:

;; Header
;; :FOO: var

I think the culprit is the '(match-end 0)' in
org-babel-tangle-single-block:

...
(comment
	  (when (or (string= "both" (cdr (assq :comments params)))
		    (string= "org" (cdr (assq :comments params))))
	    ;; From the previous heading or code-block end
	    (funcall
	     org-babel-process-comment-text
	     (buffer-substring
	      (max (condition-case nil
		       (save-excursion
			 (org-back-to-heading t) ; Sets match data
			 (match-end 0)) ;; <=========
		     (error (point-min)))
		   (save-excursion
		     (if (re-search-backward
			  org-babel-src-block-regexp nil t)
			 (match-end 0)  ;; <=========
		       (point-min))))
	      (point)))))
...

So I couldn't think of any other solution than to put the change there,
so as not to break backwards compatibility. But it is a somewhat tricky
solution...

Best regards,

Juan Manuel 

Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Rudolf Adamkovič]

Juan Manuel Macías <maciaschain@posteo.net> writes:

> As usual, feedback and suggestions for this patch are greatly
> appreciated.

Juan, hi!

I do not understand the meaning of ASCII.  How will such comments look
like?  Will they include at least the file name?  If so, those can
contain Unicode characters, right?

Rudy
-- 
"Thinking is a momentary dismissal of irrelevancies."
-- Richard Buckminster Fuller, 1969

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Juan Manuel Macías]

Hi, Rudolph, thanks for your comments,

Rudolf Adamkovič writes:

> Juan, hi!
>
> I do not understand the meaning of ASCII.  How will such comments look
> like?  Will they include at least the file name?  If so, those can
> contain Unicode characters, right?

The main motivation for proposing this new option is that when I choose
the ':comments org' option, all the Org metadata that is close to the
code block in my org file are 'preserved', so comments in the source
file are somewhat awkward to read (as simple comments). My idea is that
with this new option the comments pass as plain text, without property
drawers, keywords, etc.

For example, that a header like this:

------------------------------------
* Variables
  :PROPERTIES:
  :foo:      var
  :END:

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec
hendrerit tempor tellus. Donec pretium posuere tellus.
------------------------------------

does not pass to the source file like this:

------------------------------------
;; Variables
;;   :PROPERTIES:
;;   :foo:      var
;;   :END:
;; Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec
;; hendrerit tempor tellus. Donec pretium posuere tellus.
------------------------------------

but in this way:

------------------------------------
;; Variables
;; ==========
;; Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec
;; hendrerit tempor tellus. Donec pretium posuere tellus.
------------------------------------

Best regards,

Juan Manuel

Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Rudolf Adamkovič]

Juan Manuel Macías <maciaschain@posteo.net> writes:

> but in this way:
>
> ------------------------------------
> ;; Variables
> ;; ==========
> ;; Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec
> ;; hendrerit tempor tellus. Donec pretium posuere tellus.
> ------------------------------------

Hello again, Juan!

Oh, I see.  Thank you for the explanation.  I can see myself using such
new tangle comments all the time!  But then, I use UTF-8 and not the
standard 7-bit ASCII for my Org documents.  Hence, I would want to see
':comments plain' or ':comments plain-text' instead.

Rudy
-- 
"Genius is 1% inspiration and 99% perspiration."
-- Thomas Alva Edison, 1932

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Juan Manuel Macías]

Hi, Rudolph,

Rudolf Adamkovič writes:

> Oh, I see.  Thank you for the explanation.  I can see myself using such
> new tangle comments all the time!  But then, I use UTF-8 and not the
> standard 7-bit ASCII for my Org documents.  Hence, I would want to see
> ':comments plain' or ':comments plain-text' instead.

What you comment makes sense, because `ascii' can lead to confusion. I
chose the term `ascii' because the backend used to convert the text is
called `ascii', although if I evaluate something like

(org-export-string-as "αβγδ" 'ascii t)

the result is utf8.

I think it might be a good idea to use `plain' for the value name, as
you say, instead of `ascii'...

Best regards,

Juan Manuel 

Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

> My first approach was actually to define some options for
> org-babel-process-comment. But I noticed that a header with properties,
> for example:
> ...
>
> I think the culprit is the '(match-end 0)' in
> org-babel-tangle-single-block:
>
> ...
> 			 (org-back-to-heading t) ; Sets match data
> 			 (match-end 0)) ;; <=========
> 		     (error (point-min)))

I think that the existing code can be improved. Relying on the
undocumented behavior of (org-back-to-heading) is not ideal. Not to
mention code blocks before first headline.

It would be great if you rewrite the existing code to suite both the
defaults and the proposed behavior.

Best,
Ihor

Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Juan Manuel Macías]

Ihor Radchenko writes:

> I think that the existing code can be improved. Relying on the
> undocumented behavior of (org-back-to-heading) is not ideal. Not to
> mention code blocks before first headline.
>
> It would be great if you rewrite the existing code to suite both the
> defaults and the proposed behavior.

Yes, I agree that this needs a more robust approach. Also, I've noticed
that the patch I've proposed has a rather silly bug: replacing the
second `match-end 0' with `match-beginning 0' naturally causes
intermediate code blocks to be exported as comments (!). Returning it to
`match-end 0' everything is OK, but the present approach is still
tricky.

I'm going to see if I can try something cleaner these days. Ideally,
everything should be controlled from org-babel-process-comment-text...

On the other hand, I have a curiosity. I understand that the behavior of
the `:comments org' option should be left intact to ensure backwards
compatibility. But I've always wondered if there is any use case where
this value, as it behaves, might be practical. I don't quite understand
how useful all the Org metadata in the comments of the tangled file can
be. The expectation with `:comments org' is that only the content of the
Org document will be rendered (as comments), but not its metadata, that
all they do is unnecessarily fatten up the source file. I'm thinking,
for example, of headers with lots of properties. or comment blocks,
which would be visible in the tangled source file:

┌────
│ ;;   Header
│ ;;   :PROPERTIES:
│ ;;   :A_LOT_OF: properties
│ ;;   :END:
│ 
│ ;; #+begin_comment
│ ;; Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec hendrerit tempor tellus.
│ ;; Donec pretium posuere tellus. Proin quam nisl, tincidunt et, mattis eget, convallis nec,
│ ;; purus. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus
│ ;; mus. Nulla posuere. Donec vitae dolor. Nullam tristique diam non turpis. Cras placerat
│ ;; accumsan nulla. Nullam rutrum. Nam vestibulum accumsan nisl.
│ ;; #+end_comment
└────

Best regards,

Juan Manuel 

Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

> On the other hand, I have a curiosity. I understand that the behavior of
> the `:comments org' option should be left intact to ensure backwards
> compatibility. But I've always wondered if there is any use case where
> this value, as it behaves, might be practical. I don't quite understand
> how useful all the Org metadata in the comments of the tangled file can
> be. The expectation with `:comments org' is that only the content of the
> Org document will be rendered (as comments), but not its metadata, that
> all they do is unnecessarily fatten up the source file. I'm thinking,
> for example, of headers with lots of properties. or comment blocks,
> which would be visible in the tangled source file:

The original proposal by Eric Schulte:
https://list.orgmode.org/4BFFEE4F.5010608@ccbr.umn.edu/
>>> Maybe we should allow either exporting just the headlines of the
>>> org-mode file or exporting the entire org-mode file -- possibly after an
>>> ASCII export -- this would have the effect of prefixing every line in
>>> the org-mode file behind a comment *except* for the tangled source-code
>>> blocks.

Clearly, the "possible after an ASCII export" dropped somewhere in the
middle.

Best,
Ihor

Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Juan Manuel Macías]

Ihor Radchenko writes:

> The original proposal by Eric Schulte:
> https://list.orgmode.org/4BFFEE4F.5010608@ccbr.umn.edu/
>>>> Maybe we should allow either exporting just the headlines of the
>>>> org-mode file or exporting the entire org-mode file -- possibly after an
>>>> ASCII export -- this would have the effect of prefixing every line in
>>>> the org-mode file behind a comment *except* for the tangled source-code
>>>> blocks.
>
> Clearly, the "possible after an ASCII export" dropped somewhere in the
> middle.

I see... Thanks for the clarification! So it seems that the current
behavior of ':comments org' is no more than a fluke, rather than
intentional. One possibility that occurs to me, instead of adding a new
value to ':comments', would be to 'return' ASCII export for the
:comments org value, and leave it that way by default. And add an
option, of course, for recover the old value. It could be done from
org-babel-process-comment-text, and then redo some lines in
org-babel-tangle-single-block, as we discussed in the other mail. I
think it would be cleaner that way, but I don't know if this would be
too groundbreaking...

Best regards,

Juan Manuel 

Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Juan Manuel Macías]

[-- Attachment #1: Type: text/plain, Size: 687 bytes --]

Ihor Radchenko writes:

> The original proposal by Eric Schulte:
> https://list.orgmode.org/4BFFEE4F.5010608@ccbr.umn.edu/
>>>> Maybe we should allow either exporting just the headlines of the
>>>> org-mode file or exporting the entire org-mode file -- possibly after an
>>>> ASCII export -- this would have the effect of prefixing every line in
>>>> the org-mode file behind a comment *except* for the tangled source-code
>>>> blocks.
>
> Clearly, the "possible after an ASCII export" dropped somewhere in the
> middle.

New version of the patch attached.

`:comments org' now produces by default plain text comments previously
exported to ascii from org.

Best regards,

Juan Manuel 


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-ob-tangle.el-The-org-value-for-comments-is-now-.patch --]
[-- Type: text/x-patch, Size: 2516 bytes --]

From 7095cb5d547bfe9f0576418e71317ad3ebeade77 Mon Sep 17 00:00:00 2001
From: Juan Manuel Macias <maciaschain@posteo.net>
Date: Thu, 21 Jul 2022 13:47:23 +0200
Subject: [PATCH] lisp/ob-tangle.el: The `org' value for `:comments' is now
 plain text

* org-babel-process-comment-text:
`org-babel-export-comment-text-as-plain-text' function is added as a
new default value, which exports the raw Org text as plain text.  This
is useful for removing all org metadata from the source file's
comments.
---
 lisp/ob-tangle.el | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/lisp/ob-tangle.el b/lisp/ob-tangle.el
index f4fb2af71..aba87ef13 100644
--- a/lisp/ob-tangle.el
+++ b/lisp/ob-tangle.el
@@ -134,11 +134,12 @@ of tangled comments."
   :group 'org-babel
   :type 'boolean)
 
-(defcustom org-babel-process-comment-text 'org-remove-indentation
-  "Function called to process raw Org text collected to be
-inserted as comments in tangled source-code files.  The function
-should take a single string argument and return a string
-result.  The default value is `org-remove-indentation'."
+(defcustom org-babel-process-comment-text 'org-babel-export-comment-text-as-plain-text
+  "Function called to process raw Org text collected to be inserted
+as comments in tangled source-code files.  The function should
+take a single string argument and return a string result.  The
+default value is `org-babel-export-comment-text-as-plain-text'.
+Legacy value is `org-remove-indentation'."
   :group 'org-babel
   :version "24.1"
   :type 'function)
@@ -158,6 +159,11 @@ represented in the file."
   (with-current-buffer (get-file-buffer file)
     (revert-buffer t t t)))
 
+(defun org-babel-export-comment-text-as-plain-text (comment)
+  "Default function to process raw Org text collected to be
+inserted as comments in tangled source-code files."
+  (org-export-string-as comment 'ascii t))
+
 (defmacro org-babel-with-temp-filebuffer (file &rest body)
   "Open FILE into a temporary buffer execute BODY there like
 `progn', then kill the FILE buffer returning the result of
@@ -533,8 +539,8 @@ non-nil, return the full association list to be used by
 	     (buffer-substring
 	      (max (condition-case nil
 		       (save-excursion
-			 (org-back-to-heading t) ; Sets match data
-			 (match-end 0))
+			 (re-search-backward org-heading-regexp) ; Sets match data
+			 (match-beginning 0))
 		     (error (point-min)))
 		   (save-excursion
 		     (if (re-search-backward
-- 
2.37.1

Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

>> Clearly, the "possible after an ASCII export" dropped somewhere in the
>> middle.
>
> New version of the patch attached.
>
> `:comments org' now produces by default plain text comments previously
> exported to ascii from org.

Thanks!
This change should be in ORG-NEWS.

> +(defun org-babel-export-comment-text-as-plain-text (comment)
> +  "Default function to process raw Org text collected to be
> +inserted as comments in tangled source-code files."
> +  (org-export-string-as comment 'ascii t))

Please document what the function does as the first line and document
the arguments. See D.6 Tips for Documentation Strings in Elisp manual.

The fact that this function is default for something is secondary for
the docstring. If you mention this fact, please also link back to the
defcustom.

> -			 (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.

Best,
Ihor

Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Juan Manuel Macías]

[-- Attachment #1: Type: text/plain, Size: 996 bytes --]

Hi, Ihor,

Here is a new fixed version of the patch, with the addition to NEWS.

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
...		   
(error (point-min)))

?

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...

Best regards,

Juan Manuel


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-ob-tangle.el-The-org-value-for-comments-is-now-.patch --]
[-- Type: text/x-patch, Size: 3484 bytes --]

From b500fcb1475b0a2e8eee532f031bb5cd236560fb Mon Sep 17 00:00:00 2001
From: Juan Manuel Macias <maciaschain@posteo.net>
Date: Mon, 25 Jul 2022 18:48:45 +0200
Subject: [PATCH] lisp/ob-tangle.el: The `org' value for `:comments' is now
 plain text

* org-babel-process-comment-text:
`org-babel-export-comment-text-as-plain-text' function is added as a
new default value, which exports the raw Org text as plain text.  This
is useful for removing all org metadata from the source file's
comments.
---
 etc/ORG-NEWS      |  6 ++++++
 lisp/ob-tangle.el | 25 +++++++++++++++++++------
 2 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 478fcf95c..22daa4351 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -375,6 +375,12 @@ purpose of the variable.  The replacement variable
 accepts =listings= and =verbatim= in place of =t= and =nil= (which
 still work, but are no longer listed as valid options).
 
+*** ~ob-tangle~: the ~org~ value for ~:comments~ is now plain text 
+
+When the value of the header argument ~:comments~ is ~org~, the text
+collected in the Org document is exported to ASCII before being passed
+to the tangled source file as a comment.
+
 * Version 9.5
 
 ** Important announcements and breaking changes
diff --git a/lisp/ob-tangle.el b/lisp/ob-tangle.el
index fdba72278..da14aaa5a 100644
--- a/lisp/ob-tangle.el
+++ b/lisp/ob-tangle.el
@@ -134,11 +134,12 @@ of tangled comments."
   :group 'org-babel
   :type 'boolean)
 
-(defcustom org-babel-process-comment-text 'org-remove-indentation
-  "Function called to process raw Org text collected to be
-inserted as comments in tangled source-code files.  The function
-should take a single string argument and return a string
-result.  The default value is `org-remove-indentation'."
+(defcustom org-babel-process-comment-text 'org-babel-export-comment-text-as-plain-text
+  +  "Function called to process raw Org text collected to be inserted
++as comments in tangled source-code files.  The function should
++take a single string argument and return a string result.  The
++default value is `org-babel-export-comment-text-as-plain-text'.
++Legacy value is `org-remove-indentation'."
   :group 'org-babel
   :version "24.1"
   :type 'function)
@@ -158,6 +159,18 @@ represented in the file."
   (with-current-buffer (get-file-buffer file)
     (revert-buffer t t t)))
 
+(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)))
+
 (defmacro org-babel-with-temp-filebuffer (file &rest body)
   "Open FILE into a temporary buffer execute BODY there like
 `progn', then kill the FILE buffer returning the result of
@@ -534,7 +547,7 @@ non-nil, return the full association list to be used by
 	      (max (condition-case nil
 		       (save-excursion
 			 (org-back-to-heading t) ; Sets match data
-			 (match-end 0))
+			 (match-beginning 0))
 		     (error (point-min)))
 		   (save-excursion
 		     (if (re-search-backward
-- 
2.37.1

Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> 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
> ...		   
> (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:

   • The first line of the documentation string should consist of one or
     two complete sentences that stand on their own as a summary.  ‘M-x
     apropos’ displays just the first line, and if that line’s contents
     don’t 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,
     “What does this function do?” For a variable, the first line should
     briefly answer the question, “What does this value mean?”

     Don’t 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.

   • The first line should mention all the important arguments of the
     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.

   • For consistency, phrase the verb in the first sentence of a
     function’s documentation string as an imperative—for instance, use
     “Return the cons of A and B.” in preference to “Returns the cons of
     A and B.” 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