# [SciPy-dev] Of use and abuse of sphinx's math directive

nicky van foreest vanforeest@gmail....
Wed Oct 29 08:53:51 CDT 2008

Hi,

Suppose for later uses you want to export the documentation to some
format (e.g. latex, mediawiki (?) ) in which you like to make the
difference explicit between n and \$n\$. This would entail a lot of
searching. As an anecdote, Knuth used to write 1 rather than \$1\$. When
he developped the Euler font with Zapf, it turned out that 1 had a
different appearance than \$1\$. Knuth is Knuth, so he changed in all 1,
2, \ldots in one of his books that used the Euler font to \$1\$, \$2\$,
etc.

bye

Nicky

2008/10/28 Stéfan van der Walt <stefan@sun.ac.za>:
> 2008/10/28 Gael Varoquaux <gael.varoquaux@normalesup.org>:
>> Sphinx is great, will all love Sphinx. But I do wonder if sometimes we do
>> not use the math directive a bit too much, eg the "n" and "n-1" on:
>> http://scipy.org/scipy/scipy/browser/trunk/scipy/cluster/hierarchy.py#L1090
>> (this is just an example that I picked randomly).
>>
>> When the formula written is simple-enought that its readibility is not
>> too much affected by having it in text in the Sphinxified document, I
>> think it is a pitty to render the plain text docstrings hard-to-read.
>
> Certainly -- the idea is to use the :math: tag sparingly.
>
> Cheers
> Stéfan
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev@scipy.org
> http://projects.scipy.org/mailman/listinfo/scipy-dev
>