[Doc-SIG] The docs, reloaded

[John Gabriele]

On 5/21/07, Neal Becker <ndbecker2 at gmail.com> wrote:
> skip at pobox.com wrote:
>
> >     >>> What would be my choices for add math to the documentation?
> >
> >     >> Where in the current documentation is there any math notation /at
> >     >> all/?
> >
> >     Georg> There is exactly one instance of LaTeX math in the whole docs,
> >     Georg> it's in the description of audioop, AFAIR, an contains a sum
> >     over Georg> square roots...
> >
> >     Georg> So, that's not really a concern of mine ;)
> >
> > You must realize that people will use the core tools to create
> > documentation
> > for third party packages which aren't in the core.  If you replace LaTeX
> > with something else I think you need to keep math in mind whether it's
> > used in the core documentation or not.
> >
> Perhaps my comment was misunderstood.  I have no objection to a new system,
> and it does not have to be based on latex.  I just hope there will be some
> escape mechanism that allows math.  It happens that for math markup, there
> isn't really anything better (or more familiar) than latex.

I'm fairly new to reST, and don't know all the ins and outs of it, but
I'd always just assumed that either there is or there will be a simple
way to escape to TeX math notation. That is, such that when you run
``rst2latex``, your equations will come through unscathed. And when
you run ``rst2html``, well, probably png's will get generated and the
html will just link to them as inline images (of course, you'll need a
TeX implementation installed for that).

Writing equations as done with TeX/LaTeX is so universal and
well-known that even if the docutils folks used some other notation
for mathematics in reST-formatted docs, a way to use TeX-style math
would certainly pop out of the woodwork at some point. There's a lot
of folks out there using LaTeX because they need to put math in their
docs, and don't really have any other workable option.

---John