#11682: thematic tutorial on sandpiles
-----------------------------+----------------------------------------------
Reporter: dperkinson | Owner: mvngu
Type: enhancement | Status: needs_work
Priority: major | Milestone: sage-4.7.2
Component: documentation | Keywords: sandpile
Work_issues: | Upstream: N/A
Reviewer: | Author: David Perkinson
Merged: | Dependencies:
-----------------------------+----------------------------------------------
Comment(by dperkinson):
Rob: thanks for the comments!
I have addressed them all (see specifics below). I doctested the current
version (v4) with the --optional and -long and all tests passed.
NOTE: First apply trac_11682_sandpile_doc.v3.patch, then
trac_11682_sandpile_doc.v4.patch on top of that. Also, v4 and v4.2 are
identical. I just tried to remove a comma from the description and ended
up with two copies.
Thanks,
Dave
>I have one doctest failure (same command twice, then a follow-on command
>fails). I'm using 4.7.1.alpha4. It could be I am behind? Has this
changed?
>Which version are you testing on?
The problem here is that you do not have 4ti2 installed and I forgot to
put to
include '# optional 4ti2' next to these examples. I have added '#
optional
4ti2' in these two places in v4.
(I am testing on version 4.7.1 now.)
>1. Other tutorials have a main title (in the index of tutorials) that is
>capitalized, so maybe yours should be also.
Fixed.
>2. Maybe "is in the works" could read as "will appear as"?
Fixed (I removed the reference entirely for the time being).
>3. Installing 4ti2. Does it really need the patch level and all? I
thought it
>was smarter and sage -i 4ti2 would grab the newest spkg?
I just tested this again. The command 'sage -i 4ti2' attempts to install
the
wrong version of 4ti2 and crashes, whereas 'sage -i 4ti2.p0' works fine.
I sent
a note to sage-devel about this.
>4. URL references to other parts of the documentation should perhaps
>be.relative links, not full-blown http:// style. Sage should not presume
an
>internet connection, and indeed, many may view the documentation locally,
>especially if coming to it from within the notebook. So
>
>http://sagemath.org/doc/reference/sage/graphs/graph_generators.html
>
>could become
>
>../reference/sage/graphs/graph_generators.html
>
>There are also ways to link to documentation for classes, modules,
functions,
>etc with syntax such as
>
>:mod:`sage.graphs.graph_generators`
>
>which might even work better (ask if you need help with this).
Fixed. I used your former suggestion.
>5. SandpileConfig, ^ operator: needs a double-colon for the examples,
they are
>not being rendered verbatim.
Fixed.
>6. Do you want triple-dashes to make full-width horizontal rules in your
lists
>of methods? I'm just getting a short stubby thing, maybe you need more
dashes?
I am getting em-dashes from '---' in the rst file. I don't understand why
you
are not getting longer dashes.
>7. Are Sage code examples in the "python blocks" being tested? (Break one
and
>see.) I don't know - I've never used this construct in writing
documentation.
>Doesn't matter either way, I think.
I ascertained that the python blocks were *not* being tested. So I
checked
each manually, found several problems (due to out-of-date syntax), and
fixed
them. I do not want to have the blocks labeled as 'EXAMPLES'. I putua
warning
at the top of sandpile.rst that these blocks need to be tested by hand.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/11682#comment:15>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sage-trac?hl=en.
