Re: [PATCH] lisp/ob-plantuml.el: Insert results in buffer

[Ihor Radchenko]

Joseph Turner  writes:

>> The solution will be simply removing the default :results setting.
>
> I think you're suggesting something like this:
>
> (defvar org-babel-default-header-args:plantuml
>   '((:exports . "results"))
>   "Default arguments for evaluating a plantuml source block.")
>
> With this change, if you *do* add a :file arg, like in the following
> example, then no output will be produced:
>
> #+begin_src plantuml :file "this.png"
>   Bob->Alice : Hello1!
> #+end_src
>
> #+RESULTS:
>
> which is also wrong.

> What would the code look like if we wanted to change the
> org-babel-default-header-args:plantuml variable inside the
> org-babel-execute:plantuml function based on the value of the params
> arg? Or perhaps you have a different solution?

You can examine :result-params property inside params plist. If that
property does not explicitly mention different results Type (see 16.6
Results of Evaluation), ob-plantuml may set the type to "file" with
plist-put.

Best,
Ihor

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[Ihor Radchenko]

András Simonyi  writes:

>> See the attached.
>
> Thanks a lot for the improvements! The only suggested change which I'm
> not sure about is the renaming of the section "Bibliography printing"
> to "Printing bibliography" Neither of them are ideal but it's
> difficult to find a formulation which sounds OK and is noncommittal
> regarding the number of bibliographies (a single one vs. several). Of
> the two, I feel that "Printing bibliography" is slightly worse because
> of the missing determiner before "bibliography", maybe "Printing
> bibliographies" would be better? Admittedly, as a non-native user of
> English my intuitions do not count for much, so it'd be nice to hear
> the opinion of some of the native speaker list members.

I am also a non-native speaker, so lets obey the Bruce's judgment.

>> Reading through the patch, I noticed that :title option is not
>> documented. Does it mean :title is not supported by csl processor?
>
> yes :title is not supported by the "csl" processor. Should we perhaps
> replace the example with another one using a multi-word keyword, like
>
> :  #+print_bibliography: :nottype proceedings,article :keyword "algebraic 
> logic"
>
> WDTY?

An example without :title will be less confusing.

Though I am wondering why csl does not support :title. It feels like a
natural thing to have.

Best,
Ihor

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

[Ihor Radchenko]

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: How to force markup without spaces

[K K]

On 2022-07-26 Tue. 09:23 +0700，Max Nikulin wrote：

> However the suggestion was namely to use U+200B ZERO WIDTH SPACE and
> it
> is actually implemented since `org-emphasis-regexp-components'
> currently
> contains [:space:].
> ...
> K, could you, please, clarify what is your particular use case?

My bad, I misunderstood the "feature" mentioned in the old post.

My use case is to emphasize chinese characters without spaces being inserted, 
even those zero-width spaces. For example "中文*测*试" should be enough to 
emphasize "测".

I am using zero-width spaces right now, and it works fine in org-mode buffers, 
but if exported to latex-pdf files, the U+200B ZERO WIDTH SPACE character will 
not be zero-width for certain fonts. So I hope not to use that character.

On Tue, 26 Jul 2022 09:26:42 +0800, Ihor Radchenko wrote:
> Another idea we have discussed is using something similar to Markdown
> format: **bold**, //italics//, __underline__, etc. It is less verbose
> compared to the special blocks, which should be valuable for
> Japanese/Chinese/other languages with no spaces between words.

By the way, it seems that my use case has already been implemented by 
markdown-mode. In a markdown-mode buffer "中文**测**试" will certainly make "测" 
bold.

Re: Volunteering to maintain ob-asymptote.el within Org

[Greg Minshall]

hi, Munyoki,

i'm neutral w.r.t. asymptote support being in "core org" or in
"contrib".  but, ...

> I'm not _against_ supporting a proffesional-level
> graphics PL.  What I'm trying to say is that
> having it installed should be a choice made by the
> end-user.  Personally, I try to keep my systems as
> minimal as I can make them; and as such I advocate
> for users having that choice.  Very much by
> opinions.  Nevertheless...

in terms of keeping systems minimal, probably you knew this, but i just
wanted to mention that even if ob-asymptote.el is in "core org", the
user will not be required to install asymptote itself.

cheers, Greg

Re: How to force markup without spaces

[Max Nikulin]

On 26/07/2022 08:26, Ihor Radchenko wrote:

K writes:


The thread and post I am mentioning is at
https://list.orgmode.org/orgmode/87bodxy77m@bzg.ath.cx/


That thread references yet another thread at
http://thread.gmane.org/gmane.emacs.orgmode/59881/focus=59971
However, gname links are no longer working.
Do you happen to know which thread id or subject the link is referring
to in the mailing list archive?


https://list.orgmode.org/orgmode/9c09cf9b-5b8f-4435-98d0-7e0b32ba5...@nf.mpg.de/T/
Stefan Vollmar. suggestion for org-emphasis-regexp-components: *U*nited 
*N*ations. 2012-09-05  8:05 UTC


However the suggestion was namely to use U+200B ZERO WIDTH SPACE and it 
is actually implemented since `org-emphasis-regexp-components' currently 
contains [:space:].


