Opened 3 years ago
Closed 3 years ago
#22386 closed enhancement (fixed)
Rearrange the table of contents of the reference manual
Reported by:  klee  Owned by:  

Priority:  minor  Milestone:  sage7.6 
Component:  documentation  Keywords:  days85 
Cc:  Merged in:  
Authors:  Kwankyu Lee  Reviewers:  Julian Rüth, Dima Pasechnik 
Report Upstream:  N/A  Work issues:  
Branch:  bf2278c (Commits)  Commit:  bf2278c2fd0b3be9e6e1603952f63098b0e5e955 
Dependencies:  Stopgaps: 
Description (last modified by )
As I see it, the current table of contents of the reference manual needs some rearrangement.
In the patch, I tried to arrange the mathematics topics such that those basic and having wider interest come first and those more advanced and having narrow interest come later.
Change History (34)
comment:1 Changed 3 years ago by
 Branch set to u/klee/22386
comment:2 Changed 3 years ago by
 Commit set to 606ac666e3d8d2b22802a1d4bb1e180600efc51d
comment:3 Changed 3 years ago by
 Description modified (diff)
comment:4 Changed 3 years ago by
 Status changed from new to needs_review
comment:5 followup: ↓ 6 Changed 3 years ago by
For nonmathematicians, the integers, rationals, reals, and complexes are going to be more familiar and useful than monoids, groups, semirings, and algebras. So moving the latter earlier does not put the topics with wider interest first.
comment:6 in reply to: ↑ 5 ; followup: ↓ 7 Changed 3 years ago by
Replying to jhpalmieri:
For nonmathematicians, the integers, rationals, reals, and complexes are going to be more familiar and useful than monoids, groups, semirings, and algebras. So moving the latter earlier does not put the topics with wider interest first.
I agree. I put that there because I thought "algebraic structures" are more mathematically *basic* than "rings and fields". Where do you think is better place for "algebraic structures"?
The purpose of this ticket is to improve the TOC than to make it perfect, which I think is impossible as we all may have different ideas...
comment:7 in reply to: ↑ 6 Changed 3 years ago by
Replying to klee:
Replying to jhpalmieri:
For nonmathematicians, the integers, rationals, reals, and complexes are going to be more familiar and useful than monoids, groups, semirings, and algebras. So moving the latter earlier does not put the topics with wider interest first.
I agree. I put that there because I thought "algebraic structures" are more mathematically *basic* than "rings and fields". Where do you think is better place for "algebraic structures"?
Where it was before, after basic rings and fields and linear algebra.
comment:8 Changed 3 years ago by
 Commit changed from 606ac666e3d8d2b22802a1d4bb1e180600efc51d to 24fcda33f46f121b68022f7c8512dc4a4d459750
Branch pushed to git repo; I updated commit sha1. New commits:
24fcda3  Put algebraic structures behind basic rings

comment:9 Changed 3 years ago by
 Commit changed from 24fcda33f46f121b68022f7c8512dc4a4d459750 to da38c8bf7396d44b67f17de2db3cf72444db64a0
Branch pushed to git repo; I updated commit sha1. New commits:
da38c8b  Put algebraic structures behind linear algebra

comment:10 Changed 3 years ago by
Most things in elliptic curves is number theory not algebraic geometry. Best change the title of that new section to Arithmetic geometry and put it after number theory.
comment:11 Changed 3 years ago by
I did not intend to go down to that level, but let's do that. I think we need to keep "Algebraic Geometry" section. How about this?
Algebraic Geometry  Schemes Plane Curves Number Theory  ... Arithmetic Geometry  Elliptic and Hyperelliptic Curves
Then do you think "Modular Abelian Varieties" also should go under "Arithmetic Geometry"?
comment:12 Changed 3 years ago by
I did not mean to split it up further. Just replace "Algebraic geometry" with "Arithmetic geometry" or "Algebraic and arithmetic geometry". Then it is clear that this section will contain lots of number theory, too. No I would not move modular abelian varieties.
comment:13 Changed 3 years ago by
I think it is good to have both "Algebraic Geometry" and "Arithmetic Geometry", and to keep
Schemes
Plane Curves
under "Algebraic Geometry" section. Why not?
comment:14 Changed 3 years ago by
 Commit changed from da38c8bf7396d44b67f17de2db3cf72444db64a0 to 6038cf7299d6793c549b30b86b41603a08c0b61c
