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

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> 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 <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>