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

[nicky van foreest]

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 at sun.ac.za>:
> 2008/10/28 Gael Varoquaux <gael.varoquaux at 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 at scipy.org
> http://projects.scipy.org/mailman/listinfo/scipy-dev
>