[PATCH] org-faq.org: Inline comments

[Max Nikulin <manikulin@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 388 bytes --]

On 22/06/2023 08:50, Max Nikulin wrote:
> On 22/06/2023 07:04, ypuntot wrote:
>>
>> Could it be possible to make inline comments (# something like this) ?
...
> Previous discussion:
...

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

To my taste FAQ is rather long already. If you have an idea of another 
place on Worg where such tricks may be added then, please, share it.

[-- Attachment #2: 0001-org-faq.org-Inline-comments.patch --]
[-- Type: text/x-patch, Size: 3414 bytes --]

From a8dd1797588bdab7f63628579414c65d7444f387 Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Wed, 28 Jun 2023 22:40:40 +0700
Subject: [PATCH] org-faq.org: Inline comments

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

diff --git a/org-faq.org b/org-faq.org
index ab661395..7048ab2d 100644
--- a/org-faq.org
+++ b/org-faq.org
@@ -4492,6 +4492,59 @@ ** 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 are block-level elements, so they break paragraphs.
+However some workarounds are possible.
+
+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@@=.
+
+Define a [[https://orgmode.org/manual/Macro-Replacement.html][macro]]
+that expands to nothing
+: #+MACRO: comment
+an use it as ={{{comment( not ideal )}}}=.
+A downside of this approach is warnings issued by ~org-lint~.
+
+Define a [[https://orgmode.org/manual/Adding-Hyperlink-Types.html][custom link type]]
+#+begin_src elisp :exports code :eval never-export
+  (org-link-set-parameters "rem" :export (lambda (&rest _) ""))
+#+end_src
+A bonus is that you may create a
+=[[rem: hidden part of comment][...]]= try =C-h .= (~display-local-help~)
+or =C-c C-l= (~org-insert-link~) to read first part of the comment.
+Another link syntax is =<rem: comment>=.  Beware of patterns that may
+appear in plain text and be recognized as links even without
+enclosing brackets like =rem:10=.  Use a unique sequence of letters
+as the link type.
+
+Use inline [[https://orgmode.org/manual/Structure-of-Code-Blocks.html][source code blocks]]
+for a programming language that does not appear in your text.
+Just suppress export
+: #+header-args:csh :exports none :eval never-export
+and =src_csh{code}= becomes indistinguishable from comments.
+Perhaps with a custom ~org-babel~ backend that evaluates
+code to the same string you may control whether comments
+should appear in exported file.
+
+It is safer to avoid lines that have no text besides comments.
+They may be treated as paragraph separators.
+
+Unfortunately never approach suggested above works on sites for
+hosting of open source code projects. Literal markup
+(or broken links) will appear in e.g. formatted =README.org= files.
+
+Discussions on the mailing list:
+- [[https://list.orgmode.org/5210ac1c-ed73-4b82-a296-41cf90b9f0a7@gmail.com/][Inline comments. Thu, 22 Jun 2023 02:04:15 +0200]]
+- [[https://list.orgmode.org/mid:87zg8jwp26.fsf@localhost/][Re: [BUG] No space after footnote with org-export-with-footnotes set to nil. Sat, 11 Mar 2023 10:38:25 +0000]]
+- [[https://list.orgmode.org/87618398-cf6d-86b4-ba59-144f70d0f96e@7d.nz/][[PATCH] ox: fix comment exported as a blank line. Wed, 1 Jun 2022 07:30:01 +0200]]
+- [[https://list.orgmode.org/alpine.DEB.2.22.394.2107161156080.74845@shell3.miskatonic.org/][Comments break up a paragraph when writing one-setence-per-line. Fri, 16 Jul 2021 12:06:54 -0400]]
+
 * Backup
 
 #+index: Backup
-- 
2.25.1