comment:15 Changed 3 years ago by
It is not easy to separate out algebraic geometry from arithmetic geometry in Sage. So I follow wuthrich's suggestion.
comment:16 Changed 3 years ago by
Why would numerical optimisation be in "Special topics", but "SAT solvers" not? (these are close to each other topics, if you asked me).
And "numerical" is misleading in itselffor instance we have arbitrary precision LP solvers which output exact answers, and this is very close to other polyhedral computation tools.
comment:17 followup: ↓ 20 Changed 3 years ago by
Good idea to review this index.
Some thoughts:
 Does it really make sense that
Cryptography
is not listed under the same headline asCoding Theory
? Why not putCryptography
,Symbolic Logic
, andSAT Solvers
underDiscrete Mathematics
?
 I now realise that clicking on
Basic Infrastructure
goes to an index with the immensely useful list ofMathematical Data Structures
. Perhaps the headline should therefore instead beCore infrastructure and Mathematical Data structures
?
 What about putting
Other Algebraic Structures
afterDiscrete Mathematics
?
 What about putting
Calculus
earlier, right afterLinear Algebra
 most students will use Sage for calculus.
 I agree with Dima that
Numberical Optimization
is a weird category that I can't figure out where should go, but that it is semantically linked to SAT Solvers. Perhaps they should simply have their own headline calledSolvers
or something.
comment:18 Changed 3 years ago by
Numerical Optimization
should be split into parts. It's a weird mix of discrete optimization (Knapsack) out of place there, as it's not "numerical", but discrete, with numerical root finding, least squares approximation, and optimization of functions of one variable, and linear (LP), integer linear (ILP)again, a discrete problem and semidefinite programming (SDP).
By right, LP and SDP should be put into its own "Convex optimization", Knapsack and ILP into "Discrete optimization", and univariate things into "Calculus/numerical methods". I also think that the code for the latter and for Knapsack should be split into separate files  currently they are all dumped in numerical/optimize.py
, which also contains a little function to demonstrate the direct use of cvxopt
LP solverthe latter should also be somewhere else.
Note that ILP and LP are solved by the same frontend, specifying appropriate parameters, so I don't quite know how to structure the corresponding documentation.
(Probably one would have to link to .rst
files that further point at the concrete code documentation?)
comment:19 Changed 3 years ago by
 Commit changed from 6038cf7299d6793c549b30b86b41603a08c0b61c to bc6ff6a8e8aa207954d0ff3d90f5cb55f1d0ba2b
Branch pushed to git repo; I updated commit sha1. New commits:
bc6ff6a  Put calculus right after linear algebra

comment:20 in reply to: ↑ 17 ; followup: ↓ 22 Changed 3 years ago by
Replying to jsrn:
Does it really make sense that
Cryptography
is not listed under the same headline asCoding Theory
? Why not putCryptography
,Symbolic Logic
, andSAT Solvers
underDiscrete Mathematics
?
I moved Symbolic Logic
to under Discrete Mathematics
as suggested.
It is controversial if we could see cryptography as a branch of discrete mathematics in traditional sense. I personally do not agree.
I now realise that clicking on
Basic Infrastructure
goes to an index with the immensely useful list ofMathematical Data Structures
. Perhaps the headline should therefore instead beCore infrastructure and Mathematical Data structures
?
The title Basic infrastructure
is short and appropriate to keep the list under it. I would keep it.
What about putting
Other Algebraic Structures
afterDiscrete Mathematics
?
Done.
What about putting
Calculus
earlier, right afterLinear Algebra
 most students will use Sage for calculus.
