py-goto-initial-line doku

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

py-goto-initial-line doku

Andreas Röhler-2

Hi Barry, hi all,

suggest to drop the second sentence in doku of
`py-goto-initial-line'  --see below-- as it's confusing.

"Usually this is the line we're on" might be true, but
has no syntactic relevance.

It's not obvious, what "a continuation block" should mean.

For me a block is the body of a conditional.

Agreed? Any other opinions?

Cheers

Andreas

--
https://code.launchpad.net/~a-roehler/python-mode
https://code.launchpad.net/s-x-emacs-werkstatt/

;;;;;;;;;;;;

(defun py-goto-initial-line ()
   "Go to the initial line of the current statement.
Usually this is the line we're on, but if we're on the 2nd or
following lines of a continuation block, we need to go up to the first
line of the block."
...

_______________________________________________
Python-mode mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-mode
Reply | Threaded
Open this post in threaded view
|

Re: py-goto-initial-line doku

Barry Warsaw
On Sep 21, 2010, at 10:33 AM, Andreas Röhler wrote:

>suggest to drop the second sentence in doku of
>`py-goto-initial-line'  --see below-- as it's confusing.
>
>"Usually this is the line we're on" might be true, but
>has no syntactic relevance.
>
>It's not obvious, what "a continuation block" should mean.
>
>For me a block is the body of a conditional.

Well, almost the entire docstring makes no sense <wink>.

The Python language reference describes these things as "compound statements":

    http://docs.python.org/reference/compound_stmts.html

It goes on to describe the layout of compound statements:

    "Compound statements consist of one or more ‘clauses.’ A clause consists
    of a header and a ‘suite.’ The clause headers of a particular compound
    statement are all at the same indentation level. Each clause header begins
    with a uniquely identifying keyword and ends with a colon. A suite is a
    group of statements controlled by a clause. A suite can be one or more
    semicolon-separated simple statements on the same line as the header,
    following the header’s colon, or it can be one or more indented statements
    on subsequent lines. [...]"

So, how's this for a suggested new docstring:

  "Go to the initial line of the current statement.
When point is on a simple statement, this will go to the start of that line.
When point is on a line inside a compound statement, this will go to the line
that introduces the suite, i.e. the clause header."

If you wanted, you could also add a reference to the online docs for compound
statements given above.

-Barry


_______________________________________________
Python-mode mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-mode

signature.asc (853 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: py-goto-initial-line doku

Andreas Röhler-2
Am 21.09.2010 20:27, schrieb Barry Warsaw:
On Sep 21, 2010, at 10:33 AM, Andreas Röhler wrote:

  
suggest to drop the second sentence in doku of
`py-goto-initial-line'  --see below-- as it's confusing.

"Usually this is the line we're on" might be true, but
has no syntactic relevance.

It's not obvious, what "a continuation block" should mean.

For me a block is the body of a conditional.
    
Well, almost the entire docstring makes no sense <wink>.

The Python language reference describes these things as "compound statements":

    http://docs.python.org/reference/compound_stmts.html

It goes on to describe the layout of compound statements:

    "Compound statements consist of one or more ‘clauses.’ A clause consists
    of a header and a ‘suite.’ The clause headers of a particular compound
    statement are all at the same indentation level. Each clause header begins
    with a uniquely identifying keyword and ends with a colon. A suite is a
    group of statements controlled by a clause. A suite can be one or more
    semicolon-separated simple statements on the same line as the header,
    following the header’s colon, or it can be one or more indented statements
    on subsequent lines. [...]"

So, how's this for a suggested new docstring:

  "Go to the initial line of the current statement.
When point is on a simple statement, this will go to the start of that line.
When point is on a line inside a compound statement, this will go to the line
that introduces the suite, i.e. the clause header."

If you wanted, you could also add a reference to the online docs for compound
statements given above.

-Barry

  


Thanks,

if the lp:~a-roehler/python-mode/tqs-302834-amend branch is merged (?)

the patch from
lp:~a-roehler/python-mode/py-goto-initial-line
should work for you.

So I'll take care of the doku with this new head, send another patch then.

Andreas




_______________________________________________
Python-mode mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-mode
Reply | Threaded
Open this post in threaded view
|

Re: py-goto-initial-line doku

Andreas Röhler-2
In reply to this post by Barry Warsaw
Am 21.09.2010 20:27, schrieb Barry Warsaw:
On Sep 21, 2010, at 10:33 AM, Andreas Röhler wrote:

  
suggest to drop the second sentence in doku of
`py-goto-initial-line'  --see below-- as it's confusing.

"Usually this is the line we're on" might be true, but
has no syntactic relevance.

It's not obvious, what "a continuation block" should mean.

For me a block is the body of a conditional.
    
Well, almost the entire docstring makes no sense <wink>.

The Python language reference describes these things as "compound statements":

    http://docs.python.org/reference/compound_stmts.html

It goes on to describe the layout of compound statements:

    "Compound statements consist of one or more ‘clauses.’ A clause consists
    of a header and a ‘suite.’ The clause headers of a particular compound
    statement are all at the same indentation level. Each clause header begins
    with a uniquely identifying keyword and ends with a colon. A suite is a
    group of statements controlled by a clause. A suite can be one or more
    semicolon-separated simple statements on the same line as the header,
    following the header’s colon, or it can be one or more indented statements
    on subsequent lines. [...]"

  

Proceeding...
Will put it into the tqs-amend patch, as you are playing with it.

So, how's this for a suggested new docstring:

  "Go to the initial line of the current statement.
When point is on a simple statement, this will go to the start of that line.
  

Think we can't say that.

for example consider the following, which is a simple statement too (?)

print """Usage: %s
    ....""" % (
        os.path.basename(sys.argv[0]))


So maybe `print' is considered such a uniquely identifying keyword,
--assuming not--

what about this:

    ar_atpt_delimited_list_roh = ([
            'braced ?\{ ?\}',
            'bracketed ?\[ ?\]',
            'angled-lesser ?\< ?\>',
            'angled-greater ?\> ?\<',
            'left-right-singlequoted ?\‘ ?\’',
            'parentized ?\( ?\)',
            ])

Cheers

Andreas



When point is on a line inside a compound statement, this will go to the line
that introduces the suite, i.e. the clause header."

If you wanted, you could also add a reference to the online docs for compound
statements given above.

-Barry

  
_______________________________________________ Python-mode mailing list [hidden email] http://mail.python.org/mailman/listinfo/python-mode


_______________________________________________
Python-mode mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-mode