From a8dd1797588bdab7f63628579414c65d7444f387 Mon Sep 17 00:00:00 2001 From: Max Nikulin 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 ==. 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