#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 SimonKing):
Replying to [comment:116 kcrisman]:
> You can insert the links yourself, but I think that adding them all the
time wouldn't make sense, as such rst files might not necessarily become
part of Sage documentation, per se.
OK. I guess that in the end I have to edit the rst file anyway.
> Unrecognized tags will not be guessed at, I think that is a feature.
The notebook comes with an editor (`tinyMCE`, or what is it's name?), and
I think sws2rst should be able to work with what is produced by the
editor.
> Indentation I'm not sure about. Whitespace doesn't count; you should
really be using some formatting for that,
I used the editor in the notebook. Shouldn't that be fine?
> I think - not exactly user error, but probably not something one could
design around. What does the ''original'' worksheet have there (in its
html version)? What that looks like would have a big impact on it.
When I click on the "text" link, I see
{{{
<p><span style="text-decoration: underline;"><strong><span style="font-
size: x-large;">Outline</span></strong></span></p>
<p><strong>Use existing base classes</strong></p>
<p style="padding-left: 30px;">There are sub-classes of <span style="font-
family: arial,helvetica,sans-serif;">sage.structure.parent.Parent</span>
resp. of <span style="font-family: arial,helvetica,sans-
serif;">sage.structure.element.Element</span> that will help you a lot.
Inheriting from these classes is essential for using Sage's coercion
system.</p>
<p style="padding-left: 30px;">Arithmetic operations should be implemented
by <span style="text-decoration: underline;"><em>single
underscore</em></span> methods, such as <span style="font-family:
arial,helvetica,sans-serif;">_add_, _mul_</span>.</p>
<p><strong>Turn your parent structure into an object of a
category</strong></p>
<p style="padding-left: 30px;">Declare the category during initialisation
- Your parent structure will inherit further useful methods and
consistency tests.</p>
<p><strong>Provide your parent structure with an element
class</strong></p>
<p style="padding-left: 30px;">Assign to it an attribute called "Element"
- The elements will inherit further useful methods from the category.</p>
<p style="padding-left: 30px;">In addition, some basic conversions will
immediately work.</p>
<p><strong>Implement further conversions<br /></strong></p>
<p style="padding-left: 30px;">Never override a parent's __call__ method!
Provide <span style="font-family: arial,helvetica,sans-
serif;">_element_constructor_</span> instead.</p>
<p><strong>Declare coercions</strong></p>
<p style="padding-left: 30px;">If a conversion happens to be a morphism,
you may consider to turn it into a coercion. It will then
<em>implicitly</em> be used in arithmetic operations.</p>
<p><strong><span style="text-decoration: underline;">Advanced
coercion:</span> Define construction functors for your parent
structure</strong></p>
<p style="padding-left: 30px;">Sage will automatically create new parents
for you when needed, by some kind of "pushout" construction.</p>
<p><strong>Run the automatic test suites</strong></p>
<p style="padding-left: 30px;">Each method should be documented and
provide a doc test (we are not giving examples here). In addition, any
method defined for a category should be supported by a test method that is
executed when running the test suite.</p>
}}}
So, that's what is produced by the editor.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/10637#comment:117>
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.
