oeg-add-note and double backslash ?

oeg-add-note and double backslash ?

[David Masterson]

org-add-note puts a '\\' at the end of the first line.  Is it expected
the user will put '\\' at the end of each line of a multiline note
(except the last line)?  Why is this done?

-- 
David Masterson

Re: oeg-add-note and double backslash ?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

> org-add-note puts a '\\' at the end of the first line.  Is it expected
> the user will put '\\' at the end of each line of a multiline note
> (except the last line)?

No.

> .. Why is this done?

To prevent fill-region from concatenating the auto-generated text in the
first line and the user input in the following lines.

-- 
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>

Re: oeg-add-note and double backslash ?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>> org-add-note puts a '\\' at the end of the first line.  Is it expected
>> the user will put '\\' at the end of each line of a multiline note
>> (except the last line)?
>
> No.
>
>> .. Why is this done?
>
> To prevent fill-region from concatenating the auto-generated text in the
> first line and the user input in the following lines.

Ah.  Is that mentioned somewhere in the Org manual?  I don't mean the
details of filll-region, but a little something to answer "why is that
there?" by new users.

-- 
David Masterson

Re: oeg-add-note and double backslash ?

[Samuel Wales]

(info "(org) Paragraphs")

On 12/4/23, David Masterson <dsmasterson@gmail.com> wrote:
> Ihor Radchenko <yantar92@posteo.net> writes:
>
>> David Masterson <dsmasterson@gmail.com> writes:
>>
>>> org-add-note puts a '\\' at the end of the first line.  Is it expected
>>> the user will put '\\' at the end of each line of a multiline note
>>> (except the last line)?
>>
>> No.
>>
>>> .. Why is this done?
>>
>> To prevent fill-region from concatenating the auto-generated text in the
>> first line and the user input in the following lines.
>
> Ah.  Is that mentioned somewhere in the Org manual?  I don't mean the
> details of filll-region, but a little something to answer "why is that
> there?" by new users.
>
> --
> David Masterson
>
>


-- 
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

Re: oeg-add-note and double backslash ?

[David Masterson]

Samuel Wales <samologist@gmail.com> writes:

> On 12/4/23, David Masterson <dsmasterson@gmail.com> wrote:
>> Ihor Radchenko <yantar92@posteo.net> writes:
>>
>>> David Masterson <dsmasterson@gmail.com> writes:
>>>
>>>> org-add-note puts a '\\' at the end of the first line.  Is it expected
>>>> the user will put '\\' at the end of each line of a multiline note
>>>> (except the last line)?
>>>
>>> No.
>>>
>>>> .. Why is this done?
>>>
>>> To prevent fill-region from concatenating the auto-generated text in the
>>> first line and the user input in the following lines.
>>
>> Ah.  Is that mentioned somewhere in the Org manual?  I don't mean the
>> details of filll-region, but a little something to answer "why is that
>> there?" by new users.
>
> (info "(org) Paragraphs")

Hmm. Not quite as it doesn't say anything about Org notes.
-- 
David Masterson

Re: oeg-add-note and double backslash ?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>> To prevent fill-region from concatenating the auto-generated text in the
>> first line and the user input in the following lines.
>
> Ah.  Is that mentioned somewhere in the Org manual?  I don't mean the
> details of filll-region, but a little something to answer "why is that
> there?" by new users.

No, AFAIK, the exact format of notes is not described in the manual.
We do not describe every single detail in the manual.
I believe that the exact wording of the notes is not something we have
to describe.

-- 
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>

Re: oeg-add-note and double backslash ?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>>> To prevent fill-region from concatenating the auto-generated text in the
>>> first line and the user input in the following lines.
>>
>> Ah.  Is that mentioned somewhere in the Org manual?  I don't mean the
>> details of fill-region, but a little something to answer "why is that
>> there?" by new users.
>
> No, AFAIK, the exact format of notes is not described in the manual.
> We do not describe every single detail in the manual.
> I believe that the exact wording of the notes is not something we have
> to describe.

