back ticks versus $ signs
William Stein
I've been spending the last few days going between writing a lot of
code with very math heavy Sphinx docstrings containing many backticks,
and writing LaTeX documents (papers/notes/etc.) using $ signs for math
mode. It is driving me totally crazy! I constantly accidentally put
$'s in my Spinx docstrings and now I'm starting to put back ticks ` in
my LaTeX documents.
Is anybody else annoyed by this? I am very tempted to change Sage so
that $ signs can be used as a synonym for backquotes in docstrings. I
would leave backticks, but make it so $'s just get converted to
backticks, plus maybe some marker to leave $'s as $'s (e.g., whatever
one would currently do to enter a backtick in Sphinx).
[ ] Yes, give me $'s!
[ ] No, this doesn't bug me; let's keep ReST/Sphinx in Sage "pure".
-- William
--
William Stein
Associate Professor of Mathematics
University of Washington
http://wstein.org
Tom Boothby
>
> Hi,
>
> I've been spending the last few days going between writing a lot of
> code with very math heavy Sphinx docstrings containing many backticks,
> and writing LaTeX documents (papers/notes/etc.) using $ signs for math
> mode. It is driving me totally crazy! I constantly accidentally put
> $'s in my Spinx docstrings and now I'm starting to put back ticks ` in
> my LaTeX documents.
>
> Is anybody else annoyed by this? I am very tempted to change Sage so
> that $ signs can be used as a synonym for backquotes in docstrings. I
> would leave backticks, but make it so $'s just get converted to
> backticks, plus maybe some marker to leave $'s as $'s (e.g., whatever
> one would currently do to enter a backtick in Sphinx).
>
> [ ] Yes, give me $'s!
>
> [ ] No, this doesn't bug me; let's keep ReST/Sphinx in Sage "pure".
Ondrej Certik
>
> I've been spending the last few days going between writing a lot of
> code with very math heavy Sphinx docstrings containing many backticks,
> and writing LaTeX documents (papers/notes/etc.) using $ signs for math
> mode. It is driving me totally crazy! I constantly accidentally put
> $'s in my Spinx docstrings and now I'm starting to put back ticks ` in
> my LaTeX documents.
>
> Is anybody else annoyed by this? I am very tempted to change Sage so
> that $ signs can be used as a synonym for backquotes in docstrings. I
> would leave backticks, but make it so $'s just get converted to
> backticks, plus maybe some marker to leave $'s as $'s (e.g., whatever
> one would currently do to enter a backtick in Sphinx).
I am also writing lots of formulas using rest, e.g.:
http://certik.github.com/mhd-hermes/sphinx-doc/physics.html
and it bugs me that I have to type
:math:`\eta`
instead of just $\eta$. So how about submitting a patch to sphinx fixing it?
Ondrej
Robert Bradshaw
>
> Hi,
>
> I've been spending the last few days going between writing a lot of
> code with very math heavy Sphinx docstrings containing many backticks,
> and writing LaTeX documents (papers/notes/etc.) using $ signs for math
> mode. It is driving me totally crazy! I constantly accidentally put
> $'s in my Spinx docstrings and now I'm starting to put back ticks ` in
> my LaTeX documents.
>
> Is anybody else annoyed by this? I am very tempted to change Sage so
> that $ signs can be used as a synonym for backquotes in docstrings. I
> would leave backticks, but make it so $'s just get converted to
> backticks, plus maybe some marker to leave $'s as $'s (e.g., whatever
> one would currently do to enter a backtick in Sphinx).
>
> [X] Yes, give me $'s!
>
> [ ] No, this doesn't bug me; let's keep ReST/Sphinx in Sage "pure".
I've been annoyed by this ever since we switched over to ReST.
- Robert
William A. Stein
That's a good idea. It would certainly be better than having to
change Sage -- it would keep things "pure", but allow $'s, and even
benefit you. Great idea. It's hard to argue with that.
-- William
John Cremona
We are used to using $...$ for maths, so why should we not make the
docs markup system we use adapt to us rather than the other way round?
I find the view 'let's keep ReST/Sphinx in Sage "pure" ' very hard to
understand!
2009/9/3 William A. Stein <wst...@gmail.com>:
>
> That's a good idea. It would certainly be better than having to
> change Sage -- it would keep things "pure", but allow $'s, and even
> benefit you. Great idea. It's hard to argue with that.
I could not work out which idea is getting this thumbs up? If we can
arrange for all single $ to be changed into ` that's fine by me. I
have never used Ondrej's :math: in front, but maybe I should have.
John
Rob Beezer
> I have never used Ondrej's :math: in front, but maybe I should have.
default "mode" for the backticks, so I think Ondrej is writing docs
for one his other systems and he *must* use math:`x^2` to get LaTeX
output. However, Sage's installation has chosen to configure the
defaults so that just `x^2` is treated as being in "math" mode. So in
one sense, Sage already makes it easy to get math into the docs, since
we don't have to prepend with math: . Having to add math: would make
William more totally crazy, but would perhaps reduce the confusion.
Not a vote, not even a suggestion. Just some background (if I'm even
remembering right).
Rob
Nick Alexander
>>
>> [ ] No, this doesn't bug me; let's keep ReST/Sphinx in Sage "pure".
>
> I've been annoyed by this ever since we switched over to ReST.
I also have been annoyed by this.
Nick
Tom Boothby
>
> I believe that people rather than abstractions should take priority.
> We are used to using $...$ for maths, so why should we not make the
> docs markup system we use adapt to us rather than the other way round?
> I find the view 'let's keep ReST/Sphinx in Sage "pure" ' very hard to
> understand!
not upstreaming, etc. So, I think we should try and avoid it. If
nothing else, it increases the amount of effort required to upgrade.
OTOH, I'm hugely in favor of making this change to ReST/Sphinx, and
upstreaming it.
John H Palmieri
> On Sep 3, 1:22 pm, John Cremona <john.crem...@gmail.com> wrote:
>
> > I have never used Ondrej's :math: in front, but maybe I should have.
>
> I recall seeing somewhere that in ReST/Sphinx you can configure a
> default "mode" for the backticks,
the lines
# The reST default role (used for this markup: `text`) to use for all
documents.
default_role = 'math'
So in Sage docstrings you don't need ":math:".
John
David Roe
>> [X] Yes, give me $'s!
>>
>> [ ] No, this doesn't bug me; let's keep ReST/Sphinx in Sage "pure".
David
gsw
> and it bugs me that I have to type
>
> :math:`\eta`
>
> instead of just $\eta$. So how about submitting a patch to sphinx fixing it?
Cheers,
Georg
>
> Ondrej
John H Palmieri
documentation, in the part about writing extensions. So we could
write an extension for Sphinx which replaces "$" with "`", or
optionally replaces "$blah$" with ":math:`blah`". I don't want to
make it too fancy, so it ought to be a pretty simple regular
expression search and replace. How does that sound?
More precisely: we can have a Sphinx extension with a configurable
option; set one way, it will replace "$blah$" with "`blah`" (and
replace "\$" with "$"). Set the other way, it will replace "$blah$"
with ":math:`blah`" (and replace "\$" with "$").
What else should we do? Do we have to deal with "$$ blah $$"? "\
[ blah \]"? I don't want this to be too involved, or we'll end up
writing a LaTeX compiler.
John
Jason Grout
Would it be too hard to make a more general (and useful)
"custom-delimiter" extension, that would allow a person to specify a
right and left delimiter that is just textually replaced with the mode
of their choice? Our configuration would look something like:
right_delimiter='$'
left_delimiter='$'
mode=math
Jason
--
Jason Grout
John H Palmieri
write our own extension but instead to work with Sphinx's autodoc
extension. The autodoc extension is what extracts the docstrings to
create the reference manual, and it can be configured to pass the
docstrings to user-defined functions for preprocessing. I think
that's the right thing for us to do: search for "$" and replace it
with "`".
So while I think that we could make custom delimiters work, the whole
thing won't be a stand-alone extension, so this approach may not be
that useful. But I'll try to play with it.
John
John H Palmieri
but allowing no custom delimiters, no parsing of $$blah$$ or \[ blah
\]) is here:
<http://trac.sagemath.org/sage_trac/ticket/6892>
John
Ondrej Certik
I tried your patch (I made a sphinx extension out of it), but it
didn't work for me --- the backsubstitution to docstringlines failed
in the extension (maybe sphinx is inconsistent here), but this can be
fixed easily by just doing
docstringlines[:] = [s]
worse problem is that I want to change it to math:`sd`, not just `sdf`
(I have not figured it out how to do that using your indices
approach). In any case, I rewrote it so that it works for me,
attached. To install it, just add to your conf.py:
extensions = ['sphinx.ext.pngmath', "math_dollar"]
possibly adding the patch to math_dollar.py by:
sys.path.append(os.path.abspath('exts'))
So that's a very convenient solution, as I can ship it with my sphinx
notes and it will just work. Later on, after I gain more experience,
I'll ask on the sphinx list, if they want to ship this with sphinx
itself.
Ondrej
John H Palmieri
>
> I tried your patch (I made a sphinx extension out of it), but it
> didn't work for me --- the backsubstitution to docstringlines failed
> in the extension (maybe sphinx is inconsistent here), but this can be
> fixed easily by just doing
>
> docstringlines[:] = [s]
Sphinx autodoc extension, which passes "docstringlines" as an
argument: this is a list of strings, the lines of the doc string that
autodoc has extracted. You're using "source-read" which passes a
list containing one element, the entire docstring. Maybe you can
change the first line of your code to
s = source[0]
and then the last line would be
source[0] = s or source = [s]
I couldn't figure out how to use "source-read" for the Sage reference
manual, since "source" in our case is some autogenerated string that
doesn't contain the actual docstring -- you have to interact with
autodoc to get that.
> worse problem is that I want to change it to math:`sd`, not just `sdf`
> (I have not figured it out how to do that using your indices
> approach). In any case, I rewrote it so that it works for me,
> attached.
$` in the code, but there are strings like that in the Sage code --
e.g., ``$SAGE_ROOT...`` -- so I had to test for this and not replace
such dollar signs.
> So that's a very convenient solution, as I can ship it with my sphinx
> notes and it will just work. Later on, after I gain more experience,
> I'll ask on the sphinx list, if they want to ship this with sphinx
> itself.
default_role = 'math'
so you can use `x=y` instead of :math:`x=y` ? Maybe a better
question, which just occurred to me: is it worth adding some sort of
parameter to your extension so that it replaces $x=y$ by
either :math:`x=y` or `x=y`, depending on that parameter?
John
Ondrej Certik
Yeah, I will use \$ for that, if I ever need it. But yes, I agree it
should be more clever --- I think we can even combine my and your
approach.
>
>> So that's a very convenient solution, as I can ship it with my sphinx
>> notes and it will just work. Later on, after I gain more experience,
>> I'll ask on the sphinx list, if they want to ship this with sphinx
>> itself.
>
> Sounds good. I'm curious: for your own use, why don't you use
>
> default_role = 'math'
>
> so you can use `x=y` instead of :math:`x=y` ? Maybe a better
I just wasn't sure if this can't break other people's code, let's say
if they take my .rst file and include it in their project (where they
use a different definition for `...`).
> question, which just occurred to me: is it worth adding some sort of
> parameter to your extension so that it replaces $x=y$ by
> either :math:`x=y` or `x=y`, depending on that parameter?
Yeah, that should be easy to implement. Why would you ever need it
though? I thought you always need :math:`...` at the end of the day.
Btw, I just found a bug in my (and your) code, I have to change:
- s = re.sub(r"({[^{}$]*\$[^{}$]*\$[^{}$]*})", repl, s)
+ s = re.sub(r"({[^{}$]*\$[^{}$]*\$[^{}]*})", repl, s)
that's because there could be things like \mbox{adflj $x$ and $y$ and $z$}.
After this, here I converted some of my notes (I had them in xml and
used my own converter to generate latex or html, that was from before
sphinx was born). So I just wrote a simple converter to rst and
everything just works. It's awesome:
http://certik.github.com/theoretical-physics/book/src/qft.html
I will now convert all my physics and math notes into sphinx. Right
now I have them scattered over dozens latex documents, sometimes I
even lost the source, only have pdf. So this will now change, I put
everything into one git repository, and host it on github.
Ondrej