Done. Also Probability and statistics
still follows it.
I agree with Dima that
Numberical Optimization
is a weird category that I can't figure out where should go, but that it is semantically linked to SAT Solvers. Perhaps they should simply have their own headline calledSolvers
or something.
Numerical optimization
section seems to require a rearrangement on its own level. This ticket is not intended for that. I will open a separate one so that further discussions could be carried on there.
comment:21 Changed 3 years ago by
Now for Numerical Optimization
section reorganization, we have
comment:22 in reply to: ↑ 20 Changed 3 years ago by
Thanks for the changes. I agree that the Numerical Optimization issues can be considered as beyond this ticket.
Replying to klee:
Replying to jsrn:
Does it really make sense that
Cryptography
is not listed under the same headline asCoding Theory
? Why not putCryptography
,Symbolic Logic
, andSAT Solvers
underDiscrete Mathematics
?I moved
Symbolic Logic
to underDiscrete Mathematics
as suggested.It is controversial if we could see cryptography as a branch of discrete mathematics in traditional sense. I personally do not agree.
I see your point, and I won't insist on anything. One could, however, see the role of cryptography in the mathematics software Sage as being the discrete mathematics side of cryptography. There is no numerical side to crypto, for instance.
I now realise that clicking on
Basic Infrastructure
goes to an index with the immensely useful list ofMathematical Data Structures
. Perhaps the headline should therefore instead beCore infrastructure and Mathematical Data structures
?The title
Basic infrastructure
is short and appropriate to keep the list under it. I would keep it.
It is certainly short but not appropriate. The heading "Basic infrastructure" sounds like something I shouldn't care about as a user (together with Parent, Element, the coercion framework and all that jazz). In complete opposition to this, it is *immensely* useful for a user to know the basic mathematical data structures. Besides, would you really look under the heading Basic Infrastructure
for Subset
?
comment:23 Changed 3 years ago by
 Commit changed from bc6ff6a8e8aa207954d0ff3d90f5cb55f1d0ba2b to 00724aeb6a14c6738e9f12a27f46fc283ef3ceba
comment:24 Changed 3 years ago by
I moved Sets
to a new Mathematcal Structures
section. This also put Monoids
and others back before Discrete Mathematics
. Leave comments if you do not like this.
comment:25 Changed 3 years ago by
 Commit changed from 00724aeb6a14c6738e9f12a27f46fc283ef3ceba to 8f272041351e1f3caa02a5df564f93816db15862
comment:26 Changed 3 years ago by
OK, I'd like to propose few more changes.
 rename: Calculus > Calculus and Analysis
 move Numerical Optimization to Calculus and Analysis
 move Cryprography and SAT Solvers to Discrete Mathematics
 remove the heading Special Topics (as it's empty after these moves).
Otherwise it looks better already...
comment:27 Changed 3 years ago by
 Commit changed from 8f272041351e1f3caa02a5df564f93816db15862 to a7ed64ee3de7ba25a8a664396204ec7ad7e66003
Branch pushed to git repo; I updated commit sha1. New commits:
a7ed64e  Remove unpopular special topics section

comment:28 Changed 3 years ago by
Typo in one of the section titles: please change "Arithemtic" to "Arithmetic".
comment:29 Changed 3 years ago by
 Commit changed from a7ed64ee3de7ba25a8a664396204ec7ad7e66003 to bf2278c2fd0b3be9e6e1603952f63098b0e5e955
Branch pushed to git repo; I updated commit sha1. New commits:
bf2278c  Correct a typo

comment:30 Changed 3 years ago by
 Reviewers set to Julian Rüth
 Status changed from needs_review to positive_review
Looks good to me, unless you want to make further changes. I think that this improves the situation quite a bit.
comment:31 Changed 3 years ago by
Thank you and all that have left comments!
comment:32 Changed 3 years ago by
 Reviewers changed from Julian Rüth to Julian Rüth, Dima Pasechnik
comment:33 Changed 3 years ago by
 Keywords days85 added
comment:34 Changed 3 years ago by
 Branch changed from u/klee/22386 to bf2278c2fd0b3be9e6e1603952f63098b0e5e955
 Resolution set to fixed
 Status changed from positive_review to closed
Branch pushed to git repo; I updated commit sha1. New commits:
Rearrange the TOC