Hmm. glancing through the manual, there is a bit of assumption implicit
about the use of '\\'.  We had the problem with Unix Shell scripts that
we would need a backslash at the end of a line to prevent the EOL as
being interpreted as end-of-input. Depending on the layers of scripting
we were using, we added backslashes after the backslash because each
layer would peel off a backslash.  This is what I first thought of in
reading the manual.

Seeing '\\' at the end of the note line, I thought something would get
messed up if the EOLs (except last) in the Note were treated as
end-of-input, so I added them to all but the last line. This is what I
think needs clarification.

-- 
David Masterson

Re: oeg-add-note and double backslash ?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

> Hmm. glancing through the manual, there is a bit of assumption implicit
> about the use of '\\'.  We had the problem with Unix Shell scripts that
> we would need a backslash at the end of a line to prevent the EOL as
> being interpreted as end-of-input. Depending on the layers of scripting
> we were using, we added backslashes after the backslash because each
> layer would peel off a backslash.  This is what I first thought of in
> reading the manual.

We do document the line breaks in
https://orgmode.org/manual/Paragraphs.html

-- 
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>

Re: oeg-add-note and double backslash ?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>> Hmm. glancing through the manual, there is a bit of assumption implicit
>> about the use of '\\'.  We had the problem with Unix Shell scripts that
>> we would need a backslash at the end of a line to prevent the EOL as
>> being interpreted as end-of-input. Depending on the layers of scripting
>> we were using, we added backslashes after the backslash because each
>> layer would peel off a backslash.  This is what I first thought of in
>> reading the manual.
>
> We do document the line breaks in
> https://orgmode.org/manual/Paragraphs.html

The only thing I see with respect to '\\' is:

  Paragraphs are separated by at least one empty line.  If you need to
  enforce a line break within a paragraph, use ‘\\’ at the end of a line.

Which doesn't answer the question of why org-add-note (etc) added it the
end of the first line of a Note which lead to my confusion. It's easy to
assume, if Org is adding '\\' to the first line of the Note and the Note
is a unit, then this is there to prevent folding/wrapping in the Note
when Org does "something" (but what?).

-- 
David Masterson

Re: oeg-add-note and double backslash ?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>> We do document the line breaks in
>> https://orgmode.org/manual/Paragraphs.html
>
> The only thing I see with respect to '\\' is:
>
>   Paragraphs are separated by at least one empty line.  If you need to
>   enforce a line break within a paragraph, use ‘\\’ at the end of a line.
>
> Which doesn't answer the question of why org-add-note (etc) added it the
> end of the first line of a Note which lead to my confusion. It's easy to
> assume, if Org is adding '\\' to the first line of the Note and the Note
> is a unit, then this is there to prevent folding/wrapping in the Note
> when Org does "something" (but what?).

Line break is a "forced" break of a line in paragraph. When there is a
line break, paragraph does not re-flow to the page width.

Re-flow may imply different things, including `fill-region' command in
Emacs or paragraph layout during export.

The detailed reason why we use this particular markup is that
otherwise some internal code assumptions inside Org mode may break when
users run `fill-region' on the notes. This is an internal implementation
detail which should not be explained in the manual.

What we might explain better is what is a line break, although I am not
very sure what to explain here - I may be too familiar with the concept
from my LaTeX-foo.

-- 
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>

Re: oeg-add-note and double backslash ?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>>> We do document the line breaks in
>>> https://orgmode.org/manual/Paragraphs.html
>>
>> The only thing I see with respect to '\\' is:
>>
>>   Paragraphs are separated by at least one empty line.  If you need to
>>   enforce a line break within a paragraph, use ‘\\’ at the end of a line.
>>
>> Which doesn't answer the question of why org-add-note (etc) added it the
>> end of the first line of a Note which lead to my confusion. It's easy to
>> assume, if Org is adding '\\' to the first line of the Note and the Note
>> is a unit, then this is there to prevent folding/wrapping in the Note
>> when Org does "something" (but what?).
>
> Line break is a "forced" break of a line in paragraph. When there is a
> line break, paragraph does not re-flow to the page width.
>
> Re-flow may imply different things, including `fill-region' command in
> Emacs or paragraph layout during export.
>
> The detailed reason why we use this particular markup is that
> otherwise some internal code assumptions inside Org mode may break when
> users run `fill-region' on the notes. This is an internal implementation
> detail which should not be explained in the manual.

