Trailing whitespace after export snippets without a transcoder (was: [PATCH v2] org-faq.org: Inline comments)

[Ihor Radchenko]

Max Nikulin  writes:

>> +#+begin_src org
>> +The following line may become a patagraph separator.
>> +@@comment: might give unexpected effect @@
>> +Put some text before @@comment: a better variant
>> +@@ and after instread.
>> +#+end_src
>> 
>> I am no longer able to reproduce the problem with @@comment:...@@
>> splitting paragraph in the above example.
>
> I see no changes in respect to ox-md on the main branch.

Right.
Upon debugging further, to my great surprise, I found the following
comment in ox.el:

;; Export snippets never return a nil value so
;; that white spaces following them are never
;; ignored.
(and (eq type 'export-snippet) "")

and then even a test:

;; Ignored export snippets do not remove any blank.
  (should
   (equal "begin  end\n"
  (org-test-with-parsed-data "begin @@test:A@@ end"
(org-export-data-with-backend
 tree
 (org-export-create-backend
  :transcoders
  '((paragraph . (lambda (paragraph contents info) contents))
(section . (lambda (section contents info) contents
 info

The test was added in the commit
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=a6d9fd82e

Back-end developers should pay attention to the fact that white spaces
before and after an ignored export snippet now are accumulated in the
output.

I have no clue about the rationale of this special behaviour - it dates
back to the days when Org export was merged. It is also not documented
anywhere, AFAIK.

-- 
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-faq.org: Inline comments

[Max Nikulin]

On 15/04/2024 19:17, Ihor Radchenko wrote:



+#+begin_src org
+The following line may become a patagraph separator.
+@@comment: might give unexpected effect @@
+Put some text before @@comment: a better variant
+@@ and after instread.
+#+end_src


I am no longer able to reproduce the problem with @@comment:...@@
splitting paragraph in the above example.


I see no changes in respect to ox-md on the main branch.

 8< 
The following line may become a paragraph separator.
@@comment: might give unexpected effect @@
Put some text before @@comment: a better variant
@@ and after instead.
 >8 

is exported to

 8< 
The following line may become a paragraph separator.

Put some text before  and after instead.
 >8 

Re: [PATCH v2] org-faq.org: Inline comments

[Ihor Radchenko]

Ihor Radchenko  writes:

 +#+begin_src org
 +The following line may become a patagraph separator.
 +@@comment: might give unexpected effect @@
 +Put some text before @@comment: a better variant
 +@@ and after instread.
 +#+end_src
>>> 
>>> May you please elaborate?
>>> If you see inline export block starting a paragraph, it is a bug.
> ...
>
> As for comments, I tend to agree that it is indeed a bug.

I am no longer able to reproduce the problem with @@comment:...@@
splitting paragraph in the above example.

-- 
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-faq.org: Inline comments

[Ihor Radchenko]

Max Nikulin  writes:

> On 08/07/2023 16:31, Ihor Radchenko wrote:
 - it is what we use ourselves in WORG sources.
>
>> Max Nikulin writes:
>>> I have not found it in the worg repository. There are enough @@html:@@
>>> with a handful of @@latex:@@.
>> 
>> Yeah, not in WORG.
>> https://orgmode.org/quickstart.html#text-comments
>
> It makes the FAQ entry having no value if your suggestions are taken 
> into account. (I would add a link to annotating that is another sort of 
> comments instead of dropping content further.) So I am giving up and 
> leaving opportunity to propose changes to somebody else.

https://git.sr.ht/~bzg/worg/commit/f598c7ef

> Bing rates quickstart reasonably, but Google avoids it and I have no 
> idea why. Some hypotheses:
> - quickstart uses generic metadata for the whole site, not specific for 
> this page
> -  repeating  has display:none property
> - invalid markup in index.html (a pitfall with affiliated keywords 
> breaking paragraphs) for the link to quickstart:
>
> 
> 
> 
>
> 
>  class="org-svg" title="Start using Org. You'll never stop.">
>
> 
>
> 
> 
>
> I am unsure, but I would expect something like
>
>  >   class="org-svg">

I have no idea here. I wish somebody more familiar with search engine
optimization chimed in.

>>> +#+begin_src org
>>> +The following line may become a patagraph separator.
>>> +@@comment: might give unexpected effect @@
>>> +Put some text before @@comment: a better variant
>>> +@@ and after instread.
>>> +#+end_src
>> 
>> May you please elaborate?
>> If you see inline export block starting a paragraph, it is a bug.
>
> I failed to convince you that it is a general issue, not a LaTeX 
> specific one.
>
> Ihor Radchenko to emacs-orgmode… Re: [BUG] No space after footnote with 
> org-export-with-footnotes set to nil [9.6.1 ( @ 
> /Users/test/.emacs.d/elpa/28.0/develop/org-9.6.1/)] Tue, 14 Mar 2023 
> 12:19:11 +. https://list.orgmode.org/87fsa7o79c.fsf@localhost
>
> try to export to MarkDown. Even for LaTeX the fix is in the development 
> branch only. There are enough users of built-in Org that deserve to be 
> warned.

The linked message was talking about macros. I still think that for
macros specifically it was not a bug - macros may be expanded into
multiple paragraphs, which is perfectly fine. We should not force macro
expansion to ensure a single paragraph.

As for comments, I tend to agree that it is indeed a bug.

-- 
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-faq.org: Inline comments

[Max Nikulin]

On 08/07/2023 16:31, Ihor Radchenko wrote:

- it is what we use ourselves in WORG sources.



Max Nikulin writes:

I have not found it in the worg repository. There are enough @@html:@@
with a handful of @@latex:@@.


Yeah, not in WORG.
https://orgmode.org/quickstart.html#text-comments


It makes the FAQ entry having no value if your suggestions are taken 
into account. (I would add a link to annotating that is another sort of 
comments instead of dropping content further.) So I am giving up and 
leaving opportunity to propose changes to somebody else.


The section in quickstart was added in

64922ca 2020-10-04 14:28:00 -0400 Tom Gillespie: quickstart add sections 
for comments and macros at the end


I am surprises that quickstart is more detailed than the manual. However 
I have no idea how to have this section in both documents with proper 
balance in respect to details. Literal copy may be distracting for 
readers familiar with quickstart.


Bing rates quickstart reasonably, but Google avoids it and I have no 
idea why. Some hypotheses:
- quickstart uses generic metadata for the whole site, not specific for 
this page

-  repeating  has display:none property
- invalid markup in index.html (a pitfall with affiliated keywords 
breaking paragraphs) for the link to quickstart:







class="org-svg" title="Start using Org. You'll never stop.">







I am unsure, but I would expect something like




+#+begin_src org
+The following line may become a patagraph separator.
+@@comment: might give unexpected effect @@
+Put some text before @@comment: a better variant
+@@ and after instread.
+#+end_src


May you please elaborate?
If you see inline export block starting a paragraph, it is a bug.


I failed to convince you that it is a general issue, not a LaTeX 
specific one.


Ihor Radchenko to emacs-orgmode… Re: [BUG] No space after footnote with 
org-export-with-footnotes set to nil [9.6.1 ( @ 
/Users/test/.emacs.d/elpa/28.0/develop/org-9.6.1/)] Tue, 14 Mar 2023 
12:19:11 +. https://list.orgmode.org/87fsa7o79c.fsf@localhost


try to export to MarkDown. Even for LaTeX the fix is in the development 
branch only. There are enough users of built-in Org that deserve to be 
warned.

Re: [PATCH v2] org-faq.org: Inline comments

[Ihor Radchenko]

Max Nikulin  writes:

>> The proposed FAQ entry is overwhelming. It would work fine as a blog,
>> but not as a quick answer to a question. I recommend leaving only the
>> @@comment:...@@ part
>
> See a shortened variant.

Thanks!

>> - it is what we use ourselves in WORG sources.
>
> I have not found it in the worg repository. There are enough @@html:@@ 
> with a handful of @@latex:@@.

Yeah, not in WORG.
https://orgmode.org/quickstart.html#text-comments

> +** Is it possible to add inline comments?
> +:PROPERTIES:
> +:CUSTOM_ID: inline-comments
> +:END:
> +
> +Unfortunately [[https://orgmode.org/manual/Comment-Lines.html][comments]]
> +in Org mode are block-level elements, so they break paragraphs.

Please, avoid "unfortunately". This reads kinda strange.
Comments do break paragraphs, which is our design decision. Some people
like it, some don't.

> +It is safer to avoid export snippets having no other content before or after 
> them
> +on the same line.
> +#+begin_src org
> +The following line may become a patagraph separator.
> +@@comment: might give unexpected effect @@
> +Put some text before @@comment: a better variant
> +@@ and after instread.
> +#+end_src

May you please elaborate?
If you see inline export block starting a paragraph, it is a bug.

> +Alternatives are:
> +a [[https://orgmode.org/manual/Macro-Replacement.html][macro]]
> +expanding to nothing,
> +a [[https://orgmode.org/manual/Adding-Hyperlink-Types.html][custom link 
> type]]
> +exporting to empty string,
> +[[https://orgmode.org/manual/Structure-of-Code-Blocks.html][source code 
> blocks]]
> +with exporting and evaluation suppressed through default header arguments.

Again, this is not helpful as FAQ entry. We do not need to provide
overwhelming number of possibilities here.

> +Unfortunately sites for hosting of open source code projects
> +do not support such tricks and inline comments may appear in formatted
> +=README.org= or other files.

Why do we need to mention it here?
If you really want to explain this problem, it should be a dedicated FAQ
entry. Rendering Org files on Github and other sites has many more
problems not limited to inline export snippets.

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

[PATCH v2] org-faq.org: Inline comments

[Max Nikulin]

On 29/06/2023 17:47, Ihor Radchenko wrote:

Max Nikulin writes:

I think, it is time to add a FAQ entry, see the attachment.


The proposed FAQ entry is overwhelming. It would work fine as a blog,
but not as a quick answer to a question. I recommend leaving only the
@@comment:...@@ part


See a shortened variant.


- it is what we use ourselves in WORG sources.


I have not found it in the worg repository. There are enough @@html:@@ 
with a handful of @@latex:@@.
From fc587b06c20e865636f16104c13b3f239680e7bf Mon Sep 17 00:00:00 2001
From: Max Nikulin 
Date: Wed, 28 Jun 2023 22:40:40 +0700
Subject: [PATCH v2] org-faq.org: Inline comments

* org-faq.org (Export): New heading describing workarounds
for inline comments.
---
 org-faq.org | 32 
 1 file changed, 32 insertions(+)

diff --git a/org-faq.org b/org-faq.org
index ab661395..42cd2ef4 100644
--- a/org-faq.org
+++ b/org-faq.org
@@ -4492,6 +4492,38 @@ ** How can I suppress the page number in the footer of an exported PDF?
 
 : #+LATEX: \thispagestyle{empty}
 
+** Is it possible to add inline comments?
+:PROPERTIES:
+:CUSTOM_ID: inline-comments
+:END:
+
+Unfortunately [[https://orgmode.org/manual/Comment-Lines.html][comments]]
+in Org mode are block-level elements, so they break paragraphs.
+
+As a workaround choose a non-standard export backend name and use it in
+[[https://orgmode.org/worg/org-syntax.html#Export_Snippets][export snippets]]:
+=@@comment: rewrite it @@= or even =@@c: be concise@@=.
+It is safer to avoid export snippets having no other content before or after them
+on the same line.
+#+begin_src org
+The following line may become a patagraph separator.
+@@comment: might give unexpected effect @@
+Put some text before @@comment: a better variant
+@@ and after instread.
+#+end_src
+
+Alternatives are:
+a [[https://orgmode.org/manual/Macro-Replacement.html][macro]]
+expanding to nothing,
+a [[https://orgmode.org/manual/Adding-Hyperlink-Types.html][custom link type]]
+exporting to empty string,
+[[https://orgmode.org/manual/Structure-of-Code-Blocks.html][source code blocks]]
+with exporting and evaluation suppressed through default header arguments.
+
+Unfortunately sites for hosting of open source code projects
+do not support such tricks and inline comments may appear in formatted
+=README.org= or other files.
+
 * Backup
 
 #+index: Backup
-- 
2.25.1