The U+2060 word joiner character (from this thread) is not a space, so 
currently it can not be used in such role. Recent mention of this character:
Tom Gillespie. On zero width spaces and Org syntax. Fri, 3 Dec 2021 
20:04:28 -0800. 
https://ca+g3_pm4cxha8bu+3qg541uioaulnaqfzqu-+ukczx3itoe...@mail.gmail.com


K, could you, please, clarify what is your particular use case? Some 
other workarounds, e.g. custom links, was discussed during last couple 
of years.


P.S. list.orgmode.org supports search by gmane article number:
https://list.orgmode.org/orgmode/?q=gmane%3A59881
see
Kyle Meyer. yhetil.org/orgmode now supports searching by Gmane ID. Thu, 
23 Apr 2020 04:43:20 + 
https://list.orgmode.org/87k126revr@kyleam.com


Another recipe to fetch the article (from the same message) is
w3m -m nntp://news.gmane.io/gmane.emacs.orgmode/59971

Re: Volunteering to maintain ob-asymptote.el within Org

[Ihor Radchenko]

Jarmo Hurri  writes:

>> TBH, this is the first time I'm hearing about it.  I've looked it up,
>> and indeed it seems to be useful.  
>
> For some reason, even people who would certainly benefit from Asymptote
> often have not heard of it. The developers do not really
> advertise. Asymptote is amazingly powerful and sophisticated.

Then, it would help to have more practical examples compared to what we
have in
https://www.orgmode.org/worg/org-contrib/babel/languages/ob-doc-asymptote.html

>> That said, shouldn't this be in org-contrib?  Too many features in a
>> tool - featurism - may be distracting, in the sense that you focus
>> more on your tool than work at hand.  
>
> I do not understand this. Why would supporting a professional-level
> graphics programming language be distracting someone from their work
> when using Org?

That a common minimalist argument. Some people dislike the fact that
software includes features they do not personally use. Similar arguments
are often raised regarding, for example, games shipped with Emacs.

I disagree in this particular case. Having ob-asymptote.el is not a
featurism - I would not expect people to play around a full new
programming language just because ob-language.el is in Org. The barrier
of entry is too high to make it destructing.

Another question is long-term maintainability. We have a limited
manpower and cannot cater too many support requests or take care about
parts of code not used by most people. After removing org-contrib over a
year ago, your email is the first issue raised regarding ob-asymptote
removal. Since you are volunteering to maintain it, things gets easier.
However, the final decision is after Bastien.

>> And that said, to work around this, I reckon that's why (?)  we have
>> org-contrib.  You - the end user - install what you want/need. 
>
> Yes, but whenever we split up support, we raise the threshold for the
> use of a combination of tools, in this case Org and Asymptote.
>
> Org is a very powerful publication tool. Does it not make complete sense
> to include support for a tool for creating professional-quality
> publication graphics?

Apparently asymptote is not commonly used (at least, not in my research
field). We do provide built-in support for Gnuplot, LaTeX TikZ, and
Python (Matplotlib), PlantUML. AFAIK, they are much more common.

Best,
Ihor

Re: The fate of ob-asymptote.el

