[with patch, positive review] tutorial: add documentation for solving matrix equations

documentation for solving matrix equations

I tried to apply the patch but was unable to:

sage: hg_sage.apply("/home/john/3728.patch")
cd "/home/john/sage-3.0.4/devel/sage" && hg status
cd "/home/john/sage-3.0.4/devel/sage" && hg status
cd "/home/john/sage-3.0.4/devel/sage" && hg import   "/home/john/3728.patch"
applying /home/john/3728.patch
abort: unable to find tut/tut.tex or tut/tut.tex for patching

I'm not sure if that is my fault or the patch's.

Secondly, why not include the abbreviated form :

sage: A\z
(-2, 1, 0)

Of course this is otherwise a useful addition to the tutorial.

For the first item, try hg_doc.apply instead of hg_sage.apply. The second is a good idea, and I'll submit a new patch including something relevant.

(a few minutes later)

Having tried to including something about backslashes, I find that I can't include lines like

\begin{verbatim}
sage: A \ Y
(-2, 1, 0)
\end{verbatim}

because the \ in the verbatim environment seems to mess up the doctesting, leading to a failure. Right now I have a compromise situation, discussing the backslash in the text, without including a testable example. Looks like we might need a trac ticket for fixing the doctesting...

new version of patch; this replaces the old one

Thanks for the tip about hg_doc. I applied the patch ok, but I don't know how to view the patched tutorial!

Here's what I do:

cd ...sage/devel/doc
make tut

Then you can use the notebook interface and click on the "Help" button at the top right to get the new version.

In addition to 'make tut', you can also do make paper-letter/tut.pdf or make paper-a4/tut.pdf, which creates those pdf files (.../sage/devel/doc/paper-letter/tut.pdf, for example).

I had another go at applying this patch, but "make tut" does not work for me. Sorry, someone else will have to do this. Of course the new paragraph looks ok when I read the raw latex.

I read the diff file and appears to be a useful addition to the tutorial explaining an example of solving a matrix equation. Then I tried the patch but it would not apply to 3.1.2.alpha4 using hg_doc.apply. Sorry.

I just tested it against 3.1.1 and it worked fine. I'll try to produce a new patch against 3.1.2alpha4...

Well, the patch 3728-new.patch worked for me with hg_doc.apply in 3.1.2.alpha4. Could you try again?

hg_doc.apply opens a new screen containing this diff file:

diff -r 493137a28022 commontex/patchlevel.tex
--- a/commontex/patchlevel.tex  Tue Sep 02 05:22:45 2008 -0700
+++ b/commontex/patchlevel.tex  Wed Sep 03 05:58:39 2008 -0400
@@ -1,6 +1,6 @@
 % This file is generated by ../tools/getversioninfo;
 % do not edit manually.

-\release{3.1.2.alpha3}
+\release{3.1.2.alpha4}
 \setreleaseinfo{}
-\setshortversion{3.1.2.alpha3}
+\setshortversion{3.1.2.alpha4}

Pressing q dumps me into vi session. Then I get a runtime error:

RuntimeError: Refusing to do operation since you still have unrecorded changes. You must check in all changes in your working repository first.

David,

I keep getting this as well and it bugs the heck out of me. But I can work around it by typing the following in the devel/doc directory:

ghitza@artin:/opt/sage/devel/doc$ hg qnew -f stupid.patch

(You can give the patch your favorite name that you're unlikely to use.)

Then the annoying diff's that you got above will go away and you can happily apply doc patches. I wish someone got rid of the problem altogether, but for now this should work.

John, I've looked at the patch and it seems ok to me; it also passes sage -t. Unfortunately, latex fonts are broken on my ubuntu machine so I can't do build_pdf or build_dvi to look at the typeset version. I will try to build 3.1.2.alpha4 on my gentoo machine and apply your patch there, but it might take a while. Hopefully this will have gotten a positive review by then.

OK, I managed to fix my latex and build the tutorial with the patch applied. Looks good!

I agree. Using Alex's trick, I got the patch to apply and this addition looks good. build_dvi works without latex compiling errors.

Alex, I'm glad you figured out the solution, because I had no idea what was going wrong or how to fix it.

Thanks to both of you (and to John Cremona) for the positive reviews...

Merged in Sage 3.1.2.rc0