Hmm.  Fill-region will also compress the blanks in the generate note
header -- does that run up against the code assumptions?

I'm all for keeping internal implementation details out of the user's
manual, unless...

> What we might explain better is what is a line break, although I am not
> very sure what to explain here - I may be too familiar with the concept
> from my LaTeX-foo.

The manual should set expectations on what an Org file should look like
-- at least the key components.  It already defines Header, Paragraph
and Timestamp. What I think is missing here is the definition of a Note
along with some structure info about it (header line + 2 space indented
paragraphs[s]) to prepare the user.  In this, I probably come from a
more Reference Manual viewpoint (ie. "this is what all the pieces could
look like -- now lets discuss why you want each piece"). You could say
that the '\\' is needed to keep "other things" from combining the header
and paragraph of the note.  You could leave the details of "other
things" to variable or function docstrings as well as internal code.

p.s. would requiring a blank line after the Note header eliminate the
need for '\\' ?

-- 
David Masterson

Re: oeg-add-note and double backslash ?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>> The detailed reason why we use this particular markup is that
>> otherwise some internal code assumptions inside Org mode may break when
>> users run `fill-region' on the notes. This is an internal implementation
>> detail which should not be explained in the manual.
>
> Hmm.  Fill-region will also compress the blanks in the generate note
> header -- does that run up against the code assumptions?

No. See `org-skip-over-state-notes'.

> I'm all for keeping internal implementation details out of the user's
> manual, unless...
>
>> What we might explain better is what is a line break, although I am not
>> very sure what to explain here - I may be too familiar with the concept
>> from my LaTeX-foo.
>
> The manual should set expectations on what an Org file should look like
> -- at least the key components.  It already defines Header, Paragraph
> and Timestamp. What I think is missing here is the definition of a Note
> along with some structure info about it (header line + 2 space indented
> paragraphs[s]) to prepare the user.

Unlike headings, paragraphs, and timestamps, notes are not a part of Org
syntax. Their format is customizeable via `org-log-note-headings'.

However, it is probably worth describing the notes in 5.3 Progress
Logging section of the manual.

> ... In this, I probably come from a
> more Reference Manual viewpoint (ie. "this is what all the pieces could
> look like -- now lets discuss why you want each piece"). You could say
> that the '\\' is needed to keep "other things" from combining the header
> and paragraph of the note.  You could leave the details of "other
> things" to variable or function docstrings as well as internal code.

I am not sure if I understand what you mean here.

> p.s. would requiring a blank line after the Note header eliminate the
> need for '\\' ?

Yes.

-- 
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>

Re: oeg-add-note and double backslash ?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>>> The detailed reason why we use this particular markup is that
>>> otherwise some internal code assumptions inside Org mode may break when
>>> users run `fill-region' on the notes. This is an internal implementation
>>> detail which should not be explained in the manual.
>>
>> Hmm.  Fill-region will also compress the blanks in the generate note
>> header -- does that run up against the code assumptions?
>
> No. See `org-skip-over-state-notes'.

Hmm. The docstring on that should discuss what it's looking for to say
"this is the end of the state notes".  Does a plain note (org-add-note)
count as a state note?

>> I'm all for keeping internal implementation details out of the user's
>> manual, unless...
>>
>>> What we might explain better is what is a line break, although I am not
>>> very sure what to explain here - I may be too familiar with the concept
>>> from my LaTeX-foo.
>>
>> The manual should set expectations on what an Org file should look like
>> -- at least the key components.  It already defines Header, Paragraph
>> and Timestamp. What I think is missing here is the definition of a Note
>> along with some structure info about it (header line + 2 space indented
>> paragraphs[s]) to prepare the user.
>
> Unlike headings, paragraphs, and timestamps, notes are not a part of Org
> syntax. Their format is customizeable via `org-log-note-headings'.

Oh! That's an interesting point.  That variable is not mentioned in the
Manual (AFAICS), but perhaps it should be -- particularly around the
talk of "rescheduling" (and "delschedule" which I don't see in the
manual). Mentioned only in the sense of, if you want to change the note
header, look here.

> However, it is probably worth describing the notes in 5.3 Progress
> Logging section of the manual.

I'd agree.  In particular, what depends on the format of the note
(header) -- like Agenda.  To warn people what they can or cannot touch.

-- 
David Masterson

Re: oeg-add-note and double backslash ?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>> No. See `org-skip-over-state-notes'.
>
> Hmm. The docstring on that should discuss what it's looking for to say
> "this is the end of the state notes".  Does a plain note (org-add-note)
> count as a state note?

Yes, it does.
I tried to improve a docstring a little on main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=420ed4e03

>> Unlike headings, paragraphs, and timestamps, notes are not a part of Org
>> syntax. Their format is customizeable via `org-log-note-headings'.
>
> Oh! That's an interesting point.  That variable is not mentioned in the
> Manual (AFAICS), but perhaps it should be -- particularly around the
> talk of "rescheduling" (and "delschedule" which I don't see in the
> manual). Mentioned only in the sense of, if you want to change the note
> header, look here.
>
>> However, it is probably worth describing the notes in 5.3 Progress
>> Logging section of the manual.
>
> I'd agree.  In particular, what depends on the format of the note
> (header) -- like Agenda.  To warn people what they can or cannot touch.

Patches welcome.

-- 
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>

Re: oeg-add-note and double backslash ?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> Patches welcome.

* What is my status as far as submitting patches to documentation
  (including docstrings)?
* Is there a write-up on the process of "patching" I can follow?

-- 
David Masterson

Re: oeg-add-note and double backslash ?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

> Ihor Radchenko <yantar92@posteo.net> writes:
>
>> Patches welcome.
>
> * What is my status as far as submitting patches to documentation
>   (including docstrings)?

I can see two commits of yours in Org repo. Beyond the 15LOC limit.
So, we cannot accept more TINYCHANGE patches and need FSF copyright
assignment - https://orgmode.org/worg/org-contribute.html#copyright

> * Is there a write-up on the process of "patching" I can follow?

Yes, of course. See https://orgmode.org/worg/org-contribute.html#first-patch

-- 
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>

Re: oeg-add-note and double backslash ?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>> Ihor Radchenko <yantar92@posteo.net> writes:
>>
>>> Patches welcome.
>>
>> * What is my status as far as submitting patches to documentation
>>   (including docstrings)?
>
> I can see two commits of yours in Org repo. Beyond the 15LOC limit.
> So, we cannot accept more TINYCHANGE patches and need FSF copyright
> assignment - https://orgmode.org/worg/org-contribute.html#copyright

The form for copyright assignment asks what files have you changed so
far. I assumed the form would be universal for any past and future
changes you make to the program (Emacs).  Do people really need to fill
that part out? Do I need the info from the 2 commits?

>> * Is there a write-up on the process of "patching" I can follow?
>
> Yes, of course. See https://orgmode.org/worg/org-contribute.html#first-patch

Thanks
-- 
David Masterson

Re: oeg-add-note and double backslash ?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

> The form for copyright assignment asks what files have you changed so
> far. I assumed the form would be universal for any past and future
> changes you make to the program (Emacs).  Do people really need to fill
> that part out? Do I need the info from the 2 commits?

I think it would not hurt.
This form is just a plain text - you will receive a proper pdf form with
all the legal details later for actual signing.

-- 
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>