[Ihor Radchenko]

Jarmo Hurri  writes:

>> Then, would it make more sense to include ob-asymptote.el into the
>> asymptote distribution?
>
> I do not think this is a good idea:
>
> - I am not involved in the development of asymptote, so this solution
>   would put maintenance of ob-asymptote.el beyond my reach.

AFAIK, it is developed publicly. Anyone can open a pull request or post
on their forum.

> - I have no idea whether developers of Asymptote have any interest in
>   Org.

They are at least interested in Emacs. So, they might as well be
interested in Org (which is a part of Emacs). Can ask.

The advantage of maintaining ob-asymptote.el in the main asymptote repo
is that people who are intimately familiar with the asymptote features
can directly contribute and enhance the Org integration. Moreover,
distributing together with the asymptote means no headache with
back-compatibility issues.

Maintaining on Org side will have an advantage of using the latest
additions to Org babel features.

I feel like it is more important to make use of the asymptote features
if its devs are going to be interested. Of course, IMHO.

> - Comparing to another language: what is the situation e.g. with
>   Haskell? We have ob-haskell.el (thanks to Lawrence Bottorff). In my
>   distro at least, I have Haskell mode installed separately. Should we
>   then move ob-haskell.el into the package supplying Haskell mode?

It would make sense. The same arguments apply.

> - Somehow I also think that the proposed solution would be close to the
>   idea of including ob-C.el into a C compiler distribution.

C compiler distribution does not ship with C major mode. So, it is
different.

Best,
Ihor

Re: How to force markup without spaces

[Ihor Radchenko]

K  writes:

> The thread and post I am mentioning is at
> https://list.orgmode.org/orgmode/87bodxy77m@bzg.ath.cx/

That thread references yet another thread at
http://thread.gmane.org/gmane.emacs.orgmode/59881/focus=59971
However, gname links are no longer working.
Do you happen to know which thread id or subject the link is referring
to in the mailing list archive?

To add regarding the markup without spaces, we have discussed something
called "inline special blocks" in
https://orgmode.org/list/87a6b8pbhg@posteo.net
Such blocks can be used as an alternative markup.

Another idea we have discussed is using something similar to Markdown
format: **bold**, //italics//, __underline__, etc. It is less verbose
compared to the special blocks, which should be valuable for
Japanese/Chinese/other languages with no spaces between words.

Best,
Ihor

Re: How to force markup without spaces

[K]

Hello everyone, I am a chinese user and also came across this problem.

Bastin once wrote this almost a decade ago:

> More precisely this can be included when we decide to drop support 
> of Emacs 22.
> 
> Does anyone know what is the current backward compatibility state
> of major native Emacs packages (Gnus/ERC/etc) wrt Emacs 22?
> 
> Thanks,
> 

Since emacs has released 28.1, Could this problem be solved?

Although we have the zero-width space workaround, for some fonts the
character will not be zero-space. So it would be nice to solve this
problem.

Re: [PATCH] lisp/ob-plantuml.el: Insert results in buffer

[Joseph Turner]

Thank you for your feedback, Ihor!

> Most importantly, the patch does not change the default value of
> org-babel-default-header-args:plantuml. :results header arg is set to
> "file" by default.

Yes, I noticed this issue also.

> The solution will be simply removing the default :results setting.

I think you're suggesting something like this:

(defvar org-babel-default-header-args:plantuml
  '((:exports . "results"))
  "Default arguments for evaluating a plantuml source block.")

With this change, if you *do* add a :file arg, like in the following
example, then no output will be produced:

#+begin_src plantuml :file "this.png"
  Bob->Alice : Hello1!
#+end_src

#+RESULTS:

which is also wrong.

What would the code look like if we wanted to change the
org-babel-default-header-args:plantuml variable inside the
org-babel-execute:plantuml function based on the value of the params
arg? Or perhaps you have a different solution?

Once we straighten this issue out, I am happy to resubmit the updated
patch with your suggested style changes.

Warmly,

Joseph

Re: Volunteering to maintain ob-asymptote.el within Org

[Munyoki Kilyungi]

Jarmo Hurri  anaandika:

> Greetings Munyoki.
>

Hi!

[...]

>> That said, shouldn't this be in org-contrib?  Too many features in a
>> tool - featurism - may be distracting, in the sense that you focus
>> more on your tool than work at hand.  
>
> I do not understand this. Why would supporting a professional-level
> graphics programming language be distracting someone from their work
> when using Org?
>

I'm not _against_ supporting a proffesional-level
graphics PL.  What I'm trying to say is that
having it installed should be a choice made by the
end-user.  Personally, I try to keep my systems as
minimal as I can make them; and as such I advocate
for users having that choice.  Very much by
opinions.  Nevertheless...

>> And that said, to work around this, I reckon that's why (?)  we have
>> org-contrib.  You - the end user - install what you want/need. 
>
> Yes, but whenever we split up support, we raise the threshold for the
> use of a combination of tools, in this case Org and Asymptote.
>

I agree with this.

> Org is a very powerful publication tool. Does it not make complete sense
> to include support for a tool for creating professional-quality
> publication graphics?
>

Makes sense.  Just not complete sense to me.  I
reckon I'll give this is a shot this coming
weekend and see how this goes.  Is this:

sufficient to get me started?

-- 
(Life is like a pencil that will surely run out,
but will leave the beautiful writing of life.)
(D4F09EB110177E03C28E2FE1F5BBAE1E0392253F
(hkp://keys.openpgp.org))


signature.asc
Description: PGP signature

Re: Volunteering to maintain ob-asymptote.el within Org

[Munyoki Kilyungi]

Jarmo Hurri  anaandika:

> Greetings Munyoki.
>

Hi!

[...]

>> That said, shouldn't this be in org-contrib?  Too many features in a
>> tool - featurism - may be distracting, in the sense that you focus
>> more on your tool than work at hand.  
>
> I do not understand this. Why would supporting a professional-level
> graphics programming language be distracting someone from their work
> when using Org?
>

I'm not _against_ supporting a proffesional-level
graphics PL.  What I'm trying to say is that
having it installed should be a choice made by the
end-user.  Personally, I try to keep my systems as
minimal as I can make them; and as such I advocate
for users having that choice.  Very much by
opinions.  Nevertheless...

>> And that said, to work around this, I reckon that's why (?)  we have
>> org-contrib.  You - the end user - install what you want/need. 
>
> Yes, but whenever we split up support, we raise the threshold for the
> use of a combination of tools, in this case Org and Asymptote.
>

I agree with this.

> Org is a very powerful publication tool. Does it not make complete sense
> to include support for a tool for creating professional-quality
> publication graphics?
>

Makes sense.  Just not complete sense to me.  I
reckon I'll give this is a shot this coming
weekend and see how this goes.  Is this:

sufficient to get me started?

-- 
(Life is like a pencil that will surely run out,
but will leave the beautiful writing of life.)
(D4F09EB110177E03C28E2FE1F5BBAE1E0392253F
(hkp://keys.openpgp.org))


signature.asc
Description: PGP signature

Re: [PROPOSED-PATCH] Fix doc string quoting problems with '

[Paul Eggert]

On 7/25/22 01:50, Ihor Radchenko wrote:


The conventions sound reasonable, though I do not think that they are
documented in D.6 Tips for Documentation Strings section of the Elisp
manual.


Thanks, I added the following to the Elisp manual to try to fix that:

https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=d04701c0c4959d3c42587a4e1277bb517a2ea04b



I am not sure if it is a
good idea to change explicit 'symbol or '(...) mentions in the
documentation of the defcustoms. In particular, when 'symbol is intended
to be set as (setq variable 'symbol), I feel that 'symbol should be
preferred over `symbol' - it will make life easier for users who can
then just copy-paste the text from docstring.


OK, I went with a more conservative route there, e.g., replacing this:

  \\='((?R set-category get-category))

with this:

  (setq org-agenda-bulk-custom-functions 

\\='((?R set-category get-category))) 



Although wordier, this follows the doc string guidelines and should make 
it clear why the apostrophe is present.




Also, note that references in the babel documentation are _not_ Elisp
symbols - they are defined in #+name: name lines at the relevant src
blocks.


Yes, I left those alone. Here's what I installed:

https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=6013cb161d6f186829f6bfcfc5dd927c6cb89b49

Re: How to force markup without spaces

[K]

> Bastin once wrote this almost a decade ago:

Sorry for the misspelling, the name is Bastien, not Bastin.

The thread and post I am mentioning is at
https://list.orgmode.org/orgmode/87bodxy77m@bzg.ath.cx/

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[Bruce D'Arcus]

On Mon, Jul 25, 2022 at 2:26 PM András Simonyi  wrote:
>
> Dear All,
>
> On Sun, 24 Jul 2022 at 09:41, Ihor Radchenko  wrote:
> >
> > Thanks!
> >
> > I have made some changes to the patch, mostly fixing grammar issues (the
> > ones I can notice). I also changed the sub-section from "Bibliography
> > options" to "Bibliography options in "biblatex" and "csl" export processors"
> >
> > See the attached.
>
> Thanks a lot for the improvements! The only suggested change which I'm
> not sure about is the renaming of the section "Bibliography printing"
> to "Printing bibliography" Neither of them are ideal but it's
> difficult to find a formulation which sounds OK and is noncommittal
> regarding the number of bibliographies (a single one vs. several). Of
> the two, I feel that "Printing bibliography" is slightly worse because
> of the missing determiner before "bibliography", maybe "Printing
> bibliographies" would be better? Admittedly, as a non-native user of
> English my intuitions do not count for much, so it'd be nice to hear
> the opinion of some of the native speaker list members.

I'm a native speaker.

I think "Bibliography printing" sounds like the best option, since it
doesn't really preclude there are multiple.

"Printing bibliographies" would also be OK.

I don't think "Printing bibliography" really works.

Bruce

Re: How to force markup without spaces

[K]

Hello everyone, I am a chinese user and also came across this problem.

Bastin once wrote this almost a decade ago:

> More precisely this can be included when we decide to drop support 
> of Emacs 22.
> 
> Does anyone know what is the current backward compatibility state
> of major native Emacs packages (Gnus/ERC/etc) wrt Emacs 22?
> 
> Thanks,
> 

Since emacs has released 28.1, Could this problem be solved?

Although we have the zero-width space workaround, for some fonts the
character will not be zero-space. So it would be nice to solve this
problem.

Re: [PATCH] oc-csl: Add support for sub-bibliographies

[András Simonyi]

Dear All,

On Sun, 24 Jul 2022 at 09:41, Ihor Radchenko  wrote:
>
> Thanks!
>
> I have made some changes to the patch, mostly fixing grammar issues (the
> ones I can notice). I also changed the sub-section from "Bibliography
> options" to "Bibliography options in "biblatex" and "csl" export processors"
>
> See the attached.

Thanks a lot for the improvements! The only suggested change which I'm
not sure about is the renaming of the section "Bibliography printing"
to "Printing bibliography" Neither of them are ideal but it's
difficult to find a formulation which sounds OK and is noncommittal
regarding the number of bibliographies (a single one vs. several). Of
the two, I feel that "Printing bibliography" is slightly worse because
of the missing determiner before "bibliography", maybe "Printing
bibliographies" would be better? Admittedly, as a non-native user of
English my intuitions do not count for much, so it'd be nice to hear
the opinion of some of the native speaker list members.

> Reading through the patch, I noticed that :title option is not
> documented. Does it mean :title is not supported by csl processor?

yes :title is not supported by the "csl" processor. Should we perhaps
replace the example with another one using a multi-word keyword, like

:  #+print_bibliography: :nottype proceedings,article :keyword "algebraic logic"

WDTY?
best wishes,
András

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

[Juan Manuel Macías]

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  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: Footnote 60 in Org Manual

[Ihor Radchenko]

Perry Smith  writes:

> The text has “For example, to specify a date December 12, 2005 …” and then 
> all of the examples use 12 and 1 as if the intention was “to specify a date 
> December 1, 2005”.  I doubt if you want to use December 12 because the 
> specification would be 12 12 2005 but it would be hard to tell the user which 
> 12 is which. :-)

Thanks for reporting!
Fixed on main via eb5622b7a.

Best,
Ihor

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

[Ihor Radchenko]

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: org-encode-time bug

[Nick Dokos]

Ihor Radchenko  writes:

> Morgan Smith  writes:
>
>> I'm using emacs from commit f258f67 (quite recent) and org from commit
>> 39005dc (quite recent).
>>
>> I'm using native compilation and PGTK.
>
>> Debugger entered--Lisp error: (invalid-function org-encode-time)
>>   org-encode-time((0 0 0 21 7 2022 4 t -14400))
>>   org-matcher-time("<2022-07-21 Thu 00:00>")
>>   org-clock-get-table-data(...)
>>   org-dblock-write:clocktable(...)
>>   org-update-dblock()
>>   org-ctrl-c-ctrl-c(nil)
>>   funcall-interactively(org-ctrl-c-ctrl-c nil)
>>   command-execute(org-ctrl-c-ctrl-c)
>
> org-encode-time is defined in org-macs.el in the latest Org, but _not_
> in built-in Org. What you are seeing is most likely caused by "mixed"
> installation of Org when part of Org is loaded from built-in Org
> distribution coming from Emacs.
>
>> I was able to reproduce this with 'emacs -Q'
>>
>> When trying to update a clocktable I get the following backtrace (with a
>> little bit removed).
>
> Could you please detail on what you did to load the latest org with
> Emacs -Q? Using purely emacs -Q cannot trigger the error simply because
> org-encode-time is absent in the built-in Org.
>

In my case, it was caused by an update, followed by `make autoloads',
followed by 'org-reload'. That last part is not guaranteed to work,
particularly on the cutting edge, so restarting emacs is sometimes
necessary - as it was in this case. No problems afterwards.

-- 
Nick

"There are only two hard problems in computer science: cache
invalidation, naming things, and off-by-one errors." -Martin Fowler

Re: [PATCH] lisp/ob-plantuml.el: Insert results in buffer

[Ihor Radchenko]

Joseph Turner  writes:

> Allow src block execution without ":file" header arg. When ":file" is
> omitted, insert txt output in buffer below src block.
>
> TINYCHANGE

Thanks for your contribution!
This addition makes a lot of sense.

Some comments:

Most importantly, the patch does not change the default value of
org-babel-default-header-args:plantuml. :results header arg is set to
"file" by default. This yields something like the following:

#+begin_src plantuml 
Bob->Alice : Hello1!
#+end_src

#+RESULTS:
[[file: ,---.  ,-.
 |Bob|  |Alice|
 `-+-'  `--+--'
   |   Hello1! |   
   |-->|   
 ,-+-.  ,--+--.
 |Bob|  |Alice|
 `---'  `-'
]]


Note that the output is treated as a path to file:

[[file: ... output string ...]]

which is indeed wrong.

The solution will be simply removing the default :results setting.

Other comments are for code and documentation style.

> Allow src block execution without ":file" header arg. When ":file" is
> omitted, insert txt output in buffer below src block.

Please use double space between sentences. See
https://orgmode.org/worg/org-contribute.html

> +
> +*** =org-babel-execute:plantuml= can output ASCII graphs in the buffer
> +
> +Previously, executing PlantUML src blocks required a ":file" header 
> argument. Now, if that header argument is omitted, an ASCII graph will be 
> inserted below the src block.
> +

Likewise. Also, please fill the paragraph making sure that each line
spans less than 80 columns. Same for the code and comments inside the
code.

> -nil)) ;; signal that output has already been written to file
> +(unless do-export (with-temp-buffer
> +(insert-file-contents out-file)
> +(buffer-substring-no-properties (point-min) 
> (point-max))
> +

We follow Elisp conventions regarding indentation and parenthesis
placement as in D.1 Emacs Lisp Coding Conventions - do not leave
parenthesis on the line of their own.

Also, the way you typed unless leads to excessive indentation. You could
instead do

(unless do-export
 (with-temp-buffer
   ...))

Best,
Ihor

Re: Improvements in the default LaTeX preamble: templates?

[Juan Manuel Macías]

Ihor Radchenko writes:

> LaTeX is just one export backend to worry about. From broader
> perspective, we can have a generic template library.

Nice idea, I agree. I was targeting LaTeX specifically because of the
questions that have been raised in this thread and other parallel threads.
And because LaTeX is an extremely complex beast. And it has become much
more complex over the years[1]. No two LaTeX documents are alike just as no
two LaTeX users are alike. Just take a look at tex.stackexchange.com to
realize that reality...

(ConTeXt can be a good alternative for those who don't want to mess with
the complexity of LaTeX. In ConTeXt you don't need to load a package for
everything ---modules at most, but that's another story---, so almost
everything is out-of-the-box there).

[1] And there is also the problem of multiplicity: three TeX engines
coexisting at the same time, LaTeX2ε coexisting with LaTeX 3, etc.

> TEC is working on something along these lines. See
> https://tecosaur.github.io/emacs-config/config.html#cleverer-preamble

Thanks for the pointer! I did not know it and it seems to me a
tremendously interesting work. I'll keep an eye on it.

In my workflow, I am used to writing the configuration of a LaTeX
document (aka, "the preamble") through .sty files that I build according
to the requirements of each project. That is, I write my own packages.
That's probably why I have a bias of opinion here (I use LaTeX for
typesetting and editorial production, so I need more control), but I
tend to think that a LaTeX preamble is something so ductile that
achieving a certain degree of automation is an arduous task. At least
one automation that covers all possible use cases. That's where I got
the idea of being able to have a library of templates to cover different
types of documents, even the most idiosyncratic ones. Or, at least, that
they can serve as an inspiration to other users.

Best regards,

Juan Manuel 

Re: Improvements in the default LaTeX preamble: templates? (was: [PATCH] ox-latex.el: Unify in one single list Babel and Polyglossia languages alists)

[Ihor Radchenko]

Juan Manuel Macías  writes:

> I agree that adding more elements to the standard preamble is a complex
> matter. LaTeX is already horribly complex and multiple, and it is
> difficult to satisfy all kinds of users with a standard code. It
> occurred to me that an alternative to modifying Org's code in this
> regard could be to have some kind of "LaTeX template library". I think
> Pandoc has something similar too, if I remember correctly. Those
> templates could be on Org or provided by third parties somewhere else,
> like Worg. In Org, we also have a great system for creating LaTeX
> documents templates, which is the org-latex-classes list. A large number
> of elements could be defined in a 'single' class for any type of
> document.

LaTeX is just one export backend to worry about. From broader
perspective, we can have a generic template library.

ox.el currently allows export backends to define document template as a
function, which is the most generic way. However, we can come up with
something more customizable - customizable in a consistent way, in
contrast to the current disarray with various export backends
approaching the boilerplate code differently.

TEC is working on something along these lines. See 
https://tecosaur.github.io/emacs-config/config.html#cleverer-preamble

Note that we also have inner templates that apply to individual exported
elements.

Best,
Ihor

Re: [PROPOSED-PATCH] Fix doc string quoting problems with '

[Ihor Radchenko]

Paul Eggert  writes:

> The Emacs doc string convention is to document values as-is when that
> is clear, and surrounded by `single quotes' otherwise. For example, a
> doc string "(a b c)" stands for a list of symbols, and the doc string
> "`a'" stands for a single symbol. The doc string "\\=`a" is typically
> not correct for that single symbol, because that is equivalent to
> "(quote a)" and the typical intent is to talk about the symbol, not
> about the Lisp quoting construct.  One needs "\\=`X" only when talking
> about something intended to be equivalent to "(quote X)", as in the
> doc string "(provide \\='org-xyz)".

Thanks for the patch!
The conventions sound reasonable, though I do not think that they are
documented in D.6 Tips for Documentation Strings section of the Elisp
manual.

The patch looks good in general, however I am not sure if it is a
good idea to change explicit 'symbol or '(...) mentions in the
documentation of the defcustoms. In particular, when 'symbol is intended
to be set as (setq variable 'symbol), I feel that 'symbol should be
preferred over `symbol' - it will make life easier for users who can
then just copy-paste the text from docstring.

Also, note that references in the babel documentation are _not_ Elisp
symbols - they are defined in #+name: name lines at the relevant src
blocks.

Finally, note that your patch does not apply after Kyle backported
similar changes from Emacs master.

Best,
Ihor