Improve documentation of span method

[rbeezer]

I discovered this while working on #12541. Documentation says the check will "coerce entries of gens into base field." This does not appear to be happening, and should. (Edit: this is an integral span of rational vectors, a construction that is intended, so improving the documentation might be in order.)

sage: (QQ^2).span(gens=[vector(QQ, [1,1/2])], base_ring=ZZ, check=True)
Free module of degree 2 and rank 1 over Integer Ring
Echelon basis matrix:
[  1 1/2]

Depends: #12541

Apply:

1. attachment: trac_12688_span_documentation.patch
2. attachment: trac_12688_span_documentation-update.patch

Depends on #12541

CC: @novoselt

Component: linear algebra

Keywords: rd2, sd40.5

Author: Rob Beezer

Reviewer: Andrey Novoseltsev

Merged: sage-5.1.beta5

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

[rbeezer]

comment:2

See some discussion on #12541.

[rbeezer]

Attachment: trac_12688_span_documentation.patch.gz

[rbeezer]

Dependencies: 12541

[rbeezer]

Changed keywords from none to rd2

[rbeezer]

Author: Rob Beezer

[rbeezer]

comment:3

Patch is documentation only. More thorough, and more in keeping with current documentation standards.

[novoselt]

comment:4

I'll look at it today/tomorrow if nobody beats me.

A side remark (for probably the next ticket?): while working on #12541 I had to fix several pieces of code that looked almost the same. In fact, I have removed exactly the same wrong lines from six places or so in different specializations of free modules. Perhaps these span and submodule methods can be somehow consolidated, e.g. have span only in the base class which calls _span of subclasses for actual work after all the typechecking and conversion. Or, if it is really necessary to have them everywhere, maybe there can be only 1 or 2 good long docstrings, as the one provided by Rob here, and others should just link to it?

[novoselt]

comment:5

Little picks:

• "INPUTS" should be without "S" according to guidelines.
• There also should be "OUTPUT" and perhaps it can precisely state here where the resulting submodule lives.

Otherwise looks good to me!

[novoselt]

Reviewer: Andrey Novoseltsev

[rbeezer]

comment:6

Replying to @novoselt:

Little picks:

• "INPUTS" should be without "S" according to guidelines.
• There also should be "OUTPUT" and perhaps it can precisely state here where the resulting submodule lives.

Thanks, Andrey. I forget these in my rush to wrap it up. I'll get an updated patch up soon, but it might be a couple days.

Rob

[rbeezer]

comment:7

Replying to @novoselt:

Perhaps these span and submodule methods can be somehow consolidated

I have not looked, but it would not surprise me if there was some beneficial consolidation. Maybe at Bug Days in a few weeks I'll tackle this one.

Rob

[novoselt]

comment:8

Replying to @rbeezer:

Replying to @novoselt:

Perhaps these span and submodule methods can be somehow consolidated

I have not looked, but it would not surprise me if there was some beneficial consolidation. Maybe at Bug Days in a few weeks I'll tackle this one.

Rob

Great, I'll be there too ;-)

[novoselt]

Changed keywords from rd2 to rd2, sd40.5

[novoselt]

comment:9

#12688 comment:5 is still valid ;-)

[rbeezer]

Attachment: trac_12688_span_documentation-update.patch.gz

Address reviewer comments

[rbeezer]

comment:10

Replying to @novoselt:

Thanks again - comments addressed in "update" patch.

Rob

Little picks:

• "INPUTS" should be without "S" according to guidelines.
• There also should be "OUTPUT" and perhaps it can precisely state here where the resulting submodule lives.

Otherwise looks good to me!

[jdemeyer]

Changed dependencies from 12541 to #12541

[jdemeyer]

Merged: sage-5.1.beta5