I recently asked this question: How to display an underscore literal in math mode?; It was voted off-topic.

Based on How can I render mathematical formulas in Python Sphinx (particularly, it was migrated from StackOverflow to this site) and the mention of LaTeX in the Sphinx docs, I think it should not have been closed. However, I'm not sure and wanted to ask in meta to see what others think too.

In the meantime, I made a new question at StackOverflow if anyone is able to contribute to a solution: Sphinx LaTeX markup limitations.

See also meta.tex.stackexchange.com/q/272/86 –  Andrew Stacey Oct 23 '12 at 13:56
add comment

3 Answers

This is a tricky issue because when other software interacts or generates TeX code, it's not always easy to decide whether the problem derives from the interaction (off topic) or TeX itself (on topic).

One way to tell the difference, is if your code will compile when made into a regular LaTeX document and compiled without use of the interface. If that's the case, the problem is most likely off topic.

Although even in that case there's no completely clear dividing line. For example, many R + LaTeX questions are routinely considered on-topic here provided they are not purely R questions.

Another problem is that it's often the case when people come to TeX via this sort of route, their questions are trivial if they read a good introduction to LaTeX, which many times they haven't. (I'm not saying that this is your case.)

In the case of the new question you linked to, I think it is still off topic, since it seems to depend a lot on how the interface to LaTeX is implemented, rather than the LaTeX code itself. The question itself also contains code fragments, which makes it very hard for anyone to play with; the fact that the code is not directly LaTeX code makes the question even more off topic.

I don't understand the last few sentences. Is it the case that a question must only consist of TeX code for it to be on-topic? There are many markup languages where you express correct syntax differently than it would look in a plain TeX document, but it can be important to ask "why isn't this markup making the right thing." If the answer is, "because the markup library is wrong" then I can see it being off-topic. But if you specify the markup correctly, and the markup describes correct TeX code, but you just expressed the wrong TeX code, that would seem to be overwhelmingly on-topic. –  EMS Oct 22 '12 at 19:36
@EMS I agree with the last point, but then put the relevant TeX code into a minimal working TeX document and ask the question that way. Then there's no need to complicate the issue with a non-TeX markup system. –  Alan Munn Oct 22 '12 at 19:38
Also, even if many community members don't care to learn Sphinx, or other markup environments, it doesn't mean the questions are clutter. In my case, I'd be happy if everyone ignored my question save for the small fraction who use Python and know Sphinx. There ought to be some forum for asking questions like that, and this seems as good as any. Also, I don't like the distinction about 'trivial' questions. That same reasoning applies to beginners whether they came to TeX via a markup language or not. The whole 'what have you tried' thing... –  EMS Oct 22 '12 at 19:39
But the question might be about why the markup doesn't cause the expected TeX output. It's not about whether the markup engine is good or not, nor whether the syntax is correct or not. For example, in the Sphinx case, a user might forget the '\\' after each equation line for an array, or the & fr alignment. I don't see why they should have to translate their code to TeX first to get help on something like that. What they have is a very good minimal working example, for anyone out there who knows basic Sphinx. And it's fine to ask targeting only those responders, imo. –  EMS Oct 22 '12 at 19:41
add comment

I'd like to give another view of your question and why it got closed.

In my humble opinion, the question, as it is, doesn't provide enough information about what is being asked. I have the feeling that the error you reported is happening at the conversion time, rst -> <format>, and not the in the LaTeX -> PDF generation.

The error message clearly points at an error in the .rst file:

System Message: ERROR/3 (<fullpath>/AccrualsImplementor.rst, line 83)

You are right to think that either TeX or MathJaX (which implements a subset of TeX math stuff) will render your :math: element later on, but the parsing itself is failing, so it's not TeX fault. In this error level, it's a .rst syntax issue.

You are right in using \_ to display a literal underscore. That's the correct way of using it, including in Sphinx. I wrote the following .rst sample file:

Hello! :math:`a^2 + b^2 a\_b = c^2`.

.. math::

   (a + b)^2 = a^2 + 2ab + b^2

   (a - b)^2 = a^2 - 2ab a\_b + b^2

Then I tried to generate an HTML version:

$ make html
Running Sphinx v1.1.3
loading pickled environment... done
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] index

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index

writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in _build/html.

which gave me:

My output HTML

And then I generated the LaTeX output:

$ make latex
Running Sphinx v1.1.3
loading pickled environment... done
building [latex]: all documents
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
processing Test.tex... index
resolving references...
writing... done
copying TeX support files... done
build succeeded.

Build finished; the LaTeX files are in _build/latex.

The relevant part of the generated .tex file:


Hello! $a^2 + b^2 a\_b = c^2$.
\begin{split}(a + b)^2 = a^2 + 2ab + b^2\end{split}\notag\\\begin{split}(a - b)^2 = a^2 - 2ab a\_b + b^2\end{split}\notag


After running pdflatex, I have:

My output PDF

So you see, the problem has to rely in your .rst file.

The second part would involve posting relevant part of your code for us to reproduce your error - a minimal example. This is highly recommended, so we can track down the offending code and help you solve it. Sadly, the question only had an error message, without either the .rst or .tex code, so little we could do. :(

And since the error was not TeX-related, the question was closed as off-topic.

Don't take the closing issue too seriously, this is a great community, and I'm sure we would solve the error if it was really TeX-based. Sadly, as it is, .rst is not our cup of tea. :(

Anyway, my advice is to take a look at your .rst, I'm sure it's a markup problem, or even an error that happened some lines before and got propagated to the math part. :)

This doesn't explain why it says that \textunderscore and \textrm and \biggl or \biggr are invalid LaTeX commands. Also, as soon as I removed the underscores, everything else compiled with the docs without a problem. So I'm not buying this. –  EMS Oct 23 '12 at 13:48
However, I do totally agree with your reasoning for why it was closed as off-topic. I'm more interested in whether Sphinx-LaTeX questions are generally off-topic. I understand it in the case of my specific question. –  EMS Oct 23 '12 at 13:49
@EMS: I'm lost here, apologies for not being a Sphinx user. :) In which part of the "process" do you get those messages about \textunderscore and friends? –  Paulo Cereda Oct 23 '12 at 13:55
Check the link to the StackOverflow version of my question. When I build the documentation (e.g. invoke Sphinx's conversion to and subsequent use of TeX), I see those errors. –  EMS Oct 23 '12 at 16:01
@EMS: IMHO, I think your gather environment is the one to blame. If I remove the & right after &=, everything works fine. –  Paulo Cereda Oct 23 '12 at 16:33
Could it be a Sphinx version issue? That does not fix it for me. What version are you using? I am using: 1.1.2-1. –  EMS Oct 23 '12 at 17:00
N/M, I see that it is 1.1.3 in the answer above. Perhaps this is it. –  EMS Oct 23 '12 at 17:01
The answer, incidentally, has to do with symbols that jsMath does not recognize. The problem did not occur in the .rst file as you suggest. It was simply a matter of why TeX symbols are valid. While I agree my original question should be marked off-topic, I think Sphinx more broadly is definitely on-topic at this site. You are also mistaken about the TeX-to-PDF comment. There is no TeX to PDF step in my question, since it is doc being built for a website. And also, Sphinx does indeed use the TeX program directly. It was just jsMath which does not allow some symbols. –  EMS Oct 26 '12 at 21:40
add comment

I think that they are (and should be) off topic in general. Sphinx is, in this context, a generator of (La)TeX code. If it is generating bad code then that is a problem with the input to the generator (or the generator itself). In this respect it should be treated the same as questions about (say) a C or perl or ... program that makes LaTeX output. The site doesn't have the resources to answer questions about arbitrary programming languages that just happen to generate LaTeX.

I think in the case of Sphinx the situation is slightly obscured as the math input syntax looks latex-like, however as your question showed it is not latex and there are valid latex expressions that are not accepted by the system, so I think it is best to consider it a LaTeX generator and these, as a whole, are off topic.

Looking at the discussion on the Stack Overflow version of the question it highlights even more why it should be off topic. It appears that the TeX back end was not being used at all so that TeX was not involved and the error messages being reported were javascript errors from the old jsmath javascript library. jsmath (and its newer replacement mathjax) are also considered off topic. They parse a very restricted subset of LaTeX syntax but render it using css (or svg) and do not use TeX at all.

They aren't off-topic in general, given the link in my question above showing one that was successfully migrated from StackOverflow to this site. Also, if you follow the link to my question that's currently up at StackOverflow, one of the moderators (at both sites) suggested in the comments that it might be more appropriate here instead of there. (FWIW, I think my question probably is off-topic at this site, but many Sphinx questions would not be). Anyway, the question of whether they should be off topic is still open. –  EMS Oct 25 '12 at 18:07
Also, the solution to my question ended up being a problem with which TeX symbols are allowable in jsMath vs. mathjax. In my view, this is exactly the right community to ask about that sort of thing. –  EMS Oct 25 '12 at 18:08
Also, just to clarify, Sphinx directly uses AMSMath TeX. It doesn't generate something else. It does use unusual TeX code, but it's still TeX code. You seem to think that Sphinx is a different markup language that eventually produces TeX. That's not quite accurate. Inside of the math modes in Sphinx you are literally writing TeX code. The fact that a TeX command was invalid was an error on the part of jsMath, not Sphinx. And this meta question is about whether Sphinx is off-topic, not jsMath or mathjax. –  EMS Oct 25 '12 at 18:11
Yes I see that but if you put valid tex markup into the document and you get an error then either sphinx has generated bad tex elsewhere in the document in the conversion from restructured text, or (as in your case) TeX isn't being used at all. In either of these cases the question is clearly off topic for a TeX forum. (MathJax has specifically been considered off topic (there is a separate question here on meta discussing that) –  David Carlisle Oct 25 '12 at 18:22
TeX is being used in my case. Just not all symbols. The same error could happen in a regular TeX editor writing plain old TeX. Say I was trying to use some symbol from a package, but my environment failed to include the right package. It's not much different here. And in both cases, I would seek a community of people who were familiar with the differences in the packages for help. –  EMS Oct 25 '12 at 18:30
No, jsmath does not use TeX. It is a javascript program that parses a tex-like syntax. –  David Carlisle Oct 25 '12 at 18:38
From the Sphinx documentation: "The input language for mathematics is LaTeX markup. This is the de-facto standard for plain-text math notation and has the added advantage that no further translation is necessary when building LaTeX output." And futher: "This extension renders math via LaTeX and dvipng into PNG images. This of course means that the computer where the docs are built must have both programs available." –  EMS Oct 25 '12 at 18:42
You can also configure it to use jsMath or MathJax if you wish, but that's not Sphinx's baseline functionality. And its syntax is LaTeX syntax, not some variant. In my case, our common work system is setup to use jsMath, so my question (as I already admitted many times) would have been off-topic. But most like mine would not be. –  EMS Oct 25 '12 at 18:43
If you are generating png then my understanding is that it uses Tex, but that you were using a back end going to web pages not using images but using jsmath that does not use tex. –  David Carlisle Oct 25 '12 at 18:44
But that doesn't seem to affect the standing for general Sphinx/LaTeX questions. Just my singular question, for a very special reason. So I don't follow your generalization that my question could illustrate why general Sphinx/LaTeX questions should always be off-topic. –  EMS Oct 25 '12 at 18:46
If you are using the tex back-end then it make sense to ask the question here using the generated file that sphinx actually sends to latex (so sphinx doesn't need to be in the question) –  David Carlisle Oct 25 '12 at 18:46
let us continue this discussion in chat –  David Carlisle Oct 25 '12 at 18:47
add comment

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .