Re: Comments on Summary section of Org manual (was: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable)

[Matt]

  On Wed, 03 Jan 2024 14:41:29 +0100  Ihor Radchenko  wrote --- 

 > I do not see much benefit changing "todo list" to "to-do list". Both are
 > clear and both are grammatically correct.

I said "TODO" to "to-do".  I was reacting to it being all caps.  I'm sorry I 
didn't say that.

When it's all caps, TODO is a keyword.   Otherwise, it's prose.   The following 
are different (AFAIK):

* TODO Finish this headline
* todo Finish this headline
* to-do Finish this headline

Agreed, it's a minor detail.

 > > Regarding "markup language," that reads to me like programmer jargon.
 > > What does it mean and why should someone care?  Again, who are we
 > > writing to?  A markup language is a notation for formatting,
 > > structure, and relationships.  I think it would be best to directly
 > > say that.
 > 
 > What about "plain text file format"?

I like that it's less technical.  I worry that it's less precise.  

I still think a word like "notation," that doesn't derive from computer 
culture, has a greater chance of being meaningful to people from other domains, 
like authors, scientists, or engineers.  Of course, these same people can 
easily understand the idea when they see it.  It's more important to explain 
why it matters and that's something we're already doing.

"Markup language" is fine.  It's correct.  Org syntax is a markup language.

I'm happy to leave it rather than risk bike-shedding it more than I have.  If 
we learn that it caused friction for a newcomer, we can change it easily enough.

 > > I would also soften that Org "relies" on its markup.  It doesn't.  I
 > > used Org only for lists for a long time.  I believe lists to be a
 > > fundamental feature of Org (and hence a great item for the first
 > > sentence).  Lists are as simple as dashes.  It's hard to say that
 > > dashes before list items is a markup language.
 > 
 > Yet, it is. You cannot, for example, use "." as bullets in Org mode.
 > Also, indentation matters in Org lists, while it does not matter in more
 > free-style writing.

