Re: Feedback on Org syntax document

[Ihor Radchenko]

Bastien Guerry  writes:

> Ihor Radchenko  writes:
>
>> I will merge them if there are no objections.
>
> Thanks!  No objections.  (Sorry I moved org-syntax.org from worg/dev/
> to worg/ right before reading this email, I hope that's okay.)

Apparently git is smart enough to rebase my commits onto the new moved
file path.

Applied onto master.
https://git.sr.ht/~bzg/worg/commit/bcc7f56f
https://git.sr.ht/~bzg/worg/commit/8f5a47a2
https://git.sr.ht/~bzg/worg/commit/f10f47de
https://git.sr.ht/~bzg/worg/commit/fa554834

> Perhaps, on top of removing Tim's comments from org-syntax.org we can
> store them in a dedicated Worg page? worg/dev/org-syntax-comments.org?
>
> To make sure we can refer to a page when we want to discuss them.

Note that I listed all the comments in this thread. I was planning to
extend on them one by one branching from here.

Will it be enough?

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

Re: org-mode code fence for markdown

[Ihor Radchenko]

Norwid Behrnd  writes:

> I seek a similar fence to document a pattern in Markdown.  An example would be
> a nested list such as 
>
> ```markdown
> * Item 1
> * Item 2
>   - Item 2a
> + Item 2a1
>   - Item 2b
> * Item 3
> ```
>
> Contrasting to my anticipation, neither `C-c C-, s` followed by a tentative
> «md», nor «markdown» yield a box which opens by `C-c '`.  Neither table 1, nor
> 2 on worg's documentation[1] mentions markdown.

It should, if you have markdown-mode installed.

Try

#+begin_src markdown :tangle yes
,* Item 1
,* Item 2
  - Item 2a
+ Item 2a1
  - Item 2b
,* Item 3
#+end_src

Note that you need to escape the stars as they would be recognized as
Org headings otherwise.

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

Re: [DISCUSSION] Should we deprecate python-mode.el (alternative to built-in python.el) support in ob-python?

[Bastien]

Jack Kamm  writes:

> If python-mode support is removed, I'd be willing to help create a new
> ob-python-mode package

Indeed.  A suggestion: can you or Ihor send a help request to the
list, explaining the issue at hand and asking if someone wants to
create and maintain ob-python-mode.el?  

This way we can refer to this email on the list when announcing that
ob-python.el do not support python-mode.el anymore.

-- 
 Bastien

Re: Feedback on Org syntax document

[Bastien Guerry]

Ihor Radchenko  writes:

> I will merge them if there are no objections.

Thanks!  No objections.  (Sorry I moved org-syntax.org from worg/dev/
to worg/ right before reading this email, I hope that's okay.)

Perhaps, on top of removing Tim's comments from org-syntax.org we can
store them in a dedicated Worg page? worg/dev/org-syntax-comments.org?

To make sure we can refer to a page when we want to discuss them.

-- 
 Bastien

Re: Org Syntax Specification

[Bastien]

Ihor Radchenko  writes:

> I think we need to use rewrite rule here in addition to moving the file.
> If we simply move the file, old links will be broken.

Done now, thanks.

-- 
 Bastien

Re: Org Syntax Specification

[Ihor Radchenko]

Bastien  writes:

> A few suggestions:
>
> - Make it a description of the syntax of the latest stable Org.  (For
>   now let's consider 9.6 to be the latest stable as we are working on
>   releasing it soon.)  Perhaps this is already the case and I missed
>   it?

Yes, it should be consistent with the latest Org. (We tried our best to
make it so). We also kept some things a bit more generic for forward
compatibility.

> - Remove the "draft" status ("DRAFT v2β"). Don't describe it as a
>   draft in the org-manual.org if it accurately reflects the current
>   syntax (current = latest stable).

> - Remove all the inline notes (some suggest changes in Org's grammar,
>   that might scare the readers a bit.)

See https://orgmode.org/list/87ilj2l0cy.fsf@localhost

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

Re: Feedback on Org syntax document

[Ihor Radchenko]

Ihor Radchenko  writes:

> Below, I am listing my further feedback on the document.
> I encourage other Org users to look into it as well.
> This is one of the big projects that need to be finished as a
> prerequisite for registering Org format in RFC:

I have addressed the most important comments that should be resolved
before the coming Org release.

See the attached patches.

I will merge them if there are no objections.

>From f411e423214c113ef44ba23b09093395d7910e0c Mon Sep 17 00:00:00 2001
Message-Id: 
From: Ihor Radchenko 
Date: Sat, 26 Nov 2022 10:44:13 +0800
Subject: [PATCH 1/4] * dev/org-syntax.org: Remove all the notes

They are to be discussed on mailing list.  See
https://orgmode.org/list/877d08bkze.fsf@localhost
---
 dev/org-syntax.org | 86 --
 1 file changed, 86 deletions(-)

diff --git a/dev/org-syntax.org b/dev/org-syntax.org
index a249d011..c7e9ad60 100644
--- a/dev/org-syntax.org
+++ b/dev/org-syntax.org
@@ -43,10 +43,6 @@ * Introduction
 lightweight markup language.  However, while Markdown refers to a
 collection of similar syntaxes, Org is a single syntax.
 
-#+begin_notes
-Should markdown be mentioned at all?
-#+end_notes
-
 This document describes and comments on Org syntax as it is currently
 read by its parser (=org-element.el=) and, therefore, by the export
 framework. This is intended as a technical document for developers and
@@ -233,12 +229,6 @@ *** Sections
 of the text before the first heading in a document (which is
 considered a section), sections only occur within headings.
 
-#+begin_notes
-Since sections are usually thought of as a larger group that includes
-nested content (e.g. "section 3"), and this isn't what Org sections are,
-maybe this should be called something slightly different?
-#+end_notes
-
 *Example*
 
 Consider the following document:
@@ -393,10 +383,6 @@ *** Inlinetasks
 components (i.e. only STARS and TITLE provided) and the string =END= as
 the TITLE. This allows the inlinetask to contain elements.
 
-#+begin_notes
-Urgh, this syntax is ugly. --- Tom G, Timothy
-#+end_notes
-
 *Examples*
 
 #+begin_example
@@ -523,14 +509,6 @@ *** Property Drawers
 + CONTENTS :: A collection of zero or more [[#Node_Properties][node properties]], not
   separated by blank lines.
 
-#+begin_notes
-The failure mode for malformed contents needs to be determined more clearly
-here. We don't want property draws to suddenly become plain drawers just because
-a user has a malformed line, that could be disastrous if certain settings in the
-property drawer mask settings from further up the tree. In short, malformed
-contents should not poison the whole property drawer. --- Tom G
-#+end_notes
-
 *Example*
 
 #+begin_example
@@ -549,10 +527,6 @@ *** Tables
 + The string =+-= followed by a sequence of plus (=+=) and minus (=-=)
   signs, forming a "table.el" type table.
 
-#+begin_notes
-Maybe drop table.el from the spec?
-#+end_notes
-
 Tables cannot be immediately preceded by such lines, as the current
 line would the be part of the earlier table.
 
@@ -627,13 +601,6 @@ *** Blocks
   CONTENTS will contain Org objects and not support comma-quoting when
   the block is a verse block, it is otherwise not parsed.
 
-#+begin_notes
-Can we drop switch support? This seems like a fairly good idea.
-The functionality can simply be shifted to ARGUMENTS with the
-well-established =:key val= forms.\\
-"For the love of all that is sane" --- Tom G
-#+end_notes
-
 *Example*
 
 #+begin_example
@@ -715,10 +682,6 @@ *** Planning
 When a keyword is repeated in a planning element, the last instance of it has
 priority.
 
-#+begin_notes
-Tom G has requested adding a =OPENED= keyword to track task creation/registration.
-#+end_notes
-
 *Example*
 
 #+begin_example
@@ -785,13 +748,6 @@ *** Keywords
   than =call= (which would forms a [[#Babel_Call][babel call]] element).
 + VALUE :: A string consisting of any characters but a newline.
 
-#+begin_notes
-Perhaps this should be changed to be =#+KEY[OPT]: VAL=? It would make the syntax
-more regular, considering affiliated keywords. I can't see any backwards
-compatibility concerns. \\
-This was suggested by Tom G, but I'm a fan --- Timothy.
-#+end_notes
-
 When KEY is a member of ~org-element-parsed-keywords~[fn:oepkw], VALUE can contain
 the standard set objects, excluding footnote references.
 
@@ -823,11 +779,6 @@  Babel Call
   non-newline characters.  Opening and closing square brackets must be
   balanced.
 
-#+begin_notes
-Should this be distinguished from other keywords at the AST
-interpretation stage, instead of the base syntax? --- Tom G
-#+end_notes
-
  Affiliated Keywords
 :PROPERTIES:
 :CUSTOM_ID: Affiliated_Keywords
@@ -869,22 +820,12 @@  Affiliated Keywords
   is a series of objects from the standard set, excluding footnote
   references.
 
-#+begin_notes
-Should this even be described at a syntax level instead of an AST
-processing level? --- Tom G
-#+end_notes
-
 Repeating an 

Re: [DISCUSSION] Should we deprecate python-mode.el (alternative to built-in python.el) support in ob-python?

[Bastien Guerry]

Ihor Radchenko  writes:

> I am leaning towards announcing the deprecation in the coming
> release.

Agreed, let's move forward in this direction for the release.

-- 
 Bastien

Re: Org Syntax Specification

[Ihor Radchenko]

Bastien  writes:

> - Promote the page to orgmode.org/worg/org-syntax.html: the /dev/ path
>   in the current URL makes it read like it is the syntax for the "dev"
>   version.

I think we need to use rewrite rule here in addition to moving the file.
If we simply move the file, old links will be broken.

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

Re: [DISCUSSION] Should we deprecate python-mode.el (alternative to built-in python.el) support in ob-python? (was: [BUG] ob-python: async session evaluation does not support python-mode.el [9.6-pre (

[Ihor Radchenko]

Ihor Radchenko  writes:

> Should we deprecate the support altogether and not bother with the extra
> maintenance? Or maybe someone want to volunteer maintaining
> python-mode.el integration?

No objections have been received.
Also, python-mode support have been broken for a long time now and no
bug reports have been submitted.

I am leaning towards announcing the deprecation in the coming release.

Bastien, what do you think?

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

Re: [PATCH] Explain how to end a buffer narrowing.

[Ihor Radchenko]

yuvallangerontheroad  writes:

>> Extra [...] are redundant.
>> Please test the patch before submitting.
>
> Sorry. Removed redundant brackets.

Thanks.

It is also a good idea to add quotes around the command key. See the
example in 25.3 Substituting Key Bindings in Documentation
(I am honestly not sure how important quoting is, but let's better
follow the Elisp manual).

Also, please make the commit message more concrete.

Maybe something like

org: Mention how to widen in docstrings of the commands that do narrowing 

Finally, please follow the commit message format as described in
https://orgmode.org/worg/org-contribute.html#commit-messages
In particular, add the changelog entries and TINYCHANGE cookie (I assume
that you don't have FSF copyright assignment).

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

Re: Fix the confusing "result silenced" message

[Ihor Radchenko]

Rudolf Adamkovič  writes:

> Ihor Radchenko  writes:
>
>> :results none are not discarded. Just not inserted and not displayed.
>> Otherwise, they can still be used, for example, during noweb
>> expansion.
>
> Gotcha!
>
> So, what do we say instead of "silenced", to avoid the expected
> confusion with ":results silent"?

Hmm. Maybe not displaying message at all?

This message was introduced by me when someone complained about too
verbose tangling process when noweb references are expanded. Previously,
the results were, in fact, displayed in echo area with :results none.

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

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

Re: [PATCH] Add new :results ignore header argument (was: [External] : Re: [BUG] executing sh source block with ':results none' encounters error region is longer than org-table-convert-region-max-line

[Ihor Radchenko]

Rudolf Adamkovič  writes:

>> Any objections?
>
> With the existing imprecise names, "silent" (that talks) and "none"
> (that exists), we should try for maximum precision to avoid further
> confusion.  Looking at your documentation, the word "discard" conveys
> the meaning better than "ignore".  It says that we actually "throw the
> result away" for all intents and purposes, this time.  Other than
> discard, I found scrap, drop, ditch, swallow.

Good idea. I also like "discard" better.
See the updated patch.

>From c262579e8f1ef9ffecfc8e051fd5ea2539b4525e Mon Sep 17 00:00:00 2001
Message-Id: 
From: Ihor Radchenko 
Date: Tue, 22 Nov 2022 10:06:24 +0800
Subject: [PATCH v2] org-babel: Add new :results discard header argument

* lisp/ob-core.el (org-babel-result-cond): Unconditionally return nil
and suppress all the processing for :results discard.
(org-babel-common-header-args-w-values):
(org-babel-sha1-hash): Add the new value to know :results value list.
* doc/org-manual.org (Handling):
* etc/ORG-NEWS (New =:results discard= header argument): Document the
new value.

Reported-by: Daniel Ortmann 
Link: https://orgmode.org/list/87tu2tjary.fsf@localhost
---
 doc/org-manual.org |  8 
 etc/ORG-NEWS   |  8 
 lisp/ob-core.el| 43 ++-
 3 files changed, 38 insertions(+), 21 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 760c1ee86..67b8b4dee 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -18487,6 +18487,14 @@ *** Handling
   can still be used when referenced from another code block.
   Usage example: =:results none=.
 
+- =discard= ::
+
+  Ignore the results completely.  This option is similar to =none=,
+  but no processing is performed on the return value.  Calling the
+  code block programatically (see [[*How to evaluate source code]]) or by
+  reference (see [[*Passing arguments]] and [[*Noweb Reference Syntax]]) will
+  always yield nil.
+
 - =append= ::
 
   Append results to the Org buffer.  Latest results are at the bottom.
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 63ff5d749..fd569106a 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -373,6 +373,14 @@ value of ~org-babel-clojure-backend~. For example:
 (range 2)
 #+end_src
 
+*** New =:results discard= header argument
+
+Unlike =:results none=, the return value of code blocks called with
+=:results discard= header argument is always ~nil~.  Org does not
+attempt to analyze the results and simply returns nil.  This can be
+useful when the code block is used for side effects only but generates
+large outputs that may be slow to analyze for Org.
+
 ** New options
 *** A new option for custom setting ~org-refile-use-outline-path~ to show document title in refile targets
 
diff --git a/lisp/ob-core.el b/lisp/ob-core.el
index 3a07c10d5..5f679a5e9 100644
--- a/lisp/ob-core.el
+++ b/lisp/ob-core.el
@@ -425,7 +425,7 @@ (defconst org-babel-common-header-args-w-values
 (prologue   . :any)
 (results	. ((file list vector table scalar verbatim)
 		   (raw html latex org code pp drawer link graphics)
-		   (replace silent none append prepend)
+		   (replace silent none discard append prepend)
 		   (output value)))
 (rownames	. ((no yes)))
 (sep	. :any)
@@ -1345,7 +1345,7 @@ (defun org-babel-sha1-hash ( info context)
 		(lambda (a b) (string< (car a) (car b)
 (let* ((rm (lambda (lst)
 		 (dolist (p '("replace" "silent" "none"
-			  "append" "prepend"))
+			  "discard" "append" "prepend"))
 		   (setq lst (remove p lst)))
 		 lst))
 	   (norm (lambda (arg)
@@ -1353,8 +1353,8 @@ (defun org-babel-sha1-hash ( info context)
 (copy-sequence (cdr arg))
 			  (cdr arg
 		 (when (and v (not (and (sequencep v)
-	(not (consp v))
-	(= (length v) 0
+	  (not (consp v))
+	  (= (length v) 0
 		   (cond
 			((and (listp v) ; lists are sorted
 			  (member (car arg) '(:result-params)))
@@ -1382,10 +1382,10 @@ (defun org-babel-sha1-hash ( info context)
  (mapconcat
   #'identity
   (delq nil (mapcar (lambda (arg)
-  (let ((normalized (funcall norm arg)))
-(when normalized
-  (format "%S" normalized
-(nth 2 info))) ":")
+(let ((normalized (funcall norm arg)))
+  (when normalized
+(format "%S" normalized
+  (nth 2 info))) ":")
  expanded))
  (hash (sha1 it)))
 (when (called-interactively-p 'interactive) (message hash))
@@ -3289,19 +3289,20 @@ (defmacro org-babel-result-cond (result-params scalar-form  table-forms)
   (declare 

Re: test-org-table/sort-lines: Failing test on macOS

[Ihor Radchenko]

Max Nikulin  writes:

>> However, I feel a bit lost about what to do on Org side.
>> We can put a disclaimer in the manual and all that, but it still feels
>> too complex.
>
> My current suggestion is to provide a fallback to `downcase' in the code 
> and to explain in the manual that runtime environments (OSes) are not 
> equal and quality of locale support varies. Emacs heavily depends on 
> libc in this area.

This sounds like something to be adapted to Emacs upstream.
I suggested to change `string-collate-lessp' fallback behaviour to use
`downcase' when IGNORE-CASE is non-nil. See my last message in
bug#59275.

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

Re: [RFC] :var x=list-name should be resolved into simple lists (item1 item2 ...); not nested ((item1) (item2) ...) (was: 2 'echo' bash instructions produce a table)

[Ihor Radchenko]

Ihor Radchenko  writes:

> The attached is a fix for this discrepancy with the manual.
>
> However, it looks like at least ob-java already tried to work around the
> erroneous return value of org-babel-read-list.
>
> Hence, we at least need to announce this fix in ORG-NEWS.
>
> Or maybe there are other objections?

No objections have been raised.
Applied onto main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=b4e437f968771df9555f9306467846965857f632

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

Re: [PATCH] Add new :results ignore header argument (was: [External] : Re: [BUG] executing sh source block with ':results none' encounters error region is longer than org-table-convert-region-max-line

[Rudolf Adamkovič]

Ihor Radchenko  writes:

> Any objections?

With the existing imprecise names, "silent" (that talks) and "none"
(that exists), we should try for maximum precision to avoid further
confusion.  Looking at your documentation, the word "discard" conveys
the meaning better than "ignore".  It says that we actually "throw the
result away" for all intents and purposes, this time.  Other than
discard, I found scrap, drop, ditch, swallow.

Rudy
-- 
"Strange as it may sound, the power of mathematics rests on its evasion
of all unnecessary thought and on its wonderful saving of mental
operations."
-- Ernst Mach, 1838-1916

Rudolf Adamkovič  [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: Fix the confusing "result silenced" message

[Rudolf Adamkovič]

Ihor Radchenko  writes:

> :results none are not discarded. Just not inserted and not displayed.
> Otherwise, they can still be used, for example, during noweb
> expansion.

Gotcha!

So, what do we say instead of "silenced", to avoid the expected
confusion with ":results silent"?

Some ideas:

- Result not displayed
- Result not shown
- Result hidden
- Result suppressed

Or even something longer:

- Execution done, result not displayed
- Execution done, result not shown
- Execution done, result hidden
- Execution done, result suppressed

Rudy
-- 
"'Contrariwise,' continued Tweedledee, 'if it was so, it might be; and
if it were so, it would be; but as it isn't, it ain't.  That's logic.'"
-- Lewis Carroll, Through the Looking Glass, 1871/1872

Rudolf Adamkovič  [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

org-mode code fence for markdown

[Norwid Behrnd]

Dear list,

based on previous experience to fence small snippets of code in org-mode e.g.,
for Fortran in a pattern like

```org
* example Fortran (not FORTRAN 77)

  #+begin_src f90 :tangle echo.f90
program test
  implicit none
  write (*, '(A)') "Fortran"
end program test  
  #+end_src
```

I seek a similar fence to document a pattern in Markdown.  An example would be
a nested list such as 

```markdown
* Item 1
* Item 2
  - Item 2a
+ Item 2a1
  - Item 2b
* Item 3
```

Contrasting to my anticipation, neither `C-c C-, s` followed by a tentative
«md», nor «markdown» yield a box which opens by `C-c '`.  Neither table 1, nor
2 on worg's documentation[1] mentions markdown.

Is there a special key (similar to f90 for contemporary Fortran) /to tangle/
selected, individually fenced snippets of .md stored in one .org file into one
.md file which wasn't yet added to these tables?  Or -- given subtle
differences in the dialects e.g., by Gruber, GitHub, Pandoc -- is there too
little benefit for such an additional bridge, perhaps especially whole .org
documents may be rewritten into any of the three forms of .md by pandoc, and
`C-c C-e` equally may be configured to export a buffer of running Emacs
org-mode to .md?

Norwid

[1] https://orgmode.org/worg/org-contrib/babel/languages/index.html

Re: emphasis in embedded text

[Max Nikulin]

On 25/11/2022 10:56, David Zelinsky wrote:

I wanted to have some text emphasized when immediately following a
comma.


In some cases it is possible to use shy hyphen,\-/instead/ of zero width 
space.

Re: [PATCH] Explain how to end a buffer narrowing.

[yuvallangerontheroad]

On Friday, November 25th, 2022 at 16:52, Ihor Radchenko  
wrote:


> yuvallangerontheroad yuvallangeronther...@proton.me writes:
> 
> > + "Narrow buffer to the current subtree.
> > +Use the command \\[[widen]] to see the whole buffer again."
> 
> 
> Extra [...] are redundant.
> Please test the patch before submitting.

Sorry. Removed redundant brackets.From 2c5a5fa3cdb06390d3c20a47c97720074a1af507 Mon Sep 17 00:00:00 2001
From: Yuval Langer 
Date: Fri, 25 Nov 2022 16:40:50 +0200
Subject: [PATCH] Explain how to remove restrictions (narrowing) from current
 buffer.

---
 lisp/org.el | 12 
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 64b33e597..b30d2997a 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -7220,7 +7220,8 @@ If yes, remember the marker and the distance to BEG."
   (setq org-markers-to-move nil))
 
 (defun org-narrow-to-subtree ( element)
-  "Narrow buffer to the current subtree."
+  "Narrow buffer to the current subtree.
+Use the command \\[widen] to see the whole buffer again."
   (interactive)
   (if (org-element--cache-active-p)
   (let* ((heading (org-element-lineage
@@ -7242,7 +7243,8 @@ If yes, remember the marker and the distance to BEG."
 	 (point
 
 (defun org-toggle-narrow-to-subtree ()
-  "Narrow to the subtree at point or widen a narrowed buffer."
+  "Narrow to the subtree at point or widen a narrowed buffer.
+Use the command \\[widen] to see the whole buffer again."
   (interactive)
   (if (buffer-narrowed-p)
   (progn (widen) (message "Buffer widen"))
@@ -7250,7 +7252,8 @@ If yes, remember the marker and the distance to BEG."
 (message "Buffer narrowed to current subtree")))
 
 (defun org-narrow-to-block ()
-  "Narrow buffer to the current block."
+  "Narrow buffer to the current block.
+Use the command \\[widen] to see the whole buffer again."
   (interactive)
   (let* ((case-fold-search t)
 	 (blockp (org-between-regexps-p "^[ \t]*#\\+begin_.*"
@@ -21162,7 +21165,8 @@ ones already marked."
 	(goto-char (org-element-property :begin element))
 
 (defun org-narrow-to-element ()
-  "Narrow buffer to current element."
+  "Narrow buffer to current element.
+Use the command \\[widen] to see the whole buffer again."
   (interactive)
   (let ((elem (org-element-at-point)))
 (cond
-- 
2.30.2

Re: [PATCH] Explain how to end a buffer narrowing.

[Ihor Radchenko]

yuvallangerontheroad  writes:

> +  "Narrow buffer to the current subtree.
> +Use the command \\[[widen]] to see the whole buffer again."

Extra [...] are redundant.
Please test the patch before submitting.

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

Re: [PATCH] Explain how to end a buffer narrowing.

[yuvallangerontheroad]

On Friday, November 25th, 2022 at 16:32, Ihor Radchenko  
wrote:

> But please use `\\[widen]' instead of M-x widen. Then, Emacs will
> automatically display the actual key binding for widen or "M-x widen" if
> no binding is present.

Thank you. The change is in the attachment.From 5e0bef6c7e288191d9b7d2517fda29718e47baad Mon Sep 17 00:00:00 2001
From: Yuval Langer 
Date: Fri, 25 Nov 2022 16:40:50 +0200
Subject: [PATCH] Explain how to remove restrictions (narrowing) from current
 buffer.

---
 lisp/org.el | 12 
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 64b33e597..b4cd73ba0 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -7220,7 +7220,8 @@ If yes, remember the marker and the distance to BEG."
   (setq org-markers-to-move nil))
 
 (defun org-narrow-to-subtree ( element)
-  "Narrow buffer to the current subtree."
+  "Narrow buffer to the current subtree.
+Use the command \\[[widen]] to see the whole buffer again."
   (interactive)
   (if (org-element--cache-active-p)
   (let* ((heading (org-element-lineage
@@ -7242,7 +7243,8 @@ If yes, remember the marker and the distance to BEG."
 	 (point
 
 (defun org-toggle-narrow-to-subtree ()
-  "Narrow to the subtree at point or widen a narrowed buffer."
+  "Narrow to the subtree at point or widen a narrowed buffer.
+Use the command \\[[widen]] to see the whole buffer again."
   (interactive)
   (if (buffer-narrowed-p)
   (progn (widen) (message "Buffer widen"))
@@ -7250,7 +7252,8 @@ If yes, remember the marker and the distance to BEG."
 (message "Buffer narrowed to current subtree")))
 
 (defun org-narrow-to-block ()
-  "Narrow buffer to the current block."
+  "Narrow buffer to the current block.
+Use the command \\[[widen]] to see the whole buffer again."
   (interactive)
   (let* ((case-fold-search t)
 	 (blockp (org-between-regexps-p "^[ \t]*#\\+begin_.*"
@@ -21162,7 +21165,8 @@ ones already marked."
 	(goto-char (org-element-property :begin element))
 
 (defun org-narrow-to-element ()
-  "Narrow buffer to current element."
+  "Narrow buffer to current element.
+Use the command \\[[widen]] to see the whole buffer again."
   (interactive)
   (let ((elem (org-element-at-point)))
 (cond
-- 
2.30.2

Re: emphasis in embedded text

[Ihor Radchenko]

David Zelinsky  writes:

> I wanted to have some text emphasized when immediately following a
> comma.  I found in the manual the suggestion to use a zero-width space
> character.  That works, except that it turns out that by default emacs
> actually displays the zero-width space as 1-pixel wide.  That's not
> noticeable in a paragraph.  But in an org-mode table, it causes cell
> boundaries to be slightly misaligned.  And with more than one of these
> in a row, it becomes more than slightly.  That is very annoying.

I can see this being very annoying. Another argument to implement proper
pixel-precise table alignment.

Meanwhile, I recommend https://github.com/casouri/valign

> Before I found this, I also stumbled on suggestions (apparently
> predating adoption of the zero-width space paradigm) to customize
> `org-emphasis-regexp-components'.  That actually works very nicely for
> my purpose, so I'll probably stick with that.

Please, don't use it. It is internal variable and changing it will
break things.

> But the point of this post is to suggest that the org-mode manual ought
> to document these things more fully.  The section (12.2 Emphasis and
> Monospace) that mentions the zero-width space approach ought to also
> mention that by default in emacs these are not actually zero width.
> Something like the description in the linked post would be great.

It should not matter ideally. Zero-width space is part of syntax and the
way Emacs displays it usually does not matter. As I said, issues with
non-fixed width symbols in tables should be fixed separately.

> I don't know if this list is the right place to make such a suggestion.
> Should I submit a bug report with some suggested modifications to the
> manual?  Or is this all documented somewhere already and I just didn't
> find it?

This list is the right place for discussions, patches, and bug reports.

> ***NOTE***: I gather there's some controversy about the zero-width space
> approach, especially in regard to exports.  I very much don't want to
> trigger that debate!  I'm merely suggesting the manual say a bit more
> about how things currently work, so others won't spend as much time as I
> did figuring it out :)

+1

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

Re: [PATCH] Explain how to end a buffer narrowing.

[Ihor Radchenko]

yuvallangerontheroad  writes:

> I have added information on how to exit a narrowing. I could have used this 
> information when I started using org-narrow-to-subtree.
> ...
>  (defun org-narrow-to-subtree ( element)
> -  "Narrow buffer to the current subtree."
> +  "Narrow buffer to the current subtree.
> +   Use the command M-x widen  to see the whole buffer again."

Thanks!
I am neutral wrt this addition. Could be useful.

But please use `\\[widen]' instead of M-x widen. Then, Emacs will
automatically display the actual key binding for widen or "M-x widen" if
no binding is present.

See 25.3 Substituting Key Bindings in Documentation section of Elisp
manual.

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

emphasis in embedded text

[David Zelinsky]

I wanted to have some text emphasized when immediately following a
comma.  I found in the manual the suggestion to use a zero-width space
character.  That works, except that it turns out that by default emacs
actually displays the zero-width space as 1-pixel wide.  That's not
noticeable in a paragraph.  But in an org-mode table, it causes cell
boundaries to be slightly misaligned.  And with more than one of these
in a row, it becomes more than slightly.  That is very annoying.

At first I did not understand what was happening.  But then I found this
post on stackexchange that explains it all very clearly, along with how
to change emacs' default, either globally or just in certain modes:

https://emacs.stackexchange.com/questions/65108/zero-width-space-shows-as-underscore

Before I found this, I also stumbled on suggestions (apparently
predating adoption of the zero-width space paradigm) to customize
`org-emphasis-regexp-components'.  That actually works very nicely for
my purpose, so I'll probably stick with that.


But the point of this post is to suggest that the org-mode manual ought
to document these things more fully.  The section (12.2 Emphasis and
Monospace) that mentions the zero-width space approach ought to also
mention that by default in emacs these are not actually zero width.
Something like the description in the linked post would be great.

And for `org-emphasis-regexp-components', as far as I can tell this
variable is not mentioned at all anywhere in the manual.  I suspect
maybe this is because it's a kind of kludgy variable and maybe its use
should not be encouraged.  But it could at least be mentioned.  I only
learned of its existence from those older posts I mentioned above.


I don't know if this list is the right place to make such a suggestion.
Should I submit a bug report with some suggested modifications to the
manual?  Or is this all documented somewhere already and I just didn't
find it?


***NOTE***: I gather there's some controversy about the zero-width space
approach, especially in regard to exports.  I very much don't want to
trigger that debate!  I'm merely suggesting the manual say a bit more
about how things currently work, so others won't spend as much time as I
did figuring it out :)


-David

[PATCH] Explain how to end a buffer narrowing.

[yuvallangerontheroad]

I have added information on how to exit a narrowing. I could have used this 
information when I started using org-narrow-to-subtree.From 680fbfc0a91552c5d73e853effadeaa683266ec9 Mon Sep 17 00:00:00 2001
From: Yuval Langer 
Date: Thu, 24 Nov 2022 19:27:00 +0200
Subject: [PATCH] Explain how to remove restrictions (narrowing) from current
 buffer.

---
 lisp/org.el | 12 
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 64b33e597..45650efb5 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -7220,7 +7220,8 @@ If yes, remember the marker and the distance to BEG."
   (setq org-markers-to-move nil))
 
 (defun org-narrow-to-subtree ( element)
-  "Narrow buffer to the current subtree."
+  "Narrow buffer to the current subtree.
+   Use the command M-x widen  to see the whole buffer again."
   (interactive)
   (if (org-element--cache-active-p)
   (let* ((heading (org-element-lineage
@@ -7242,7 +7243,8 @@ If yes, remember the marker and the distance to BEG."
 	 (point
 
 (defun org-toggle-narrow-to-subtree ()
-  "Narrow to the subtree at point or widen a narrowed buffer."
+  "Narrow to the subtree at point or widen a narrowed buffer.
+   Use the command M-x widen  to see the whole buffer again."
   (interactive)
   (if (buffer-narrowed-p)
   (progn (widen) (message "Buffer widen"))
@@ -7250,7 +7252,8 @@ If yes, remember the marker and the distance to BEG."
 (message "Buffer narrowed to current subtree")))
 
 (defun org-narrow-to-block ()
-  "Narrow buffer to the current block."
+  "Narrow buffer to the current block.
+   Use the command M-x widen  to see the whole buffer again."
   (interactive)
   (let* ((case-fold-search t)
 	 (blockp (org-between-regexps-p "^[ \t]*#\\+begin_.*"
@@ -21162,7 +21165,8 @@ ones already marked."
 	(goto-char (org-element-property :begin element))
 
 (defun org-narrow-to-element ()
-  "Narrow buffer to current element."
+  "Narrow buffer to current element.
+   Use the command M-x widen  to see the whole buffer again."
   (interactive)
   (let ((elem (org-element-at-point)))
 (cond
-- 
2.30.2

Re: Problem in org-inlinetask-min-level's docstring?

[Ihor Radchenko]

alain.coch...@unistra.fr writes:

> The last paragraph of this docstring is:
>
>It is strongly recommended that you set ‘org-cycle-max-level’ not
>at all, or to a number smaller than this one.  In fact, when
>‘org-cycle-max-level’ is not set, it will be assumed to be one less
>than the value of smaller than the value of this variable.
>
> I do not understand the last sentence, even assuming that the 1st 'of'
> is 'or'.   Is my English the problem?

That sentence is indeed screwed up.

Does `org-cycle-max-level' docstring sound better?

Maximum level which should still be subject to visibility cycling.
Levels higher than this will, for cycling, be treated as text, not a 
headline.
When `org-odd-levels-only' is set, a value of N in this variable actually
means 2N-1 stars as the limiting headline.
When nil, cycle all levels.
Note that the limiting level of cycling is also influenced by
`org-inlinetask-min-level'.  When `org-cycle-max-level' is not set but
`org-inlinetask-min-level' is, cycling will be limited to levels one less
than its value.

We may simply replace the faulty sentence with a link to
`org-cycle-max-level' docstring.

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

Problem in org-inlinetask-min-level's docstring?

[Alain . Cochard]

The last paragraph of this docstring is:

   It is strongly recommended that you set ‘org-cycle-max-level’ not
   at all, or to a number smaller than this one.  In fact, when
   ‘org-cycle-max-level’ is not set, it will be assumed to be one less
   than the value of smaller than the value of this variable.

I do not understand the last sentence, even assuming that the 1st 'of'
is 'or'.   Is my English the problem?

Thanks

-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.coch...@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France | [ slot available for rent ]