Please read: Announcing #2309: Limit where section references may appear

[Edward K. Ream]

Issue #2309 suggests that Leo should recognize section references only:

1. When nothing except whitespace appears before or after the section reference.
2. Only when the apparent section reference is not part of an `@doc` section.

Imo, this proposal is much less risky than it might appear!

I won't go more into detail here. See #2309 for the advantages, prospects for success, impact on code, migration strategy, and motivating examples.

I am actively asking for comments. Please make your comments here, not in the issue itself. Thanks for your attention to this matter.

Edward

P. S. I shall soon begin work on the project in the ekr-section-refs branch. I expect to complete work in just a few days. Speed matters because Félix may want to start transliterating leoAtFile.py into typescript!

EKR

[tbp1...@gmail.com]

I do like to write """<< quotation-section >>""" or even single quoted "<< quotation-section >>".  Not crucial, but perhaps the test could be for whitespace + quotes?

I didn't even know you could have more than one section reference on a line, and I wouldn't know what indentation would be used for a second one if it existed.  That makes me think that it would be good to enforce the proposed rule (modulo the quotes).

[Edward K. Ream]

On Fri, Nov 5, 2021 at 8:42 AM tbp1...@gmail.com <tbp1...@gmail.com> wrote:

I do like to write """<< quotation-section >>""" or even single quoted "<< quotation-section >>".  Not crucial, but perhaps the test could be for whitespace + quotes?

I really do not want to do this.  It would complicate the code (even one 'if' is too many), and imo it is mostly useless.  Indeed, given the reference:

"""<< quotation-section >>"""

And the corresponding definition node containing:

line 1
line 2
line 3

the output is:

"""
#@+<< quotation-section >>
#@+node:ekr.20211105101807.1: ** << quotation-section >>
line 1
line 2
line 3
#@-<< quotation-section >>
#@afterref
"""

How can this possibly be what you want? There are Leo sentinel comments inside the triple-quoted string!

There is an straightforward alternative, which Leo's unit tests use frequently.  Define the contents of << quotation-section 2 >> this way:

a_var = textwrap.dedent('''\

    line 1

    line 2

    line 3

''')

This is straightforward, and the generated code is:

#@+<< quotation-section 2 >>
#@+node:ekr.20211105102445.1: ** << quotation-section 2 >>
a_var = textwrap.dedent('''\
line 1
line 2
line 3
''')
#@-<< quotation-section 2 >>

Now the triple-quoted string contains only the expected lines!

Edward

[tbp1...@gmail.com]

Here is an @file that I just made.  Yes, the << ... >>  sentinal is inside the quoted string.  But I don't mind that as long as 1) Python sees the correct code, and 2) Leo can read the file and reproduce it. And that is currently the case, except that Leo may move one or the other of the triple quotes to its own line during a round trip, and that would be fine too.

Why am I interested in this?  Mostly because PEP 8, the Python style guide, wants docstrings to start right after the triple quotes on the same line.  I agree with this so I'd like to be possible.  PEP8 also wants the ending triple quotes to be on the same line if the docstring is a single line, but you wouldn't be using a section reference for a short docstring anyway.

Of course, one could also put the triple quotes inside the section itself.  I'm not sure how that works if the docstring section itself is a tree of nodes, but it probably does.  You tend to get that kind of long, segmented docstring when the docstring is used directly for an About or Help display, as they are for Leo plugins.

#@+leo-ver=5-thin

#@+node:tom.20211105130433.1: * @file c:\temp\section_quotes.py

#@@language python

"""

#@+<< docstring >>

#@+node:tom.20211105130454.1: ** << docstring >>

This represents a long 

doctring section.

#@-<< docstring >>

#@afterref

"""

# Code here

def f(x):

    return x**2

#@-leo

[Edward K. Ream]

On Fri, Nov 5, 2021 at 12:26 PM tbp1...@gmail.com <tbp1...@gmail.com> wrote:

Why am I interested in this?  Mostly because PEP 8, the Python style guide, wants docstrings to start right after the triple quotes on the same line. 

#2309 has nothing to do with pep 8, no matter how large your docstrings are.

Imo, the questions to ask are:

1. Can you do what you want to do with Leo?

2. Will the proposal strengthen Leo?

Edward

[tbp1...@gmail.com]

Actually, it was PEP 257 : )  I misremembered.  Anyway, with regards to the way sections work currently, I can do what I want with Leo. As long as I can use docstring sections for long docstrings, even if the details are slightly changed, I'll be happy.

[Edward K. Ream]

On Fri, Nov 5, 2021 at 3:30 PM tbp1...@gmail.com <tbp1...@gmail.com> wrote:

Actually, it was PEP 257 : )  I misremembered.  Anyway, with regards to the way sections work currently, I can do what I want with Leo. As long as I can use docstring sections for long docstrings, even if the details are slightly changed, I'll be happy.

Glad to hear it :-)

Edward