Fair points.  I concede.  :)

 > > Finally, I don't think the file extension is relevant for the first
 > > paragraph.  Technically, an extension isn't necessary.  A person can
 > > call M-x org-mode or use a file local variable.  Worse, I think the
 > > extension contradicts the point that any text editor can view an Org
 > > file.  Ever try to open a .org file in Windows?  It asks for the
 > > program.  Yes, *technically* Windows could open a .org file *if* the
 > > person opening it knew which program to use (or to change the
 > > extension to something like .txt).  Again, who are we writing to?  If
 > > it's someone who believes file extensions matter, then this would
 > > introduce unnecessary friction.  It seems best to avoid it.  Better to
 > > do as you've done and say Org is readable (which it is) rather than
 > > specify the extension (which doesn't really matter).
 > 
 > I am mostly neutral here, but I can see an argument why mentioning .org
 > extension may be useful - unlike Windows, GitHub does expect .org file
 > extension specifically to render Org mode files. The same goes for
 > non-Emacs editors that support Org markup. For example, Vim/Neovim.
 
That's a good point.

Knowing about the .org extension is useful.  I don't think it hurts anything 
other than taking up valuable space.  If we need to bump something from the 
first paragraph, this gets my vote.

--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode

Re: [PATCH] Fix org-agenda-skip-scheduled-if-deadline-is-shown bug

[Morgan Smith]

Ihor Radchenko  writes:

> Morgan Smith  writes:
>
>>> May you please provide a detailed reproducer demonstrating the bug you
>>> are trying to fix? Such reproducer could be a basis of a new test.
>>
>> See a detailed reproducer attached to this mail.  It has a task defined
>> as this:
>>
>> * TODO task
>> SCHEDULED: <2017-03-06 Mon +2d> DEADLINE: <2017-03-10>
>>
>> Running said reproducer currently fails as follows (the numbers are the
>> days of the month).
>>
>> (string-equal
>> "06\nScheduled: task\n08\nScheduled: task\n10\nScheduled: task\nDeadline:  
>> task\n"
>> "06\nScheduled: task\n08\nScheduled: task\n10\nScheduled: task\nDeadline:  
>> task\n12\nScheduled: task\n")
>>
>> As you can see, we expect to not see anything scheduled after the
>> deadline if 'org-agenda-skip-scheduled-if-deadline-is-shown' is set to
>> 'repeated-after-deadline', however, we actually see that things continue
>> to be scheduled.  Hence the bug is that that option currently does
>> nothing.
>
> I think that you misunderstand the purpose of 'repeated-after-deadline
> value. Let me provide an example:
>
> 'repeated-after-deadline allows this task
>
> * Do me every day before March, 16th (included)
>   SCHEDULED: <2013-03-12 mar. +1d> DEADLINE: <2013-03-16 sam.>
>
> to step being displayed after March, 16th.

In my above example I have a task with a deadline of March 10th.
My test shows that it will continue to be scheduled after March 10th, on
the 12th.  That is wrong.  It is still scheduled on the 10th which is
good.  Being scheduled on the 12th is wrong.

Re: org table export to latex, longtable, code does not compile

[Uwe Brauer]

>>> "IR" == Ihor Radchenko  writes:

> Uwe Brauer  writes:
>> I am running emacs 29 and org mode 9.6.9
>> 
>> I have set (setq org-latex-line-break-safe "")
>> ...
>> Will be translated to 
>> 
>> #+begin_src 
>> 
>> \begin{longtable}{|r|r|l|l|l|l|l|}
>> \hline
>> Num & Documento & \textit{26.04.2024} & \textit{29.04.2024} & 
>> \textit{06.05.2024} & \textit{08.05.2024} & \textit{10.05.2024}\\ \hline

> This is not what I am seeing with Emacs 29.

Very strange I have not set 
org-export-filter-table-row-functions to nil

But still the above example gets exported as 

\begin{longtable}{|r|r|l|l|l|l|l|}
\hline
Num & Documento & \textit{26.04.2024} & \textit{29.04.2024} & 
\textit{06.05.2024} & \textit{08.05.2024} & \textit{10.05.2024}\\
\hline
\endfirsthead
\multicolumn{7}{l}{Continued from previous page} \\[0pt]
\hline

Num & Documento & \textit{26.04.2024} & \textit{29.04.2024} & 
\textit{06.05.2024} & \textit{08.05.2024} & \textit{10.05.2024} \\[0pt]

\hline
\endhead
\hline\multicolumn{7}{r}{Continued on next page} \\
\endfoot
\endlastfoot
\hline
1 & 12345678 &  &  &  &  & \\
2 & 12345678 &  &  &  &  & \\
3 & 12345678 &  &  &  &  & \\
4 & 12345678 &  &  &  &  & \\
\end{longtable}

That compiles with TL2023.

Is this the same result as yours.

In my particular use case (I want \hline always) the solution is 

--8<---cut here---start->8---
(defun my-latex-insert-hline-always (row backend info)
  "Add a hline to every row when exporting to  LaTeX."
  (when (org-export-derived-backend-p backend 'latex)
(replace-regexp-in-string "\\[0pt\\]\\|" " 
hline" row)))
--8<---cut here---end--->8---





-- 
I strongly condemn Hamas heinous despicable pogroms/atrocities on Israel
I strongly condemn Putin's war of aggression against Ukraine.
I support to deliver weapons to Ukraine's military. 
I support the EU and NATO membership of Ukraine. 



smime.p7s
Description: S/MIME cryptographic signature

Re: [PATCH] Re: Suggestion to add hook to be run when org-indent completes a buffer's initialization

[Ihor Radchenko]

dark.key8...@151e.ai writes:

> Understood. Please find amended patch.

Applied, onto main, with minor amendments.
I capitalized all the sentences in commit message and added
:package-version keyword to the `defcustom' definition.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=3aac00e45

Thanks for your contribution!

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: table of contents + export = Unable to resolve link

[Ihor Radchenko]

libreville  writes:

> if i create an org file with these three lines:
>
> * contents :TOC:
> * a headline
> * another
>
> org helpfully completes the table of contents for me:
>
> * contents :TOC:
> - [[#a-headline][a headline]]
> - [[#another][another]]

May you please elaborate what you mean by "completes"?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: [PATCH] Fix org-agenda-skip-scheduled-if-deadline-is-shown bug

[Ihor Radchenko]

Morgan Smith  writes:

>> May you please provide a detailed reproducer demonstrating the bug you
>> are trying to fix? Such reproducer could be a basis of a new test.
>
> See a detailed reproducer attached to this mail.  It has a task defined
> as this:
>
> * TODO task
> SCHEDULED: <2017-03-06 Mon +2d> DEADLINE: <2017-03-10>
>
> Running said reproducer currently fails as follows (the numbers are the
> days of the month).
>
> (string-equal
> "06\nScheduled: task\n08\nScheduled: task\n10\nScheduled: task\nDeadline:  
> task\n"
> "06\nScheduled: task\n08\nScheduled: task\n10\nScheduled: task\nDeadline:  
> task\n12\nScheduled: task\n")
>
> As you can see, we expect to not see anything scheduled after the
> deadline if 'org-agenda-skip-scheduled-if-deadline-is-shown' is set to
> 'repeated-after-deadline', however, we actually see that things continue
> to be scheduled.  Hence the bug is that that option currently does
> nothing.

I think that you misunderstand the purpose of 'repeated-after-deadline
value. Let me provide an example:

'repeated-after-deadline allows this task

* Do me every day before March, 16th (included)
  SCHEDULED: <2013-03-12 mar. +1d> DEADLINE: <2013-03-16 sam.>

to step being displayed after March, 16th.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: [PATCH] org-babel-demarcate-block: split using org-element instead of regexp

[Ihor Radchenko]

gerard.vermeu...@posteo.net writes:

> Attached you'll find a new patch trying to implement your suggestions.
> Interactive splitting by demarcation seems to work quite well (see the
> before and after splitting snippets in the PS).

Thanks!

> However, I cannot run the test because org-babel-demarcate-block
> always errors "org-element--cache: Emergency exit" while the same
> input works interactively. Could there be a problem of cache
> synchronization or something like that? Is there something I can do?

This was a bug in `org-element-copy'. Fixed, on main now.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=dfeff03c5

> I also did not yet look into how to propagate a switch like -n10.

-n10 is not a valid switch, AFAIK. We demand space: -n 10.
See 12.6 Literal Examples section of the manual.

I made some adjustments to the patch, making use of org-element API.
See the attached updated version of the patch.

I am not yet merging it as I found some weirdness with indentation.
Consider the following (indentation is important):

#+BEGIN_SRC emacs-lisp -n 20
  ;; This exports with line number 20.
   (message "This is line 21")
#+END_SRC

After M-x org-babel-demarcate-block, I am getting

#+BEGIN_SRC emacs-lisp -n 20
  ;; This exports with line number 20.
  #+END_SRC
  
#+begin_src emacs-lisp -n 20
  (message "This is line 21")
#+end_src

>From f5b9a6862cdb71ab33b7a291386221fff6648d53 Mon Sep 17 00:00:00 2001
Message-ID: 
From: Gerard Vermeulen 
Date: Sat, 30 Dec 2023 19:25:25 +0100
Subject: [PATCH] org-babel-demarcate-block: split using org-element instead of
 regexp

* lisp/ob-babel.el (org-babel-demarcate-block): Delete the caption and
the name from a copy of (org-element-at-point) and set its value to
the body inside the source block after point.  Delete all superfluous
text after point from the current Emacs buffer and add a proper
sentinel to the upper source block.  Insert the lower block by
applying `org-element-interpret-data' to the modified copy.  Leave
point in a convenient position.
* testing/lisp/test-ob.el (test-ob/demarcate-block-split): New test
for block splitting by demarcation.  It checks also that the language,
switches, and header arguments are duplicated.
---
 lisp/ob-core.el | 38 ++
 testing/lisp/test-ob.el | 35 +++
 2 files changed, 49 insertions(+), 24 deletions(-)

diff --git a/lisp/ob-core.el b/lisp/ob-core.el
index f7e4e255f..300747dae 100644
--- a/lisp/ob-core.el
+++ b/lisp/ob-core.el
@@ -73,6 +73,7 @@ (declare-function org-element-contents-end "org-element" (node))
 (declare-function org-element-parent "org-element-ast" (node))
 (declare-function org-element-type "org-element-ast" (node  anonymous))
 (declare-function org-element-type-p "org-element-ast" (node  types))
+(declare-function org-element-interpret-data "org-element" (data))
 (declare-function org-entry-get "org" (pom property  inherit literal-nil))
 (declare-function org-escape-code-in-region "org-src" (beg end))
 (declare-function org-forward-heading-same-level "org" (arg  invisible-ok))
@@ -2067,35 +2068,24 @@ (defun org-babel-demarcate-block ( arg)
 	 (start (org-babel-where-is-src-block-head))
  ;; `start' will be nil when within space lines after src block.
 	 (block (and start (match-string 0)))
-	 (headers (and start (match-string 4)))
 	 (stars (concat (make-string (or (org-current-level) 1) ?*) " "))
 	 (upper-case-p (and block
 			(let (case-fold-search)
 			  (string-match-p "#\\+BEGIN_SRC" block)
 (if (and info start) ;; At src block, but not within blank lines after it.
-(mapc
- (lambda (place)
-   (save-excursion
- (goto-char place)
- (let ((lang (nth 0 info))
-   (indent (make-string (org-current-text-indentation) ?\s)))
-	   (when (string-match "^[[:space:]]*$"
-   (buffer-substring (line-beginning-position)
- (line-end-position)))
- (delete-region (line-beginning-position) (line-end-position)))
-   (insert (concat
-		(if (looking-at "^") "" "\n")
-		indent (if upper-case-p "#+END_SRC\n" "#+end_src\n")
-		(if arg stars indent) "\n"
-		indent (if upper-case-p "#+BEGIN_SRC " "#+begin_src ")
-		lang
-		(if (> (length headers) 1)
-			(concat " " headers) headers)
-		(if (looking-at "[\n\r]")
-			""
-			  (concat "\n" (make-string (current-column) ? )))
-	   (move-end-of-line 2))
- (sort (if (org-region-active-p) (list (mark) (point)) (list (point))) #'>))
+(let* ((body-end (match-end 5))
+   (copy (org-element-copy (org-element-at-point)))
+   (end (org-element-end copy))
+   (indent (make-string 

Re: org table export to latex, longtable, code does not compile

[Ihor Radchenko]

Uwe Brauer  writes:

> I am running emacs 29 and org mode 9.6.9
>
> I have set (setq org-latex-line-break-safe "")
> ...
> Will be translated to 
>
> #+begin_src 
>
> \begin{longtable}{|r|r|l|l|l|l|l|}
> \hline
> Num & Documento & \textit{26.04.2024} & \textit{29.04.2024} & 
> \textit{06.05.2024} & \textit{08.05.2024} & \textit{10.05.2024}\\ \hline

This is not what I am seeing with Emacs 29.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: [PATCH v2] org-id: allow using parent's existing id in links to headlines

[Ihor Radchenko]

"Rick Lupton"  writes:

> Thanks for the comments. On this point, I'd like to modify 
> `org-insert-heading' to allow for choosing the level of the newly inserted 
> heading, but first wanted to check if you have a preference for how to change 
> it.
>
>
> I think it would be simplest to change the current:
>
> (defun org-insert-heading ( arg invisible-ok top)
>   "...When optional argument TOP is non-nil, insert a level 1 heading, 
> unconditionally."
>
> to:
>
> (defun org-insert-heading ( arg invisible-ok level)
>   "...When optional argument LEVEL is a number, insert a heading at that 
> level.  For backwards compatibility, when LEVEL is non-nil but not a number, 
> insert a level-1 heading."
>
> but that is not totally backwards compatible -- is that ok?

I think that it is OK. I very much doubt that anyone at all uses
numerical value for TOP in the existing `org-insert-heading' calls from
Elisp. And adding yet another extra optional argument is not justified
in this particular case.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Comments on Summary section of Org manual (was: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable)

[Ihor Radchenko]

Matt  writes:

> Several things in the first paragraph unrelated to your changes stick
> out to me. I can't help but make some other remarks.
>
> "TODO" should probably be "to-do".  Every dictionary I looked in has
> an entry for "to-do".  I think that's the common spelling.

Yet, we consistently use TODO keyword and TODO list across the whole
manual. Stackexchange tells that both variants are valid:
https://english.stackexchange.com/questions/46217/todo-list-or-to-do-list
although "todo" is much less widely used.

I do not see much benefit changing "todo list" to "to-do list". Both are
clear and both are grammatically correct.

> Regarding "markup language," that reads to me like programmer jargon.
> What does it mean and why should someone care?  Again, who are we
> writing to?  A markup language is a notation for formatting,
> structure, and relationships.  I think it would be best to directly
> say that.

What about "plain text file format"?

> I would also soften that Org "relies" on its markup.  It doesn't.  I
> used Org only for lists for a long time.  I believe lists to be a
> fundamental feature of Org (and hence a great item for the first
> sentence).  Lists are as simple as dashes.  It's hard to say that
> dashes before list items is a markup language.

Yet, it is. You cannot, for example, use "." as bullets in Org mode.
Also, indentation matters in Org lists, while it does not matter in more
free-style writing.

> Finally, I don't think the file extension is relevant for the first
> paragraph.  Technically, an extension isn't necessary.  A person can
> call M-x org-mode or use a file local variable.  Worse, I think the
> extension contradicts the point that any text editor can view an Org
> file.  Ever try to open a .org file in Windows?  It asks for the
> program.  Yes, *technically* Windows could open a .org file *if* the
> person opening it knew which program to use (or to change the
> extension to something like .txt).  Again, who are we writing to?  If
> it's someone who believes file extensions matter, then this would
> introduce unnecessary friction.  It seems best to avoid it.  Better to
> do as you've done and say Org is readable (which it is) rather than
> specify the extension (which doesn't really matter).

I am mostly neutral here, but I can see an argument why mentioning .org
extension may be useful - unlike Windows, GitHub does expect .org file
extension specifically to render Org mode files. The same goes for
non-Emacs editors that support Org markup. For example, Vim/Neovim.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable

[Ihor Radchenko]

Jean Louis  writes:

> In my opinion, it's not that Org was intentionally designed to be
> "lightweight markup readable for humans"; rather, it was maintained in
> a manner that focused on preserving its readability and prevented it
> from evolving into something less comprehensible.

The point of my patch is not to show history of Org markup. Rather to
guide the future direction - if we ever add new or change the existing
Org syntax, readability is one of the design guidelines we should follow
(IMHO). Stating it explicitly in the manual will make this guidelines
explicit.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable

[Bastien Guerry]

Jean Louis  writes:

> It's primary use was for Emacs users to make notes, TODO tasks,
> etc. It is secondary that it became leightweight markup language that
> can export to various documents.

IMHO it has always been a _lightweight markup language_, used for
notes and TODO tasks, then soon enough for exporting too.

I got interested to Org back circa 2006 after I stopped working on a
small library called bhl.el: https://www.nongnu.org/bhl/

BHL was a lightweight markup language targetting export only. Org was
vastly superior in all accounts, so I contributed to Org.

-- 
 Bastien Guerry

Re: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable

[Jean Louis]

* Thomas S. Dye  [2024-01-02 08:39]:
> Aloha Ihor,
> 
> Ihor Radchenko  writes:
> 
> > @@ -22,6 +22,10 @@ ** Summary
> >  It relies on a lightweight plain-text markup language used in  files
> >  with the =.org= extension.
> >   +Org files can be viewed using any text editor.  You can read and
> > +understand raw Org markup with a naked eye.  Although authoring Org
> > +files is best-supported inside Emacs.
> > +
> >  As an authoring tool, Org helps you write structured documents  and
> >  provides exporting facilities. Org files can also be used for  literate
> >  programming and reproducible research.  As a TODO lists  manager, Org
> > -- 
> > 2.42.0
> 
> How about this, assuming lightweight is equivalent to readable and easy to
> understand?
> 
> It relies on a readable and easy to understand plain-text markup language
> saved to files with the =.org= extension. Authoring Org files is best
> supported by Emacs, but you can view and change them with any text editor.
> As an authoring tool ...

In my opinion, it's not that Org was intentionally designed to be
"lightweight markup readable for humans"; rather, it was maintained in
a manner that focused on preserving its readability and prevented it
from evolving into something less comprehensible.

It's primary use was for Emacs users to make notes, TODO tasks,
etc. It is secondary that it became leightweight markup language that
can export to various documents.

-- 
Jean

Take action in Free Software Foundation campaigns:
https://www.fsf.org/campaigns

In support of Richard M. Stallman
https://stallmansupport.org/

table of contents + export = Unable to resolve link

[libreville]

hello,

if i create an org file with these three lines:

* contents :TOC:
* a headline
* another

org helpfully completes the table of contents for me:

* contents :TOC:
- [[#a-headline][a headline]]
- [[#another][another]]

* a headline
* another

clicking on one of the links sends point to the corresponding headline.
however, if i now call org-export-dispatch and select a format, org
throws `Unable to resolve link: "a-headline"'.

is it me or is it org?

best,
liv