Comments break up a paragraph when writing one-setence-per-line

Comments break up a paragraph when writing one-setence-per-line

[William Denton]

I'm writing an article and decided to try putting each sentence on a different 
line, which I've seen some people here recommend because it makes using version 
control easier.  It took a little while to get used to it, but I think I like 
it.

However, I was a bit surprised when I found that a commented line starts a new 
paragraph.  For example, let's say I have a paragraph but I want to comment out 
a sentence because I'm not sure if I want it in.

#+begin_src org

In this paragraph I introduce an idea.
# Here is something I'm not sure about yet.
But I am sure about this.
And here is my conclusion.

#+end_src org

When this is exported, it becomes two paragraphs, as though the commented line 
was a blank line.  This was unexpected, because to me this is one paragraph with 
one sentence hidden.

People who write one-sentence-per-line, have you had this problem, and if so how 
did you handle it?

Bill

--
William Denton
https://www.miskatonic.org/
Librarian, artist and licensed private investigator.
Toronto, Canada

Re: Comments break up a paragraph when writing one-setence-per-line

[Bruce D'Arcus]

On Fri, Jul 16, 2021 at 12:07 PM William Denton <wtd@pobox.com> wrote:

> However, I was a bit surprised when I found that a commented line starts a new
> paragraph.

I hadn't yet discovered that, but I think it should be considered a
bug. The output of your example should remove the commented line
entirely, and so be:

In this paragraph I introduce an idea.
But I am sure about this. And here is my conclusion.

Perhaps it can be easily fixed?


Bruce

Re: Comments break up a paragraph when writing one-setence-per-line

[Kaushal Modi]

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

Hello,


On Fri, Jul 16, 2021 at 12:35 PM Bruce D'Arcus <bdarcus@gmail.com> wrote:

> On Fri, Jul 16, 2021 at 12:07 PM William Denton <wtd@pobox.com> wrote:
>
> > However, I was a bit surprised when I found that a commented line starts
> a new
> > paragraph.
>
> I hadn't yet discovered that, but I think it should be considered a
> bug.


Comments causing paragraph breaks has been a long known behavior. I learned
about it few years back, probably from one of the threads here or by
reading the code.


> The output of your example should remove the commented line
> entirely, and so be:
>
> In this paragraph I introduce an idea.
> But I am sure about this. And here is my conclusion.
>
> Perhaps it can be easily fixed?
>

I don't think it would be a very easy fix as the behavior stems from an
intentional low level implementation in org-element.el. Changing this
behavior will cause a regression in all Org exporters out there.

[-- Attachment #2: Type: text/html, Size: 1683 bytes --]

Re: Comments break up a paragraph when writing one-setence-per-line

[Samuel Wales]

on the other hand, if it were fixed, it would possibly make par sep
blank lines be more controllable in such exporters as ascii.


On 7/16/21, Kaushal Modi <kaushal.modi@gmail.com> wrote:
> Hello,
>
>
> On Fri, Jul 16, 2021 at 12:35 PM Bruce D'Arcus <bdarcus@gmail.com> wrote:
>
>> On Fri, Jul 16, 2021 at 12:07 PM William Denton <wtd@pobox.com> wrote:
>>
>> > However, I was a bit surprised when I found that a commented line
>> > starts
>> a new
>> > paragraph.
>>
>> I hadn't yet discovered that, but I think it should be considered a
>> bug.
>
>
> Comments causing paragraph breaks has been a long known behavior. I learned
> about it few years back, probably from one of the threads here or by
> reading the code.
>
>
>> The output of your example should remove the commented line
>> entirely, and so be:
>>
>> In this paragraph I introduce an idea.
>> But I am sure about this. And here is my conclusion.
>>
>> Perhaps it can be easily fixed?
>>
>
> I don't think it would be a very easy fix as the behavior stems from an
> intentional low level implementation in org-element.el. Changing this
> behavior will cause a regression in all Org exporters out there.
>


-- 
The Kafka Pandemic

Please learn what misopathy is.
https://thekafkapandemic.blogspot.com/2013/10/why-some-diseases-are-wronged.html

Re: Comments break up a paragraph when writing one-setence-per-line

[Maxim Nikulin]

On 16/07/2021 23:06, William Denton wrote:
> #+begin_src org
> 
> In this paragraph I introduce an idea.
> # Here is something I'm not sure about yet.
> But I am sure about this.
> And here is my conclusion.
> 
> #+end_src org
> 
> When this is exported, it becomes two paragraphs, as though the 
> commented line was a blank line.  This was unexpected, because to me 
> this is one paragraph with one sentence hidden.
> 
> People who write one-sentence-per-line, have you had this problem, and 
> if so how did you handle it?

This is unexpected and inconvenient for me as well. However it may be 
considered consistent with

https://orgmode.org/worg/dev/org-syntax.html#Paragraphs
> Empty lines and other elements end paragraphs.

I do not write one-sentence-per-line, but I do not think it matters at 
all. As a workaround I can suggest the following hack

#+macro: comment

Another test
{{{comment(some text
)}}} with macro comment.

Re: Comments break up a paragraph when writing one-setence-per-line

[Eric S Fraga]

On Friday, 16 Jul 2021 at 12:06, William Denton wrote:
> People who write one-sentence-per-line, have you had this problem, and if so how 
> did you handle it?

If I will be exporting to LaTeX, I do the following:

--8<---------------cut here---------------start------------->8---
One sentence is here.
#+latex: % a sentence that has been commented out.
The third sentence is here and should be in the same paragraph as the first.
--8<---------------cut here---------------end--------------->8---

The LaTeX directive is a LaTeX comment (% at the start) and so replaces
what would otherwise be a blank line causing a new paragraph to start.

It may not be pretty but it works just fine.

HTH,
eric

-- 
: Eric S Fraga via Emacs 28.0.50, Org release_9.4.6-598-g604bfd
: Latest paper written in org: https://arxiv.org/abs/2106.05096

Re: Comments break up a paragraph when writing one-setence-per-line

[Maxim Nikulin]

On 19/07/2021 21:03, Eric S Fraga wrote:
> On Friday, 16 Jul 2021 at 12:06, William Denton wrote:
>> People who write one-sentence-per-line, have you had this problem, and if so how
>> did you handle it?
> 
> If I will be exporting to LaTeX, I do the following:
> 
> --8<---------------cut here---------------start------------->8---
> One sentence is here.
> #+latex: % a sentence that has been commented out.
> The third sentence is here and should be in the same paragraph as the first.
> --8<---------------cut here---------------end--------------->8---
> 
> The LaTeX directive is a LaTeX comment (% at the start) and so replaces
> what would otherwise be a blank line causing a new paragraph to start.
> 
> It may not be pretty but it works just fine.

It is at least fragile. HTML export results in separate paragraphs:

<p>
One sentence is here.
</p>
<p>
The third sentence is here and should be in the same paragraph as the 
first.</p>

https://orgmode.org/worg/dev/org-syntax.html#Paragraphs
 > Empty lines and other elements end paragraphs.

I am unsure, but "#+latex:" probably belongs to "Keywords" that are 
elements, so it should end a paragraph. If such interpretation is 
correct than either LaTeX exporter has a bug or syntax description 
should be justified.

Re: Comments break up a paragraph when writing one-setence-per-line

[Eric S Fraga]

On Wednesday, 21 Jul 2021 at 21:48, Maxim Nikulin wrote:
> It is at least fragile. HTML export results in separate paragraphs:

Yes, I said "if exporting to LaTeX"... ;-)

> I am unsure, but "#+latex:" probably belongs to "Keywords" that are
> elements, so it should end a paragraph. If such interpretation is
> correct than either LaTeX exporter has a bug or syntax description
> should be justified.

No, I don't think of it as a keyword and it cannot end a paragraph as it
would then break any document that uses such constructs.  Not sure what
to call it but it falls into the same category as inline directives like
@@latex:...@@.  And, in fact, this would work as well as the first
example, again failing for HTML export:

--8<---------------cut here---------------start------------->8---
This is the first sentence.
@@latex:%@@ this is the second which is commented out.
And this is the third.
--8<---------------cut here---------------end--------------->8---

Both of these rely on the fact that % is a comment character for
LaTeX.  For HTML, you would have to something even more ugly, as in:

--8<---------------cut here---------------start------------->8---
This is the first sentence.
@@html:<!-- @@ this is the second which is commented out. @@html:-->@@
And this is the third.
--8<---------------cut here---------------end--------------->8---

and if you are really masochistic, you could combine the two:

--8<---------------cut here---------------start------------->8---
This is the first sentence.
@@latex:%@@@@html:<!-- @@ this is the second which is commented out. @@html:-->@@
And this is the third.
--8<---------------cut here---------------end--------------->8---

(untested) :-)

