#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: |
-------------------------+-------------------------------------------------
Comment (by ncohen):
Yo !
> I like the overall idea behind this ticket, but I think you should
separate this into "cleaning up things that truly are a mess" and
"removing/moving large sections that may or may not belong in the
installation guide".
To be honest this branch does not 'clean up' a lot of mess. That was my
first intent, but I figured out that it would be too much for one ticket,
so I left it out. Except for a couple of typoes, this branch only moves
things around: much more work will have to go into the 'install from
sources' and 'install from binaries' pages, in other tickets.
> Among other things, this may break third-party links...
I understand, though that should not stop us from reorganizing our doc. If
you want some kind of 'deprecation' for the doc we could add empty pages
(corresponding to the ones I removed), saying that the doc is now
available somewhere else.
I do not mind doing that if you ask, but if you do please create a poll on
sage-devel to ask what everybody thinks. That would be some kind of
'deprecation policy' for doc.
> but mostly I think that I would like to ''expand'' the influence of the
installation guide and make it more obvious, not make it harder to find
things. So the more extra information (KDE, SageTeX, ...) the merrier!
As long as it's well organized. And certainly those things fall under
"installation"; I would be happy to include information about CPLEX and
friends there, as a one-stop-shop is a good thing. Then the tutorial
could point to the installation guide for installation questions, leaving
the tutorial to be just a tutorial.
While we should obviously provide as ample and useful explanations as
possible with respect to all packages that we provide (even the optional
ones), I think that gathering them all in this document would be a
mistake.
Each package would have pretty different instructions, and nobody would be
interested by the 'installation instructions for all "complicated"
packages". We should make this information available, but we should keep
it close to the general documentation on these packages. It would give us,
for each package, a self-contained page about its uses and its
installation instruction, if necessary.
Furthermore, there does not seem to be a reliable way to link *between*
documents (except toward the reference manual). If we had all installation
instructions in this 'installation' manual, we would not be able to link
from a tutorial to the installation instructions (this branch actually
removes some such links), or from the installation back to the tutorial.
Also, I know for a fact that I only update reliably the files on which I
work. I forgot one thousand times to update the MILP tutorial when I
update the code, and I know that this would not happen if everything was
in the same file (as I browse its code and documentation much more often).
On the other hand, anybody working on a manual would necessarily recompile
it often, glance at it and notice some other thing which should be updated
too.
I am in favor of pages explaining at the same time how the software can be
used, and how it should be installed. Of course, we have ReST chapter to
differenciate the two in the same page.
Nathann
--
Ticket URL: <http://trac.sagemath.org/ticket/18405#comment:3>
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.
