#10637: Implement sage -sws2rst
------------------------------------------------------------+---------------
Reporter: nthiery | Owner:
jason, mpatel, was
Type: enhancement | Status:
needs_review
Priority: major | Milestone:
sage-5.2
Component: notebook | Resolution:
Keywords: ReST, worksheet | Work issues:
Report Upstream: Workaround found; Bug reported upstream. | Reviewers:
Nicolas Thiéry, Jason Grout, Karl-Dieter Crisman, Jason Bandlow
Authors: Pablo Angulo, Karl-Dieter Crisman | Merged in:
Dependencies: #11080, #11459 | Stopgaps:
------------------------------------------------------------+---------------
Comment (by kcrisman):
Okay, here are some comments from a first try of a bunch of worksheets.
It is a long list! So before I get to it, I want to say that '''in
general, this is working great; everything that doesn't work is easily
fixable in the rst source file by a very much non-expert in ReST like
myself'''. If some of these things are fixable - particularly the extra
newline needed in lists, and the issue with math formatting - that would
be best before this makes it into Sage, but most of the rest should be in
an upgrade. Great work!
----
* As I suspected, intra-worksheets links are not respected. For example,
I had
{{{
<a href="#Main">below</a>
}}}
and then later
{{{
<p id="Main">The main part of ...
}}}
The ReST is
{{{
please skip `below <#Main>`_ .
}}}
I don't know if that is easy to fix, but anyway it's not perfect.
Again, given the goals of this, that could be in a second version, but I
wanted to point it out. Maybe if the text is {{{#foo}}} it could be
prepended somehow? But of course the ids are mostly gone, I guess.
* The way you replace a span by a `\n` means that sometimes TinyMCE stuff
left over from trying to unformat things gets in a new line. TinyMCE is
annoying that way - sometimes to unitalicize you have to do a few things.
Anyway, users will have to expect lots of newlines because of that. In
one case, I ''intentionally'' had used a lot of different ones, and since
bold isn't a span, but everything else you can do is, the doc looked kind
of weird, lots of new lines. In another case, the text was colored on
purpose.
{{{
Plot a green <span style="color: #008000;">$y=\sin(x)$</span> together
with...
}}}
and then it made a new line there. I'm wondering why you chose to make
{{{\n}}} instead of just a space - surely you encountered some "real-life"
examples where that was the better option. I'm assuming we can't easily
take the color info in, if that's the only info.
* I think one might need a few other new lines in other places. Here is
an example of something that didn't work right. The html:
{{{
<p>For a typical mathematical function, it's pretty straightforward to
define it. Below, we define the function $$f(x)=x^2\; .$$</p>
}}}
which became
{{{
For a typical mathematical function, it's pretty straightforward to define
it. Below, we define the function
.. MATH::
f(x)=x^2\; .
}}}
which typeset with the {{{.. MATH:}}} as part of the paragraph,
interpreting the double colon as making it an input cell (which it then
looked like. I'm not sure what happened here, but I'm guessing it has
something to do with the removal of the paragraphs with double dollar
signs.
* Here's an even worse example of math not behaving right.
{{{
<ul>
<li>For instance, it isn't too hard to add things like
$$\zeta(s)=\sum_{n=1}^{\infty}\frac{1}{n^s}=\prod_p
\left(\frac{1}{1-p^{-s}}\right)\; .$$ </li>
<li>One just types things
like "\$\$\zeta(s)=\sum_{n=1}^{\infty}\frac{1}{n^s}=\prod_p
\left(\frac{1}{1-p^{-s}}\right)\$\$" in the word processor. </li>
<li>Whether this shows up as nicely as possible depends on what fonts you
have in your browser, but it should be legible. </li>
<li>More realistically, we might type "\$f(x)=x^2\$" so that we remember
that $f(x)=x^2$ in this worksheet.</li>
</ul>
}}}
became all math mode, because the indentation
{{{
- For instance, it isn't too hard to add things like
.. MATH::
\zeta(s)=\sum_{n=1}^{\infty}\frac{1}{n^s}=\prod_p
\left(\frac{1}{1-p^{-s}}\right)\; .
- One just types things like
"\$\$\zeta(s)=\sum_{n=1}^{\infty}\frac{1}{n^s}=\prod_p
\left(\frac{1}{1\-p^{\-s}}\right)\$\$$
- Whether this shows up as nicely as possible depends on what fonts you
have in your browser, but it should be legible.
}}}
all was interpreted as being part of the math block! Instead, the math
block should have been inside the list, I guess?
* This is just amusing.
{{{
arrow $\mapsto$ as "|-->").
}}}
becomes the same thing, so it doesn't turn back into {{{|-->}}}, the
arrow! Not sure what to do about that; why didn't the greater than sign
just become a greater than sign when translated from html back? Also, I
thought that {{{|}}} was one of the characters you escaped, but maybe this
one escaped being escaped?
* In that same line, Sphinx says
{{{
WARNING: Inline substitution_reference start-string without end-string.
}}}
which I assume is related because of the open pipe {{{|}}} without a
close pipe.
* Dumb question; is there a way to have an empty cell? Currently you
remove them, but if the input ''and'' output are empty, then maybe it's
supposed to be an empty cell in the "live" documentation... that's
obviously very low priority.
* Hyperlinks (to other sites, which do work) add an extra space on either
side. That looks ok if there isn't punctuation, but if there is, it looks
weird.
{{{
the `Sage website <http://www.sagemath.org/help.html>`_ , which
}}}
Note the space before the comma, which shows up in the built doc as
well.
* Here is an example of the very common error about bullet lists.
{{{
- Sage uses the Python programming language, which uses this syntax,
'under the hood', and
- Because it makes it easier to distinguish among
- The mathematical object,
}}}
yields
{{{
WARNING: Bullet list ends without a blank line; unexpected unindent.
}}}
pretty consistently. This should be fixed, and probably isn't too
hard to do by adding an extra {{{\n}}} somewhere in the ul code. I would
say that 90% of the Sphinx errors I got were this.
* There were also a few like this.
{{{
WARNING: Block quote ends without a blank line; unexpected unindent.
}}}
This comes from turning things like
{{{
<p>The most obvious one is simply turning $$\int f(x)dx$$ into $$\int_a^b
f(x)dx\; ,$$ as indicated in the Calculus I section. </p>
}}}
into
{{{
The most obvious one is simply turning
.. MATH::
\int f(x)dx
into
.. MATH::
\int_a^b f(x)dx\; ,
as indicated in the Calculus I section.
}}}
Not only is there the issue with the reinterpretation of the math block
as a literal block, but it interprets the extra words as part of the
literal block - but only because they for some reason got extra spaces.
* I found one thing that doesn't show up properly because of the html
blocks being removed - documentation! If one evaluates a cell like
{{{binomial??}}} then that is all html, and just disappears. Maybe just
making it plain text? I'm not sure either, you are right about that being
a pain in the neck to do anything intelligent with.
* There isn't much you can do about this, but since "the order enforced
will be the order as encountered" with section heading markup, one can
pretty easily get a lot of {{{SEVERE: Title level inconsistent:}}}
warnings. This is because we have a WYSIWYG editor which doesn't remember
state between cells.
* Back to issues about lists. I think that you are starting too big.
The first indent level should just be at the main level; the ones after
that can be indented by one. Isn't this
{{{
- item one
- item 1a
- item 1b
- item two
- item 2a
-item 2b
}}}
more correct than
{{{
- item one
- item 1a
- item 1b
- item two
- item 2a
-item 2b
}}}
which you currently have? If you look at rendered worksheets, you'll
see what I mean - everything is just a little too far in.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/10637#comment:63>
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.
