4.4 Modifying the Sage Manuals

We use the tutorial as an example.

You just modify the file SAGE_ROOT/devel/doc/tut/tut.tex To build a test copy of the tutorial with your changes, type ./build_dvi in the devel/doc/tut directory. You'll get a file tut.dvi. You can also build HTML versions of everything by typing make html in the devel/doc directory. Build pdfs with make pdf.

It is a good idea to type sage -t tut.tex to make sure any examples you added to the tutorial work as claimed.

The SAGE_ROOT/devel/doc directory is a Mercurial repository (see Chapter 7), so you can see exactly what changes you've made to the documentation, make patches of what you've done available, etc. You can do this from within Sage by typing hg_doc.[tab].

Imagine you have edited this Programming Manual found in devel/doc/prog. Before you started you did a pull to be sure your docs are up to date:

sage: hg_doc.pull()
cd "/home/jaap/sage/devel/doc" && hg status
cd "/home/jaap/sage/devel/doc" && hg status
cd "/home/jaap/sage/devel/doc" && hg pull -u http://sagemath.org/sage//hg//doc-main
pulling from http://sagemath.org/sage//hg//doc-main
searching for changes
adding changesets
adding manifests
adding file changes
added 3 changesets with 3 changes to 1 files
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
If it says use 'hg merge' above, then you should
type hg_sage.merge(), where hg_sage is the name
of the repository you are using.  This might not
work with the notebook yet.

After you made many changes, you want to commit them:

sage: hg_doc.commit()
cd "/home/jaap/downloads/sage-1.6/devel/doc" && hg diff  | less
cd "/home/jaap/downloads/sage-1.6/devel/doc" && hg commit

You saw the differences piped through diff, you were asked to comment: type 'i' or 'a', your comment, hit 'Escape' and type ':wq".

Now you can make a patch 'patchname'. e.g.:

sage: hg_doc.send('prog20070118.hg')
Writing to /home/jaap/sage/prog20070118.hg
cd "/home/jaap/sage/devel/doc" && hg bundle  tmphg http://sagemath.org/sage//hg//doc-main
searching for changes
Successfully created hg patch bundle /home/jaap/sage/prog20070118.hg

Send the file 'patchname' to the sage-devel Google group.

See About this document... for information on suggesting changes.