-- 
: Eric S Fraga via Emacs 28.0.50, Org release_9.4.6-598-g604bfd
: Latest paper written in org: https://arxiv.org/abs/2106.05096

Re: Comments break up a paragraph when writing one-setence-per-line

[Maxim Nikulin]

On 21/07/2021 22:22, Eric S Fraga wrote:
> On Wednesday, 21 Jul 2021 at 21:48, Maxim Nikulin wrote:
>> It is at least fragile. HTML export results in separate paragraphs:
> 
> Yes, I said "if exporting to LaTeX"... ;-)
> 
>> I am unsure, but "#+latex:" probably belongs to "Keywords" that are
>> elements, so it should end a paragraph. If such interpretation is
>> correct than either LaTeX exporter has a bug or syntax description
>> should be justified.
> 
> No, I don't think of it as a keyword and it cannot end a paragraph as it
> would then break any document that uses such constructs.  Not sure what
> to call it but it falls into the same category as inline directives like
> @@latex:...@@.  And, in fact, this would work as well as the first
> example, again failing for HTML export:
...
> (untested) :-)

"@@backend:@@" aka Export Snippet is an "object", not "element"
thus is should not start paragraph
https://orgmode.org/worg/dev/org-syntax.html#Export_Snippets

Though... With LaTeX you should be careful

