# HG changeset patch
# User Mitesh Patel
# Date 1259521097 28800
# Node ID 874e6507c55571a55c0da7146cd7c7bb9b35413c
# Parent c97fa208548170efd4b3b3b2c60a4af78acb3017
#6495/doc: Break the reference manual into more manageable pieces
diff git a/.hgignore b/.hgignore
 a/.hgignore
+++ b/.hgignore
@@ 123,5 +123,4 @@ sage/rings/complex_double_api.h
sage/misc/allocator.h
sage/symbolic/pynac.h
doc/output/*
doc/en/reference/utils/*
doc/en/reference/sage/*
+doc/en/reference/.*/sage/*
diff git a/doc/common/builder.py b/doc/common/builder.py
 a/doc/common/builder.py
+++ b/doc/common/builder.py
@@ 135,11 +135,15 @@ class DocBuilder(object):
 ``lang``  (default "en") the language of the document.
"""
 if '/' in name:
 lang, name = name.split(os.path.sep)
 self.name = name
+ doc = name.split(os.path.sep)
+
+ if doc[0] in LANGUAGES:
+ lang = doc[0]
+ doc.pop(0)
+
+ self.name = os.path.join(*doc)
self.lang = lang
 self.dir = os.path.join(SAGE_DOC, lang, name)
+ self.dir = os.path.join(SAGE_DOC, self.lang, self.name)
#Make sure the .static and .templates directories are there
mkdir(os.path.join(self.dir, "static"))
@@ 237,6 +241,7 @@ class DocBuilder(object):
changes = builder_helper('changes')
linkcheck = builder_helper('linkcheck')
+
class AllBuilder(object):
"""
A class used to build all of the documentation.
@@ 279,6 +284,7 @@ class AllBuilder(object):
documents.append(os.path.join(lang, document))
return documents
+
class WebsiteBuilder(DocBuilder):
def html(self):
"""
@@ 310,9 +316,53 @@ class WebsiteBuilder(DocBuilder):
DocBuilder.clean(self)
class ReferenceBuilder(DocBuilder):
+
+class ReferenceBuilder(AllBuilder):
"""
 This the class used to build the reference manual. It is
+ This class builds the reference manual. It uses DocBuilder to
+ build the toplevel page and ReferenceSubBuilder for each
+ subcomponent.
+ """
+ def __init__(self, name):
+ """
+ Records the reference manual's name, in case it's not
+ identical to 'reference'.
+ """
+ AllBuilder.__init__(self)
+ self.name = name
+
+ def _wrapper(self, format, *args, **kwds):
+ """
+ Builds reference manuals. For each language, it builds the
+ toplevel document and its components.
+ """
+ for lang in LANGUAGES:
+ refdir = os.path.join(SAGE_DOC, lang, self.name)
+ if not os.path.exists(refdir):
+ continue
+
+ getattr(DocBuilder(self.name, lang), format)(*args, **kwds)
+ for doc in self.get_all_documents(refdir):
+ getattr(ReferenceSubBuilder(doc, lang), format)(*args, **kwds)
+
+ def get_all_documents(self, refdir):
+ """
+ Returns a list of all reference manual components to build.
+ We add a component name if it's a subdirectory of the manual's
+ directory and contains a file named 'index.rst'.
+ """
+ documents = []
+
+ for doc in os.listdir(refdir):
+ if os.path.exists(os.path.join(refdir, doc, 'index.rst')):
+ documents.append(os.path.join(self.name, doc))
+
+ return documents
+
+
+class ReferenceSubBuilder(DocBuilder):
+ """
+ This class builds subcomponents of the reference manual. It is
resposible for making sure the auto generated ReST files for the
Sage library are up to date.
@@ 696,14 +746,16 @@ class ReferenceBuilder(DocBuilder):
def get_builder(name):
"""
 Returns a either a AllBuilder or DocBuilder object depending
 on whether ``name`` is 'all' or not. These are the objects
 which do all the real work in building the documentation.
+ Returns an appropriate *Builder object for the document ``name``.
+ DocBuilder and its subclasses do all the real work in building the
+ documentation.
"""
if name == 'all':
return AllBuilder()
elif name.endswith('reference'):
return ReferenceBuilder(name)
+ elif 'reference' in name:
+ return ReferenceSubBuilder(name)
elif name.endswith('website'):
return WebsiteBuilder(name)
elif name in get_documents() or name in AllBuilder().get_all_documents():
diff git a/doc/common/conf.py b/doc/common/conf.py
 a/doc/common/conf.py
+++ b/doc/common/conf.py
@@ 183,8 +183,18 @@ html_split_index = True
# Output file base name for HTML help builder.
#htmlhelp_basename = ''
# Crosslinks to other project's online documentation.
intersphinx_mapping = {'http://docs.python.org/dev': None}
+# Crossreferences within Sage docs and to other projects' docs.
+intersphinx_mapping = {
+ 'http://docs.python.org/dev': None
+ }
+
+ref_src = os.path.join(SAGE_DOC, 'en', 'reference')
+ref_out = os.path.join(SAGE_DOC, 'output', 'html', 'en', 'reference')
+intersphinx_mapping[ref_out] = None
+
+for doc in os.listdir(ref_src):
+ if os.path.exists(os.path.join(ref_src, doc, 'index.rst')):
+ intersphinx_mapping[os.path.join(ref_out, doc)] = None
# Options for LaTeX output
diff git a/doc/en/reference/algebras.rst b/doc/en/reference/algebras.rst
deleted file mode 100644
 a/doc/en/reference/algebras.rst
+++ /dev/null
@@ 1,17 +0,0 @@
.. _ch:algebras:

Algebras
========

.. toctree::
 :maxdepth: 2

 sage/algebras/free_algebra
 sage/algebras/free_algebra_element

 sage/algebras/free_algebra_quotient
 sage/algebras/free_algebra_quotient_element

 sage/algebras/steenrod_algebra
 sage/algebras/steenrod_algebra_element
 sage/algebras/steenrod_algebra_bases
\ No newline at end of file
diff git a/doc/en/reference/algebras/conf.py b/doc/en/reference/algebras/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/algebras/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/algebras/index.rst b/doc/en/reference/algebras/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/algebras/index.rst
@@ 0,0 +1,18 @@
+Algebras
+========
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/algebras/free_algebra
+ sage/algebras/free_algebra_element
+
+ sage/algebras/free_algebra_quotient
+ sage/algebras/free_algebra_quotient_element
+
+ sage/algebras/steenrod_algebra
+ sage/algebras/steenrod_algebra_element
+ sage/algebras/steenrod_algebra_bases
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/arithgroup.rst b/doc/en/reference/arithgroup.rst
deleted file mode 100644
 a/doc/en/reference/arithgroup.rst
+++ /dev/null
@@ 1,20 +0,0 @@
.. _ch:arithgroup:

Arithmetic Subgroups of `{\rm SL}_2(\ZZ)`
================================================

This chapter describes the basic functionality for finite index subgroups of
the modular group `{\rm SL}_2(\ZZ)`.

.. toctree::
 :maxdepth: 2

 sage/modular/arithgroup/arithgroup_generic
 sage/modular/arithgroup/arithgroup_perm
 sage/modular/arithgroup/arithgroup_element
 sage/modular/arithgroup/congroup_generic
 sage/modular/arithgroup/congroup_gammaH
 sage/modular/arithgroup/congroup_gamma1
 sage/modular/arithgroup/congroup_gamma0
 sage/modular/arithgroup/congroup_gamma
 sage/modular/arithgroup/congroup_sl2z
diff git a/doc/en/reference/arithgroup/conf.py b/doc/en/reference/arithgroup/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/arithgroup/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/arithgroup/index.rst b/doc/en/reference/arithgroup/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/arithgroup/index.rst
@@ 0,0 +1,21 @@
+Arithmetic Subgroups of `{\rm SL}_2(\ZZ)`
+================================================
+
+This chapter describes the basic functionality for finite index subgroups of
+the modular group `{\rm SL}_2(\ZZ)`.
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/modular/arithgroup/arithgroup_generic
+ sage/modular/arithgroup/arithgroup_perm
+ sage/modular/arithgroup/arithgroup_element
+ sage/modular/arithgroup/congroup_generic
+ sage/modular/arithgroup/congroup_gammaH
+ sage/modular/arithgroup/congroup_gamma1
+ sage/modular/arithgroup/congroup_gamma0
+ sage/modular/arithgroup/congroup_gamma
+ sage/modular/arithgroup/congroup_sl2z
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/calculus.rst b/doc/en/reference/calculus.rst
deleted file mode 100644
 a/doc/en/reference/calculus.rst
+++ /dev/null
@@ 1,15 +0,0 @@
Symbolic Calculus
=================

.. toctree::
 :maxdepth: 2

 sage/symbolic/expression
 sage/symbolic/relation
 sage/calculus/calculus
 sage/symbolic/ring
 sage/calculus/functional
 sage/calculus/test_sympy
 sage/calculus/tests
 sage/symbolic/expression_conversions
 sage/calculus/wester
diff git a/doc/en/reference/calculus/conf.py b/doc/en/reference/calculus/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/calculus/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/calculus/index.rst b/doc/en/reference/calculus/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/calculus/index.rst
@@ 0,0 +1,18 @@
+Symbolic Calculus
+=================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/symbolic/expression
+ sage/symbolic/relation
+ sage/calculus/calculus
+ sage/symbolic/ring
+ sage/calculus/functional
+ sage/calculus/test_sympy
+ sage/calculus/tests
+ sage/symbolic/expression_conversions
+ sage/calculus/wester
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/categories.rst b/doc/en/reference/categories.rst
deleted file mode 100644
 a/doc/en/reference/categories.rst
+++ /dev/null
@@ 1,135 +0,0 @@
.. _ch:categories:

Category Theory
===============

.. toctree::
 :maxdepth: 2

 sage/categories/primer
 sage/categories/tutorial
 sage/categories/category
 sage/categories/category_types
 sage/categories/homset
 sage/categories/morphism
 sage/categories/functor

Functorial constructions
========================

.. toctree::
 :maxdepth: 2

 sage/categories/cartesian_product
 sage/categories/tensor
 sage/categories/dual

Categories
==========

.. toctree::
 :maxdepth: 2

 sage/categories/algebra_ideals
 sage/categories/algebra_modules
 sage/categories/algebras
 sage/categories/algebras_with_basis
 sage/categories/bialgebras
 sage/categories/bialgebras_with_basis
 sage/categories/bimodules
 sage/categories/coalgebras
 sage/categories/coalgebras_with_basis
 sage/categories/commutative_additive_groups
 sage/categories/commutative_additive_monoids
 sage/categories/commutative_additive_semigroups
 sage/categories/commutative_algebra_ideals
 sage/categories/commutative_algebras
 sage/categories/commutative_ring_ideals
 sage/categories/commutative_rings
 sage/categories/coxeter_groups
 sage/categories/division_rings
 sage/categories/domains
 sage/categories/enumerated_sets
 sage/categories/euclidean_domains
 sage/categories/fields
 sage/categories/finite_coxeter_groups
 sage/categories/finite_dimensional_algebras_with_basis
 sage/categories/finite_dimensional_bialgebras_with_basis
 sage/categories/finite_dimensional_coalgebras_with_basis
 sage/categories/finite_dimensional_hopf_algebras_with_basis
 sage/categories/finite_dimensional_modules_with_basis
 sage/categories/finite_enumerated_sets
 sage/categories/finite_fields
 sage/categories/finite_monoids
 sage/categories/finite_semigroups
 sage/categories/finite_weyl_groups
 sage/categories/gcd_domains
 sage/categories/graded_algebras
 sage/categories/graded_algebras_with_basis
 sage/categories/graded_bialgebras
 sage/categories/graded_bialgebras_with_basis
 sage/categories/graded_coalgebras
 sage/categories/graded_coalgebras_with_basis
 sage/categories/graded_hopf_algebras
 sage/categories/graded_hopf_algebras_with_basis
 sage/categories/graded_modules
 sage/categories/graded_modules_with_basis
 sage/categories/groupoid
 sage/categories/groups
 sage/categories/g_sets
 sage/categories/hecke_modules
 sage/categories/hopf_algebras
 sage/categories/hopf_algebras_with_basis
 sage/categories/infinite_enumerated_sets
 sage/categories/integral_domains
 sage/categories/left_modules
 sage/categories/matrix_algebras
 sage/categories/modular_abelian_varieties
 sage/categories/modules
 sage/categories/modules_with_basis
 sage/categories/monoid_algebras
 sage/categories/monoids
 sage/categories/number_fields
 sage/categories/objects
 sage/categories/partially_ordered_monoids
 sage/categories/partially_ordered_sets
 sage/categories/pointed_sets
 sage/categories/principal_ideal_domains
 sage/categories/quotient_fields
 sage/categories/right_modules
 sage/categories/ring_ideals
 sage/categories/rings
 sage/categories/rngs
 sage/categories/schemes
 sage/categories/semigroups
 sage/categories/sets_cat
 sage/categories/unique_factorization_domains
 sage/categories/vector_spaces
 sage/categories/weyl_groups

.. autoclass:: sage.categories.sets_cat::Sets.ParentMethods
 :members:


Examples of parents using categories
=====================================

.. toctree::
 :maxdepth: 2

 sage/categories/examples/algebras_with_basis
 sage/categories/examples/commutative_additive_monoids
 sage/categories/examples/commutative_additive_semigroups
 sage/categories/examples/finite_coxeter_groups
 sage/categories/examples/finite_enumerated_sets
 sage/categories/examples/finite_monoids
 sage/categories/examples/finite_semigroups
 sage/categories/examples/finite_weyl_groups
 sage/categories/examples/hopf_algebras_with_basis
 sage/categories/examples/infinite_enumerated_sets
 sage/categories/examples/monoids
 sage/categories/examples/semigroups
 sage/categories/examples/sets_cat
 sage/categories/examples/semigroups_cython

.. sage/categories/examples/coxeter_groups
diff git a/doc/en/reference/categories/conf.py b/doc/en/reference/categories/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/categories/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/categories/index.rst b/doc/en/reference/categories/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/categories/index.rst
@@ 0,0 +1,136 @@
+Category Theory
+===============
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/categories/primer
+ sage/categories/tutorial
+ sage/categories/category
+ sage/categories/category_types
+ sage/categories/homset
+ sage/categories/morphism
+ sage/categories/functor
+
+Functorial constructions
+========================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/categories/cartesian_product
+ sage/categories/tensor
+ sage/categories/dual
+
+Categories
+==========
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/categories/algebra_ideals
+ sage/categories/algebra_modules
+ sage/categories/algebras
+ sage/categories/algebras_with_basis
+ sage/categories/bialgebras
+ sage/categories/bialgebras_with_basis
+ sage/categories/bimodules
+ sage/categories/coalgebras
+ sage/categories/coalgebras_with_basis
+ sage/categories/commutative_additive_groups
+ sage/categories/commutative_additive_monoids
+ sage/categories/commutative_additive_semigroups
+ sage/categories/commutative_algebra_ideals
+ sage/categories/commutative_algebras
+ sage/categories/commutative_ring_ideals
+ sage/categories/commutative_rings
+ sage/categories/coxeter_groups
+ sage/categories/division_rings
+ sage/categories/domains
+ sage/categories/enumerated_sets
+ sage/categories/euclidean_domains
+ sage/categories/fields
+ sage/categories/finite_coxeter_groups
+ sage/categories/finite_dimensional_algebras_with_basis
+ sage/categories/finite_dimensional_bialgebras_with_basis
+ sage/categories/finite_dimensional_coalgebras_with_basis
+ sage/categories/finite_dimensional_hopf_algebras_with_basis
+ sage/categories/finite_dimensional_modules_with_basis
+ sage/categories/finite_enumerated_sets
+ sage/categories/finite_fields
+ sage/categories/finite_monoids
+ sage/categories/finite_semigroups
+ sage/categories/finite_weyl_groups
+ sage/categories/gcd_domains
+ sage/categories/graded_algebras
+ sage/categories/graded_algebras_with_basis
+ sage/categories/graded_bialgebras
+ sage/categories/graded_bialgebras_with_basis
+ sage/categories/graded_coalgebras
+ sage/categories/graded_coalgebras_with_basis
+ sage/categories/graded_hopf_algebras
+ sage/categories/graded_hopf_algebras_with_basis
+ sage/categories/graded_modules
+ sage/categories/graded_modules_with_basis
+ sage/categories/groupoid
+ sage/categories/groups
+ sage/categories/g_sets
+ sage/categories/hecke_modules
+ sage/categories/hopf_algebras
+ sage/categories/hopf_algebras_with_basis
+ sage/categories/infinite_enumerated_sets
+ sage/categories/integral_domains
+ sage/categories/left_modules
+ sage/categories/matrix_algebras
+ sage/categories/modular_abelian_varieties
+ sage/categories/modules
+ sage/categories/modules_with_basis
+ sage/categories/monoid_algebras
+ sage/categories/monoids
+ sage/categories/number_fields
+ sage/categories/objects
+ sage/categories/partially_ordered_monoids
+ sage/categories/partially_ordered_sets
+ sage/categories/pointed_sets
+ sage/categories/principal_ideal_domains
+ sage/categories/quotient_fields
+ sage/categories/right_modules
+ sage/categories/ring_ideals
+ sage/categories/rings
+ sage/categories/rngs
+ sage/categories/schemes
+ sage/categories/semigroups
+ sage/categories/sets_cat
+ sage/categories/unique_factorization_domains
+ sage/categories/vector_spaces
+ sage/categories/weyl_groups
+
+.. autoclass:: sage.categories.sets_cat::Sets.ParentMethods
+ :members:
+
+
+Examples of parents using categories
+=====================================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/categories/examples/algebras_with_basis
+ sage/categories/examples/commutative_additive_monoids
+ sage/categories/examples/commutative_additive_semigroups
+ sage/categories/examples/finite_coxeter_groups
+ sage/categories/examples/finite_enumerated_sets
+ sage/categories/examples/finite_monoids
+ sage/categories/examples/finite_semigroups
+ sage/categories/examples/finite_weyl_groups
+ sage/categories/examples/hopf_algebras_with_basis
+ sage/categories/examples/infinite_enumerated_sets
+ sage/categories/examples/monoids
+ sage/categories/examples/semigroups
+ sage/categories/examples/sets_cat
+ sage/categories/examples/semigroups_cython
+
+.. sage/categories/examples/coxeter_groups
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/cmd.rst b/doc/en/reference/cmd.rst
deleted file mode 100644
 a/doc/en/reference/cmd.rst
+++ /dev/null
@@ 1,15 +0,0 @@
.. _ch:cmdline:

The Sage Command Line
=====================

The chapter lists the Sage command line options. For more details
about how to use the Sage command line once it starts up, see the
Sage tutorial and the documentation for IPython.

.. toctree::
 :maxdepth: 2

 sage/misc/attach
 sage/misc/trace
 options
diff git a/doc/en/reference/cmd/conf.py b/doc/en/reference/cmd/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/cmd/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/cmd/index.rst b/doc/en/reference/cmd/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/cmd/index.rst
@@ 0,0 +1,16 @@
+The Sage Command Line
+=====================
+
+The chapter lists the Sage command line options. For more details
+about how to use the Sage command line once it starts up, see the
+Sage tutorial and the documentation for IPython.
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/misc/attach
+ sage/misc/trace
+ options
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/coding.rst b/doc/en/reference/coding.rst
deleted file mode 100644
 a/doc/en/reference/coding.rst
+++ /dev/null
@@ 1,10 +0,0 @@
Coding Theory
=============

.. toctree::
 :maxdepth: 2

 sage/coding/linear_code
 sage/coding/code_constructions
 sage/coding/sd_codes
 sage/coding/code_bounds
\ No newline at end of file
diff git a/doc/en/reference/coding/conf.py b/doc/en/reference/coding/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/coding/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/coding/index.rst b/doc/en/reference/coding/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/coding/index.rst
@@ 0,0 +1,12 @@
+Coding Theory
+=============
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/coding/linear_code
+ sage/coding/code_constructions
+ sage/coding/sd_codes
+ sage/coding/code_bounds
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/coercion.rst b/doc/en/reference/coercion.rst
deleted file mode 100644
 a/doc/en/reference/coercion.rst
+++ /dev/null
@@ 1,656 +0,0 @@
Coercion
========

Preliminaries


What is coercion all about?
~~~~~~~~~~~~~~~~~~~~~~~~~~~

*The primary goal of coercion is to be able to transparently do arithmetic, comparisons, etc. between elements of distinct sets.*

As a concrete example, when one writes `1 + 1/2` one wants to perform
arithmetic on the operands as rational numbers, despite the left being
an integer. This makes sense given the obvious and natural inclusion
of the integers into the rational numbers. The goal of the coercion
system is to facilitate this (and more complicated arithmetic) without
having to explicitly map everything over into the same domain, and at
the same time being strict enough to not resolve ambiguity or accept
nonsense. Here are some examples::

 sage: 1 + 1/2
 3/2
 sage: R. = ZZ[]
 sage: R
 Multivariate Polynomial Ring in x, y over Integer Ring
 sage: parent(x)
 Multivariate Polynomial Ring in x, y over Integer Ring
 sage: parent(1/3)
 Rational Field
 sage: x+1/3
 x + 1/3
 sage: parent(x+1/3)
 Multivariate Polynomial Ring in x, y over Rational Field

 sage: GF(5)(1) + CC(I)
 Traceback (most recent call last):
 ...
 TypeError: unsupported operand parent(s) for '+': 'Finite Field of size 5' and 'Complex Field with 53 bits of precision'

Parents and Elements
~~~~~~~~~~~~~~~~~~~~

Parents are objects in concrete categories, and Elements are their
members. Parents are firstclass objects. Most things in Sage are
either parents or have a parent. Typically whenever one sees the word
*Parent* one can think *Set*. Here are some examples::

 sage: parent(1)
 Integer Ring
 sage: parent(1) is ZZ
 True
 sage: ZZ
 Integer Ring
 sage: parent(1.50000000000000000000000000000000000)
 Real Field with 120 bits of precision
 sage: parent(x)
 Symbolic Ring
 sage: x^sin(x)
 x^sin(x)
 sage: R. = Qp(5)[]
 sage: f = t^35; f
 (1 + O(5^20))*t^3 + (4*5 + 4*5^2 + 4*5^3 + 4*5^4 + 4*5^5 + 4*5^6 + 4*5^7 + 4*5^8 + 4*5^9 + 4*5^10 + 4*5^11 + 4*5^12 + 4*5^13 + 4*5^14 + 4*5^15 + 4*5^16 + 4*5^17 + 4*5^18 + 4*5^19 + 4*5^20 + O(5^21))
 sage: parent(f)
 Univariate Polynomial Ring in t over 5adic Field with capped relative precision 20
 sage: f = EllipticCurve('37a').lseries().taylor_series(10); f
 0.997997869801216 + 0.00140712894524925*z  0.000498127610960097*z^2 + 0.000118835596665956*z^3  0.0000215906522442707*z^4 + (3.20363155418419e6)*z^5 + O(z^6) # 32bit
 0.997997869801216 + 0.00140712894524925*z  0.000498127610960098*z^2 + 0.000118835596665956*z^3  0.0000215906522442713*z^4 + (3.20363155418461e6)*z^5 + O(z^6) # 64bit
 sage: parent(f)
 Power Series Ring in z over Complex Field with 53 bits of precision

There is an important distinction between Parents and types::

 sage: a = GF(5).random_element()
 sage: b = GF(7).random_element()
 sage: type(a)

 sage: type(b)

 sage: type(a) == type(b)
 True
 sage: parent(a)
 Finite Field of size 5
 sage: parent(a) == parent(b)
 False

However, nonSage objects don't really have parents, but we still want
to be able to reason with them, so their type is used instead::

 sage: a = int(10)
 sage: parent(a)


In fact, under the hood, a special kind of parent "The set of all
Python objects of type T" is used in these cases.

Note that parents are **not** always as tight as possible.

::

 sage: parent(1/2)
 Rational Field
 sage: parent(2/1)
 Rational Field

Maps between Parents
~~~~~~~~~~~~~~~~~~~~

Many parents come with maps to and from other parents.

Sage makes a distinction between being able to **convert** between
various parents, and **coerce** between them. Conversion is explicit
and tries to make sense of an object in the target domain if at all
possible. It is invoked by calling::

 sage: ZZ(5)
 5
 sage: ZZ(10/5)
 2
 sage: QQ(10)
 10
 sage: parent(QQ(10))
 Rational Field
 sage: a = GF(5)(2); a
 2
 sage: parent(a)
 Finite Field of size 5
 sage: parent(ZZ(a))
 Integer Ring
 sage: GF(71)(1/5)
 57
 sage: ZZ(1/2)
 Traceback (most recent call last):
 ...
 TypeError: no conversion of this rational to integer

Conversions need not be canonical (they may for example involve a
choice of lift) or even make sense mathematically (e.g. constructions
of some kind).

::

 sage: ZZ("123")
 123
 sage: ZZ(GF(5)(14))
 4
 sage: ZZ['x']([4,3,2,1])
 x^3 + 2*x^2 + 3*x + 4
 sage: a = Qp(5, 10)(1/3); a
 2 + 3*5 + 5^2 + 3*5^3 + 5^4 + 3*5^5 + 5^6 + 3*5^7 + 5^8 + 3*5^9 + O(5^10)
 sage: ZZ(a)
 6510417

On the other hand, Sage has the notion of a **coercion**, which is a
canonical morphism (occasionally up to a conventional choice made by
developers) between parents. A coercion from one parent to another
**must** be defined on the whole domain, and always succeeds. As it
may be invoked implicitly, it should be obvious and natural (in both
the mathematically rigorous and colloquial sense of the word). Up to
inescapable rounding issues that arise with inexact representations,
these coercion morphisms should all commute. In particular, if there
are coercion maps `A \to B` and `B \to A`, then their composites
must be the identity maps.

Coercions can be discovered via the :meth:`has_coerce_map_from` method, and
if needed explicitly invoked with the :meth:`coerce` method::

 sage: QQ.has_coerce_map_from(ZZ)
 True
 sage: QQ.has_coerce_map_from(RR)
 False
 sage: ZZ['x'].has_coerce_map_from(QQ)
 False
 sage: ZZ['x'].has_coerce_map_from(ZZ)
 True
 sage: ZZ['x'].coerce(5)
 5
 sage: ZZ['x'].coerce(5).parent()
 Univariate Polynomial Ring in x over Integer Ring
 sage: ZZ['x'].coerce(5/1)
 Traceback (most recent call last):
 ...
 TypeError: no canonical coercion from Rational Field to Univariate Polynomial Ring in x over Integer Ring

Basic Arithmetic Rules


Suppose we want to add two element, a and b, whose parents are A and B
respectively. When we type ``a+b`` then

1. If A ``is`` B, call a._add_(b)

2. If there is a coercion `\phi: B \rightarrow A`, call a._add_( `\phi` (b))

3. If there is a coercion `\phi: A \rightarrow B`, call `\phi` (a)._add_(b)

4. Look for `Z` such that there is a coercion `\phi_A: A \rightarrow Z` and
 `\phi_B: B \rightarrow Z`, call `\phi_A` (a)._add_( `\phi_B` (b))

These rules are evaluated in order; therefore if there are coercions
in both directions, then the parent of a._add_b is A  the parent
of the lefthand operand is used in such cases.

These rules are evaluated in order; therefore if there are coercions
in both directions, then the parent of a._add_b is A  the parent
of the lefthand operand is used in such cases.

The same rules are used for subtraction, multiplication, and
division. This logic is embedded in a coercion model object, which can
be obtained and queried.

::

 sage: parent(1 + 1/2)
 Rational Field
 sage: cm = sage.structure.element.get_coercion_model(); cm

 sage: cm.explain(ZZ, QQ)
 Coercion on left operand via
 Natural morphism:
 From: Integer Ring
 To: Rational Field
 Arithmetic performed after coercions.
 Result lives in Rational Field
 Rational Field

 sage: cm.explain(ZZ['x','y'], QQ['x'])
 Coercion on left operand via
 Call morphism:
 From: Multivariate Polynomial Ring in x, y over Integer Ring
 To: Multivariate Polynomial Ring in x, y over Rational Field
 Coercion on right operand via
 Call morphism:
 From: Univariate Polynomial Ring in x over Rational Field
 To: Multivariate Polynomial Ring in x, y over Rational Field
 Arithmetic performed after coercions.
 Result lives in Multivariate Polynomial Ring in x, y over Rational Field
 Multivariate Polynomial Ring in x, y over Rational Field

The coercion model can be used directly for any binary operation
(callable taking two arguments).

.. link

::

 sage: cm.bin_op(77, 9, gcd)
 1

There are also **actions** in the sense that a field `K` acts on a
module over `K`, or a permutation group acts on a set. These are
discovered between steps 1 and 2 above.

.. link

::

 sage: cm.explain(ZZ['x'], ZZ, operator.mul)
 Action discovered.
 Right scalar multiplication by Integer Ring on Univariate Polynomial Ring in x over Integer Ring
 Result lives in Univariate Polynomial Ring in x over Integer Ring
 Univariate Polynomial Ring in x over Integer Ring

 sage: cm.explain(ZZ['x'], ZZ, operator.div)
 Action discovered.
 Right inverse action by Rational Field on Univariate Polynomial Ring in x over Integer Ring
 with precomposition on right by Natural morphism:
 From: Integer Ring
 To: Rational Field
 Result lives in Univariate Polynomial Ring in x over Rational Field
 Univariate Polynomial Ring in x over Rational Field

 sage: f = QQ.coerce_map_from(ZZ)
 sage: f(3).parent()
 Rational Field
 sage: QQ.coerce_map_from(int)
 Native morphism:
 From: Set of Python objects of type 'int'
 To: Rational Field
 sage: QQ.has_coerce_map_from(RR)
 False
 sage: QQ['x'].get_action(QQ)
 Right scalar multiplication by Rational Field on Univariate Polynomial Ring in x over Rational Field
 sage: (QQ^2).get_action(QQ)
 Right scalar multiplication by Rational Field on Vector space of dimension 2 over Rational Field
 sage: QQ['x'].get_action(RR)
 Right scalar multiplication by Real Field with 53 bits of precision on Univariate Polynomial Ring in x over Rational Field

How to Implement


Methods to implement
~~~~~~~~~~~~~~~~~~~~

* Arithmetic on Elements: ``_add_``, ``_sub_``, ``_mul_``, ``_div_``

 This is where the binary arithmetic operators should be
 implemented. Unlike Python's ``__add__``, both operands are
 *guaranteed* to have the same Parent at this point.

* Coercion for Parents: ``_coerce_map_from_``

 Given two parents R and S, ``R._coerce_map_from_(S)`` is called to
 determine if there is a coercion `\phi: S \rightarrow R`. Note that
 the function is called on the potential codomain. To indicate that
 there is no coercion from S to R (self), return ``False`` or
 ``None``. This is the default behavior. If there is a coercion,
 return ``True`` (in which case an morphism using
 ``R._element_constructor_`` will be created) or an actual
 :class:`Morphism` object with S as the domain and R as the codomain.

* Actions for Parents: ``_get_action_`` or ``_rmul_``, ``_lmul_``, ``_r_action_``, ``_l_action_``

 Suppose one wants R to act on S. Some examples of this could be
 `R = \QQ`, `S = \QQ[x]` or `R = {\rm Gal}(S/\QQ)`
 where `S` is a number field. There are several ways to implement this:

 * If `R` is the base of `S` (as in the first example), simply
 implement ``_rmul_`` and/or ``_lmul_`` on the Elements of `S`.
 In this case ``r * s`` gets handled as ``s._rmul_(r)`` and
 ``s * r`` as ``s._lmul_(r)``. The argument to ``_rmul_``
 and ``_lmul_`` are *guaranteed* to be Elements of the base of
 `S` (with coercion happening beforehand if necessary).

 * If `R` acts on `S`, one can alternatively define the methods
 ``_r_action_`` and/or ``_l_action_`` on the Elements of `R`.
 There is no constraint on the type or parents of objects passed to
 these methods; raise a ``TypeError`` or ``ValueError`` if the
 wrong kind of object is passed in to indicate the action is not
 appropriate here.

 * If either `R` acts on `S` *or* `S` acts on `R`, one may
 implement ``R._get_action_`` to return an actual :class:`Action`
 object to be used. This is how nonmultiplicative actions must be
 implemented, and is the most powerful (and completed) way to do
 things.

* Element conversion/construction for Parents: use
 ``_element_constructor_`` **not** ``__call__``

 The :meth:`Parent.__call__` method dispatches to
 ``_element_constructor_``. When someone writes ``R(x, ...)``, this is
 the method that eventually gets called in most cases. See the
 documentation on the ``__call__`` method below.

Parents may also call the ``self._populate_coercion_lists_`` method in
their ``__init__`` functions to pass any callable for use instead of
``_element_constructor_``, provide a list of Parents with coercions to
self (as an alternative to implementing ``_coerce_map_from_``),
provide special construction methods (like ``_integer_`` for ZZ),
etc. This also allows one to specify a single coercion embedding *out*
of self (whereas the rest of the coercion functions all specify maps
*into* self). There is extensive documentation in the docstring of the
``_populate_coercion_lists_`` method.

Example
~~~~~~~

Sometimes a simple example is worth a thousand words. Here is a
minimal example of setting up a simple Ring that handles coercion. (It
is easy to imagine much more sophisticated and powerful localizations,
but that would obscure the main points being made here.)

::

 class Localization(Ring):
 def __init__(self, primes):
 """
 Localization of `\ZZ` away from primes.
 """
 Ring.__init__(self, base=ZZ)
 self._primes = primes
 self._populate_coercion_lists_()

 def _repr_(self):
 """
 How to print self.
 """
 return "%s localized at %s" % (self.base(), self._primes)

 def _element_constructor_(self, x):
 """
 Make sure x is a valid member of self, and return the constructed element.
 """
 if isinstance(x, LocalizationElement):
 x = x._x
 else:
 x = QQ(x)
 for p, e in x.denominator().factor():
 if p not in self._primes:
 raise ValueError, "Not integral at %s" % p
 return LocalizationElement(self, x)

 def _coerce_map_from_(self, S):
 """
 The only things that coerce into this ring are:

  the integer ring

  other localizations away from fewer primes
 """
 if S is ZZ:
 return True
 elif isinstance(S, Localization):
 return all(p in self._primes for p in S._primes)


 class LocalizationElement(RingElement):

 def __init__(self, parent, x):
 RingElement.__init__(self, parent)
 self._value = x


 # We're just printing out this way to make it easy to see what's going on in the examples.

 def _repr_(self):
 return "LocalElt(%s)" % self._value

 # Now define addition, subtraction, and multiplication of elements.
 # Note that left and right always have the same parent.

 def _add_(left, right):
 return LocalizationElement(left.parent(), left._value + right._value)

 def _sub_(left, right):
 return LocalizationElement(left.parent(), left._value  right._value)

 def _mul_(left, right):
 return LocalizationElement(left.parent(), left._value * right._value)

 # The basering was set to ZZ, so c is guaranteed to be in ZZ

 def _rmul_(self, c):
 return LocalizationElement(self.parent(), c * self._value)

 def _lmul_(self, c):
 return LocalizationElement(self.parent(), self._value * c)

That's all there is to it. Now we can test it out:

.. skip

::

 sage: R = Localization([2]); R
 Integer Ring localized at [2]
 sage: R(1)
 LocalElt(1)
 sage: R(1/2)
 LocalElt(1/2)
 sage: R(1/3)
 Traceback (most recent call last):
 ...
 ValueError: Not integral at 3

 sage: R.coerce(1)
 LocalElt(1)
 sage: R.coerce(1/4)
 Traceback (click to the left for traceback)
 ...
 TypeError: no cannonical coercion from Rational Field to Integer Ring localized at [2]

 sage: R(1/2) + R(3/4)
 LocalElt(5/4)
 sage: R(1/2) + 5
 LocalElt(11/2)
 sage: 5 + R(1/2)
 LocalElt(11/2)
 sage: R(1/2) + 1/7
 Traceback (most recent call last):
 ...
 TypeError: unsupported operand parent(s) for '+': 'Integer Ring localized at [2]' and 'Rational Field'
 sage: R(3/4) * 7
 LocalElt(21/4)

 sage: R.get_action(ZZ)
 Right scalar multiplication by Integer Ring on Integer Ring localized at [2]
 sage: cm = sage.structure.element.get_coercion_model()
 sage: cm.explain(R, ZZ, operator.add)
 Coercion on right operand via
 Conversion map:
 From: Integer Ring
 To: Integer Ring localized at [2]
 Arithmetic performed after coercions.
 Result lives in Integer Ring localized at [2]
 Integer Ring localized at [2]

 sage: cm.explain(R, ZZ, operator.mul)
 Action discovered.
 Right scalar multiplication by Integer Ring on Integer Ring localized at [2]
 Result lives in Integer Ring localized at [2]
 Integer Ring localized at [2]

 sage: R6 = Localization([2,3]); R6
 Integer Ring localized at [2, 3]
 sage: R6(1/3)  R(1/2)
 LocalElt(1/6)
 sage: parent(R6(1/3)  R(1/2))
 Integer Ring localized at [2, 3]

 sage: R.has_coerce_map_from(ZZ)
 True
 sage: R.coerce_map_from(ZZ)
 Conversion map:
 From: Integer Ring
 To: Integer Ring localized at [2]

 sage: R6.coerce_map_from(R)
 Conversion map:
 From: Integer Ring localized at [2]
 To: Integer Ring localized at [2, 3]

 sage: R6.coerce(R(1/2))
 LocalElt(1/2)

 sage: cm.explain(R, R6, operator.mul)
 Coercion on left operand via
 Conversion map:
 From: Integer Ring localized at [2]
 To: Integer Ring localized at [2, 3]
 Arithmetic performed after coercions.
 Result lives in Integer Ring localized at [2, 3]
 Integer Ring localized at [2, 3]

Provided Methods
~~~~~~~~~~~~~~~~

* ``__call__``

 This provides a consistent interface for element construction. In
 particular, it makes sure that conversion always gives the same
 result as coercion, if a coercion exists. (This used to be violated
 for some Rings in Sage as the code for conversion and coercion got
 edited separately.) Let R be a Parent and assume the user types
 R(x), where x has parent X. Roughly speaking, the following occurs:

 1. If X ``is`` R, return x (*)

 2. If there is a coercion `f: X \rightarrow R`, return `f(x)`

 3. If there is a coercion `f: R \rightarrow X`, try to return `{f^{1}}(x)`

 4. Return ``R._element_constructor_(x)`` (**)

 Keywords and extra arguments are passed on. The result of all this logic is cached.

 (*) Unless there is a "copy" keyword like R(x, copy=False)

 (**) Technically, a generic morphism is created from X to R, which
 may use magic methods like ``_integer_`` or other data provided by
 ``_populate_coercion_lists_``.

* ``coerce``

 Coerces elements into self, raising a type error if there is no
 coercion map.

* ``coerce_map_from, convert_map_from``

 Returns an actual ``Morphism`` object to coerce/convert from
 another Parent to self. Barring direct construction of elements of
 R, ``R.convert_map_from(S)`` will provide a callable Python object
 which is the fastest way to convert elements of S to elements of
 R. From Cython, it can be invoked via the cdef ``_call_`` method.

* ``has_coerce_map_from``

 Returns ``True`` or ``False`` depending on whether or not there is
 a coercion. ``R.has_coerce_map_from(S)`` is shorthand for
 ``R.coerce_map_from(S) is not None``

* ``get_action``

 This will unwind all the
 ``_rmul_, _lmul_, _r_action_, _l_action_, ...`` methods to provide
 an actual ``Action`` object, if one exists.


Discovering new parents


New parents are discovered using an algorithm in
sage/category/pushout.py. The fundamental idea is that most Parents
in Sage are constructed from simpler objects via various functors.
These are accessed via the :meth:`construction` method, which returns a
(simpler) Parent along with a functor with which one can create self.

::

 sage: CC.construction()
 (AlgebraicClosureFunctor, Real Field with 53 bits of precision)
 sage: RR.construction()
 (CompletionFunctor, Rational Field)
 sage: QQ.construction()
 (FractionField, Integer Ring)
 sage: ZZ.construction() # None

 sage: Qp(5).construction()
 (CompletionFunctor, Rational Field)
 sage: QQ.completion(5, 100)
 5adic Field with capped relative precision 100
 sage: c, R = RR.construction()
 sage: a = CC.construction()[0]
 sage: a.commutes(c)
 False
 sage: RR == c(QQ)
 True

 sage: sage.categories.pushout.construction_tower(Frac(CDF['x']))
 [(None,
 Fraction Field of Univariate Polynomial Ring in x over Complex Double Field),
 (FractionField, Univariate Polynomial Ring in x over Complex Double Field),
 (Poly[x], Complex Double Field),
 (AlgebraicClosureFunctor, Real Double Field),
 (CompletionFunctor, Rational Field),
 (FractionField, Integer Ring)]

Given Parents R and S, such that there is no coercion either from R to
S or from S to R, one can find a common Z with coercions
`R \rightarrow Z` and `S \rightarrow Z` by considering the sequence of
construction functors to get from a common ancestor to both R and S.
We then use a *heuristic* algorithm to interleave these constructors
in an attempt to arrive at a suitable Z (if one exists). For example::

 sage: ZZ['x'].construction()
 (Poly[x], Integer Ring)
 sage: QQ.construction()
 (FractionField, Integer Ring)
 sage: sage.categories.pushout.pushout(ZZ['x'], QQ)
 Univariate Polynomial Ring in x over Rational Field
 sage: sage.categories.pushout.pushout(ZZ['x'], QQ).construction()
 (Poly[x], Rational Field)

The common ancestor is `Z` and our options for Z are
`\mathrm{Frac}(\ZZ[x])` or `\mathrm{Frac}(\ZZ)[x]`.
In Sage we choose the later, treating the fraction
field functor as binding "more tightly" than the polynomial functor,
as most people agree that `\QQ[x]` is the more natural choice. The same
procedure is applied to more complicated Parents, returning a new
Parent if one can be unambiguously determined.

::

 sage: sage.categories.pushout.pushout(Frac(ZZ['x,y,z']), QQ['z, t'])
 Univariate Polynomial Ring in t over Fraction Field of Multivariate Polynomial Ring in x, y, z over Rational Field

Modules


.. toctree::
 :maxdepth: 2

 sage/structure/coerce
 sage/structure/coerce_actions
 sage/structure/coerce_maps

diff git a/doc/en/reference/coercion/conf.py b/doc/en/reference/coercion/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/coercion/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/coercion/index.rst b/doc/en/reference/coercion/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/coercion/index.rst
@@ 0,0 +1,659 @@
+Coercion
+========
+
+Preliminaries
+
+
+What is coercion all about?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*The primary goal of coercion is to be able to transparently do arithmetic, comparisons, etc. between elements of distinct sets.*
+
+As a concrete example, when one writes `1 + 1/2` one wants to perform
+arithmetic on the operands as rational numbers, despite the left being
+an integer. This makes sense given the obvious and natural inclusion
+of the integers into the rational numbers. The goal of the coercion
+system is to facilitate this (and more complicated arithmetic) without
+having to explicitly map everything over into the same domain, and at
+the same time being strict enough to not resolve ambiguity or accept
+nonsense. Here are some examples::
+
+ sage: 1 + 1/2
+ 3/2
+ sage: R. = ZZ[]
+ sage: R
+ Multivariate Polynomial Ring in x, y over Integer Ring
+ sage: parent(x)
+ Multivariate Polynomial Ring in x, y over Integer Ring
+ sage: parent(1/3)
+ Rational Field
+ sage: x+1/3
+ x + 1/3
+ sage: parent(x+1/3)
+ Multivariate Polynomial Ring in x, y over Rational Field
+
+ sage: GF(5)(1) + CC(I)
+ Traceback (most recent call last):
+ ...
+ TypeError: unsupported operand parent(s) for '+': 'Finite Field of size 5' and 'Complex Field with 53 bits of precision'
+
+Parents and Elements
+~~~~~~~~~~~~~~~~~~~~
+
+Parents are objects in concrete categories, and Elements are their
+members. Parents are firstclass objects. Most things in Sage are
+either parents or have a parent. Typically whenever one sees the word
+*Parent* one can think *Set*. Here are some examples::
+
+ sage: parent(1)
+ Integer Ring
+ sage: parent(1) is ZZ
+ True
+ sage: ZZ
+ Integer Ring
+ sage: parent(1.50000000000000000000000000000000000)
+ Real Field with 120 bits of precision
+ sage: parent(x)
+ Symbolic Ring
+ sage: x^sin(x)
+ x^sin(x)
+ sage: R. = Qp(5)[]
+ sage: f = t^35; f
+ (1 + O(5^20))*t^3 + (4*5 + 4*5^2 + 4*5^3 + 4*5^4 + 4*5^5 + 4*5^6 + 4*5^7 + 4*5^8 + 4*5^9 + 4*5^10 + 4*5^11 + 4*5^12 + 4*5^13 + 4*5^14 + 4*5^15 + 4*5^16 + 4*5^17 + 4*5^18 + 4*5^19 + 4*5^20 + O(5^21))
+ sage: parent(f)
+ Univariate Polynomial Ring in t over 5adic Field with capped relative precision 20
+ sage: f = EllipticCurve('37a').lseries().taylor_series(10); f
+ 0.997997869801216 + 0.00140712894524925*z  0.000498127610960097*z^2 + 0.000118835596665956*z^3  0.0000215906522442707*z^4 + (3.20363155418419e6)*z^5 + O(z^6) # 32bit
+ 0.997997869801216 + 0.00140712894524925*z  0.000498127610960098*z^2 + 0.000118835596665956*z^3  0.0000215906522442713*z^4 + (3.20363155418461e6)*z^5 + O(z^6) # 64bit
+ sage: parent(f)
+ Power Series Ring in z over Complex Field with 53 bits of precision
+
+There is an important distinction between Parents and types::
+
+ sage: a = GF(5).random_element()
+ sage: b = GF(7).random_element()
+ sage: type(a)
+
+ sage: type(b)
+
+ sage: type(a) == type(b)
+ True
+ sage: parent(a)
+ Finite Field of size 5
+ sage: parent(a) == parent(b)
+ False
+
+However, nonSage objects don't really have parents, but we still want
+to be able to reason with them, so their type is used instead::
+
+ sage: a = int(10)
+ sage: parent(a)
+
+
+In fact, under the hood, a special kind of parent "The set of all
+Python objects of type T" is used in these cases.
+
+Note that parents are **not** always as tight as possible.
+
+::
+
+ sage: parent(1/2)
+ Rational Field
+ sage: parent(2/1)
+ Rational Field
+
+Maps between Parents
+~~~~~~~~~~~~~~~~~~~~
+
+Many parents come with maps to and from other parents.
+
+Sage makes a distinction between being able to **convert** between
+various parents, and **coerce** between them. Conversion is explicit
+and tries to make sense of an object in the target domain if at all
+possible. It is invoked by calling::
+
+ sage: ZZ(5)
+ 5
+ sage: ZZ(10/5)
+ 2
+ sage: QQ(10)
+ 10
+ sage: parent(QQ(10))
+ Rational Field
+ sage: a = GF(5)(2); a
+ 2
+ sage: parent(a)
+ Finite Field of size 5
+ sage: parent(ZZ(a))
+ Integer Ring
+ sage: GF(71)(1/5)
+ 57
+ sage: ZZ(1/2)
+ Traceback (most recent call last):
+ ...
+ TypeError: no conversion of this rational to integer
+
+Conversions need not be canonical (they may for example involve a
+choice of lift) or even make sense mathematically (e.g. constructions
+of some kind).
+
+::
+
+ sage: ZZ("123")
+ 123
+ sage: ZZ(GF(5)(14))
+ 4
+ sage: ZZ['x']([4,3,2,1])
+ x^3 + 2*x^2 + 3*x + 4
+ sage: a = Qp(5, 10)(1/3); a
+ 2 + 3*5 + 5^2 + 3*5^3 + 5^4 + 3*5^5 + 5^6 + 3*5^7 + 5^8 + 3*5^9 + O(5^10)
+ sage: ZZ(a)
+ 6510417
+
+On the other hand, Sage has the notion of a **coercion**, which is a
+canonical morphism (occasionally up to a conventional choice made by
+developers) between parents. A coercion from one parent to another
+**must** be defined on the whole domain, and always succeeds. As it
+may be invoked implicitly, it should be obvious and natural (in both
+the mathematically rigorous and colloquial sense of the word). Up to
+inescapable rounding issues that arise with inexact representations,
+these coercion morphisms should all commute. In particular, if there
+are coercion maps `A \to B` and `B \to A`, then their composites
+must be the identity maps.
+
+Coercions can be discovered via the :meth:`has_coerce_map_from` method, and
+if needed explicitly invoked with the :meth:`coerce` method::
+
+ sage: QQ.has_coerce_map_from(ZZ)
+ True
+ sage: QQ.has_coerce_map_from(RR)
+ False
+ sage: ZZ['x'].has_coerce_map_from(QQ)
+ False
+ sage: ZZ['x'].has_coerce_map_from(ZZ)
+ True
+ sage: ZZ['x'].coerce(5)
+ 5
+ sage: ZZ['x'].coerce(5).parent()
+ Univariate Polynomial Ring in x over Integer Ring
+ sage: ZZ['x'].coerce(5/1)
+ Traceback (most recent call last):
+ ...
+ TypeError: no canonical coercion from Rational Field to Univariate Polynomial Ring in x over Integer Ring
+
+Basic Arithmetic Rules
+
+
+Suppose we want to add two element, a and b, whose parents are A and B
+respectively. When we type ``a+b`` then
+
+1. If A ``is`` B, call a._add_(b)
+
+2. If there is a coercion `\phi: B \rightarrow A`, call a._add_( `\phi` (b))
+
+3. If there is a coercion `\phi: A \rightarrow B`, call `\phi` (a)._add_(b)
+
+4. Look for `Z` such that there is a coercion `\phi_A: A \rightarrow Z` and
+ `\phi_B: B \rightarrow Z`, call `\phi_A` (a)._add_( `\phi_B` (b))
+
+These rules are evaluated in order; therefore if there are coercions
+in both directions, then the parent of a._add_b is A  the parent
+of the lefthand operand is used in such cases.
+
+These rules are evaluated in order; therefore if there are coercions
+in both directions, then the parent of a._add_b is A  the parent
+of the lefthand operand is used in such cases.
+
+The same rules are used for subtraction, multiplication, and
+division. This logic is embedded in a coercion model object, which can
+be obtained and queried.
+
+::
+
+ sage: parent(1 + 1/2)
+ Rational Field
+ sage: cm = sage.structure.element.get_coercion_model(); cm
+
+ sage: cm.explain(ZZ, QQ)
+ Coercion on left operand via
+ Natural morphism:
+ From: Integer Ring
+ To: Rational Field
+ Arithmetic performed after coercions.
+ Result lives in Rational Field
+ Rational Field
+
+ sage: cm.explain(ZZ['x','y'], QQ['x'])
+ Coercion on left operand via
+ Call morphism:
+ From: Multivariate Polynomial Ring in x, y over Integer Ring
+ To: Multivariate Polynomial Ring in x, y over Rational Field
+ Coercion on right operand via
+ Call morphism:
+ From: Univariate Polynomial Ring in x over Rational Field
+ To: Multivariate Polynomial Ring in x, y over Rational Field
+ Arithmetic performed after coercions.
+ Result lives in Multivariate Polynomial Ring in x, y over Rational Field
+ Multivariate Polynomial Ring in x, y over Rational Field
+
+The coercion model can be used directly for any binary operation
+(callable taking two arguments).
+
+.. link
+
+::
+
+ sage: cm.bin_op(77, 9, gcd)
+ 1
+
+There are also **actions** in the sense that a field `K` acts on a
+module over `K`, or a permutation group acts on a set. These are
+discovered between steps 1 and 2 above.
+
+.. link
+
+::
+
+ sage: cm.explain(ZZ['x'], ZZ, operator.mul)
+ Action discovered.
+ Right scalar multiplication by Integer Ring on Univariate Polynomial Ring in x over Integer Ring
+ Result lives in Univariate Polynomial Ring in x over Integer Ring
+ Univariate Polynomial Ring in x over Integer Ring
+
+ sage: cm.explain(ZZ['x'], ZZ, operator.div)
+ Action discovered.
+ Right inverse action by Rational Field on Univariate Polynomial Ring in x over Integer Ring
+ with precomposition on right by Natural morphism:
+ From: Integer Ring
+ To: Rational Field
+ Result lives in Univariate Polynomial Ring in x over Rational Field
+ Univariate Polynomial Ring in x over Rational Field
+
+ sage: f = QQ.coerce_map_from(ZZ)
+ sage: f(3).parent()
+ Rational Field
+ sage: QQ.coerce_map_from(int)
+ Native morphism:
+ From: Set of Python objects of type 'int'
+ To: Rational Field
+ sage: QQ.has_coerce_map_from(RR)
+ False
+ sage: QQ['x'].get_action(QQ)
+ Right scalar multiplication by Rational Field on Univariate Polynomial Ring in x over Rational Field
+ sage: (QQ^2).get_action(QQ)
+ Right scalar multiplication by Rational Field on Vector space of dimension 2 over Rational Field
+ sage: QQ['x'].get_action(RR)
+ Right scalar multiplication by Real Field with 53 bits of precision on Univariate Polynomial Ring in x over Rational Field
+
+How to Implement
+
+
+Methods to implement
+~~~~~~~~~~~~~~~~~~~~
+
+* Arithmetic on Elements: ``_add_``, ``_sub_``, ``_mul_``, ``_div_``
+
+ This is where the binary arithmetic operators should be
+ implemented. Unlike Python's ``__add__``, both operands are
+ *guaranteed* to have the same Parent at this point.
+
+* Coercion for Parents: ``_coerce_map_from_``
+
+ Given two parents R and S, ``R._coerce_map_from_(S)`` is called to
+ determine if there is a coercion `\phi: S \rightarrow R`. Note that
+ the function is called on the potential codomain. To indicate that
+ there is no coercion from S to R (self), return ``False`` or
+ ``None``. This is the default behavior. If there is a coercion,
+ return ``True`` (in which case an morphism using
+ ``R._element_constructor_`` will be created) or an actual
+ :class:`Morphism` object with S as the domain and R as the codomain.
+
+* Actions for Parents: ``_get_action_`` or ``_rmul_``, ``_lmul_``, ``_r_action_``, ``_l_action_``
+
+ Suppose one wants R to act on S. Some examples of this could be
+ `R = \QQ`, `S = \QQ[x]` or `R = {\rm Gal}(S/\QQ)`
+ where `S` is a number field. There are several ways to implement this:
+
+ * If `R` is the base of `S` (as in the first example), simply
+ implement ``_rmul_`` and/or ``_lmul_`` on the Elements of `S`.
+ In this case ``r * s`` gets handled as ``s._rmul_(r)`` and
+ ``s * r`` as ``s._lmul_(r)``. The argument to ``_rmul_``
+ and ``_lmul_`` are *guaranteed* to be Elements of the base of
+ `S` (with coercion happening beforehand if necessary).
+
+ * If `R` acts on `S`, one can alternatively define the methods
+ ``_r_action_`` and/or ``_l_action_`` on the Elements of `R`.
+ There is no constraint on the type or parents of objects passed to
+ these methods; raise a ``TypeError`` or ``ValueError`` if the
+ wrong kind of object is passed in to indicate the action is not
+ appropriate here.
+
+ * If either `R` acts on `S` *or* `S` acts on `R`, one may
+ implement ``R._get_action_`` to return an actual :class:`Action`
+ object to be used. This is how nonmultiplicative actions must be
+ implemented, and is the most powerful (and completed) way to do
+ things.
+
+* Element conversion/construction for Parents: use
+ ``_element_constructor_`` **not** ``__call__``
+
+ The :meth:`Parent.__call__` method dispatches to
+ ``_element_constructor_``. When someone writes ``R(x, ...)``, this is
+ the method that eventually gets called in most cases. See the
+ documentation on the ``__call__`` method below.
+
+Parents may also call the ``self._populate_coercion_lists_`` method in
+their ``__init__`` functions to pass any callable for use instead of
+``_element_constructor_``, provide a list of Parents with coercions to
+self (as an alternative to implementing ``_coerce_map_from_``),
+provide special construction methods (like ``_integer_`` for ZZ),
+etc. This also allows one to specify a single coercion embedding *out*
+of self (whereas the rest of the coercion functions all specify maps
+*into* self). There is extensive documentation in the docstring of the
+``_populate_coercion_lists_`` method.
+
+Example
+~~~~~~~
+
+Sometimes a simple example is worth a thousand words. Here is a
+minimal example of setting up a simple Ring that handles coercion. (It
+is easy to imagine much more sophisticated and powerful localizations,
+but that would obscure the main points being made here.)
+
+::
+
+ class Localization(Ring):
+ def __init__(self, primes):
+ """
+ Localization of `\ZZ` away from primes.
+ """
+ Ring.__init__(self, base=ZZ)
+ self._primes = primes
+ self._populate_coercion_lists_()
+
+ def _repr_(self):
+ """
+ How to print self.
+ """
+ return "%s localized at %s" % (self.base(), self._primes)
+
+ def _element_constructor_(self, x):
+ """
+ Make sure x is a valid member of self, and return the constructed element.
+ """
+ if isinstance(x, LocalizationElement):
+ x = x._x
+ else:
+ x = QQ(x)
+ for p, e in x.denominator().factor():
+ if p not in self._primes:
+ raise ValueError, "Not integral at %s" % p
+ return LocalizationElement(self, x)
+
+ def _coerce_map_from_(self, S):
+ """
+ The only things that coerce into this ring are:
+
+  the integer ring
+
+  other localizations away from fewer primes
+ """
+ if S is ZZ:
+ return True
+ elif isinstance(S, Localization):
+ return all(p in self._primes for p in S._primes)
+
+
+ class LocalizationElement(RingElement):
+
+ def __init__(self, parent, x):
+ RingElement.__init__(self, parent)
+ self._value = x
+
+
+ # We're just printing out this way to make it easy to see what's going on in the examples.
+
+ def _repr_(self):
+ return "LocalElt(%s)" % self._value
+
+ # Now define addition, subtraction, and multiplication of elements.
+ # Note that left and right always have the same parent.
+
+ def _add_(left, right):
+ return LocalizationElement(left.parent(), left._value + right._value)
+
+ def _sub_(left, right):
+ return LocalizationElement(left.parent(), left._value  right._value)
+
+ def _mul_(left, right):
+ return LocalizationElement(left.parent(), left._value * right._value)
+
+ # The basering was set to ZZ, so c is guaranteed to be in ZZ
+
+ def _rmul_(self, c):
+ return LocalizationElement(self.parent(), c * self._value)
+
+ def _lmul_(self, c):
+ return LocalizationElement(self.parent(), self._value * c)
+
+That's all there is to it. Now we can test it out:
+
+.. skip
+
+::
+
+ sage: R = Localization([2]); R
+ Integer Ring localized at [2]
+ sage: R(1)
+ LocalElt(1)
+ sage: R(1/2)
+ LocalElt(1/2)
+ sage: R(1/3)
+ Traceback (most recent call last):
+ ...
+ ValueError: Not integral at 3
+
+ sage: R.coerce(1)
+ LocalElt(1)
+ sage: R.coerce(1/4)
+ Traceback (click to the left for traceback)
+ ...
+ TypeError: no cannonical coercion from Rational Field to Integer Ring localized at [2]
+
+ sage: R(1/2) + R(3/4)
+ LocalElt(5/4)
+ sage: R(1/2) + 5
+ LocalElt(11/2)
+ sage: 5 + R(1/2)
+ LocalElt(11/2)
+ sage: R(1/2) + 1/7
+ Traceback (most recent call last):
+ ...
+ TypeError: unsupported operand parent(s) for '+': 'Integer Ring localized at [2]' and 'Rational Field'
+ sage: R(3/4) * 7
+ LocalElt(21/4)
+
+ sage: R.get_action(ZZ)
+ Right scalar multiplication by Integer Ring on Integer Ring localized at [2]
+ sage: cm = sage.structure.element.get_coercion_model()
+ sage: cm.explain(R, ZZ, operator.add)
+ Coercion on right operand via
+ Conversion map:
+ From: Integer Ring
+ To: Integer Ring localized at [2]
+ Arithmetic performed after coercions.
+ Result lives in Integer Ring localized at [2]
+ Integer Ring localized at [2]
+
+ sage: cm.explain(R, ZZ, operator.mul)
+ Action discovered.
+ Right scalar multiplication by Integer Ring on Integer Ring localized at [2]
+ Result lives in Integer Ring localized at [2]
+ Integer Ring localized at [2]
+
+ sage: R6 = Localization([2,3]); R6
+ Integer Ring localized at [2, 3]
+ sage: R6(1/3)  R(1/2)
+ LocalElt(1/6)
+ sage: parent(R6(1/3)  R(1/2))
+ Integer Ring localized at [2, 3]
+
+ sage: R.has_coerce_map_from(ZZ)
+ True
+ sage: R.coerce_map_from(ZZ)
+ Conversion map:
+ From: Integer Ring
+ To: Integer Ring localized at [2]
+
+ sage: R6.coerce_map_from(R)
+ Conversion map:
+ From: Integer Ring localized at [2]
+ To: Integer Ring localized at [2, 3]
+
+ sage: R6.coerce(R(1/2))
+ LocalElt(1/2)
+
+ sage: cm.explain(R, R6, operator.mul)
+ Coercion on left operand via
+ Conversion map:
+ From: Integer Ring localized at [2]
+ To: Integer Ring localized at [2, 3]
+ Arithmetic performed after coercions.
+ Result lives in Integer Ring localized at [2, 3]
+ Integer Ring localized at [2, 3]
+
+Provided Methods
+~~~~~~~~~~~~~~~~
+
+* ``__call__``
+
+ This provides a consistent interface for element construction. In
+ particular, it makes sure that conversion always gives the same
+ result as coercion, if a coercion exists. (This used to be violated
+ for some Rings in Sage as the code for conversion and coercion got
+ edited separately.) Let R be a Parent and assume the user types
+ R(x), where x has parent X. Roughly speaking, the following occurs:
+
+ 1. If X ``is`` R, return x (*)
+
+ 2. If there is a coercion `f: X \rightarrow R`, return `f(x)`
+
+ 3. If there is a coercion `f: R \rightarrow X`, try to return `{f^{1}}(x)`
+
+ 4. Return ``R._element_constructor_(x)`` (**)
+
+ Keywords and extra arguments are passed on. The result of all this logic is cached.
+
+ (*) Unless there is a "copy" keyword like R(x, copy=False)
+
+ (**) Technically, a generic morphism is created from X to R, which
+ may use magic methods like ``_integer_`` or other data provided by
+ ``_populate_coercion_lists_``.
+
+* ``coerce``
+
+ Coerces elements into self, raising a type error if there is no
+ coercion map.
+
+* ``coerce_map_from, convert_map_from``
+
+ Returns an actual ``Morphism`` object to coerce/convert from
+ another Parent to self. Barring direct construction of elements of
+ R, ``R.convert_map_from(S)`` will provide a callable Python object
+ which is the fastest way to convert elements of S to elements of
+ R. From Cython, it can be invoked via the cdef ``_call_`` method.
+
+* ``has_coerce_map_from``
+
+ Returns ``True`` or ``False`` depending on whether or not there is
+ a coercion. ``R.has_coerce_map_from(S)`` is shorthand for
+ ``R.coerce_map_from(S) is not None``
+
+* ``get_action``
+
+ This will unwind all the
+ ``_rmul_, _lmul_, _r_action_, _l_action_, ...`` methods to provide
+ an actual ``Action`` object, if one exists.
+
+
+Discovering new parents
+
+
+New parents are discovered using an algorithm in
+sage/category/pushout.py. The fundamental idea is that most Parents
+in Sage are constructed from simpler objects via various functors.
+These are accessed via the :meth:`construction` method, which returns a
+(simpler) Parent along with a functor with which one can create self.
+
+::
+
+ sage: CC.construction()
+ (AlgebraicClosureFunctor, Real Field with 53 bits of precision)
+ sage: RR.construction()
+ (CompletionFunctor, Rational Field)
+ sage: QQ.construction()
+ (FractionField, Integer Ring)
+ sage: ZZ.construction() # None
+
+ sage: Qp(5).construction()
+ (CompletionFunctor, Rational Field)
+ sage: QQ.completion(5, 100)
+ 5adic Field with capped relative precision 100
+ sage: c, R = RR.construction()
+ sage: a = CC.construction()[0]
+ sage: a.commutes(c)
+ False
+ sage: RR == c(QQ)
+ True
+
+ sage: sage.categories.pushout.construction_tower(Frac(CDF['x']))
+ [(None,
+ Fraction Field of Univariate Polynomial Ring in x over Complex Double Field),
+ (FractionField, Univariate Polynomial Ring in x over Complex Double Field),
+ (Poly[x], Complex Double Field),
+ (AlgebraicClosureFunctor, Real Double Field),
+ (CompletionFunctor, Rational Field),
+ (FractionField, Integer Ring)]
+
+Given Parents R and S, such that there is no coercion either from R to
+S or from S to R, one can find a common Z with coercions
+`R \rightarrow Z` and `S \rightarrow Z` by considering the sequence of
+construction functors to get from a common ancestor to both R and S.
+We then use a *heuristic* algorithm to interleave these constructors
+in an attempt to arrive at a suitable Z (if one exists). For example::
+
+ sage: ZZ['x'].construction()
+ (Poly[x], Integer Ring)
+ sage: QQ.construction()
+ (FractionField, Integer Ring)
+ sage: sage.categories.pushout.pushout(ZZ['x'], QQ)
+ Univariate Polynomial Ring in x over Rational Field
+ sage: sage.categories.pushout.pushout(ZZ['x'], QQ).construction()
+ (Poly[x], Rational Field)
+
+The common ancestor is `Z` and our options for Z are
+`\mathrm{Frac}(\ZZ[x])` or `\mathrm{Frac}(\ZZ)[x]`.
+In Sage we choose the later, treating the fraction
+field functor as binding "more tightly" than the polynomial functor,
+as most people agree that `\QQ[x]` is the more natural choice. The same
+procedure is applied to more complicated Parents, returning a new
+Parent if one can be unambiguously determined.
+
+::
+
+ sage: sage.categories.pushout.pushout(Frac(ZZ['x,y,z']), QQ['z, t'])
+ Univariate Polynomial Ring in t over Fraction Field of Multivariate Polynomial Ring in x, y, z over Rational Field
+
+Modules
+
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/structure/coerce
+ sage/structure/coerce_actions
+ sage/structure/coerce_maps
+
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/combinat/conf.py b/doc/en/reference/combinat/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/combinat/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/combinat/index.rst b/doc/en/reference/combinat/index.rst
 a/doc/en/reference/combinat/index.rst
+++ b/doc/en/reference/combinat/index.rst
@@ 4,37 +4,37 @@ Combinatorics
.. toctree::
:maxdepth: 2
 ../sage/combinat/combinat
 ../sage/combinat/sloane_functions
 ../sage/combinat/expnums
 ../sage/combinat/alternating_sign_matrix
 ../sage/combinat/cartesian_product
 ../sage/combinat/combination
 ../sage/combinat/composition_signed
 ../sage/combinat/composition
 ../sage/combinat/dlx
 ../sage/combinat/matrices/dlxcpp
 ../sage/combinat/dyck_word
 ../sage/combinat/finite_class
 ../sage/combinat/integer_list
 ../sage/combinat/integer_vector
 ../sage/combinat/integer_vector_weighted
 ../sage/combinat/restricted_growth
 ../sage/combinat/yamanouchi
 ../sage/combinat/graph_path
 ../sage/combinat/matrices/latin
 ../sage/combinat/lyndon_word
 ../sage/combinat/necklace
 ../sage/combinat/non_decreasing_parking_function
 ../sage/combinat/partition
 ../sage/combinat/permutation
 ../sage/combinat/q_analogues
 ../sage/combinat/set_partition_ordered
 ../sage/combinat/set_partition
 ../sage/combinat/skew_partition
 ../sage/combinat/subset
 ../sage/combinat/subword
 ../sage/combinat/tuple
+ sage/combinat/combinat
+ sage/combinat/sloane_functions
+ sage/combinat/expnums
+ sage/combinat/alternating_sign_matrix
+ sage/combinat/cartesian_product
+ sage/combinat/combination
+ sage/combinat/composition_signed
+ sage/combinat/composition
+ sage/combinat/dlx
+ sage/combinat/matrices/dlxcpp
+ sage/combinat/dyck_word
+ sage/combinat/finite_class
+ sage/combinat/integer_list
+ sage/combinat/integer_vector
+ sage/combinat/integer_vector_weighted
+ sage/combinat/restricted_growth
+ sage/combinat/yamanouchi
+ sage/combinat/graph_path
+ sage/combinat/matrices/latin
+ sage/combinat/lyndon_word
+ sage/combinat/necklace
+ sage/combinat/non_decreasing_parking_function
+ sage/combinat/partition
+ sage/combinat/permutation
+ sage/combinat/q_analogues
+ sage/combinat/set_partition_ordered
+ sage/combinat/set_partition
+ sage/combinat/skew_partition
+ sage/combinat/subset
+ sage/combinat/subword
+ sage/combinat/tuple
algebra
tableaux
@@ 47,4 +47,7 @@ Combinatorics
developer
words
 ../sage/combinat/misc
+ sage/combinat/misc
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/conf.py b/doc/en/reference/conf.py
 a/doc/en/reference/conf.py
+++ b/doc/en/reference/conf.py
@@ 35,3 +35,61 @@ latex_documents = [
#Ignore all .rst in the _sage subdirectory
exclude_trees = exclude_trees + ['_sage']
+
+# List of directories, relative to source directory, that shouldn't be
+# searched for source files.
+exclude_trees = exclude_trees + [
+ 'algebras',
+ 'arithgroup',
+ 'calculus',
+ 'categories',
+ 'cmd',
+ 'coding',
+ 'coercion',
+ 'combinat',
+ 'constants',
+ 'cryptography',
+ 'databases',
+ 'dsage',
+ 'functions',
+ 'games',
+ 'geometry',
+ 'graphs',
+ 'groups',
+ 'hecke',
+ 'history_and_license',
+ 'homology',
+ 'interfaces',
+ 'lfunctions',
+ 'libs',
+ 'matrices',
+ 'misc',
+ 'modabvar',
+ 'modfrm',
+ 'modmisc',
+ 'modsym',
+ 'modules',
+ 'monoids',
+ 'networking',
+ 'notebook',
+ 'number_fields',
+ 'numerical',
+ 'options',
+ 'padics',
+ 'plane_curves',
+ 'plot3d',
+ 'plotting',
+ 'polynomial_rings',
+ 'polynomial_rings_multivar',
+ 'polynomial_rings_univar',
+ 'power_series',
+ 'probability',
+ 'quat_algebras',
+ 'rings',
+ 'rings_numerical',
+ 'rings_standard',
+ 'sage',
+ 'sagenb',
+ 'schemes',
+ 'structure'
+ ]
diff git a/doc/en/reference/constants.rst b/doc/en/reference/constants.rst
deleted file mode 100644
 a/doc/en/reference/constants.rst
+++ /dev/null
@@ 1,7 +0,0 @@
Constants
=========

.. toctree::
 :maxdepth: 2

 sage/symbolic/constants
diff git a/doc/en/reference/constants/conf.py b/doc/en/reference/constants/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/constants/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/constants/index.rst b/doc/en/reference/constants/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/constants/index.rst
@@ 0,0 +1,10 @@
+Constants
+=========
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/symbolic/constants
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/cryptography.rst b/doc/en/reference/cryptography.rst
deleted file mode 100644
 a/doc/en/reference/cryptography.rst
+++ /dev/null
@@ 1,26 +0,0 @@
Cryptography
============

.. toctree::
 :maxdepth: 2

 sage/crypto/cryptosystem

 sage/crypto/cipher

 sage/crypto/classical
 sage/crypto/classical_cipher

 sage/crypto/block_cipher/sdes
 sage/crypto/block_cipher/miniaes

 sage/crypto/stream
 sage/crypto/stream_cipher

 sage/crypto/lfsr

 sage/crypto/boolean_function

 sage/crypto/mq/sr
 sage/crypto/mq/mpolynomialsystem
 sage/crypto/mq/sbox
diff git a/doc/en/reference/cryptography/conf.py b/doc/en/reference/cryptography/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/cryptography/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/cryptography/index.rst b/doc/en/reference/cryptography/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/cryptography/index.rst
@@ 0,0 +1,29 @@
+Cryptography
+============
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/crypto/cryptosystem
+
+ sage/crypto/cipher
+
+ sage/crypto/classical
+ sage/crypto/classical_cipher
+
+ sage/crypto/block_cipher/sdes
+ sage/crypto/block_cipher/miniaes
+
+ sage/crypto/stream
+ sage/crypto/stream_cipher
+
+ sage/crypto/lfsr
+
+ sage/crypto/boolean_function
+
+ sage/crypto/mq/sr
+ sage/crypto/mq/mpolynomialsystem
+ sage/crypto/mq/sbox
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/databases.rst b/doc/en/reference/databases.rst
deleted file mode 100644
 a/doc/en/reference/databases.rst
+++ /dev/null
@@ 1,61 +0,0 @@
.. _ch:databases:

Databases
=========

There are numerous specific mathematical databases either included
in Sage or available as optional packages. Also, Sage includes two
powerful general database packages.

Sage includes the ZOPE object oriented database ZODB, which
"is a Python object persistence system. It provides transparent objectoriented persistency."

Sage also includes the powerful relational database SQLite, along
with a Python interface to SQLite. SQlite is a small C library that
implements a selfcontained, embeddable, zeroconfiguration SQL
database engine.


 Transactions are atomic, consistent, isolated, and durable
 (ACID) even after system crashes and power failures.

 Zeroconfiguration  no setup or administration needed.

 Implements most of SQL92. (Features not supported)

 A complete database is stored in a single disk file.

 Database files can be freely shared between machines with
 different byte orders.

 Supports databases up to 2 tebibytes (2^41 bytes) in size.

 Strings and BLOBs up to 2 gibibytes (2^31 bytes) in size.

 Small code footprint: less than 250KiB fully configured or less
 than 150KiB with optional features omitted.

 Faster than popular client/server database engines for most
 common operations.

 Simple, easy to use API.

 TCL bindings included. Bindings for many other languages
 available separately.

 Wellcommented source code with over 95% test coverage.

 Selfcontained: no external dependencies.

 Sources are in the public domain. Use for any purpose.

.. toctree::
 :maxdepth: 2

 sage/databases/cremona
 sage/databases/stein_watkins
 sage/databases/jones
 sage/databases/lincodes
 sage/databases/sloane
 sage/databases/conway
 sage/databases/odlyzko
diff git a/doc/en/reference/databases/conf.py b/doc/en/reference/databases/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/databases/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/databases/index.rst b/doc/en/reference/databases/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/databases/index.rst
@@ 0,0 +1,62 @@
+Databases
+=========
+
+There are numerous specific mathematical databases either included
+in Sage or available as optional packages. Also, Sage includes two
+powerful general database packages.
+
+Sage includes the ZOPE object oriented database ZODB, which
+"is a Python object persistence system. It provides transparent objectoriented persistency."
+
+Sage also includes the powerful relational database SQLite, along
+with a Python interface to SQLite. SQlite is a small C library that
+implements a selfcontained, embeddable, zeroconfiguration SQL
+database engine.
+
+
+ Transactions are atomic, consistent, isolated, and durable
+ (ACID) even after system crashes and power failures.
+
+ Zeroconfiguration  no setup or administration needed.
+
+ Implements most of SQL92. (Features not supported)
+
+ A complete database is stored in a single disk file.
+
+ Database files can be freely shared between machines with
+ different byte orders.
+
+ Supports databases up to 2 tebibytes (2^41 bytes) in size.
+
+ Strings and BLOBs up to 2 gibibytes (2^31 bytes) in size.
+
+ Small code footprint: less than 250KiB fully configured or less
+ than 150KiB with optional features omitted.
+
+ Faster than popular client/server database engines for most
+ common operations.
+
+ Simple, easy to use API.
+
+ TCL bindings included. Bindings for many other languages
+ available separately.
+
+ Wellcommented source code with over 95% test coverage.
+
+ Selfcontained: no external dependencies.
+
+ Sources are in the public domain. Use for any purpose.
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/databases/cremona
+ sage/databases/stein_watkins
+ sage/databases/jones
+ sage/databases/lincodes
+ sage/databases/sloane
+ sage/databases/conway
+ sage/databases/odlyzko
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/dsage.rst b/doc/en/reference/dsage.rst
deleted file mode 100644
 a/doc/en/reference/dsage.rst
+++ /dev/null
@@ 1,7 +0,0 @@
DSage: Distributed Sage
=======================

.. automodule:: dsage.dsage
 :members:
 :undocmembers:

diff git a/doc/en/reference/dsage/conf.py b/doc/en/reference/dsage/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/dsage/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/dsage/index.rst b/doc/en/reference/dsage/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/dsage/index.rst
@@ 0,0 +1,10 @@
+DSage: Distributed Sage
+=======================
+
+.. automodule:: dsage.dsage
+ :members:
+ :undocmembers:
+
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/footer.txt b/doc/en/reference/footer.txt
new file mode 100644
 /dev/null
+++ b/doc/en/reference/footer.txt
@@ 0,0 +1,9 @@
+Indices and Tables
+==================
+
+.. toctree::
+ :maxdepth: 1
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff git a/doc/en/reference/functions.rst b/doc/en/reference/functions.rst
deleted file mode 100644
 a/doc/en/reference/functions.rst
+++ /dev/null
@@ 1,15 +0,0 @@
Functions
=========

.. toctree::
 :maxdepth: 2

 sage/functions/log
 sage/functions/hyperbolic
 sage/functions/transcendental
 sage/functions/piecewise
 sage/functions/orthogonal_polys
 sage/functions/special
 sage/functions/wigner
 sage/functions/generalized
 sage/functions/prime_pi
\ No newline at end of file
diff git a/doc/en/reference/functions/conf.py b/doc/en/reference/functions/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/functions/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/functions/index.rst b/doc/en/reference/functions/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/functions/index.rst
@@ 0,0 +1,17 @@
+Functions
+=========
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/functions/log
+ sage/functions/hyperbolic
+ sage/functions/transcendental
+ sage/functions/piecewise
+ sage/functions/orthogonal_polys
+ sage/functions/special
+ sage/functions/wigner
+ sage/functions/generalized
+ sage/functions/prime_pi
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/games.rst b/doc/en/reference/games.rst
deleted file mode 100644
 a/doc/en/reference/games.rst
+++ /dev/null
@@ 1,10 +0,0 @@
Games
=====

Sage includes a sophisticated Sudoku solver. It also has a
Rubik's cube solver (see :ref:`Rubik's Cube Group `).

.. toctree::
 :maxdepth: 2

 sage/games/sudoku
\ No newline at end of file
diff git a/doc/en/reference/games/conf.py b/doc/en/reference/games/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/games/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/games/index.rst b/doc/en/reference/games/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/games/index.rst
@@ 0,0 +1,12 @@
+Games
+=====
+
+Sage includes a sophisticated Sudoku solver. It also has a
+Rubik's cube solver (see :ref:`Rubik's Cube Group `).
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/games/sudoku
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/geometry.rst b/doc/en/reference/geometry.rst
deleted file mode 100644
 a/doc/en/reference/geometry.rst
+++ /dev/null
@@ 1,13 +0,0 @@
Combinatorial Geometry
======================

Sage includes support for computing with lattice and reflexive
polytopes and Groebner fans. It also has optional support for
computing with general polytopes via the polymake program.

.. toctree::
 :maxdepth: 2

 sage/geometry/lattice_polytope
 sage/rings/polynomial/groebner_fan
 sage/geometry/polytope
\ No newline at end of file
diff git a/doc/en/reference/geometry/conf.py b/doc/en/reference/geometry/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/geometry/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/geometry/index.rst b/doc/en/reference/geometry/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/geometry/index.rst
@@ 0,0 +1,15 @@
+Combinatorial Geometry
+======================
+
+Sage includes support for computing with lattice and reflexive
+polytopes and Groebner fans. It also has optional support for
+computing with general polytopes via the polymake program.
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/geometry/lattice_polytope
+ sage/rings/polynomial/groebner_fan
+ sage/geometry/polytope
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/graphs.rst b/doc/en/reference/graphs.rst
deleted file mode 100644
 a/doc/en/reference/graphs.rst
+++ /dev/null
@@ 1,15 +0,0 @@
Graph Theory
============

.. toctree::
 :maxdepth: 2

 sage/graphs/cliquer
 sage/graphs/graph
 sage/graphs/graph_generators
 sage/graphs/graph_database
 sage/graphs/graph_list
 sage/graphs/base/c_graph
 sage/graphs/base/sparse_graph
 sage/graphs/base/dense_graph
 sage/graphs/graph_latex
diff git a/doc/en/reference/graphs/conf.py b/doc/en/reference/graphs/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/graphs/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/graphs/index.rst b/doc/en/reference/graphs/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/graphs/index.rst
@@ 0,0 +1,18 @@
+Graph Theory
+============
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/graphs/cliquer
+ sage/graphs/graph
+ sage/graphs/graph_generators
+ sage/graphs/graph_database
+ sage/graphs/graph_list
+ sage/graphs/base/c_graph
+ sage/graphs/base/sparse_graph
+ sage/graphs/base/dense_graph
+ sage/graphs/graph_latex
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/groups.rst b/doc/en/reference/groups.rst
deleted file mode 100644
 a/doc/en/reference/groups.rst
+++ /dev/null
@@ 1,30 +0,0 @@
.. _ch:groups:

Groups
======

.. toctree::
 :maxdepth: 2

 sage/groups/group
 sage/groups/generic
 sage/groups/abelian_gps/abelian_group
 sage/groups/abelian_gps/abelian_group_element
 sage/groups/abelian_gps/abelian_group_morphism
 sage/groups/abelian_gps/dual_abelian_group
 sage/groups/perm_gps/permgroup
 sage/groups/perm_gps/permgroup_element
 sage/groups/perm_gps/permgroup_morphism
 sage/groups/perm_gps/cubegroup
 sage/groups/matrix_gps/matrix_group
 sage/groups/matrix_gps/matrix_group_element
 sage/groups/matrix_gps/matrix_group_morphism
 sage/groups/matrix_gps/homset
 sage/groups/matrix_gps/linear
 sage/groups/matrix_gps/general_linear
 sage/groups/matrix_gps/special_linear
 sage/groups/matrix_gps/orthogonal
 sage/groups/matrix_gps/symplectic
 sage/groups/matrix_gps/unitary


diff git a/doc/en/reference/groups/conf.py b/doc/en/reference/groups/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/groups/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/groups/index.rst b/doc/en/reference/groups/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/groups/index.rst
@@ 0,0 +1,31 @@
+Groups
+======
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/groups/group
+ sage/groups/generic
+ sage/groups/abelian_gps/abelian_group
+ sage/groups/abelian_gps/abelian_group_element
+ sage/groups/abelian_gps/abelian_group_morphism
+ sage/groups/abelian_gps/dual_abelian_group
+ sage/groups/perm_gps/permgroup
+ sage/groups/perm_gps/permgroup_element
+ sage/groups/perm_gps/permgroup_morphism
+ sage/groups/perm_gps/cubegroup
+ sage/groups/matrix_gps/matrix_group
+ sage/groups/matrix_gps/matrix_group_element
+ sage/groups/matrix_gps/matrix_group_morphism
+ sage/groups/matrix_gps/homset
+ sage/groups/matrix_gps/linear
+ sage/groups/matrix_gps/general_linear
+ sage/groups/matrix_gps/special_linear
+ sage/groups/matrix_gps/orthogonal
+ sage/groups/matrix_gps/symplectic
+ sage/groups/matrix_gps/unitary
+
+
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/hecke.rst b/doc/en/reference/hecke.rst
deleted file mode 100644
 a/doc/en/reference/hecke.rst
+++ /dev/null
@@ 1,24 +0,0 @@
.. _ch:hecke:

General Hecke Algebras and Hecke Modules
========================================

This chapter describes the basic functionality for modules over Hecke
algebras, including decompositions, degeneracy maps and so on. For specific
examples of Hecke algebras that use this functionality see :ref:`ch:modsym` and
:ref:`ch:modular`.

.. toctree::
 :maxdepth: 2

 sage/modular/hecke/module
 sage/modular/hecke/ambient_module
 sage/modular/hecke/submodule
 sage/modular/hecke/element

 sage/modular/hecke/homspace
 sage/modular/hecke/morphism
 sage/modular/hecke/degenmap

 sage/modular/hecke/algebra
 sage/modular/hecke/hecke_operator
diff git a/doc/en/reference/hecke/conf.py b/doc/en/reference/hecke/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/hecke/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/hecke/index.rst b/doc/en/reference/hecke/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/hecke/index.rst
@@ 0,0 +1,25 @@
+General Hecke Algebras and Hecke Modules
+========================================
+
+This chapter describes the basic functionality for modules over Hecke
+algebras, including decompositions, degeneracy maps and so on. For specific
+examples of Hecke algebras that use this functionality see :ref:`ch:modsym` and
+:ref:`ch:modular`.
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/modular/hecke/module
+ sage/modular/hecke/ambient_module
+ sage/modular/hecke/submodule
+ sage/modular/hecke/element
+
+ sage/modular/hecke/homspace
+ sage/modular/hecke/morphism
+ sage/modular/hecke/degenmap
+
+ sage/modular/hecke/algebra
+ sage/modular/hecke/hecke_operator
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/history_and_license.rst b/doc/en/reference/history_and_license.rst
deleted file mode 100644
 a/doc/en/reference/history_and_license.rst
+++ /dev/null
@@ 1,393 +0,0 @@
History and License
===================
Sage was initially created by William Stein in 20042005, using
Python, IPython, PARI, SWIG, Pyrex, NTL, and GMP. These programs
are all open source and released under the GPL or a GPLcompatible
license.

All Sage releases are released under the GPL. All documentation
is released under the GNU Free Documentation License.


The GNU General Public License

Version 2, June 1991

::

 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
 51 Franklin Street, Fifth Floor, Boston, MA 021101301, USA

 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.


Preamble
~~~~~~~~

The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change
free softwareto make sure the software is free for all its users.
This General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit
to using it. (Some other Free Software Foundation software is
covered by the GNU Library General Public License instead.) You can
apply it to your programs, too.

When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and
charge for this service if you wish), that you receive source code
or can get it if you want it, that you can change the software or
use pieces of it in new free programs; and that you know you can do
these things.

To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the
rights. These restrictions translate to certain responsibilities
for you if you distribute copies of the software, or if you modify
it.

For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights
that you have. You must make sure that they, too, receive or can
get the source code. And you must show them these terms so they
know their rights.

We protect your rights with two steps: (1) copyright the software,
and (2) offer you this license which gives you legal permission to
copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make
certain that everyone understands that there is no warranty for
this free software. If the software is modified by someone else and
passed on, we want its recipients to know that what they have is
not the original, so that any problems introduced by others will
not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software
patents. We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making
the program proprietary. To prevent this, we have made it clear
that any patent must be licensed for everyone's free use or not
licensed at all.

The precise terms and conditions for copying, distribution and
modification follow.

Terms and Conditions For Copying, Distribution and Modification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



0. This License applies to any program or other work which contains a
 notice placed by the copyright holder saying it may be distributed
 under the terms of this General Public License. The "Program",
 below, refers to any such program or work, and a
 "work based on the Program" means either the Program or any
 derivative work under copyright law: that is to say, a work
 containing the Program or a portion of it, either verbatim or with
 modifications and/or translated into another language.
 (Hereinafter, translation is included without limitation in the
 term "modification".) Each licensee is addressed as "you".

 Activities other than copying, distribution and modification are
 not covered by this License; they are outside its scope. The act of
 running the Program is not restricted, and the output from the
 Program is covered only if its contents constitute a work based on
 the Program (independent of having been made by running the
 Program). Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program's source
 code as you receive it, in any medium, provided that you
 conspicuously and appropriately publish on each copy an appropriate
 copyright notice and disclaimer of warranty; keep intact all the
 notices that refer to this License and to the absence of any
 warranty; and give any other recipients of the Program a copy of
 this License along with the Program.

 You may charge a fee for the physical act of transferring a copy,
 and you may at your option offer warranty protection in exchange
 for a fee.

 You may modify your copy or copies of the Program or any portion of
 it, thus forming a work based on the Program, and copy and
 distribute such modifications or work under the terms of Section 1
 above, provided that you also meet all of these conditions:


 a. You must cause the modified files to carry prominent notices
 stating that you changed the files and the date of any change.

 b. You must cause any work that you distribute or publish, that in
 whole or in part contains or is derived from the Program or any
 part thereof, to be licensed as a whole at no charge to all third
 parties under the terms of this License.

 c. If the modified program normally reads commands interactively
 when run, you must cause it, when started running for such
 interactive use in the most ordinary way, to print or display an
 announcement including an appropriate copyright notice and a notice
 that there is no warranty (or else, saying that you provide a
 warranty) and that users may redistribute the program under these
 conditions, and telling the user how to view a copy of this
 License. (Exception: if the Program itself is interactive but does
 not normally print such an announcement, your work based on the
 Program is not required to print an announcement.)


2. These requirements apply to the modified work as a whole. If
 identifiable sections of that work are not derived from the
 Program, and can be reasonably considered independent and separate
 works in themselves, then this License, and its terms, do not apply
 to those sections when you distribute them as separate works. But
 when you distribute the same sections as part of a whole which is a
 work based on the Program, the distribution of the whole must be on
 the terms of this License, whose permissions for other licensees
 extend to the entire whole, and thus to each and every part
 regardless of who wrote it.

 Thus, it is not the intent of this section to claim rights or
 contest your rights to work written entirely by you; rather, the
 intent is to exercise the right to control the distribution of
 derivative or collective works based on the Program.

 In addition, mere aggregation of another work not based on the
 Program with the Program (or with a work based on the Program) on a
 volume of a storage or distribution medium does not bring the other
 work under the scope of this License.

3. You may copy and distribute the Program (or a work based on it,
 under Section 2) in object code or executable form under the terms
 of Sections 1 and 2 above provided that you also do one of the
 following:


 a. Accompany it with the complete corresponding machinereadable
 source code, which must be distributed under the terms of Sections
 1 and 2 above on a medium customarily used for software
 interchange; or,

 b. Accompany it with a written offer, valid for at least three
 years, to give any third party, for a charge no more than your cost
 of physically performing source distribution, a complete
 machinereadable copy of the corresponding source code, to be
 distributed under the terms of Sections 1 and 2 above on a medium
 customarily used for software interchange; or,

 c. Accompany it with the information you received as to the offer
 to distribute corresponding source code. (This alternative is
 allowed only for noncommercial distribution and only if you
 received the program in object code or executable form with such an
 offer, in accord with Subsection b above.)


 The source code for a work means the preferred form of the work for
 making modifications to it. For an executable work, complete source
 code means all the source code for all modules it contains, plus
 any associated interface definition files, plus the scripts used to
 control compilation and installation of the executable. However, as
 a special exception, the source code distributed need not include
 anything that is normally distributed (in either source or binary
 form) with the major components (compiler, kernel, and so on) of
 the operating system on which the executable runs, unless that
 component itself accompanies the executable.

 If distribution of executable or object code is made by offering
 access to copy from a designated place, then offering equivalent
 access to copy the source code from the same place counts as
 distribution of the source code, even though third parties are not
 compelled to copy the source along with the object code.

4. You may not copy, modify, sublicense, or distribute the Program
 except as expressly provided under this License. Any attempt
 otherwise to copy, modify, sublicense or distribute the Program is
 void, and will automatically terminate your rights under this
 License. However, parties who have received copies, or rights, from
 you under this License will not have their licenses terminated so
 long as such parties remain in full compliance.

5. You are not required to accept this License, since you have not
 signed it. However, nothing else grants you permission to modify or
 distribute the Program or its derivative works. These actions are
 prohibited by law if you do not accept this License. Therefore, by
 modifying or distributing the Program (or any work based on the
 Program), you indicate your acceptance of this License to do so,
 and all its terms and conditions for copying, distributing or
 modifying the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the
 Program), the recipient automatically receives a license from the
 original licensor to copy, distribute or modify the Program subject
 to these terms and conditions. You may not impose any further
 restrictions on the recipients' exercise of the rights granted
 herein. You are not responsible for enforcing compliance by third
 parties to this License.

7. If, as a consequence of a court judgment or allegation of patent
 infringement or for any other reason (not limited to patent
 issues), conditions are imposed on you (whether by court order,
 agreement or otherwise) that contradict the conditions of this
 License, they do not excuse you from the conditions of this
 License. If you cannot distribute so as to satisfy simultaneously
 your obligations under this License and any other pertinent
 obligations, then as a consequence you may not distribute the
 Program at all. For example, if a patent license would not permit
 royaltyfree redistribution of the Program by all those who receive
 copies directly or indirectly through you, then the only way you
 could satisfy both it and this License would be to refrain entirely
 from distribution of the Program.

 If any portion of this section is held invalid or unenforceable
 under any particular circumstance, the balance of the section is
 intended to apply and the section as a whole is intended to apply
 in other circumstances.

 It is not the purpose of this section to induce you to infringe any
 patents or other property right claims or to contest validity of
 any such claims; this section has the sole purpose of protecting
 the integrity of the free software distribution system, which is
 implemented by public license practices. Many people have made
 generous contributions to the wide range of software distributed
 through that system in reliance on consistent application of that
 system; it is up to the author/donor to decide if he or she is
 willing to distribute software through any other system and a
 licensee cannot impose that choice.

 This section is intended to make thoroughly clear what is believed
 to be a consequence of the rest of this License.

8. If the distribution and/or use of the Program is restricted in
 certain countries either by patents or by copyrighted interfaces,
 the original copyright holder who places the Program under this
 License may add an explicit geographical distribution limitation
 excluding those countries, so that distribution is permitted only
 in or among countries not thus excluded. In such case, this License
 incorporates the limitation as if written in the body of this
 License.

9. The Free Software Foundation may publish revised and/or new
 versions of the General Public License from time to time. Such new
 versions will be similar in spirit to the present version, but may
 differ in detail to address new problems or concerns.

 Each version is given a distinguishing version number. If the
 Program specifies a version number of this License which applies to
 it and "any later version", you have the option of following the
 terms and conditions either of that version or of any later version
 published by the Free Software Foundation. If the Program does not
 specify a version number of this License, you may choose any
 version ever published by the Free Software Foundation.

10. If you wish to incorporate parts of the Program into other free
 programs whose distribution conditions are different, write to the
 author to ask for permission. For software which is copyrighted by
 the Free Software Foundation, write to the Free Software
 Foundation; we sometimes make exceptions for this. Our decision
 will be guided by the two goals of preserving the free status of
 all derivatives of our free software and of promoting the sharing
 and reuse of software generally.

**NO WARRANTY**

11. Because the program is licensed free of charge, there is no
 warranty for the program, to the extent permitted by applicable
 law. Except when otherwise stated in writing the copyright holders
 and/or other parties provide the program "as is" without warranty
 of any kind, either expressed or implied, including, but not
 limited to, the implied warranties of merchantability and fitness
 for a particular purpose. The entire risk as to the quality and
 performance of the program is with you. Should the program prove
 defective, you assume the cost of all necessary servicing, repair
 or correction.

12. In no event unless required by applicable law or agreed to in
 writing will any copyright holder, or any other party who may
 modify and/or redistribute the program as permitted above, be
 liable to you for damages, including any general, special,
 incidental or consequential damages arising out of the use or
 inability to use the program (including but not limited to loss of
 data or data being rendered inaccurate or losses sustained by you
 or third parties or a failure of the program to operate with any
 other programs), even if such holder or other party has been
 advised of the possibility of such damages.


**End of Terms and Conditions**

Appendix: How to Apply These Terms to Your New Programs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make
it free software which everyone can redistribute and change under
these terms.

To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at
least the "copyright" line and a pointer to where the full notice
is found.

::

 one line to give the program's name and a brief idea of what it
 does.
 Copyright (C) yyyy name of author

 This program is free software; you can redistribute it and/or
 modify it under the terms of the GNU General Public License as
 published by the Free Software Foundation; either version 2 of the
 License, or (at your option) any later version.

 This program is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 021101301, USA.


Also add information on how to contact you by electronic and paper
mail.

If the program is interactive, make it output a short notice like
this when it starts in an interactive mode::

 Gnomovision version 69, Copyright (C) yyyy name of author
 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type
 'show w'.
 This is free software, and you are welcome to redistribute it under
 certain conditions; type 'show c' for details.


The hypothetical commands show w and show c should show the
appropriate parts of the General Public License. Of course, the
commands you use may be called something other than show w and show
c; they could even be mouseclicks or menu itemswhatever suits
your program.

You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the
program, if necessary. Here is a sample; alter the names::

 Yoyodyne, Inc., hereby disclaims all copyright interest in the
 program
 'Gnomovision' (which makes passes at compilers) written by James
 Hacker.

 signature of Ty Coon, 1 April 1989
 Ty Coon, President of Vice


This General Public License does not permit incorporating your
program into proprietary programs. If your program is a subroutine
library, you may consider it more useful to permit linking
proprietary applications with the library. If this is what you want
to do, use the GNU Library General Public License instead of this
License.

diff git a/doc/en/reference/history_and_license/conf.py b/doc/en/reference/history_and_license/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/history_and_license/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/history_and_license/index.rst b/doc/en/reference/history_and_license/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/history_and_license/index.rst
@@ 0,0 +1,396 @@
+History and License
+===================
+Sage was initially created by William Stein in 20042005, using
+Python, IPython, PARI, SWIG, Pyrex, NTL, and GMP. These programs
+are all open source and released under the GPL or a GPLcompatible
+license.
+
+All Sage releases are released under the GPL. All documentation
+is released under the GNU Free Documentation License.
+
+
+The GNU General Public License
+
+Version 2, June 1991
+
+::
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+ 51 Franklin Street, Fifth Floor, Boston, MA 021101301, USA
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+Preamble
+~~~~~~~~
+
+The licenses for most software are designed to take away your
+freedom to share and change it. By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change
+free softwareto make sure the software is free for all its users.
+This General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit
+to using it. (Some other Free Software Foundation software is
+covered by the GNU Library General Public License instead.) You can
+apply it to your programs, too.
+
+When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and
+charge for this service if you wish), that you receive source code
+or can get it if you want it, that you can change the software or
+use pieces of it in new free programs; and that you know you can do
+these things.
+
+To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the
+rights. These restrictions translate to certain responsibilities
+for you if you distribute copies of the software, or if you modify
+it.
+
+For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights
+that you have. You must make sure that they, too, receive or can
+get the source code. And you must show them these terms so they
+know their rights.
+
+We protect your rights with two steps: (1) copyright the software,
+and (2) offer you this license which gives you legal permission to
+copy, distribute and/or modify the software.
+
+Also, for each author's protection and ours, we want to make
+certain that everyone understands that there is no warranty for
+this free software. If the software is modified by someone else and
+passed on, we want its recipients to know that what they have is
+not the original, so that any problems introduced by others will
+not reflect on the original authors' reputations.
+
+Finally, any free program is threatened constantly by software
+patents. We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making
+the program proprietary. To prevent this, we have made it clear
+that any patent must be licensed for everyone's free use or not
+licensed at all.
+
+The precise terms and conditions for copying, distribution and
+modification follow.
+
+Terms and Conditions For Copying, Distribution and Modification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+
+0. This License applies to any program or other work which contains a
+ notice placed by the copyright holder saying it may be distributed
+ under the terms of this General Public License. The "Program",
+ below, refers to any such program or work, and a
+ "work based on the Program" means either the Program or any
+ derivative work under copyright law: that is to say, a work
+ containing the Program or a portion of it, either verbatim or with
+ modifications and/or translated into another language.
+ (Hereinafter, translation is included without limitation in the
+ term "modification".) Each licensee is addressed as "you".
+
+ Activities other than copying, distribution and modification are
+ not covered by this License; they are outside its scope. The act of
+ running the Program is not restricted, and the output from the
+ Program is covered only if its contents constitute a work based on
+ the Program (independent of having been made by running the
+ Program). Whether that is true depends on what the Program does.
+
+1. You may copy and distribute verbatim copies of the Program's source
+ code as you receive it, in any medium, provided that you
+ conspicuously and appropriately publish on each copy an appropriate
+ copyright notice and disclaimer of warranty; keep intact all the
+ notices that refer to this License and to the absence of any
+ warranty; and give any other recipients of the Program a copy of
+ this License along with the Program.
+
+ You may charge a fee for the physical act of transferring a copy,
+ and you may at your option offer warranty protection in exchange
+ for a fee.
+
+ You may modify your copy or copies of the Program or any portion of
+ it, thus forming a work based on the Program, and copy and
+ distribute such modifications or work under the terms of Section 1
+ above, provided that you also meet all of these conditions:
+
+
+ a. You must cause the modified files to carry prominent notices
+ stating that you changed the files and the date of any change.
+
+ b. You must cause any work that you distribute or publish, that in
+ whole or in part contains or is derived from the Program or any
+ part thereof, to be licensed as a whole at no charge to all third
+ parties under the terms of this License.
+
+ c. If the modified program normally reads commands interactively
+ when run, you must cause it, when started running for such
+ interactive use in the most ordinary way, to print or display an
+ announcement including an appropriate copyright notice and a notice
+ that there is no warranty (or else, saying that you provide a
+ warranty) and that users may redistribute the program under these
+ conditions, and telling the user how to view a copy of this
+ License. (Exception: if the Program itself is interactive but does
+ not normally print such an announcement, your work based on the
+ Program is not required to print an announcement.)
+
+
+2. These requirements apply to the modified work as a whole. If
+ identifiable sections of that work are not derived from the
+ Program, and can be reasonably considered independent and separate
+ works in themselves, then this License, and its terms, do not apply
+ to those sections when you distribute them as separate works. But
+ when you distribute the same sections as part of a whole which is a
+ work based on the Program, the distribution of the whole must be on
+ the terms of this License, whose permissions for other licensees
+ extend to the entire whole, and thus to each and every part
+ regardless of who wrote it.
+
+ Thus, it is not the intent of this section to claim rights or
+ contest your rights to work written entirely by you; rather, the
+ intent is to exercise the right to control the distribution of
+ derivative or collective works based on the Program.
+
+ In addition, mere aggregation of another work not based on the
+ Program with the Program (or with a work based on the Program) on a
+ volume of a storage or distribution medium does not bring the other
+ work under the scope of this License.
+
+3. You may copy and distribute the Program (or a work based on it,
+ under Section 2) in object code or executable form under the terms
+ of Sections 1 and 2 above provided that you also do one of the
+ following:
+
+
+ a. Accompany it with the complete corresponding machinereadable
+ source code, which must be distributed under the terms of Sections
+ 1 and 2 above on a medium customarily used for software
+ interchange; or,
+
+ b. Accompany it with a written offer, valid for at least three
+ years, to give any third party, for a charge no more than your cost
+ of physically performing source distribution, a complete
+ machinereadable copy of the corresponding source code, to be
+ distributed under the terms of Sections 1 and 2 above on a medium
+ customarily used for software interchange; or,
+
+ c. Accompany it with the information you received as to the offer
+ to distribute corresponding source code. (This alternative is
+ allowed only for noncommercial distribution and only if you
+ received the program in object code or executable form with such an
+ offer, in accord with Subsection b above.)
+
+
+ The source code for a work means the preferred form of the work for
+ making modifications to it. For an executable work, complete source
+ code means all the source code for all modules it contains, plus
+ any associated interface definition files, plus the scripts used to
+ control compilation and installation of the executable. However, as
+ a special exception, the source code distributed need not include
+ anything that is normally distributed (in either source or binary
+ form) with the major components (compiler, kernel, and so on) of
+ the operating system on which the executable runs, unless that
+ component itself accompanies the executable.
+
+ If distribution of executable or object code is made by offering
+ access to copy from a designated place, then offering equivalent
+ access to copy the source code from the same place counts as
+ distribution of the source code, even though third parties are not
+ compelled to copy the source along with the object code.
+
+4. You may not copy, modify, sublicense, or distribute the Program
+ except as expressly provided under this License. Any attempt
+ otherwise to copy, modify, sublicense or distribute the Program is
+ void, and will automatically terminate your rights under this
+ License. However, parties who have received copies, or rights, from
+ you under this License will not have their licenses terminated so
+ long as such parties remain in full compliance.
+
+5. You are not required to accept this License, since you have not
+ signed it. However, nothing else grants you permission to modify or
+ distribute the Program or its derivative works. These actions are
+ prohibited by law if you do not accept this License. Therefore, by
+ modifying or distributing the Program (or any work based on the
+ Program), you indicate your acceptance of this License to do so,
+ and all its terms and conditions for copying, distributing or
+ modifying the Program or works based on it.
+
+6. Each time you redistribute the Program (or any work based on the
+ Program), the recipient automatically receives a license from the
+ original licensor to copy, distribute or modify the Program subject
+ to these terms and conditions. You may not impose any further
+ restrictions on the recipients' exercise of the rights granted
+ herein. You are not responsible for enforcing compliance by third
+ parties to this License.
+
+7. If, as a consequence of a court judgment or allegation of patent
+ infringement or for any other reason (not limited to patent
+ issues), conditions are imposed on you (whether by court order,
+ agreement or otherwise) that contradict the conditions of this
+ License, they do not excuse you from the conditions of this
+ License. If you cannot distribute so as to satisfy simultaneously
+ your obligations under this License and any other pertinent
+ obligations, then as a consequence you may not distribute the
+ Program at all. For example, if a patent license would not permit
+ royaltyfree redistribution of the Program by all those who receive
+ copies directly or indirectly through you, then the only way you
+ could satisfy both it and this License would be to refrain entirely
+ from distribution of the Program.
+
+ If any portion of this section is held invalid or unenforceable
+ under any particular circumstance, the balance of the section is
+ intended to apply and the section as a whole is intended to apply
+ in other circumstances.
+
+ It is not the purpose of this section to induce you to infringe any
+ patents or other property right claims or to contest validity of
+ any such claims; this section has the sole purpose of protecting
+ the integrity of the free software distribution system, which is
+ implemented by public license practices. Many people have made
+ generous contributions to the wide range of software distributed
+ through that system in reliance on consistent application of that
+ system; it is up to the author/donor to decide if he or she is
+ willing to distribute software through any other system and a
+ licensee cannot impose that choice.
+
+ This section is intended to make thoroughly clear what is believed
+ to be a consequence of the rest of this License.
+
+8. If the distribution and/or use of the Program is restricted in
+ certain countries either by patents or by copyrighted interfaces,
+ the original copyright holder who places the Program under this
+ License may add an explicit geographical distribution limitation
+ excluding those countries, so that distribution is permitted only
+ in or among countries not thus excluded. In such case, this License
+ incorporates the limitation as if written in the body of this
+ License.
+
+9. The Free Software Foundation may publish revised and/or new
+ versions of the General Public License from time to time. Such new
+ versions will be similar in spirit to the present version, but may
+ differ in detail to address new problems or concerns.
+
+ Each version is given a distinguishing version number. If the
+ Program specifies a version number of this License which applies to
+ it and "any later version", you have the option of following the
+ terms and conditions either of that version or of any later version
+ published by the Free Software Foundation. If the Program does not
+ specify a version number of this License, you may choose any
+ version ever published by the Free Software Foundation.
+
+10. If you wish to incorporate parts of the Program into other free
+ programs whose distribution conditions are different, write to the
+ author to ask for permission. For software which is copyrighted by
+ the Free Software Foundation, write to the Free Software
+ Foundation; we sometimes make exceptions for this. Our decision
+ will be guided by the two goals of preserving the free status of
+ all derivatives of our free software and of promoting the sharing
+ and reuse of software generally.
+
+**NO WARRANTY**
+
+11. Because the program is licensed free of charge, there is no
+ warranty for the program, to the extent permitted by applicable
+ law. Except when otherwise stated in writing the copyright holders
+ and/or other parties provide the program "as is" without warranty
+ of any kind, either expressed or implied, including, but not
+ limited to, the implied warranties of merchantability and fitness
+ for a particular purpose. The entire risk as to the quality and
+ performance of the program is with you. Should the program prove
+ defective, you assume the cost of all necessary servicing, repair
+ or correction.
+
+12. In no event unless required by applicable law or agreed to in
+ writing will any copyright holder, or any other party who may
+ modify and/or redistribute the program as permitted above, be
+ liable to you for damages, including any general, special,
+ incidental or consequential damages arising out of the use or
+ inability to use the program (including but not limited to loss of
+ data or data being rendered inaccurate or losses sustained by you
+ or third parties or a failure of the program to operate with any
+ other programs), even if such holder or other party has been
+ advised of the possibility of such damages.
+
+
+**End of Terms and Conditions**
+
+Appendix: How to Apply These Terms to Your New Programs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make
+it free software which everyone can redistribute and change under
+these terms.
+
+To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at
+least the "copyright" line and a pointer to where the full notice
+is found.
+
+::
+
+ one line to give the program's name and a brief idea of what it
+ does.
+ Copyright (C) yyyy name of author
+
+ This program is free software; you can redistribute it and/or
+ modify it under the terms of the GNU General Public License as
+ published by the Free Software Foundation; either version 2 of the
+ License, or (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 021101301, USA.
+
+
+Also add information on how to contact you by electronic and paper
+mail.
+
+If the program is interactive, make it output a short notice like
+this when it starts in an interactive mode::
+
+ Gnomovision version 69, Copyright (C) yyyy name of author
+ Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type
+ 'show w'.
+ This is free software, and you are welcome to redistribute it under
+ certain conditions; type 'show c' for details.
+
+
+The hypothetical commands show w and show c should show the
+appropriate parts of the General Public License. Of course, the
+commands you use may be called something other than show w and show
+c; they could even be mouseclicks or menu itemswhatever suits
+your program.
+
+You should also get your employer (if you work as a programmer) or
+your school, if any, to sign a "copyright disclaimer" for the
+program, if necessary. Here is a sample; alter the names::
+
+ Yoyodyne, Inc., hereby disclaims all copyright interest in the
+ program
+ 'Gnomovision' (which makes passes at compilers) written by James
+ Hacker.
+
+ signature of Ty Coon, 1 April 1989
+ Ty Coon, President of Vice
+
+
+This General Public License does not permit incorporating your
+program into proprietary programs. If your program is a subroutine
+library, you may consider it more useful to permit linking
+proprietary applications with the library. If this is what you want
+to do, use the GNU Library General Public License instead of this
+License.
+
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/homology.rst b/doc/en/reference/homology.rst
deleted file mode 100644
 a/doc/en/reference/homology.rst
+++ /dev/null
@@ 1,12 +0,0 @@
Homology of Simplicial Complexes
================================

Sage includes support for constructing simplicial complexes and
computing their homology.

.. toctree::
 :maxdepth: 2

 sage/homology/simplicial_complex
 sage/homology/chain_complex
 sage/homology/examples
diff git a/doc/en/reference/homology/conf.py b/doc/en/reference/homology/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/homology/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/homology/index.rst b/doc/en/reference/homology/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/homology/index.rst
@@ 0,0 +1,15 @@
+Homology of Simplicial Complexes
+================================
+
+Sage includes support for constructing simplicial complexes and
+computing their homology.
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/homology/simplicial_complex
+ sage/homology/chain_complex
+ sage/homology/examples
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/index.rst b/doc/en/reference/index.rst
 a/doc/en/reference/index.rst
+++ b/doc/en/reference/index.rst
@@ 1,98 +1,87 @@
.. Sage Reference Manual documentation master file, created by sphinxquickstart on Sun Sep 28 03:34:37 2008.
 You can adapt this file completely to your liking, but it should at least
 contain the root `toctree` directive.
+Welcome to Sage's Reference Manual!
+===================================
.. _ch:intro:
+This is the manual for the Sage mathematical software system. Sage is
+free open source math software that supports research and teaching in
+algebra, geometry, number theory, cryptography, and related
+areas. Both the Sage development model and the technology in Sage
+itself are distinguished by an extremely strong emphasis on openness,
+community, cooperation, and collaboration: we are building the car,
+not reinventing the wheel.
Welcome to Sage's Reference Manual!
=================================================
+This reference manual contains many examples that illustrate the usage
+of Sage. The examples are all tested with each release of Sage, and
+should produce exactly the same output as in this manual, except for
+line breaks.
This is the manual for the Sage mathematical software system. Sage
is free open source math software that supports research and
teaching in algebra, geometry, number theory, cryptography, and
related areas. Both the Sage development model and the technology
in Sage itself are distinguished by an extremely strong emphasis on
openness, community, cooperation, and collaboration: we are
building the car, not reinventing the wheel.
+The Sage command line is briefly described in `The Sage Command Line
+`_, which lists the command line options. For more
+details about the command line, see the Sage tutorial.
This reference manual contains many examples that illustrate the
usage of Sage. The examples are all tested with each release of
Sage, and should produce exactly the same output as in this manual,
except for line breaks.
+The Sage graphical user interface is described in `The Sage Notebook
+`_. This graphical user interface is unusual in
+that it operates via your web browser. It provides you with Sage
+worksheets that you can edit and evaluate, which contain scalable
+typeset mathematics and beautiful antialiased images.
The Sage command line is briefly described in :ref:`ch:cmdline`, which
lists the command line options. For more details about the command
line, see the Sage tutorial.

The Sage graphical user interface is described in
:ref:`ch:notebook`. This graphical user interface is unusual in that
it operates via your web browser. It provides you with Sage worksheets
that you can edit and evaluate, which contain scalable typeset
mathematics and beautiful antialiased images.

This work is licensed under a `Creative Commons AttributionShare Alike
3.0 License`__.
+This work is licensed under a `Creative Commons AttributionShare
+Alike 3.0 License`__.
__ http://creativecommons.org/licenses/bysa/3.0/
Enjoy Sage!
.. toctree::
 :maxdepth: 2
 cmd
 notebook
 calculus
 plotting
 plot3d
 games
 graphs
 constants
 functions
 structure
 coercion
 misc
 databases
 interfaces
 libs
 networking
 cryptography
 combinat/index
 numerical
 probability
 categories
 monoids
 groups
 rings
 rings_standard
 rings_numerical
 number_fields
 padics
 polynomial_rings
 power_series
 algebras
 quat_algebras
 matrices
 modules
 geometry
 homology
 lfunctions
 schemes
 plane_curves
 coding
 arithgroup
 hecke
 modsym
 modfrm
 modabvar
 modmisc
+Table of Contents
+=================
 history_and_license
+ * `The Sage Command Line `_
+ * `The Sage Notebook `_
+ * `Symbolic Calculus `_
+ * `2D Graphics `_
+ * `3D Graphics `_
+ * `Games `_
+ * `Graph Theory `_
+ * `Constants `_
+ * `Functions `_
+ * `Basic Structures `_
+ * `Coercion `_
+ * `Miscellaneous `_
+ * `Databases `_
+ * `Interpreter Interfaces `_
+ * `C/C++ Library Interfaces `_
+ * `Networking and Grid Computing `_
+ * `Cryptography `_
+ * `Combinatorics `_
+ * `Numerical Optimization `_
+ * `Probability `_
+ * `Category Theory and Categories `_
+ * `Monoids `_
+ * `Groups `_
+ * `General Rings, Ideals, and Morphisms `_
+ * `Standard Commutative Rings `_
+ * `Fixed and Arbitrary Precision Numerical Fields `_
+ * `Algebraic Number Fields `_
+ * `pAdics `_
+ * `Polynomial Rings `_
+ * `Power Series Rings `_
+ * `Algebras `_
+ * `Quaternion Algebras `_
+ * `Matrices and Spaces of Matrices `_
+ * `Modules `_
+ * `Combinatorial Geometry `_
+ * `Homology of Simplicial Complexes `_
+ * `LFunctions `_
+ * `Schemes `_
+ * `Elliptic, Plane, and Hyperelliptic Curves `_
+ * `Coding Theory `_
+ * `Arithmetic Subgroups of $${\rm SL}_2(\ZZ)$$ `_
+ * `General Hecke Algebras and Hecke Modules `_
+ * `Modular Symbols `_
+ * `Modular Forms `_
+ * `Modular Abelian Varieties `_
+ * `Miscellaneous ModularFormRelated Modules `_
+ * `History and License `_
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

+.. include:: footer.txt
diff git a/doc/en/reference/interfaces.rst b/doc/en/reference/interfaces.rst
deleted file mode 100644
 a/doc/en/reference/interfaces.rst
+++ /dev/null
@@ 1,78 +0,0 @@
.. _ch:interfaces:

Interpreter Interfaces
======================

Sage provides a unified interface to the best computational
software. This is accomplished using both Clibraries (see
:ref:`ch:libraries`) and interpreter interfaces, which are
implemented using pseudotty's, system files, etc. This chapter is
about these interpreter interfaces.

.. note::

 Each interface requires that the corresponding software is
 installed on your computer. Sage includes GAP, PARI, Singular, and
 Maxima, but does not include Octave (very easy to install), MAGMA
 (nonfree), Maple (nonfree), or Mathematica (nonfree).


 There is overhead associated with each call to one of these
 systems. For example, computing ``2+2`` thousands of times using
 the GAP interface will be slower than doing it directly in
 Sage. In contrast, the Clibrary interfaces of :ref:`ch:libraries`
 incur less overhead.


In addition to the commands described for each of the interfaces
below, you can also type e.g., ``%gap``,
``%magma``, etc., to directly interact with a given
interface in its state. Alternatively, if ``X`` is an
interface object, typing ``X.interact()`` allows you to
interact with it. This is completely different than
``X.console()`` which starts a complete new copy of
whatever program ``X`` interacts with. Note that the
input for ``X.interact()`` is handled by Sage, so the
history buffer is the same as for Sage, tab completion is as for
Sage (unfortunately!), and input that spans multiple lines must be
indicated using a backslash at the end of each line. You can pull
data into an interactive session with ``X`` using
``sage(expression)``.

The console and interact methods of an interface do very different
things. For example, using gap as an example:


#. ``gap.console()``: You are completely using another
 program, e.g., gap/magma/gp Here Sage is serving as nothing more
 than a convenient program launcher, similar to bash.

#. ``gap.interact()``: This is a convenient way to
 interact with a running gap instance that may be "full of" Sage
 objects. You can import Sage objects into this gap (even from the
 interactive interface), etc.


The console function is very useful on occasion, since you get the
exact actual program available (especially useful for tab completion
and testing to make sure nothing funny is going on).

.. toctree::
 :maxdepth: 2

 sage/interfaces/expect
 sage/interfaces/axiom
 sage/interfaces/gap
 sage/interfaces/gp
 sage/interfaces/gnuplot
 sage/interfaces/kash
 sage/interfaces/magma
 sage/interfaces/maple
 sage/interfaces/matlab
 sage/interfaces/maxima
 sage/interfaces/mathematica
 sage/interfaces/mwrank
 sage/interfaces/octave
 sage/interfaces/sage0
 sage/interfaces/singular
 sage/interfaces/tachyon
diff git a/doc/en/reference/interfaces/conf.py b/doc/en/reference/interfaces/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/interfaces/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/interfaces/index.rst b/doc/en/reference/interfaces/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/interfaces/index.rst
@@ 0,0 +1,79 @@
+Interpreter Interfaces
+======================
+
+Sage provides a unified interface to the best computational
+software. This is accomplished using both Clibraries (see
+:ref:`ch:libraries`) and interpreter interfaces, which are
+implemented using pseudotty's, system files, etc. This chapter is
+about these interpreter interfaces.
+
+.. note::
+
+ Each interface requires that the corresponding software is
+ installed on your computer. Sage includes GAP, PARI, Singular, and
+ Maxima, but does not include Octave (very easy to install), MAGMA
+ (nonfree), Maple (nonfree), or Mathematica (nonfree).
+
+
+ There is overhead associated with each call to one of these
+ systems. For example, computing ``2+2`` thousands of times using
+ the GAP interface will be slower than doing it directly in
+ Sage. In contrast, the Clibrary interfaces of :ref:`ch:libraries`
+ incur less overhead.
+
+
+In addition to the commands described for each of the interfaces
+below, you can also type e.g., ``%gap``,
+``%magma``, etc., to directly interact with a given
+interface in its state. Alternatively, if ``X`` is an
+interface object, typing ``X.interact()`` allows you to
+interact with it. This is completely different than
+``X.console()`` which starts a complete new copy of
+whatever program ``X`` interacts with. Note that the
+input for ``X.interact()`` is handled by Sage, so the
+history buffer is the same as for Sage, tab completion is as for
+Sage (unfortunately!), and input that spans multiple lines must be
+indicated using a backslash at the end of each line. You can pull
+data into an interactive session with ``X`` using
+``sage(expression)``.
+
+The console and interact methods of an interface do very different
+things. For example, using gap as an example:
+
+
+#. ``gap.console()``: You are completely using another
+ program, e.g., gap/magma/gp Here Sage is serving as nothing more
+ than a convenient program launcher, similar to bash.
+
+#. ``gap.interact()``: This is a convenient way to
+ interact with a running gap instance that may be "full of" Sage
+ objects. You can import Sage objects into this gap (even from the
+ interactive interface), etc.
+
+
+The console function is very useful on occasion, since you get the
+exact actual program available (especially useful for tab completion
+and testing to make sure nothing funny is going on).
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/interfaces/expect
+ sage/interfaces/axiom
+ sage/interfaces/gap
+ sage/interfaces/gp
+ sage/interfaces/gnuplot
+ sage/interfaces/kash
+ sage/interfaces/magma
+ sage/interfaces/maple
+ sage/interfaces/matlab
+ sage/interfaces/maxima
+ sage/interfaces/mathematica
+ sage/interfaces/mwrank
+ sage/interfaces/octave
+ sage/interfaces/sage0
+ sage/interfaces/singular
+ sage/interfaces/tachyon
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/lfunctions.rst b/doc/en/reference/lfunctions.rst
deleted file mode 100644
 a/doc/en/reference/lfunctions.rst
+++ /dev/null
@@ 1,12 +0,0 @@
LFunctions
===========

Sage includes several standard open source packages for computing
with :math:`L`functions.

.. toctree::
 :maxdepth: 2

 sage/lfunctions/lcalc
 sage/lfunctions/sympow
 sage/lfunctions/dokchitser
\ No newline at end of file
diff git a/doc/en/reference/lfunctions/conf.py b/doc/en/reference/lfunctions/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/lfunctions/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/lfunctions/index.rst b/doc/en/reference/lfunctions/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/lfunctions/index.rst
@@ 0,0 +1,14 @@
+LFunctions
+===========
+
+Sage includes several standard open source packages for computing
+with :math:`L`functions.
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/lfunctions/lcalc
+ sage/lfunctions/sympow
+ sage/lfunctions/dokchitser
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/libs.rst b/doc/en/reference/libs.rst
deleted file mode 100644
 a/doc/en/reference/libs.rst
+++ /dev/null
@@ 1,30 +0,0 @@
.. _ch:libraries:

C/C++ Library Interfaces
========================

An underlying philosophy in the development of Sage is that it
should provide unified librarylevel access to the some of the best
GPL'd C/C++ libraries. Currently Sage provides some access to
MWRANK, NTL, PARI, and Hanke, each of which are included with
Sage.

The interfaces are implemented via shared libraries and data is
moved between systems purely in memory. In particular, there is no
interprocess interpreter parsing (e.g., ``expect``),
since everything is linked together and run as a single process.
This is much more robust and efficient than using
``expect``.

Each of these interfaces is used by other parts of Sage. For
example, mwrank is used by the elliptic curves module to compute
ranks of elliptic curves, and PARI is used for computation of class
groups. It is thus probably not necessary for a casual user of Sage
to be aware of the modules described in this chapter.

.. toctree::
 :maxdepth: 2

 sage/libs/pari/gen
 sage/libs/ntl/all
 sage/libs/mwrank/all
diff git a/doc/en/reference/libs/conf.py b/doc/en/reference/libs/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/libs/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/libs/index.rst b/doc/en/reference/libs/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/libs/index.rst
@@ 0,0 +1,31 @@
+C/C++ Library Interfaces
+========================
+
+An underlying philosophy in the development of Sage is that it
+should provide unified librarylevel access to the some of the best
+GPL'd C/C++ libraries. Currently Sage provides some access to
+MWRANK, NTL, PARI, and Hanke, each of which are included with
+Sage.
+
+The interfaces are implemented via shared libraries and data is
+moved between systems purely in memory. In particular, there is no
+interprocess interpreter parsing (e.g., ``expect``),
+since everything is linked together and run as a single process.
+This is much more robust and efficient than using
+``expect``.
+
+Each of these interfaces is used by other parts of Sage. For
+example, mwrank is used by the elliptic curves module to compute
+ranks of elliptic curves, and PARI is used for computation of class
+groups. It is thus probably not necessary for a casual user of Sage
+to be aware of the modules described in this chapter.
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/libs/pari/gen
+ sage/libs/ntl/all
+ sage/libs/mwrank/all
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/matrices.rst b/doc/en/reference/matrices.rst
deleted file mode 100644
 a/doc/en/reference/matrices.rst
+++ /dev/null
@@ 1,82 +0,0 @@
.. _ch:matrices:

Matrices and Spaces of Matrices
===============================

Sage provides native support for working with matrices over any
commutative or noncommutative ring. The parent object for a matrix
is a matrix space ``MatrixSpace(R, n, m)`` of all
:math:`n\times
m` matrices over a ring :math:`R`.

To create a matrix, either use the ``matrix(...)``
function or create a matrix space using the
``MatrixSpace`` command and coerce an object into it.

Matrices also act on row vectors, which you create using the
``vector(...)`` command or by making a
``VectorSpace`` and coercing lists into it. The natural
action of matrices on row vectors is from the right. Sage currently
does not have a column vector class (on which matrices would act
from the left), but this is planned.

In addition to native Sage matrices, Sage also includes the
following additional ways to compute with matrices:


 Several math software systems included with Sage have their own
 native matrix support, which can be used from Sage. E.g., PARI,
 GAP, Maxima, and Singular all have a notion of matrices.

 The GSL Clibrary is included with Sage, and can be used via
 Cython.

 The ``scipy`` module provides support for
 *sparse* numerical linear algebra, among many other things.

 The ``numpy`` module, which you load by typing
 ``import numpy`` is included standard with Sage. It
 contains a very sophisticated and well developed array class, plus
 optimized support for *numerical linear algebra*. Sage's matrices
 over RDF and CDF (native floatingpoint real and complex numbers)
 use numpy.


.. toctree::
 :maxdepth: 2


 sage/matrix/matrix_space

 sage/matrix/constructor

 sage/matrix/docs

 sage/matrix/matrix

 sage/matrix/matrix0

 sage/matrix/matrix1

 sage/matrix/matrix2

 sage/matrix/strassen

 sage/matrix/berlekamp_massey

 sage/matrix/matrix_dense
 sage/matrix/matrix_sparse

 sage/matrix/matrix_generic_dense
 sage/matrix/matrix_generic_sparse

 sage/matrix/matrix_modn_dense
 sage/matrix/matrix_modn_sparse

 sage/matrix/matrix_integer_dense

 sage/matrix/matrix_rational_dense

 sage/matrix/matrix_real_double_dense

 sage/matrix/matrix_complex_double_dense
diff git a/doc/en/reference/matrices/conf.py b/doc/en/reference/matrices/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/matrices/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/matrices/index.rst b/doc/en/reference/matrices/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/matrices/index.rst
@@ 0,0 +1,83 @@
+Matrices and Spaces of Matrices
+===============================
+
+Sage provides native support for working with matrices over any
+commutative or noncommutative ring. The parent object for a matrix
+is a matrix space ``MatrixSpace(R, n, m)`` of all
+:math:`n\times
+m` matrices over a ring :math:`R`.
+
+To create a matrix, either use the ``matrix(...)``
+function or create a matrix space using the
+``MatrixSpace`` command and coerce an object into it.
+
+Matrices also act on row vectors, which you create using the
+``vector(...)`` command or by making a
+``VectorSpace`` and coercing lists into it. The natural
+action of matrices on row vectors is from the right. Sage currently
+does not have a column vector class (on which matrices would act
+from the left), but this is planned.
+
+In addition to native Sage matrices, Sage also includes the
+following additional ways to compute with matrices:
+
+
+ Several math software systems included with Sage have their own
+ native matrix support, which can be used from Sage. E.g., PARI,
+ GAP, Maxima, and Singular all have a notion of matrices.
+
+ The GSL Clibrary is included with Sage, and can be used via
+ Cython.
+
+ The ``scipy`` module provides support for
+ *sparse* numerical linear algebra, among many other things.
+
+ The ``numpy`` module, which you load by typing
+ ``import numpy`` is included standard with Sage. It
+ contains a very sophisticated and well developed array class, plus
+ optimized support for *numerical linear algebra*. Sage's matrices
+ over RDF and CDF (native floatingpoint real and complex numbers)
+ use numpy.
+
+
+.. toctree::
+ :maxdepth: 2
+
+
+ sage/matrix/matrix_space
+
+ sage/matrix/constructor
+
+ sage/matrix/docs
+
+ sage/matrix/matrix
+
+ sage/matrix/matrix0
+
+ sage/matrix/matrix1
+
+ sage/matrix/matrix2
+
+ sage/matrix/strassen
+
+ sage/matrix/berlekamp_massey
+
+ sage/matrix/matrix_dense
+ sage/matrix/matrix_sparse
+
+ sage/matrix/matrix_generic_dense
+ sage/matrix/matrix_generic_sparse
+
+ sage/matrix/matrix_modn_dense
+ sage/matrix/matrix_modn_sparse
+
+ sage/matrix/matrix_integer_dense
+
+ sage/matrix/matrix_rational_dense
+
+ sage/matrix/matrix_real_double_dense
+
+ sage/matrix/matrix_complex_double_dense
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/misc.rst b/doc/en/reference/misc.rst
deleted file mode 100644
 a/doc/en/reference/misc.rst
+++ /dev/null
@@ 1,29 +0,0 @@
.. _ch:misc:

Miscellaneous
=============

.. toctree::
 :maxdepth: 2

 sage/misc/abstract_method
 sage/misc/misc
 sage/misc/bitset
 sage/misc/constant_function
 sage/misc/package
 sage/misc/explain_pickle
 sage/misc/getusage
 sage/misc/mrange
 sage/misc/dist
 sage/misc/hg
 sage/misc/functional
 sage/misc/latex
 sage/misc/latex_macros
 sage/misc/lazy_attribute
 sage/misc/log
 sage/misc/persist
 sage/misc/func_persist
 sage/misc/sage_eval
 sage/misc/random_testing
 sage/misc/sagedoc
 sage/rings/arith
diff git a/doc/en/reference/misc/conf.py b/doc/en/reference/misc/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/misc/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/misc/index.rst b/doc/en/reference/misc/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/misc/index.rst
@@ 0,0 +1,30 @@
+Miscellaneous
+=============
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/misc/abstract_method
+ sage/misc/misc
+ sage/misc/bitset
+ sage/misc/constant_function
+ sage/misc/package
+ sage/misc/explain_pickle
+ sage/misc/getusage
+ sage/misc/mrange
+ sage/misc/dist
+ sage/misc/hg
+ sage/misc/functional
+ sage/misc/latex
+ sage/misc/latex_macros
+ sage/misc/lazy_attribute
+ sage/misc/log
+ sage/misc/persist
+ sage/misc/func_persist
+ sage/misc/sage_eval
+ sage/misc/random_testing
+ sage/misc/sagedoc
+ sage/rings/arith
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/modabvar.rst b/doc/en/reference/modabvar.rst
deleted file mode 100644
 a/doc/en/reference/modabvar.rst
+++ /dev/null
@@ 1,19 +0,0 @@
.. _ch:modabvar:

Modular Abelian Varieties
=========================

.. toctree::
 :maxdepth: 2

 sage/modular/abvar/constructor
 sage/modular/abvar/abvar
 sage/modular/abvar/abvar_ambient_jacobian
 sage/modular/abvar/finite_subgroup
 sage/modular/abvar/torsion_subgroup
 sage/modular/abvar/cuspidal_subgroup
 sage/modular/abvar/homology
 sage/modular/abvar/homspace
 sage/modular/abvar/morphism
 sage/modular/abvar/abvar_newform
 sage/modular/abvar/lseries
diff git a/doc/en/reference/modabvar/conf.py b/doc/en/reference/modabvar/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/modabvar/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/modabvar/index.rst b/doc/en/reference/modabvar/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/modabvar/index.rst
@@ 0,0 +1,20 @@
+Modular Abelian Varieties
+=========================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/modular/abvar/constructor
+ sage/modular/abvar/abvar
+ sage/modular/abvar/abvar_ambient_jacobian
+ sage/modular/abvar/finite_subgroup
+ sage/modular/abvar/torsion_subgroup
+ sage/modular/abvar/cuspidal_subgroup
+ sage/modular/abvar/homology
+ sage/modular/abvar/homspace
+ sage/modular/abvar/morphism
+ sage/modular/abvar/abvar_newform
+ sage/modular/abvar/lseries
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/modfrm.rst b/doc/en/reference/modfrm.rst
deleted file mode 100644
 a/doc/en/reference/modfrm.rst
+++ /dev/null
@@ 1,27 +0,0 @@
.. _ch:modular:

Modular Forms
=============

.. toctree::
 :maxdepth: 2

 sage/modular/modform/constructor
 sage/modular/modform/space
 sage/modular/modform/ambient
 sage/modular/modform/ambient_eps
 sage/modular/modform/ambient_g0
 sage/modular/modform/ambient_g1
 sage/modular/modform/ambient_R
 sage/modular/modform/submodule
 sage/modular/modform/cuspidal_submodule
 sage/modular/modform/eisenstein_submodule
 sage/modular/modform/eis_series
 sage/modular/modform/element
 sage/modular/modform/hecke_operator_on_qexp
 sage/modular/modform/numerical
 sage/modular/modform/vm_basis
 sage/modular/modform/ambient
 sage/modular/modform/half_integral
 sage/modular/modform/find_generators

diff git a/doc/en/reference/modfrm/conf.py b/doc/en/reference/modfrm/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/modfrm/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/modfrm/index.rst b/doc/en/reference/modfrm/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/modfrm/index.rst
@@ 0,0 +1,28 @@
+Modular Forms
+=============
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/modular/modform/constructor
+ sage/modular/modform/space
+ sage/modular/modform/ambient
+ sage/modular/modform/ambient_eps
+ sage/modular/modform/ambient_g0
+ sage/modular/modform/ambient_g1
+ sage/modular/modform/ambient_R
+ sage/modular/modform/submodule
+ sage/modular/modform/cuspidal_submodule
+ sage/modular/modform/eisenstein_submodule
+ sage/modular/modform/eis_series
+ sage/modular/modform/element
+ sage/modular/modform/hecke_operator_on_qexp
+ sage/modular/modform/numerical
+ sage/modular/modform/vm_basis
+ sage/modular/modform/ambient
+ sage/modular/modform/half_integral
+ sage/modular/modform/find_generators
+
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/modmisc.rst b/doc/en/reference/modmisc.rst
deleted file mode 100644
 a/doc/en/reference/modmisc.rst
+++ /dev/null
@@ 1,18 +0,0 @@
.. _ch:modmisc:

Miscellaneous ModularFormRelated Modules
==========================================

.. toctree::
 :maxdepth: 2

 sage/modular/dirichlet
 sage/modular/cusps
 sage/modular/dims
 sage/modular/buzzard

 sage/modular/etaproducts
 sage/modular/overconvergent/weightspace
 sage/modular/overconvergent/genus0
 sage/modular/ssmod/ssmod
 sage/modular/quatalg/brandt
diff git a/doc/en/reference/modmisc/conf.py b/doc/en/reference/modmisc/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/modmisc/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/modmisc/index.rst b/doc/en/reference/modmisc/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/modmisc/index.rst
@@ 0,0 +1,19 @@
+Miscellaneous ModularFormRelated Modules
+==========================================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/modular/dirichlet
+ sage/modular/cusps
+ sage/modular/dims
+ sage/modular/buzzard
+
+ sage/modular/etaproducts
+ sage/modular/overconvergent/weightspace
+ sage/modular/overconvergent/genus0
+ sage/modular/ssmod/ssmod
+ sage/modular/quatalg/brandt
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/modsym.rst b/doc/en/reference/modsym.rst
deleted file mode 100644
 a/doc/en/reference/modsym.rst
+++ /dev/null
@@ 1,30 +0,0 @@
.. _ch:modsym:

Modular Symbols
===============

.. toctree::
 :maxdepth: 2

 sage/modular/modsym/modsym

 sage/modular/modsym/space
 sage/modular/modsym/ambient
 sage/modular/modsym/subspace

 sage/modular/modsym/element
 sage/modular/modsym/modular_symbols
 sage/modular/modsym/manin_symbols

 sage/modular/modsym/boundary

 sage/modular/modsym/heilbronn

 sage/modular/modsym/p1list
 sage/modular/modsym/g1list
 sage/modular/modsym/ghlist

 sage/modular/modsym/relation_matrix

 sage/modular/modsym/p1list_nf

diff git a/doc/en/reference/modsym/conf.py b/doc/en/reference/modsym/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/modsym/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/modsym/index.rst b/doc/en/reference/modsym/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/modsym/index.rst
@@ 0,0 +1,31 @@
+Modular Symbols
+===============
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/modular/modsym/modsym
+
+ sage/modular/modsym/space
+ sage/modular/modsym/ambient
+ sage/modular/modsym/subspace
+
+ sage/modular/modsym/element
+ sage/modular/modsym/modular_symbols
+ sage/modular/modsym/manin_symbols
+
+ sage/modular/modsym/boundary
+
+ sage/modular/modsym/heilbronn
+
+ sage/modular/modsym/p1list
+ sage/modular/modsym/g1list
+ sage/modular/modsym/ghlist
+
+ sage/modular/modsym/relation_matrix
+
+ sage/modular/modsym/p1list_nf
+
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/modules.rst b/doc/en/reference/modules.rst
deleted file mode 100644
 a/doc/en/reference/modules.rst
+++ /dev/null
@@ 1,23 +0,0 @@
.. _ch:modules:

Modules
=======

.. toctree::
 :maxdepth: 2

 sage/modules/module
 sage/modules/free_module
 sage/modules/free_module_element

 sage/modules/complex_double_vector
 sage/modules/real_double_vector

 sage/modules/free_module_homspace
 sage/modules/free_module_morphism

 sage/modules/matrix_morphism

 sage/modules/fg_pid/fgp_module
 sage/modules/fg_pid/fgp_element
 sage/modules/fg_pid/fgp_morphism
diff git a/doc/en/reference/modules/conf.py b/doc/en/reference/modules/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/modules/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/modules/index.rst b/doc/en/reference/modules/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/modules/index.rst
@@ 0,0 +1,24 @@
+Modules
+=======
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/modules/module
+ sage/modules/free_module
+ sage/modules/free_module_element
+
+ sage/modules/complex_double_vector
+ sage/modules/real_double_vector
+
+ sage/modules/free_module_homspace
+ sage/modules/free_module_morphism
+
+ sage/modules/matrix_morphism
+
+ sage/modules/fg_pid/fgp_module
+ sage/modules/fg_pid/fgp_element
+ sage/modules/fg_pid/fgp_morphism
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/monoids.rst b/doc/en/reference/monoids.rst
deleted file mode 100644
 a/doc/en/reference/monoids.rst
+++ /dev/null
@@ 1,17 +0,0 @@
.. _ch:monoids:

Monoids
=======

Sage supports free monoids and free abelian monoids in any
finite number of indeterminates.

.. toctree::
 :maxdepth: 2

 sage/monoids/free_monoid
 sage/monoids/free_monoid_element
 sage/monoids/free_abelian_monoid
 sage/monoids/free_abelian_monoid_element
 sage/monoids/string_monoid_element
 sage/monoids/string_monoid
diff git a/doc/en/reference/monoids/conf.py b/doc/en/reference/monoids/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/monoids/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/monoids/index.rst b/doc/en/reference/monoids/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/monoids/index.rst
@@ 0,0 +1,18 @@
+Monoids
+=======
+
+Sage supports free monoids and free abelian monoids in any
+finite number of indeterminates.
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/monoids/free_monoid
+ sage/monoids/free_monoid_element
+ sage/monoids/free_abelian_monoid
+ sage/monoids/free_abelian_monoid_element
+ sage/monoids/string_monoid_element
+ sage/monoids/string_monoid
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/networking.rst b/doc/en/reference/networking.rst
deleted file mode 100644
 a/doc/en/reference/networking.rst
+++ /dev/null
@@ 1,25 +0,0 @@
Networking and Grid Computing
=============================

Sage includes custom highlyintegrated support for coarse grain
distributed (or "grid") computing. See the chapter below on
``dsage``.

Sage includes the Moin Moin Wiki by default, which
"is an advanced, easy to use and extensible WikiEngine with a large
community of users. Said in a few words, it is about collaboration on
easily editable web pages."

The Twisted, an eventdriven networking framework written in
Python, is a networking library that is included with Sage. It is
robust, mature, fast, and offers a vast range of networking
functionality.

The Sage Notebook (see Chapter :ref:`ch:notebook`) is another
networking application included with Sage.

.. toctree::
 :maxdepth: 2

 sage/server/wiki/moin
 dsage
diff git a/doc/en/reference/networking/conf.py b/doc/en/reference/networking/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/networking/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/networking/index.rst b/doc/en/reference/networking/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/networking/index.rst
@@ 0,0 +1,28 @@
+Networking and Grid Computing
+=============================
+
+Sage includes custom highlyintegrated support for coarse grain
+distributed (or "grid") computing. See the chapter below on
+``dsage``.
+
+Sage includes the Moin Moin Wiki by default, which
+"is an advanced, easy to use and extensible WikiEngine with a large
+community of users. Said in a few words, it is about collaboration on
+easily editable web pages."
+
+The Twisted, an eventdriven networking framework written in
+Python, is a networking library that is included with Sage. It is
+robust, mature, fast, and offers a vast range of networking
+functionality.
+
+The Sage Notebook (see Chapter :ref:`ch:notebook`) is another
+networking application included with Sage.
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/server/wiki/moin
+ dsage
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/notebook.rst b/doc/en/reference/notebook.rst
deleted file mode 100644
 a/doc/en/reference/notebook.rst
+++ /dev/null
@@ 1,58 +0,0 @@
.. _ch:notebook:

The Sage Notebook
=================

.. toctree::
 :maxdepth: 2

 sagenb/notebook/config
 sagenb/notebook/interact
 sagenb/notebook/cell
 sagenb/notebook/worksheet
 sagenb/notebook/notebook
 sagenb/notebook/js
 sagenb/notebook/css
 sagenb/notebook/template

Servers


.. toctree::
 :maxdepth: 2

 sagenb/notebook/twist
 sagenb/simple/twist
 sage/server/trac/trac
 sagenb/notebook/challenge

Miscellaneous


.. toctree::
 :maxdepth: 2

 sagenb/misc/misc
 sagenb/misc/support
 sagenb/misc/introspect
 sagenb/misc/sageinspect
 sagenb/misc/sphinxify
 sagenb/notebook/docHTMLProcessor

Storage


.. toctree::
 :maxdepth: 2

 sagenb/storage/abstract_storage
 sagenb/storage/filesystem_storage

.. Commented out, for now.

 Interfaces
 

 SKIP sagenb/interfaces/worksheet_process
 SKIP sagenb/interfaces/reference
 SKIP sagenb/interfaces/expect
diff git a/doc/en/reference/notebook/conf.py b/doc/en/reference/notebook/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/notebook/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/notebook/index.rst b/doc/en/reference/notebook/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/notebook/index.rst
@@ 0,0 +1,59 @@
+The Sage Notebook
+=================
+
+.. toctree::
+ :maxdepth: 2
+
+ sagenb/notebook/config
+ sagenb/notebook/interact
+ sagenb/notebook/cell
+ sagenb/notebook/worksheet
+ sagenb/notebook/notebook
+ sagenb/notebook/js
+ sagenb/notebook/css
+ sagenb/notebook/template
+
+Servers
+
+
+.. toctree::
+ :maxdepth: 2
+
+ sagenb/notebook/twist
+ sagenb/simple/twist
+ sage/server/trac/trac
+ sagenb/notebook/challenge
+
+Miscellaneous
+
+
+.. toctree::
+ :maxdepth: 2
+
+ sagenb/misc/misc
+ sagenb/misc/support
+ sagenb/misc/introspect
+ sagenb/misc/sageinspect
+ sagenb/misc/sphinxify
+ sagenb/notebook/docHTMLProcessor
+
+Storage
+
+
+.. toctree::
+ :maxdepth: 2
+
+ sagenb/storage/abstract_storage
+ sagenb/storage/filesystem_storage
+
+.. Commented out, for now.
+
+ Interfaces
+ 
+
+ SKIP sagenb/interfaces/worksheet_process
+ SKIP sagenb/interfaces/reference
+ SKIP sagenb/interfaces/expect
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/number_fields.rst b/doc/en/reference/number_fields.rst
deleted file mode 100644
 a/doc/en/reference/number_fields.rst
+++ /dev/null
@@ 1,18 +0,0 @@
Algebraic Number Fields
=======================

.. toctree::
 :maxdepth: 2

 sage/rings/number_field/number_field
 sage/rings/number_field/number_field_rel
 sage/rings/number_field/number_field_element
 sage/rings/number_field/number_field_element_quadratic
 sage/rings/number_field/order
 sage/rings/number_field/number_field_ideal
 sage/rings/number_field/number_field_ideal_rel
 sage/rings/number_field/class_group
 sage/rings/number_field/galois_group
 sage/rings/number_field/unit_group
 sage/rings/number_field/small_primes_of_degree_one
 sage/rings/qqbar
diff git a/doc/en/reference/number_fields/conf.py b/doc/en/reference/number_fields/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/number_fields/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/number_fields/index.rst b/doc/en/reference/number_fields/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/number_fields/index.rst
@@ 0,0 +1,21 @@
+Algebraic Number Fields
+=======================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/rings/number_field/number_field
+ sage/rings/number_field/number_field_rel
+ sage/rings/number_field/number_field_element
+ sage/rings/number_field/number_field_element_quadratic
+ sage/rings/number_field/order
+ sage/rings/number_field/number_field_ideal
+ sage/rings/number_field/number_field_ideal_rel
+ sage/rings/number_field/class_group
+ sage/rings/number_field/galois_group
+ sage/rings/number_field/unit_group
+ sage/rings/number_field/small_primes_of_degree_one
+ sage/rings/qqbar
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/numerical.rst b/doc/en/reference/numerical.rst
deleted file mode 100644
 a/doc/en/reference/numerical.rst
+++ /dev/null
@@ 1,9 +0,0 @@
Numerical Optimization
======================

.. toctree::
 :maxdepth: 2

 sage/numerical/knapsack
 sage/numerical/mip
 sage/numerical/optimize
diff git a/doc/en/reference/numerical/conf.py b/doc/en/reference/numerical/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/numerical/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/numerical/index.rst b/doc/en/reference/numerical/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/numerical/index.rst
@@ 0,0 +1,12 @@
+Numerical Optimization
+======================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/numerical/knapsack
+ sage/numerical/mip
+ sage/numerical/optimize
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/options.rst b/doc/en/reference/options.rst
deleted file mode 100644
 a/doc/en/reference/options.rst
+++ /dev/null
@@ 1,44 +0,0 @@
Sage: Command Line Arguments
============================

There are several flags you can pass to Sage via the command line:


 ``h, ?`` Prints a help message.

 ``notebook`` Starts the Sage notebook running in default mode.
 This does not open a browser; it just starts a Sage Notebook server
 running on http://localhost:8000 (or a subsequent port if that port
 is not available). Pressing {Controlc} stops the server.

 ``i [packages]`` Installs the given Sage packages. If a package
 is listed at
 http://modular.math.washington.edu/sage/packages/optional/ and not
 available in your current directory, then Sage will try to download
 the package and install it.

 ``optional`` Lists all optional packages that can be
 downloaded.

 ``t `` Tests examples in .py, .pyx, .sage or .tex
 files.

 ``testall`` Tests all examples in Sage.

 ``upgrade`` Downloads the latest nonoptional Sage packages
 from http://modular.math.washington.edu/sage/packages/standard/,
 then builds and installs them. In many cases this requires that
 your computer has the necessary software development tools (listed
 in the installation documentation). Optional packages have to
 upgraded manually using ``sage i``. (There are no
 binary packages yet.)

 ``file1.sage file2.sage file.py ...`` Starts Sage, compiles any
 .sage files to .py files, and runs files.

 ``advanced`` Displays additional options that can be passed to
 Sage.




diff git a/doc/en/reference/options/conf.py b/doc/en/reference/options/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/options/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/options/index.rst b/doc/en/reference/options/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/options/index.rst
@@ 0,0 +1,47 @@
+Sage: Command Line Arguments
+============================
+
+There are several flags you can pass to Sage via the command line:
+
+
+ ``h, ?`` Prints a help message.
+
+ ``notebook`` Starts the Sage notebook running in default mode.
+ This does not open a browser; it just starts a Sage Notebook server
+ running on http://localhost:8000 (or a subsequent port if that port
+ is not available). Pressing {Controlc} stops the server.
+
+ ``i [packages]`` Installs the given Sage packages. If a package
+ is listed at
+ http://modular.math.washington.edu/sage/packages/optional/ and not
+ available in your current directory, then Sage will try to download
+ the package and install it.
+
+ ``optional`` Lists all optional packages that can be
+ downloaded.
+
+ ``t `` Tests examples in .py, .pyx, .sage or .tex
+ files.
+
+ ``testall`` Tests all examples in Sage.
+
+ ``upgrade`` Downloads the latest nonoptional Sage packages
+ from http://modular.math.washington.edu/sage/packages/standard/,
+ then builds and installs them. In many cases this requires that
+ your computer has the necessary software development tools (listed
+ in the installation documentation). Optional packages have to
+ upgraded manually using ``sage i``. (There are no
+ binary packages yet.)
+
+ ``file1.sage file2.sage file.py ...`` Starts Sage, compiles any
+ .sage files to .py files, and runs files.
+
+ ``advanced`` Displays additional options that can be passed to
+ Sage.
+
+
+
+
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/padics.rst b/doc/en/reference/padics.rst
deleted file mode 100644
 a/doc/en/reference/padics.rst
+++ /dev/null
@@ 1,45 +0,0 @@
pAdics
=======================

.. toctree::
 :maxdepth: 2

 sage/rings/padics/tutorial


 sage/rings/padics/factory


 sage/rings/padics/local_generic
 sage/rings/padics/padic_generic

 sage/rings/padics/generic_nodes
 sage/rings/padics/padic_base_generic
 sage/rings/padics/padic_extension_generic
 sage/rings/padics/eisenstein_extension_generic
 sage/rings/padics/unramified_extension_generic

 sage/rings/padics/padic_base_leaves
 sage/rings/padics/padic_extension_leaves


 sage/rings/padics/local_generic_element
 sage/rings/padics/padic_generic_element

 sage/rings/padics/padic_base_generic_element
 sage/rings/padics/padic_capped_relative_element
 sage/rings/padics/padic_capped_absolute_element
 sage/rings/padics/padic_fixed_mod_element

 sage/rings/padics/padic_ext_element
 sage/rings/padics/padic_ZZ_pX_element
 sage/rings/padics/padic_ZZ_pX_CR_element
 sage/rings/padics/padic_ZZ_pX_CA_element
 sage/rings/padics/padic_ZZ_pX_FM_element


 sage/rings/padics/pow_computer
 sage/rings/padics/pow_computer_ext
 sage/rings/padics/padic_printing
 sage/rings/padics/precision_error
 sage/rings/padics/misc
\ No newline at end of file
diff git a/doc/en/reference/padics/conf.py b/doc/en/reference/padics/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/padics/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/padics/index.rst b/doc/en/reference/padics/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/padics/index.rst
@@ 0,0 +1,47 @@
+pAdics
+=======================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/rings/padics/tutorial
+
+
+ sage/rings/padics/factory
+
+
+ sage/rings/padics/local_generic
+ sage/rings/padics/padic_generic
+
+ sage/rings/padics/generic_nodes
+ sage/rings/padics/padic_base_generic
+ sage/rings/padics/padic_extension_generic
+ sage/rings/padics/eisenstein_extension_generic
+ sage/rings/padics/unramified_extension_generic
+
+ sage/rings/padics/padic_base_leaves
+ sage/rings/padics/padic_extension_leaves
+
+
+ sage/rings/padics/local_generic_element
+ sage/rings/padics/padic_generic_element
+
+ sage/rings/padics/padic_base_generic_element
+ sage/rings/padics/padic_capped_relative_element
+ sage/rings/padics/padic_capped_absolute_element
+ sage/rings/padics/padic_fixed_mod_element
+
+ sage/rings/padics/padic_ext_element
+ sage/rings/padics/padic_ZZ_pX_element
+ sage/rings/padics/padic_ZZ_pX_CR_element
+ sage/rings/padics/padic_ZZ_pX_CA_element
+ sage/rings/padics/padic_ZZ_pX_FM_element
+
+
+ sage/rings/padics/pow_computer
+ sage/rings/padics/pow_computer_ext
+ sage/rings/padics/padic_printing
+ sage/rings/padics/precision_error
+ sage/rings/padics/misc
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/plane_curves.rst b/doc/en/reference/plane_curves.rst
deleted file mode 100644
 a/doc/en/reference/plane_curves.rst
+++ /dev/null
@@ 1,57 +0,0 @@
.. _ch:planecurves:

Elliptic and Plane Curves
=========================


.. toctree::
 :maxdepth: 2

 sage/schemes/plane_curves/constructor
 sage/schemes/plane_curves/affine_curve
 sage/schemes/plane_curves/projective_curve

 sage/schemes/elliptic_curves/constructor
 sage/schemes/elliptic_curves/ell_generic
 sage/schemes/elliptic_curves/ell_field
 sage/schemes/elliptic_curves/ell_rational_field
 sage/schemes/elliptic_curves/ec_database
 sage/schemes/elliptic_curves/ell_number_field
 sage/schemes/elliptic_curves/ell_finite_field
 sage/schemes/elliptic_curves/ell_point
 sage/schemes/elliptic_curves/ell_torsion
 sage/schemes/elliptic_curves/ell_local_data
 sage/schemes/elliptic_curves/kodaira_symbol
 sage/schemes/elliptic_curves/weierstrass_morphism
 sage/schemes/elliptic_curves/ell_curve_isogeny
 sage/schemes/elliptic_curves/ell_wp
 sage/schemes/elliptic_curves/period_lattice
 sage/schemes/elliptic_curves/formal_group
 sage/schemes/elliptic_curves/ell_tate_curve
 sage/schemes/elliptic_curves/monsky_washnitzer
 sage/schemes/elliptic_curves/padic_lseries
 sage/schemes/elliptic_curves/ell_modular_symbols
 sage/schemes/elliptic_curves/sha_tate
 sage/schemes/elliptic_curves/padics
 sage/schemes/elliptic_curves/cm


.. _ch:jacobians:

Hyperelliptic Curves
====================

.. toctree::
 :maxdepth: 2

 sage/schemes/hyperelliptic_curves/constructor
 sage/schemes/hyperelliptic_curves/hyperelliptic_finite_field
 sage/schemes/hyperelliptic_curves/hyperelliptic_generic

 sage/schemes/hyperelliptic_curves/jacobian_constructor
 sage/schemes/hyperelliptic_curves/jacobian_g2
 sage/schemes/hyperelliptic_curves/jacobian_generic
 sage/schemes/hyperelliptic_curves/jacobian_homset
 sage/schemes/hyperelliptic_curves/jacobian_morphism

 sage/interfaces/genus2reduction
diff git a/doc/en/reference/plane_curves/conf.py b/doc/en/reference/plane_curves/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/plane_curves/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/plane_curves/index.rst b/doc/en/reference/plane_curves/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/plane_curves/index.rst
@@ 0,0 +1,55 @@
+Elliptic and Plane Curves
+=========================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/schemes/plane_curves/constructor
+ sage/schemes/plane_curves/affine_curve
+ sage/schemes/plane_curves/projective_curve
+
+ sage/schemes/elliptic_curves/constructor
+ sage/schemes/elliptic_curves/ell_generic
+ sage/schemes/elliptic_curves/ell_field
+ sage/schemes/elliptic_curves/ell_rational_field
+ sage/schemes/elliptic_curves/ec_database
+ sage/schemes/elliptic_curves/ell_number_field
+ sage/schemes/elliptic_curves/ell_finite_field
+ sage/schemes/elliptic_curves/ell_point
+ sage/schemes/elliptic_curves/ell_torsion
+ sage/schemes/elliptic_curves/ell_local_data
+ sage/schemes/elliptic_curves/kodaira_symbol
+ sage/schemes/elliptic_curves/weierstrass_morphism
+ sage/schemes/elliptic_curves/ell_curve_isogeny
+ sage/schemes/elliptic_curves/ell_wp
+ sage/schemes/elliptic_curves/period_lattice
+ sage/schemes/elliptic_curves/formal_group
+ sage/schemes/elliptic_curves/ell_tate_curve
+ sage/schemes/elliptic_curves/monsky_washnitzer
+ sage/schemes/elliptic_curves/padic_lseries
+ sage/schemes/elliptic_curves/ell_modular_symbols
+ sage/schemes/elliptic_curves/sha_tate
+ sage/schemes/elliptic_curves/padics
+ sage/schemes/elliptic_curves/cm
+
+
+Hyperelliptic Curves
+====================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/schemes/hyperelliptic_curves/constructor
+ sage/schemes/hyperelliptic_curves/hyperelliptic_finite_field
+ sage/schemes/hyperelliptic_curves/hyperelliptic_generic
+
+ sage/schemes/hyperelliptic_curves/jacobian_constructor
+ sage/schemes/hyperelliptic_curves/jacobian_g2
+ sage/schemes/hyperelliptic_curves/jacobian_generic
+ sage/schemes/hyperelliptic_curves/jacobian_homset
+ sage/schemes/hyperelliptic_curves/jacobian_morphism
+
+ sage/interfaces/genus2reduction
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/plot3d.rst b/doc/en/reference/plot3d.rst
deleted file mode 100644
 a/doc/en/reference/plot3d.rst
+++ /dev/null
@@ 1,16 +0,0 @@
3D Graphics
===========

.. toctree::
 :maxdepth: 2

 sage/plot/plot3d/examples
 sage/plot/plot3d/parametric_plot3d
 sage/plot/plot3d/plot_field3d
 sage/plot/plot3d/implicit_plot3d
 sage/plot/plot3d/list_plot3d
 sage/plot/plot3d/plot3d
 sage/plot/plot3d/platonic
 sage/plot/plot3d/shapes2
 sage/plot/plot3d/base
 sage/plot/plot3d/tachyon
diff git a/doc/en/reference/plot3d/conf.py b/doc/en/reference/plot3d/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/plot3d/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/plot3d/index.rst b/doc/en/reference/plot3d/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/plot3d/index.rst
@@ 0,0 +1,19 @@
+3D Graphics
+===========
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/plot/plot3d/examples
+ sage/plot/plot3d/parametric_plot3d
+ sage/plot/plot3d/plot_field3d
+ sage/plot/plot3d/implicit_plot3d
+ sage/plot/plot3d/list_plot3d
+ sage/plot/plot3d/plot3d
+ sage/plot/plot3d/platonic
+ sage/plot/plot3d/shapes2
+ sage/plot/plot3d/base
+ sage/plot/plot3d/tachyon
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/plotting.rst b/doc/en/reference/plotting.rst
deleted file mode 100644
 a/doc/en/reference/plotting.rst
+++ /dev/null
@@ 1,25 +0,0 @@
2D Graphics
===========

.. toctree::
 :maxdepth: 2

 sage/plot/plot
 sage/plot/animate
 sage/plot/arrow
 sage/plot/bar_chart
 sage/plot/bezier_path
 sage/plot/circle
 sage/plot/complex_plot
 sage/plot/contour_plot
 sage/plot/density_plot
 sage/plot/disk
 sage/plot/line
 sage/plot/step
 sage/plot/matrix_plot
 sage/plot/plot_field
 sage/plot/point
 sage/plot/polygon
 sage/plot/primitive
 sage/plot/scatter_plot
 sage/plot/text
diff git a/doc/en/reference/plotting/conf.py b/doc/en/reference/plotting/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/plotting/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/plotting/index.rst b/doc/en/reference/plotting/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/plotting/index.rst
@@ 0,0 +1,28 @@
+2D Graphics
+===========
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/plot/plot
+ sage/plot/animate
+ sage/plot/arrow
+ sage/plot/bar_chart
+ sage/plot/bezier_path
+ sage/plot/circle
+ sage/plot/complex_plot
+ sage/plot/contour_plot
+ sage/plot/density_plot
+ sage/plot/disk
+ sage/plot/line
+ sage/plot/step
+ sage/plot/matrix_plot
+ sage/plot/plot_field
+ sage/plot/point
+ sage/plot/polygon
+ sage/plot/primitive
+ sage/plot/scatter_plot
+ sage/plot/text
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/polynomial_rings.rst b/doc/en/reference/polynomial_rings.rst
deleted file mode 100644
 a/doc/en/reference/polynomial_rings.rst
+++ /dev/null
@@ 1,33 +0,0 @@

.. _ch:polynomialrings:

Polynomial Rings
================

.. toctree::
 :maxdepth: 2

 sage/rings/polynomial/polynomial_ring_constructor

 polynomial_rings_univar

 polynomial_rings_multivar

 sage/rings/polynomial/laurent_polynomial_ring
 sage/rings/polynomial/laurent_polynomial

 sage/rings/polynomial/pbori

 sage/rings/polynomial/symmetric_ideal
 sage/rings/polynomial/symmetric_reduction

 sage/rings/polynomial/infinite_polynomial_ring
 sage/rings/polynomial/infinite_polynomial_element

 sage/rings/polynomial/toy_buchberger
 sage/rings/polynomial/toy_variety
 sage/rings/polynomial/toy_d_basis


 sage/rings/polynomial/convolution
 sage/rings/polynomial/cyclotomic
diff git a/doc/en/reference/polynomial_rings/conf.py b/doc/en/reference/polynomial_rings/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/polynomial_rings/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/polynomial_rings/index.rst b/doc/en/reference/polynomial_rings/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/polynomial_rings/index.rst
@@ 0,0 +1,33 @@
+Polynomial Rings
+================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/rings/polynomial/polynomial_ring_constructor
+
+ polynomial_rings_univar
+
+ polynomial_rings_multivar
+
+ sage/rings/polynomial/laurent_polynomial_ring
+ sage/rings/polynomial/laurent_polynomial
+
+ sage/rings/polynomial/pbori
+
+ sage/rings/polynomial/symmetric_ideal
+ sage/rings/polynomial/symmetric_reduction
+
+ sage/rings/polynomial/infinite_polynomial_ring
+ sage/rings/polynomial/infinite_polynomial_element
+
+ sage/rings/polynomial/toy_buchberger
+ sage/rings/polynomial/toy_variety
+ sage/rings/polynomial/toy_d_basis
+
+
+ sage/rings/polynomial/convolution
+ sage/rings/polynomial/cyclotomic
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/polynomial_rings_multivar.rst b/doc/en/reference/polynomial_rings_multivar.rst
deleted file mode 100644
 a/doc/en/reference/polynomial_rings_multivar.rst
+++ /dev/null
@@ 1,37 +0,0 @@

Multivariate Polynomials and Polynomial Rings
=============================================

Sage implements multivariate polynomial rings through several
backends. The most generic implementation uses the classes
:class:`sage.rings.polynomial.polydict.PolyDict` and
:class:`sage.rings.polynomial.polydict.ETuple` to construct a dictionary with
exponent tuples as keys and coefficients as values.

Additionally, specialized and optimized implementations over many
specific coefficient rings are implemented via a shared library interface to
SINGULAR; and polynomials in the boolean polynomial ring

.. math::

 \GF{2}[x_1,...,x_n]/ \langle x_1^2+x_1,...,x_n^2+x_n \rangle.

are implemented using the PolyBoRi library (cf. :mod:`sage.rings.polynomial.pbori`).


.. toctree::
 :maxdepth: 2

 sage/rings/polynomial/term_order

 sage/rings/polynomial/multi_polynomial_ring_generic
 sage/rings/polynomial/multi_polynomial

 sage/rings/polynomial/multi_polynomial_ring
 sage/rings/polynomial/multi_polynomial_element
 sage/rings/polynomial/multi_polynomial_ideal

 sage/rings/polynomial/multi_polynomial_libsingular
 sage/rings/polynomial/multi_polynomial_ideal_libsingular

 sage/rings/polynomial/polydict
diff git a/doc/en/reference/polynomial_rings_multivar/conf.py b/doc/en/reference/polynomial_rings_multivar/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/polynomial_rings_multivar/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/polynomial_rings_multivar/index.rst b/doc/en/reference/polynomial_rings_multivar/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/polynomial_rings_multivar/index.rst
@@ 0,0 +1,40 @@
+
+Multivariate Polynomials and Polynomial Rings
+=============================================
+
+Sage implements multivariate polynomial rings through several
+backends. The most generic implementation uses the classes
+:class:`sage.rings.polynomial.polydict.PolyDict` and
+:class:`sage.rings.polynomial.polydict.ETuple` to construct a dictionary with
+exponent tuples as keys and coefficients as values.
+
+Additionally, specialized and optimized implementations over many
+specific coefficient rings are implemented via a shared library interface to
+SINGULAR; and polynomials in the boolean polynomial ring
+
+.. math::
+
+ \GF{2}[x_1,...,x_n]/ \langle x_1^2+x_1,...,x_n^2+x_n \rangle.
+
+are implemented using the PolyBoRi library (cf. :mod:`sage.rings.polynomial.pbori`).
+
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/rings/polynomial/term_order
+
+ sage/rings/polynomial/multi_polynomial_ring_generic
+ sage/rings/polynomial/multi_polynomial
+
+ sage/rings/polynomial/multi_polynomial_ring
+ sage/rings/polynomial/multi_polynomial_element
+ sage/rings/polynomial/multi_polynomial_ideal
+
+ sage/rings/polynomial/multi_polynomial_libsingular
+ sage/rings/polynomial/multi_polynomial_ideal_libsingular
+
+ sage/rings/polynomial/polydict
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/polynomial_rings_univar.rst b/doc/en/reference/polynomial_rings_univar.rst
deleted file mode 100644
 a/doc/en/reference/polynomial_rings_univar.rst
+++ /dev/null
@@ 1,36 +0,0 @@

Univariate Polynomials and Polynomial Rings
===========================================

Sage's architecture for polynomials 'under the hood' is complex, interfacing to
a variety of C/C++ libraries for polynomials over specific rings. In practice,
the user rarely has to worry about which backend is being used.

The hierarchy of class inheritance is somewhat confusing, since most of the
polynomial element classes are implemented as Cython extension types rather
than pure Python classes and thus can only inherit from a single base class,
whereas others have multiple bases.

.. toctree::
 :maxdepth: 2

 sage/rings/polynomial/polynomial_ring

 sage/rings/polynomial/polynomial_element
 sage/rings/polynomial/polynomial_element_generic
 sage/rings/polynomial/polynomial_gf2x
 sage/rings/polynomial/polynomial_integer_dense_flint
 sage/rings/polynomial/polynomial_integer_dense_ntl
 sage/rings/polynomial/polynomial_zmod_flint
 sage/rings/polynomial/polynomial_modn_dense_ntl
 sage/rings/polynomial/polynomial_real_mpfr_dense
 sage/rings/polynomial/polynomial_singular_interface

 sage/rings/polynomial/real_roots
 sage/rings/polynomial/complex_roots

 sage/rings/polynomial/polynomial_quotient_ring
 sage/rings/polynomial/polynomial_quotient_ring_element



diff git a/doc/en/reference/polynomial_rings_univar/conf.py b/doc/en/reference/polynomial_rings_univar/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/polynomial_rings_univar/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/polynomial_rings_univar/index.rst b/doc/en/reference/polynomial_rings_univar/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/polynomial_rings_univar/index.rst
@@ 0,0 +1,39 @@
+
+Univariate Polynomials and Polynomial Rings
+===========================================
+
+Sage's architecture for polynomials 'under the hood' is complex, interfacing to
+a variety of C/C++ libraries for polynomials over specific rings. In practice,
+the user rarely has to worry about which backend is being used.
+
+The hierarchy of class inheritance is somewhat confusing, since most of the
+polynomial element classes are implemented as Cython extension types rather
+than pure Python classes and thus can only inherit from a single base class,
+whereas others have multiple bases.
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/rings/polynomial/polynomial_ring
+
+ sage/rings/polynomial/polynomial_element
+ sage/rings/polynomial/polynomial_element_generic
+ sage/rings/polynomial/polynomial_gf2x
+ sage/rings/polynomial/polynomial_integer_dense_flint
+ sage/rings/polynomial/polynomial_integer_dense_ntl
+ sage/rings/polynomial/polynomial_zmod_flint
+ sage/rings/polynomial/polynomial_modn_dense_ntl
+ sage/rings/polynomial/polynomial_real_mpfr_dense
+ sage/rings/polynomial/polynomial_singular_interface
+
+ sage/rings/polynomial/real_roots
+ sage/rings/polynomial/complex_roots
+
+ sage/rings/polynomial/polynomial_quotient_ring
+ sage/rings/polynomial/polynomial_quotient_ring_element
+
+
+
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/power_series.rst b/doc/en/reference/power_series.rst
deleted file mode 100644
 a/doc/en/reference/power_series.rst
+++ /dev/null
@@ 1,13 +0,0 @@
.. _ch:powerseries:

Power Series Rings
==================

.. toctree::
 :maxdepth: 2

 sage/rings/power_series_ring
 sage/rings/power_series_ring_element

 sage/rings/laurent_series_ring
 sage/rings/laurent_series_ring_element
\ No newline at end of file
diff git a/doc/en/reference/power_series/conf.py b/doc/en/reference/power_series/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/power_series/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/power_series/index.rst b/doc/en/reference/power_series/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/power_series/index.rst
@@ 0,0 +1,14 @@
+Power Series Rings
+==================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/rings/power_series_ring
+ sage/rings/power_series_ring_element
+
+ sage/rings/laurent_series_ring
+ sage/rings/laurent_series_ring_element
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/probability.rst b/doc/en/reference/probability.rst
deleted file mode 100644
 a/doc/en/reference/probability.rst
+++ /dev/null
@@ 1,8 +0,0 @@
Probability
===========

.. toctree::
 :maxdepth: 2

 sage/gsl/probability_distribution
 sage/probability/random_variable
diff git a/doc/en/reference/probability/conf.py b/doc/en/reference/probability/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/probability/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/probability/index.rst b/doc/en/reference/probability/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/probability/index.rst
@@ 0,0 +1,11 @@
+Probability
+===========
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/gsl/probability_distribution
+ sage/probability/random_variable
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/quat_algebras.rst b/doc/en/reference/quat_algebras.rst
deleted file mode 100644
 a/doc/en/reference/quat_algebras.rst
+++ /dev/null
@@ 1,11 +0,0 @@
.. _ch:quatalgebras:

Quaternion Algebras
===================

.. toctree::
 :maxdepth: 2

 sage/algebras/quatalg/quaternion_algebra
 sage/algebras/quatalg/quaternion_algebra_element

diff git a/doc/en/reference/quat_algebras/conf.py b/doc/en/reference/quat_algebras/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/quat_algebras/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/quat_algebras/index.rst b/doc/en/reference/quat_algebras/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/quat_algebras/index.rst
@@ 0,0 +1,12 @@
+Quaternion Algebras
+===================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/algebras/quatalg/quaternion_algebra
+ sage/algebras/quatalg/quaternion_algebra_element
+
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/rings.rst b/doc/en/reference/rings.rst
deleted file mode 100644
 a/doc/en/reference/rings.rst
+++ /dev/null
@@ 1,18 +0,0 @@
.. _ch:rings:

General Rings, Ideals, and Morphisms
====================================

.. toctree::
 :maxdepth: 2

 sage/rings/ring
 sage/rings/ideal
 sage/rings/ideal_monoid
 sage/rings/morphism
 sage/rings/homset
 sage/rings/infinity
 sage/rings/fraction_field
 sage/rings/fraction_field_element
 sage/rings/quotient_ring
 sage/rings/quotient_ring_element
diff git a/doc/en/reference/rings/conf.py b/doc/en/reference/rings/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/rings/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/rings/index.rst b/doc/en/reference/rings/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/rings/index.rst
@@ 0,0 +1,19 @@
+General Rings, Ideals, and Morphisms
+====================================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/rings/ring
+ sage/rings/ideal
+ sage/rings/ideal_monoid
+ sage/rings/morphism
+ sage/rings/homset
+ sage/rings/infinity
+ sage/rings/fraction_field
+ sage/rings/fraction_field_element
+ sage/rings/quotient_ring
+ sage/rings/quotient_ring_element
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/rings_numerical.rst b/doc/en/reference/rings_numerical.rst
deleted file mode 100644
 a/doc/en/reference/rings_numerical.rst
+++ /dev/null
@@ 1,30 +0,0 @@
Fixed and Arbitrary Precision Numerical Fields
==============================================

Sage supports two optimized fixed precision fields for numerical
computation, the real double (RealDoubleField) and complex double
fields (ComplexDoubleField).
Sage also supports arbitrary precision real (RealField) and
complex fields (ComplexField), and real and complex
interval arithmetic (RealIntervalField and ComplexIntervalField).


Real and complex double elements are optimized implementations that
use the GNU Scientific Library for arithmetic and some special
functions. Arbitrary precision real and complex numbers are
implemented using the MPFR library, which builds on GMP. (Note that
Sage doesn't currently use the MPC library.) The interval arithmetic
field is implemented using the MPFI library.

In many cases the PARI Clibrary is used to compute special functions
when implementations aren't otherwise available.

.. toctree::
 :maxdepth: 2

 sage/rings/real_double
 sage/rings/complex_double
 sage/rings/real_mpfr
 sage/rings/complex_field
 sage/rings/complex_number
 sage/rings/real_mpfi
\ No newline at end of file
diff git a/doc/en/reference/rings_numerical/conf.py b/doc/en/reference/rings_numerical/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/rings_numerical/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/rings_numerical/index.rst b/doc/en/reference/rings_numerical/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/rings_numerical/index.rst
@@ 0,0 +1,32 @@
+Fixed and Arbitrary Precision Numerical Fields
+==============================================
+
+Sage supports two optimized fixed precision fields for numerical
+computation, the real double (RealDoubleField) and complex double
+fields (ComplexDoubleField).
+Sage also supports arbitrary precision real (RealField) and
+complex fields (ComplexField), and real and complex
+interval arithmetic (RealIntervalField and ComplexIntervalField).
+
+
+Real and complex double elements are optimized implementations that
+use the GNU Scientific Library for arithmetic and some special
+functions. Arbitrary precision real and complex numbers are
+implemented using the MPFR library, which builds on GMP. (Note that
+Sage doesn't currently use the MPC library.) The interval arithmetic
+field is implemented using the MPFI library.
+
+In many cases the PARI Clibrary is used to compute special functions
+when implementations aren't otherwise available.
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/rings/real_double
+ sage/rings/complex_double
+ sage/rings/real_mpfr
+ sage/rings/complex_field
+ sage/rings/complex_number
+ sage/rings/real_mpfi
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/rings_standard.rst b/doc/en/reference/rings_standard.rst
deleted file mode 100644
 a/doc/en/reference/rings_standard.rst
+++ /dev/null
@@ 1,17 +0,0 @@
Standard Commutative Rings
==========================

.. toctree::
 :maxdepth: 2

 sage/rings/integer_ring
 sage/rings/integer

 sage/rings/integer_mod_ring
 sage/rings/integer_mod

 sage/rings/rational_field
 sage/rings/rational

 sage/rings/finite_field
 sage/rings/finite_field_element
diff git a/doc/en/reference/rings_standard/conf.py b/doc/en/reference/rings_standard/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/rings_standard/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/rings_standard/index.rst b/doc/en/reference/rings_standard/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/rings_standard/index.rst
@@ 0,0 +1,20 @@
+Standard Commutative Rings
+==========================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/rings/integer_ring
+ sage/rings/integer
+
+ sage/rings/integer_mod_ring
+ sage/rings/integer_mod
+
+ sage/rings/rational_field
+ sage/rings/rational
+
+ sage/rings/finite_field
+ sage/rings/finite_field_element
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/schemes.rst b/doc/en/reference/schemes.rst
deleted file mode 100644
 a/doc/en/reference/schemes.rst
+++ /dev/null
@@ 1,25 +0,0 @@
.. _ch:schemes:

Schemes
=======

.. toctree::
 :maxdepth: 2

 sage/schemes/readme

 sage/schemes/generic/scheme
 sage/schemes/generic/spec
 sage/schemes/generic/glue
 sage/schemes/generic/point

 sage/schemes/generic/ambient_space
 sage/schemes/generic/affine_space
 sage/schemes/generic/projective_space
 sage/schemes/generic/algebraic_scheme
 sage/schemes/generic/hypersurface

 sage/schemes/generic/homset
 sage/schemes/generic/morphism
 sage/schemes/generic/divisor

diff git a/doc/en/reference/schemes/conf.py b/doc/en/reference/schemes/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/schemes/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/schemes/index.rst b/doc/en/reference/schemes/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/schemes/index.rst
@@ 0,0 +1,26 @@
+Schemes
+=======
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/schemes/readme
+
+ sage/schemes/generic/scheme
+ sage/schemes/generic/spec
+ sage/schemes/generic/glue
+ sage/schemes/generic/point
+
+ sage/schemes/generic/ambient_space
+ sage/schemes/generic/affine_space
+ sage/schemes/generic/projective_space
+ sage/schemes/generic/algebraic_scheme
+ sage/schemes/generic/hypersurface
+
+ sage/schemes/generic/homset
+ sage/schemes/generic/morphism
+ sage/schemes/generic/divisor
+
+
+
+.. include:: ../footer.txt
diff git a/doc/en/reference/structure.rst b/doc/en/reference/structure.rst
deleted file mode 100644
 a/doc/en/reference/structure.rst
+++ /dev/null
@@ 1,27 +0,0 @@
Basic Structures
================

.. toctree::
 :maxdepth: 2

 sage/structure/sage_object
 sage/structure/category_object
 sage/structure/parent_gens
 sage/structure/formal_sum
 sage/structure/factorization
 sage/structure/element
 sage/structure/unique_representation
 sage/structure/dynamic_class
 sage/structure/mutability
 sage/structure/sequence
 sage/structure/element_wrapper

 sage/sets/family
 sage/sets/set
 sage/sets/disjoint_union_enumerated_sets
 sage/sets/finite_enumerated_set
 sage/sets/non_negative_integers
 sage/sets/primes

 sage/structure/parent

diff git a/doc/en/reference/structure/conf.py b/doc/en/reference/structure/conf.py
new file mode 100644
 /dev/null
+++ b/doc/en/reference/structure/conf.py
@@ 0,0 +1,37 @@
+# * coding: utf8 *
+#
+# Sage documentation build configuration file, created by
+# sphinxquickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# General information about the project.
+project = u"Sage Reference Manual"
+name = "reference"
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+html_title = project + " v"+release
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', name + '.tex', u'Sage Reference Manual',
+ u'The Sage Development Team', 'manual'),
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
diff git a/doc/en/reference/structure/index.rst b/doc/en/reference/structure/index.rst
new file mode 100644
 /dev/null
+++ b/doc/en/reference/structure/index.rst
@@ 0,0 +1,30 @@
+Basic Structures
+================
+
+.. toctree::
+ :maxdepth: 2
+
+ sage/structure/sage_object
+ sage/structure/category_object
+ sage/structure/parent_gens
+ sage/structure/formal_sum
+ sage/structure/factorization
+ sage/structure/element
+ sage/structure/unique_representation
+ sage/structure/dynamic_class
+ sage/structure/mutability
+ sage/structure/sequence
+ sage/structure/element_wrapper
+
+ sage/sets/family
+ sage/sets/set
+ sage/sets/disjoint_union_enumerated_sets
+ sage/sets/finite_enumerated_set
+ sage/sets/non_negative_integers
+ sage/sets/primes
+
+ sage/structure/parent
+
+
+
+.. include:: ../footer.txt