ASKSAGE: Sage Q&A Forum - Individual question feedhttp://ask.sagemath.org/questions/Q&A Forum for SageenCopyright Sage, 2010. Some rights reserved under creative commons license.Wed, 09 Jul 2014 13:49:40 -0500how to contribute tutorial/notebook guide?http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/ I'm nearly done writing a notebook that gives an overview of the Sage polytope commands for people who want to compute a la Gr\"unbuam / Brondsted.
Is there a standard way to make this available to the community? Of course I can just post it on my webpage, but people are less likely to find it there than if it's somehow in some repository somewhere. (True?)Sat, 05 Jul 2014 08:57:29 -0500http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/Comment by smbelcas for <p>I'm nearly done writing a notebook that gives an overview of the Sage polytope commands for people who want to compute a la Gr\"unbuam / Brondsted. </p>
<p>Is there a standard way to make this available to the community? Of course I can just post it on my webpage, but people are less likely to find it there than if it's somehow in some repository somewhere. (True?)</p>
http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?comment=23230#post-id-23230Clarification: I'm talking about a notebook, not a tutorial. I know there are repositories of things---but not how to find them. Example: Sometime in the past I was given a link to some @interacts for stuff like Euler's Method implementation---wait, google found that again---it's at http://wiki.sagemath.org/interact/diffeq---and there must be some central place people can go to find code... right? (No, I know that's probably too much to hope for. But where are people *supposed* to go to find code?)Sat, 05 Jul 2014 15:49:45 -0500http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?comment=23230#post-id-23230Answer by rws for <p>I'm nearly done writing a notebook that gives an overview of the Sage polytope commands for people who want to compute a la Gr\"unbuam / Brondsted. </p>
<p>Is there a standard way to make this available to the community? Of course I can just post it on my webpage, but people are less likely to find it there than if it's somehow in some repository somewhere. (True?)</p>
http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?answer=23228#post-id-23228 The documentation that is attached to the Sage distribution consists of the reference manual, the developers manual, and a collection of thematic tutorials. Your subject obviously fits the latter. All such Sage documentation is written in a format understandable by Sphinx, the tutorials mostly are in RST format. Please see the developers manual on how to write tutorials, and how to contribute them to Sage. A helpful tool to convert e.g. LaTeX into RST or many other formats is the highly recommended Pandoc program.Sat, 05 Jul 2014 13:08:48 -0500http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?answer=23228#post-id-23228Comment by smbelcas for <p>The documentation that is attached to the Sage distribution consists of the reference manual, the developers manual, and a collection of thematic tutorials. Your subject obviously fits the latter. All such Sage documentation is written in a format understandable by Sphinx, the tutorials mostly are in RST format. Please see the developers manual on how to write tutorials, and how to contribute them to Sage. A helpful tool to convert e.g. LaTeX into RST or many other formats is the highly recommended Pandoc program.</p>
http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?comment=23229#post-id-23229This was not a very helpful response.
First, it didn't tell me where to find the developer's manual. (Google answered that for me.)
Second, it didn't tell me where in the developer's manual to find instructions---the table of contents doesn't list such a thing.
But third and most importantly, I'm not writing a "thematic tutorial" as in the documentation. Personally, I find those unhelpful. What I've written is a notebook. And what I find helpful are notebook-like things, of which I know there are repositories somewhere because at various points Sage folk have directed me to them.Sat, 05 Jul 2014 15:45:09 -0500http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?comment=23229#post-id-23229Comment by kcrisman for <p>The documentation that is attached to the Sage distribution consists of the reference manual, the developers manual, and a collection of thematic tutorials. Your subject obviously fits the latter. All such Sage documentation is written in a format understandable by Sphinx, the tutorials mostly are in RST format. Please see the developers manual on how to write tutorials, and how to contribute them to Sage. A helpful tool to convert e.g. LaTeX into RST or many other formats is the highly recommended Pandoc program.</p>
http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?comment=23318#post-id-23318@rws, is there a place in the developer guide where how to write tutorials is discussed? That may need to be a little more prominent.Wed, 09 Jul 2014 13:49:40 -0500http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?comment=23318#post-id-23318Answer by kcrisman for <p>I'm nearly done writing a notebook that gives an overview of the Sage polytope commands for people who want to compute a la Gr\"unbuam / Brondsted. </p>
<p>Is there a standard way to make this available to the community? Of course I can just post it on my webpage, but people are less likely to find it there than if it's somehow in some repository somewhere. (True?)</p>
http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?answer=23232#post-id-23232I'd use [sws2rst](http://git.sagemath.org/sage.git/tree/src/bin/sage-sws2rst) for a start in converting it to a thematic tutorial. I understand your reticence to go all the way to doing so if you only have a notebook worksheet, but unfortunately there is (currently) no centralized repo for such things. (And a thematic tutorial, or just tutorial, actually probably is appropriate - perhaps the "thematic tutorial" name is not appropriate?)
More importantly, they are not available to people using the command line or just browsing the web without using the notebook or importing them to the cloud. One easier thing to do is for you for now is to post a link to somewhere on the internet with the raw file, and we could open a Trac ticket for adding this somewhere in the documentation.Sat, 05 Jul 2014 16:29:35 -0500http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?answer=23232#post-id-23232Comment by kcrisman for <p>I'd use <a href="http://git.sagemath.org/sage.git/tree/src/bin/sage-sws2rst">sws2rst</a> for a start in converting it to a thematic tutorial. I understand your reticence to go all the way to doing so if you only have a notebook worksheet, but unfortunately there is (currently) no centralized repo for such things. (And a thematic tutorial, or just tutorial, actually probably is appropriate - perhaps the "thematic tutorial" name is not appropriate?) </p>
<p>More importantly, they are not available to people using the command line or just browsing the web without using the notebook or importing them to the cloud. One easier thing to do is for you for now is to post a link to somewhere on the internet with the raw file, and we could open a Trac ticket for adding this somewhere in the documentation.</p>
http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?comment=23317#post-id-23317For now, you could post a link (or send someone working with Sage such a link) to the documents you have created and ask them to open Trac tickets for including these items. Alternately, you could acquire a Sage Trac account (see http://trac.sagemath.org/ for details) and do so yourself, though that would be a few extra steps that may seem onerous. The latter seems especially useful.Wed, 09 Jul 2014 13:48:50 -0500http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?comment=23317#post-id-23317Comment by smbelcas for <p>I'd use <a href="http://git.sagemath.org/sage.git/tree/src/bin/sage-sws2rst">sws2rst</a> for a start in converting it to a thematic tutorial. I understand your reticence to go all the way to doing so if you only have a notebook worksheet, but unfortunately there is (currently) no centralized repo for such things. (And a thematic tutorial, or just tutorial, actually probably is appropriate - perhaps the "thematic tutorial" name is not appropriate?) </p>
<p>More importantly, they are not available to people using the command line or just browsing the web without using the notebook or importing them to the cloud. One easier thing to do is for you for now is to post a link to somewhere on the internet with the raw file, and we could open a Trac ticket for adding this somewhere in the documentation.</p>
http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?comment=23308#post-id-23308And (metaquestion) what do I do with the directions I wrote for how to make tutorials?Wed, 09 Jul 2014 09:39:42 -0500http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?comment=23308#post-id-23308Comment by smbelcas for <p>I'd use <a href="http://git.sagemath.org/sage.git/tree/src/bin/sage-sws2rst">sws2rst</a> for a start in converting it to a thematic tutorial. I understand your reticence to go all the way to doing so if you only have a notebook worksheet, but unfortunately there is (currently) no centralized repo for such things. (And a thematic tutorial, or just tutorial, actually probably is appropriate - perhaps the "thematic tutorial" name is not appropriate?) </p>
<p>More importantly, they are not available to people using the command line or just browsing the web without using the notebook or importing them to the cloud. One easier thing to do is for you for now is to post a link to somewhere on the internet with the raw file, and we could open a Trac ticket for adding this somewhere in the documentation.</p>
http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?comment=23307#post-id-23307Now that I have a thematic tutorial (in need of some finessing), what do I do with it?Wed, 09 Jul 2014 09:39:02 -0500http://ask.sagemath.org/question/23225/how-to-contribute-tutorialnotebook-guide/?comment=23307#post-id-23307