#18405: Cleanup in the 'installation' manual
-------------------------+-------------------------------------------------
Reporter: | Owner:
ncohen | Status: needs_review
Type: | Milestone: sage-6.7
enhancement | Resolution:
Priority: major | Merged in:
Component: | Reviewers:
documentation | Work issues:
Keywords: | Commit:
Authors: | dbd2c63637a6d6d71eec606959b85931295dc973
Nathann Cohen | Stopgaps:
Report Upstream: N/A |
Branch: |
public/18405 |
Dependencies: |
-------------------------+-------------------------------------------------
Changes (by ncohen):
* status: new => needs_review
* commit: => dbd2c63637a6d6d71eec606959b85931295dc973
* branch: => public/18405
Old description:
> The installation manual is the first thing I get when I type 'install
> Sage' in
> Google. And from that manual, it is not totally obvious how Sage should
> be
> installed (especially from its sources). Read it and see how hard it is
> to get
> the basic info, like 'what to download' and 'what to type'
>
> This branch tries to clean that manual a bit, mostly by moving things
> around,
> making lengthy explanations shorter and adding table of contents where
> one is
> needed.
>
> In particular:
>
> - There is no need of a section about how to build the doc in this
> manual. It is
> already explained somewhere else (in the developer's manual), and the
> doc is
> already built when you install Sage anyway.
>
> - The section on SageTex is being moved to the (already existing)
> tutorial/sagetex document. Indeed:
> - Something as specific as 'how to configure Sagetex' does not belong
> to a
> document explaining how Sage should be installed (many packages
> require
> specific configuration, e.g. CPLEX,Gurobi,dot2tex,...)
> - Many links from the SageTex tutorial are broken if no internet
> connection is
> available, as they point directly to the online 'installation'
> manual. Besides, they point to the index and not to the actual
> install page.
> http://www.sagemath.org/doc/tutorial/sagetex.html
> - Some information is repeated in both documents (which usually leads
> to only
> one of the two being updated)
>
> - 'Desktop icon' is renamed to 'KDE Desktop icon'. Though I do not
> personally
> believe that it is Sage's role to explain how to customize KDE.
>
> - The 'introduction' section is merged with the 'index' page. Most of
> that
> section is actually a list of Sage's standard packages, and so this
> section
> has been renamed to 'standard packages'. Something will have to be done
> with
> this section later, see
> https://groups.google.com/d/topic/sage-devel/aEmUmFOwJYQ/discussion
New description:
The installation manual is the first thing I get when I type 'install
Sage' in Google. And from that manual, it is not totally obvious how Sage
should be installed (especially from its sources). Read it and see how
hard it is to get the basic info, like 'what to download' and 'what to
type'
This branch tries to clean that manual a bit, mostly by moving things
around, making lengthy explanations shorter and adding table of contents
where one is needed.
In particular:
- There is no need of a section about how to build the doc in this manual.
It is
already explained somewhere else (in the developer's manual), and the
doc is
already built when you install Sage anyway.
- The section on SageTex is being moved to the (already existing)
tutorial/sagetex document. Indeed:
- Something as specific as 'how to configure Sagetex' does not belong to
a
document explaining how Sage should be installed (many packages
require
specific configuration, e.g. CPLEX,Gurobi,dot2tex,...)
- Many links from the SageTex tutorial are broken if no internet
connection is
available, as they point directly to the online 'installation'
manual. Besides, they point to the index and not to the actual install
page.
http://www.sagemath.org/doc/tutorial/sagetex.html
- Some information is repeated in both documents (which usually leads to
only
one of the two being updated)
- 'Desktop icon' is renamed to 'KDE Desktop icon'. Though I do not
personally
believe that it is Sage's role to explain how to customize KDE.
- The 'introduction' section is merged with the 'index' page. Most of that
section is actually a list of Sage's standard packages, and so this
section
has been renamed to 'standard packages'. Something will have to be done
with
this section later, see
https://groups.google.com/d/topic/sage-devel/aEmUmFOwJYQ/discussion
Further work will have to be done to clean&simplify the two pages:
http://www.sagemath.org/doc/installation/source.html
http://www.sagemath.org/doc/installation/binary.html
Nathann
--
Comment:
New commits:
||[http://git.sagemath.org/sage.git/commit/?id=006c90fa41a711cfb41128ff6cb9e708362eda55
006c90f]||{{{trac #18405: Shorten the index page}}}||
||[http://git.sagemath.org/sage.git/commit/?id=b276bf8c4a3be1164992bcf53b3f64f18818a8bd
b276bf8]||{{{trac #18405: Explaining how to build the doc is already done
somewhere else}}}||
||[http://git.sagemath.org/sage.git/commit/?id=410479514fd041cb9612b721cd2d09c3ac0bbe40
4104795]||{{{trac #18405: 'Desktop icon' -> 'KDE Desktop icon'}}}||
||[http://git.sagemath.org/sage.git/commit/?id=bd702c0e06caf1a77eca59cd4a1ff441d513644b
bd702c0]||{{{trac #18405: *move* the content of sagetex.rst to the sagetex
tutorial (nothing else is done)}}}||
||[http://git.sagemath.org/sage.git/commit/?id=844361d91ac890588013f8f525a0d606e403065f
844361d]||{{{trac #18405: Merge the two documents and remove the old index
entry}}}||
||[http://git.sagemath.org/sage.git/commit/?id=b6836c617f43408dab5403b27d8b319830b66fee
b6836c6]||{{{trac #18405: Move the first paragraph of the intro to the
index}}}||
||[http://git.sagemath.org/sage.git/commit/?id=b25b0c9fc67ad1a0600fb90454c63e5704e39ed1
b25b0c9]||{{{trac #18405: Rename 'introduction' to
'standard_packages'}}}||
||[http://git.sagemath.org/sage.git/commit/?id=1e1f25a5c9a8e7b957e018478492c53a11f9632a
1e1f25a]||{{{trac #18405: Simplify the first paragraph of 'index'}}}||
||[http://git.sagemath.org/sage.git/commit/?id=dbd2c63637a6d6d71eec606959b85931295dc973
dbd2c63]||{{{trac #18405: Links and typoes}}}||
--
Ticket URL: <http://trac.sagemath.org/ticket/18405#comment:1>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sage-trac.
For more options, visit https://groups.google.com/d/optout.
