Documentation for sum() function should indicate Python syntax *first*

[rlmill]

When did we hijack the sum function? Based on the documentation there, I have (today alone) had four different people come up to me and ask why something like the following doesn't work:

sage: sum(Integer(x), x, 0, 9)

I know the reasons this shouldn't work, but newbies definitely don't. It should say something about how to do

sage: sum( Integer(x) for x in range(10) )

before "getting all symbolic."

CC: @kcrisman

Component: documentation

Author: Ralf Stephan

Branch/Commit: 5f47daf

Reviewer: Karl-Dieter Crisman, Travis Scrimshaw

Issue created by migration from https://trac.sagemath.org/ticket/9321

[rwst]

comment:2

The sagenb bug spreadsheet has several examples, too.

[rwst]

Branch: u/rws/ticket/9321

[rwst]

New commits:

228fd67

Trac #9321: add warnings to sum() and symbolic_sum() documentation

[rwst]

Commit: 228fd67

[rwst]

Author: Ralf Stephan

[kcrisman]

comment:6

Nice first step. I would also add some actual examples as the original reporter suggests - maybe with an explicit example showing what does and doesn't work along these lines.

[sagetrac-git]

Changed commit from 228fd67 to 09ba9b9

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

09ba9b9

examples when/not to use Sage sum(); same also in calculus.py

[rwst]

comment:8

How about this? Cannot make it any shorter than that.

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

45fbd50

fix doctests

[sagetrac-git]

Changed commit from 09ba9b9 to 45fbd50

[tscrim]

comment:10

Your warning messages are indented one too many times.

[sagetrac-git]

Changed commit from 45fbd50 to eb0ddc0

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

eb0ddc0

too much indentation

[kcrisman]

Reviewer: Karl-Dieter Crisman, Travis Scrimshaw

[rwst]

comment:13

Thanks for the review.

[kcrisman]

comment:14

Okay, I'm going to ask for one final thing. Probably it isn't appropriate to have this warning be before one even sees the INPUT block! Can you put this after the first few examples, and then have some wording indicating "now back to the examples" in a not-informal way? Otherwise we'll have the opposite problem of everyone avoiding this function :)

Also, another nit-pick - try to put the sum() in double back ticks so that it typesets properly as code. And... is there any general reference for the Python sum, or are all of them version-dependent? (I think the latter, just checking in case you know).

Thanks! Sorry this is an incremental review but it will be more awesomer soon.

[rwst]

Changed branch from u/rws/ticket/9321 to u/rws/new9321

[rwst]

comment:15

I moved the warning a bit lower and added necessary backticks. I also removed the version string from the python link, although you will still arrive at the 2.x version. It's no longer hardcoded however. Finally, I had to change the branch path because git amended commits are not accepted by sage -dev push.

---

New commits:

5f47daf

moved warning after some examples

[rwst]

Changed commit from eb0ddc0 to 5f47daf

[tscrim]

comment:16

Karl-Dieter, are you happy with the current version? (Really this is an elaborate ping.)

[kcrisman]

comment:17

I also removed the version string from the python link, although you will still arrive at the 2.x version. It's no longer hardcoded however.

https://docs.python.org/{2,3}/library/functions.html#sum is the link, technically. I won't hold it up for that, though, since they can just click on "sum" from the big list at that location. Doc looks good now.

Karl-Dieter, are you happy with the current version? (Really this is an elaborate ping.)

:-) Sorry for the delay; I definitely have been having to cut back even on review time the past few months.

[vbraun]

Changed branch from u/rws/new9321 to 5f47daf