Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'
Juan Manuel Macías 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
Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'
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 >From b500fcb1475b0a2e8eee532f031bb5cd236560fb Mon Sep 17 00:00:00 2001 From: Juan Manuel Macias 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'
Juan Manuel Macías 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'
Ihor Radchenko writes: > The original proposal by Eric Schulte: > https://list.orgmode.org/4bffee4f.5010...@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 >From 7095cb5d547bfe9f0576418e71317ad3ebeade77 Mon Sep 17 00:00:00 2001 From: Juan Manuel Macias 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 writes: > The original proposal by Eric Schulte: > https://list.orgmode.org/4bffee4f.5010...@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 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.5010...@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'
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'
Juan Manuel Macías 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'
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'
Juan Manuel Macías 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č [he/him] Studenohorská 25 84103 Bratislava Slovakia
Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'
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'
Juan Manuel Macías 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č [he/him] Studenohorská 25 84103 Bratislava Slovakia
Re: [Patch] ob-tangle.el: New value 'ascii' for the header argument ':comments'
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'
Juan Manuel Macías 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
