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

[rlm]

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

[rws]

The sagenb bug spreadsheet has several examples, too.

[rws]

New commits:

​228fd67

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

[kcrisman]

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.

[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

[rws]

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

[git]

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

​45fbd50

fix doctests

[tscrim]

Your warning messages are indented one too many times.

[git]

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

​eb0ddc0

too much indentation

[rws]

Thanks for the review.

[kcrisman]

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.

[rws]

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

[tscrim]

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

[kcrisman]

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.