#10637: Implement sage -sws2rst
------------------------------------------------------------+---------------
Reporter: nthiery | Owner:
jason, mpatel, was
Type: enhancement | Status:
needs_review
Priority: major | Milestone:
sage-5.7
Component: notebook | Resolution:
Keywords: ReST, worksheet | Work issues:
answer questions, math formatting, lists, maybe absolute paths?
Report Upstream: Workaround found; Bug reported upstream. | Reviewers:
Nicolas Thiéry, Jason Grout, Karl-Dieter Crisman, Jason Bandlow, John Palmieri
Authors: Pablo Angulo, Karl-Dieter Crisman | Merged in:
Dependencies: #11080, #11459 | Stopgaps:
------------------------------------------------------------+---------------
Comment (by pang):
In general, we ignore style completely. That's part of the goal, not a
failure.
The goal of this script is to turn worksheets into simpler, more
maintainable, doctest-friendly, restructured text. Restructured text does
not support style, it's roughly equivalent to (a subset of) html without
css. For instance, there is no construct for underlined text. Html docs
generated from rst sources could be shown underlined, depending on the
style used by rst2html.
So some info is lost, but that means it will be easier for the next guy to
keep your documentation at sync with the current sage version, and correct
typos.
If your text is bold and cursive because it is "strong", then this script
must recognize it and sorround it with asterisks. If it bold and cursive
because you applied some style, it's not going to work, and it's hopeless
and a loss of time to try to convert html into rst so that it generates
html with the exact same style. Any way of doing so involves hacking
sphinx so that it keeps the original html in a style file, in one way or
another. By the way, I don't think rst supports text that is both strong
and em, I vaguely recall some problems trying to nest one inside the
other. I'll check this eventually, forgive my lousy memory.
Regarding indentation, please think which html tag would correspond to the
text you wanted to indent: is it a quote? is a code snippet? Then a sws to
rst converter will have a chance.
It is true that tinyMCE abuses style, at points at which tags could be
used. For example, I had to use the courier font to mark variable names
within the text. I wrote a plugin for tinyMCE to add a code button that
worked much like the strong button. It was quick dirty code, and the
tinyMCE guys ignored the suggestion, but it's definitely doable. May be
could tweak the editor so that uses more tags and less style.
In the meantime, different people might use underline and indent to mean
different things, and there's little I can do. Please take this script as
a help in your conversion work. At some points, it won't guess the
canonical way to map your intentions into the simpler rst format, and
you'll have to do it manually.
This said, thanks a lot for trying the code, and finding the h5 bug. For
some reason, I stopped at h4: there are only 5 levels, are there?. It's
hard to know if I can do anything about the rest, given the goal I
described above. I'll check carefully, but will probably need more info.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/10637#comment:119>
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 unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sage-trac?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