---- >8 ----
One sentence is here.
@@html:inline HTML@@
Second sentence.
---- 8< ----

Export to LaTeX:
---- >8 ----
One sentence is here.

Second sentence.
---- 8< ----

"@@latex:@@" line in HTML export generates empty line but does not break 
the paragraph. "#+html:" construct splits paragraphs:

One sentence is here.
#+html: <!-- HTML -->
Second sentence.

<p>
One sentence is here.
</p>
<!-- HTML -->
<p>
Second sentence.
</p>

I find behavior of HTML exporter more consistent but partially the 
difference originates in distinct interpretation of empty lines.

P.S. There are two types of comments: ones that should be exported as 
comments and that should be completely removed. "#+latex: %" comments 
leak to LaTeX, though they will be stripped during generation of PDF. So 
depending of what format you should provide, such behavior may be 
acceptable or not.

Re: Comments break up a paragraph when writing one-setence-per-line

[Tom Gillespie]

A general comment (heh) here. This is not a bug and not easily fixed.
Line comments are their own top level element distinct from
paragraphs. If you need something that fits in a paragraph you can use
@@comment:@@ at the start of a line.

I agree that it is annoying, but Org line comment syntax also only
works if it starts the line, so the behavior diverges from traditional
code comments. It may make sense to update the docs to call them "line
comments" instead of just comments.

One area where we could almost certainly do better is in how line
comments break up the flow of text. I'm not sure there will ultimately
be much we can do about it, but it is worth investigating.

Best,
Tom

Re: Comments break up a paragraph when writing one-setence-per-line

[Max Nikulin]

On 03/10/2021 00:57, Tom Gillespie wrote:
> A general comment (heh) here. This is not a bug and not easily fixed.
> Line comments are their own top level element distinct from
> paragraphs. If you need something that fits in a paragraph you can use
> @@comment:@@ at the start of a line.
> 
> I agree that it is annoying, but Org line comment syntax also only
> works if it starts the line, so the behavior diverges from traditional
> code comments. It may make sense to update the docs to call them "line
> comments" instead of just comments.

Agree, if parser is not changed, I suppose, the manual and the guide 
should state very prominent that comment line disrupts current paragraph 
unlike "%" in TeX.

However there 5 users in this thread who expect that "# " or "#+latex:" 
should not be "element" and should be a part of surrounding paragraph.

Thank you for the idea with @@comment:@@, let me stress that final @@ 
should be on the next line. It is similar to my idea with a macro 
expanding to nothing. It may be documented in the manual. However I 
would expect that `org-lint' issues a warning concerning unknown 
backends to catch typos in names. By the way, `org-lint' does not like 
the variant with comment as macro.

I think, it is a bug in LaTeX backend that the following becomes 3 
separate paragraphs:

    #+macro: comment
    Beginning of a paragraph A.
    @@comment: FIXME@@
    Paragraph A continues.
    {{{comment(TODO)}}}
    End of paragraph A.

And the following is really confusing:

    How many paragraphs
    #+html: <!-- comment -->
    is here
    #+latex: %
    in LaTeX and HTML output?

LaTeX backend exports it as a continuous paragraph (an idea of a weird 
hack how to comment a line if only LaTeX export is needed). HTML backend 
believes that it is 3 paragraphs.