Re: [Haskell-cafe] Haddock Markup
On 15 Feb 2009, at 5:45 am, Wolfgang Jeltsch wrote: So you mean a language which * directly corresponds to a subset of MathML (and is therefore easily convertible into sensible MathML) * is at the same time valid TeX source which can be processed by TeX based on a few macro definitions (like \mrow) Yes. The thing is clearly doable in principle; whether it would work well in practice is another matter, of course. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
Am Freitag, 13. Februar 2009 01:30 schrieben Sie: On 12 Feb 2009, at 8:48 pm, Wolfgang Jeltsch wrote: I don’t understand this. The way which works is conversion from MathML to TeX. So your suggestion would be to use MathML as the source language. But this is obviously not what you suggest. I’m confused. It's explicit enough in the original message: Use a substantial chunk of MathML in a TeX-parseable syntax. If you want to use a subset of TeX in Haddock comments, how would you render them on a webpage? I didn't say a subset of TeX but a subset of MathML. [explaination follows] So you mean a language which * directly corresponds to a subset of MathML (and is therefore easily convertible into sensible MathML) * is at the same time valid TeX source which can be processed by TeX based on a few macro definitions (like \mrow) This sounds interesting, indeed. Best wishes, Wolfgang ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
On 12 Feb 2009, at 8:48 pm, Wolfgang Jeltsch wrote:
I don’t understand this. The way which works is conversion from
MathML to TeX.
So your suggestion would be to use MathML as the source language.
But this is
obviously not what you suggest. I’m confused.
It's explicit enough in the original message:
Use a substantial chunk of MathML
in a TeX-parseable syntax.
If you want to use a subset of TeX in Haddock comments, how would
you render them on a webpage?
I didn't say a subset of TeX but a subset of MathML.
MathML is two things: a set of labelled trees with some sort
of semantics, and a representation of those trees as XML.
Anything that can be written as
X a=b.../X
can also be written as
\X[b]{...}
with a reasonable amount of care. (Not necessarily the same X and b,
of course, and ... would be recursively transformed.)
Let's take this example from the web.
math mrow msup mix/mimn2/mn /msup mo+/mo mrow
mn4/mnmoInvisibleTimes;/momix/mi /mrow mo+/mo
mn4/mn /mrow /math
Step 1. Rule that letters c stand for \mi{c} unless otherwise
quoted. Rule that digit sequences d stand for \mn{d} unless
otherwise quoted. Rule that normal operators x stand for \mo{x}
unless otherwise quoted. Rule that x^y stands for
\msup{x}{y}. Rule that x_y stands for \msub{x}{y}.
Step 2. Introduce names for (some) things MathML has, like
InvisibleTimes; and TeX does not.
Step 3. Write a checker that enforces the conventions.
By step 3, we have the ability to write
\mathml{\mrow{x^2 + \mrow{4\itimes x} + 4}}
and have LaTeX process it directly. The advantage of this stuff
is that you can put it in your technical papers. Why bother?
Because of the checker. (I do not have such a program. This is
a design sketch on a tablecloth, not to be taken any more seriously
than that.) Why not use MathML? (La)TeX macros spring to mind as
a good reason... Not having to use XML as another.
Step 4. Based on the checker, write a program to convert this
notation to MathML. MathML was, after all, designed for machines
to write and read; it is not practical for people to write and it
couldn't be called even remotely readable by its best friend.
That makes it a pretty appalling choice for something to write
in Haddock comments in source files.
By step 4, you have something you can check better than standard
TeX, something you can cut and paste between TeX papers and
Haddock documentation without making the source code unreadable,
and at the same time something that can be converted to MathML
any time you want.
By the way, I wonder very much how much semantics people _are_
putting into their MathML? The INEX consortium of people doing
XML-based information retrieval have run into the problem that
there is very little semantic markup out there, so for getting
semantics out XML is *in practice as yet* little or no advance
on plain text. Even with an equation editor, writing formulas
on a computer is enough work that I'd expect people to do the
minimum they need for the immediate taste, even using MathML.
I don't have a body of MathML to examine, so I make no empirical
claim here, I just raise the question.
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
On Fri, 2009-02-13 at 13:30 +1300, Richard O'Keefe wrote: Let's take this example from the web. math mrow msup mix/mimn2/mn /msup mo+/mo mrow mn4/mnmoInvisibleTimes;/momix/mi /mrow mo+/mo mn4/mn /mrow /math NB: This example is *precisely* why I will never adopt MathML as an authoring format. Bowing and scraping at the alter of W3C is not worth using such a terrible syntax, not ever. (Indented, that's math mrow msup mix/mi mn2/mn /msup mo+/mo mrow mn4/mn moInvisibleTimes;/mo mix/mi /mrow mo+/mo mn4/mn /mrow /math Which is still unforgivably horrible. I *think* it's trying to say $x^2 + 4x + 4$, but I'm not confident even of that. I'm also unconvinced it's actually easier to parse than $x^2 + 4x + 4$.) jcc ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
Am Mittwoch, 11. Februar 2009 00:46 schrieben Sie: I suppose I should point out what seems obvious to me, which is that one could embed a substantial chunk of MathML (possibly all of it) in TeX. I mean, give it a TeX-parseable syntax. You can convert MathML into TeX but not the other way round. How would you translate $a \odot b \otimes c$? It depends on the precedence of the operators. Best wishes, Wolfgang ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
On 12 Feb 2009, at 1:40 am, Wolfgang Jeltsch wrote: Am Mittwoch, 11. Februar 2009 00:46 schrieben Sie: I suppose I should point out what seems obvious to me, which is that one could embed a substantial chunk of MathML (possibly all of it) in TeX. I mean, give it a TeX-parseable syntax. You can convert MathML into TeX but not the other way round. How would you translate $a \odot b \otimes c$? It depends on the precedence of the operators. And the point of that is? What I suggested is the way around that works. And the point of my suggestion was that one could have something that could be embedded directly in a (La)TeX document *or* processed by Haddock: no changes when copying from one document to another means fewer new mistakes. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
Am Mittwoch, 11. Februar 2009 22:38 schrieben Sie: On 12 Feb 2009, at 1:40 am, Wolfgang Jeltsch wrote: Am Mittwoch, 11. Februar 2009 00:46 schrieben Sie: I suppose I should point out what seems obvious to me, which is that one could embed a substantial chunk of MathML (possibly all of it) in TeX. I mean, give it a TeX-parseable syntax. You can convert MathML into TeX but not the other way round. How would you translate $a \odot b \otimes c$? It depends on the precedence of the operators. And the point of that is? What I suggested is the way around that works. And the point of my suggestion was that one could have something that could be embedded directly in a (La)TeX document *or* processed by Haddock: no changes when copying from one document to another means fewer new mistakes. I don’t understand this. The way which works is conversion from MathML to TeX. So your suggestion would be to use MathML as the source language. But this is obviously not what you suggest. I’m confused. If you want to use a subset of TeX in Haddock comments, how would you render them on a webpage? Best wishes, Wolfgang ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
Am Dienstag, 10. Februar 2009 02:56 schrieben Sie: On 10 Feb 2009, at 1:19 am, Wolfgang Jeltsch wrote: This is only true if your destination format is PDF, DVI or PS. For a webpage, you’ll need MathML in the end and TeX is not so good in producing MathML, I suppose. Hmm. I find designed-for-HTML documentation horrible. I did *not* want to argue pro “designed-for-HTML”. I wanted to argue contra “designed-for-PDF” and pro “designed-for-any-output-format”. Best wishes, Wolfgang ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
Wolfgang Jeltsch schrieb: This reminds me of an idea which I had some time ago. The idea is to write all your documentation in Template Haskell, possibly using quasiquoting to support Haddock-like syntax. Then you could write math as ordinary Haskell expressions and embed these expressions into your documentation expressions. This would make the documentation language very extensible since you could always write your own extensions in the form of some Haskell code fragments or libraries. If Template Haskell is capable of such processing that we be great since we wouldn't need to develop a new tool, but can concentrate on writing the transformations to TeX, MathML and so on. And if someone wants to include chemical formulas he may write appropriate transformations himself, upload them to Hackage, and cabal will be able to install them when needed. Everything becomes scalable, extensible, flexible and everything becomes great. Even versioning conflicts will become possible for documentation generation. :-) ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
Am Samstag, 7. Februar 2009 13:46 schrieb Khudyakov Alexey: On Friday 06 February 2009 21:24:35 Andy Smith wrote: 2009/2/6 Wolfgang Jeltsch g9ks1...@acme.softbase.org: So using TeX as a general language for math is a very bad idea, in my opinion. The problem is that there is no good language which provides enough structural information for conversion into MathML and is at the same time simple to write and read. Maybe, both requirements contradict. ASCIIMathML [1] is designed to do this. It doesn't cover everything in Presentation MathML, and makes no attempt to handle Content MathML, but you can do quite a lot with it. The notation has a formally defined grammar and rules for conversion to MathML [2]. [1] http://www1.chapman.edu/~jipsen/asciimath.html [2] http://www1.chapman.edu/~jipsen/mathml/asciimathsyntax.html TeX aim is presentation quality not structural information. And it's rather good at it. If one want really good looking formulae TeX is the answer. This is only true if your destination format is PDF, DVI or PS. For a webpage, you’ll need MathML in the end and TeX is not so good in producing MathML, I suppose. ASCIIMathML is nice but its produce not so good looking formulae. How can you say that in general? ASCIIMathML can be converted into several formats (in principal) and is usually converted into MathML. And the rendering of MathML depends very much on the browser, plugin or whatever. Are there general deficiencies in ASCIIMathML or its usual conversion into MathML that prevent any MathML renderer from doing a good job? Or is it just a problem with your concrete MathML renderer? I've tried it some time ago and found it clearly inferior to TeX. It gives too little control over presentation. If you want a format suitable for multiple output formats (including more strucuture-oriented ones like MathML) than control over presentation is probably not what you want. I wasn't able even to place integration indices exactly over and under integral sign. In my opinion, you should just say what the indices are and the renderer should place them correctly. If it doesn’t, it’s a failure of the renderer, not of ASCIIMathML. Best wishes, Wolfgang ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
Wolfgang Jeltsch wrote:
TeX is not so great for mathematics and especially not for conversion into
MathML (which would be needed for HTML output). The TeX math language
provides rather little semantic information. As input language for the
concrete software named TeX this is mostly okay since the concrete rendering
algorithm of TeX doesn’t need certain information (for example, about
implicit bracketing).
However, even for rendering with TeX, you sometimes have to ressort to ugly
tricks since TeX sometimes misinterprets what you wrote. Knuth gives some
examples in chapter 18 of The TeXbook. For conversion into MathML, a TeX
source generally doesn’t have enough information since even presentation
MathML code contains much more structure than ordinary TeX source code does.
So using TeX as a general language for math is a very bad idea, in my opinion.
The problem is that there is no good language which provides enough
structural information for conversion into MathML and is at the same time
simple to write and read. Maybe, both requirements contradict.
I want for long to write math formulas in a paper in Haskell. Actually,
lhs2TeX can do such transformations but it is quite limited in handling
of parentheses and does not support more complicated transformations
(transforming prefix notation in infix notation or vice versa with
minimal parentheses).
I would like to write
sumFor [0..n] (\i - i^2)
(with sumFor xs f = sum $ map f xs)
which is rendered as
\sum_{i=0}^{n} i^2
or
integrate 1000 (a,b) (\t - f t)
to be rendered as
\int_a^b f(t) \dif t
I imagine some rule based configuration that is implemented using
haskell-src, that handles all identifiers, say, with prefix parameter
as wildcards:
sumFor [parameterA..parameterB] (\parameterI - parameterS)
=\sum_{parameterI=parameterA}^{parameterB} parameterS
Unfortunately a tool for this transformation still has to be written,
but wouldn't that be really cool? The tool might be even relatively
simple, but the configuration is certainly non-trivial and it would have
to be hard-wired into cabal in order to provide identical rendering on
all systems and output formats (TeX or MathML).
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
Khudyakov Alexey wrote: I think MathML is much less accessible than images. Yes, there are problems with them but any browser is able to display them save for text based ones. MathML on contrary doesn't have much support. According to wikipedia only recent versions of gecko based browsers and opera =9.5 can do this. For IE special plugin is required (MathPlayer). I believe image are safest way at least for now. As far as I know, Haddock is not bound to HTML output. (And if it is bound this way, I wished it wouldn't.) For PDF Haddock output TeX formula will be the best choice, whereas for HTML, MathML or embedded images are the best. I expect there will be no consensus and the Haddock user should decide how he wants the formulas to be rendered. That's best generated from a structure preserving notation of math formulas (like Haskell expressions). ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
On Mon, 2009-02-09 at 15:18 +0100, Henning Thielemann wrote: Khudyakov Alexey wrote: I think MathML is much less accessible than images. Yes, there are problems with them but any browser is able to display them save for text based ones. MathML on contrary doesn't have much support. According to wikipedia only recent versions of gecko based browsers and opera =9.5 can do this. For IE special plugin is required (MathPlayer). I believe image are safest way at least for now. As far as I know, Haddock is not bound to HTML output. (And if it is bound this way, I wished it wouldn't.) Right, it's not. Though there are not many other backends. Translating haddock markup into pandoc or docbook might be an easy way to get more. For PDF Haddock output TeX formula will be the best choice, whereas for HTML, MathML or embedded images are the best. I expect there will be no consensus and the Haddock user should decide how he wants the formulas to be rendered. That's best generated from a structure preserving notation of math formulas (like Haskell expressions). Right, the problem is that since it is not bound to a specific output format then it cannot use embedded tex or whatever. The current haddock markup is deliberately very limited and simple so that it can be rendered in more or less any output format. Duncan ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
Wolfgang Jeltsch-2 wrote: This is only true if your destination format is PDF, DVI or PS. For a webpage, you’ll need MathML in the end and TeX is not so good in producing MathML, I suppose. Has jsMath been considered as an alternative to images in HTML? (http://www.math.union.edu/~dpvc/jsMath/) It's supposed to work on most browsers, and the screen output is very nice. -- View this message in context: http://www.nabble.com/Haddock-Markup-tp21864389p21914911.html Sent from the Haskell - Haskell-Cafe mailing list archive at Nabble.com. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
Am Montag, 9. Februar 2009 15:10 schrieben Sie:
I want for long to write math formulas in a paper in Haskell. Actually,
lhs2TeX can do such transformations but it is quite limited in handling
of parentheses and does not support more complicated transformations
(transforming prefix notation in infix notation or vice versa with
minimal parentheses).
[…]
I imagine some rule based configuration that is implemented using
haskell-src, that handles all identifiers, say, with prefix parameter
as wildcards:
sumFor [parameterA..parameterB] (\parameterI - parameterS)
=\sum_{parameterI=parameterA}^{parameterB} parameterS
Unfortunately a tool for this transformation still has to be written,
but wouldn't that be really cool? The tool might be even relatively
simple, but the configuration is certainly non-trivial and it would have
to be hard-wired into cabal in order to provide identical rendering on
all systems and output formats (TeX or MathML).
This reminds me of an idea which I had some time ago. The idea is to write all
your documentation in Template Haskell, possibly using quasiquoting to
support Haddock-like syntax. Then you could write math as ordinary Haskell
expressions and embed these expressions into your documentation expressions.
This would make the documentation language very extensible since you could
always write your own extensions in the form of some Haskell code fragments
or libraries.
To build the documentation, one would run GHC with a special flag or whatever
which makes the Template Haskell parts build HTML or whatever. Without the
flag, the documentation code would do nothing. By using Template Haskell, one
would have access to information about identifiers, types etc. A basic
Haddock Haskell library could provide functions which use that information to
build HTML or whatever from the actual documentation. These functions would
then be used in the Template Haskell code.
Does this make some sense?
Best wishes,
Wolfgang
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
On 10 Feb 2009, at 1:19 am, Wolfgang Jeltsch wrote: This is only true if your destination format is PDF, DVI or PS. For a webpage, you’ll need MathML in the end and TeX is not so good in producing MathML, I suppose. Hmm. I find designed-for-HTML documentation horrible. In many ways the current Haddock output is the worst of both worlds: it is inconvenient for on-screen viewing and doesn't exploit paper very well either. Amongst other things, people who are learning a library package need overviews, examples, conceptual models, all sorts of details, whereas people who already know them mainly need reminders, for which web pages are well suited. I would point out that you DON'T need MathML for a web page, because a PDF document can *be* a web page. You can link to one, you can display it in your browser, and it may contain links to other pages. Especially if one can download a tolerably full snapshot of the library and all its documentation, updating this at rare intervals, PDF-on-the-local-host suits me much better than HTML-on-the-Web. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
Am Freitag, 6. Februar 2009 21:17 schrieben Sie: It doesn't really matter if TeX is a good or bad idea for writing maths. For our users, they might do a formula if it's TeX, they won't if it's something else. Oh, what ignorant users! ;-) Well, if this discussion is about changing the real Haddock (not about making a fork) than the arguments about TeX not being good as a general math language should count, I’d say. Best wishes, Wolfgang ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
On Friday 06 February 2009 21:24:35 Andy Smith wrote: 2009/2/6 Wolfgang Jeltsch g9ks1...@acme.softbase.org: So using TeX as a general language for math is a very bad idea, in my opinion. The problem is that there is no good language which provides enough structural information for conversion into MathML and is at the same time simple to write and read. Maybe, both requirements contradict. ASCIIMathML [1] is designed to do this. It doesn't cover everything in Presentation MathML, and makes no attempt to handle Content MathML, but you can do quite a lot with it. The notation has a formally defined grammar and rules for conversion to MathML [2]. [1] http://www1.chapman.edu/~jipsen/asciimath.html [2] http://www1.chapman.edu/~jipsen/mathml/asciimathsyntax.html TeX aim is presentation quality not structural information. And it's rather good at it. If one want really good looking formulae TeX is the answer. ASCIIMathML is nice but its produce not so good looking formulae. I've tried it some time ago and found it clearly inferior to TeX. It gives too little control over presentation. I wasn't able even to place integration indices exactly over and under integral sign. P.S. Maybe I just to used to TeX. -- Khudyakov Alexey ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
On Friday 06 February 2009 13:31:34 George Pollard wrote: My comment isn't related to the wider implications of third-party hooks into Haddock, but just for the (La?)TeX stuff itself. I think that the TeX *language* is great for writing mathematics, but that we should be wary of blindly incorporating TeX *output* into Haddock. Most of Haddock's documentation is currently HTML-based, and if we add TeX mathematics in the usual way (i.e. embedding images) it is very ‘inaccessible content’ (no selection, scaling, and a myriad of other small niggles) compared to the rest of the HTML file. My thoughts would be to use the TeX engine itself for when generating high-quality PDF documentation, and have something else translate TeX to (e.g.) MathML for the HTML pages. There are various programs to do this (or it could be done in Haskell :D!) Thanks, - George I think MathML is much less accessible than images. Yes, there are problems with them but any browser is able to display them save for text based ones. MathML on contrary doesn't have much support. According to wikipedia only recent versions of gecko based browsers and opera =9.5 can do this. For IE special plugin is required (MathPlayer). I believe image are safest way at least for now. -- Khudyakov Alexey ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
On Fri, Feb 6, 2009 at 12:35 AM, David Waern david.wa...@gmail.com wrote: [..] As for running arbitrary commands, I think we are opening up to a lot of unfamiliar syntax. I'd like to hear what everyone thinks about that. How do I find out what I need to install in order to build documentation for a specific package on Hackage? (Will cabal be extended to introduce dependencies on tools?) There's also the distinct risk that someone's system gets completely hosed by running Haddock on a Haskell source file. I'm not necessarily saying it's a security problem (though that aspect is worth considering), I'm more worried about someone writing Haddock docs that rely on system layout. I'd say limiting it to a set of application, a set that grows as needed, where each tool satisfies the following: * readily available on all platforms that has a Haskell runtime that Haddock is happy with * traditionally used to process or generate text/images (somewhat vague but e.g. no cop-out by adding bash to the set) Adding LaTeX now, and other tools as needed/requested later would be my suggestion. /M -- Magnus Therning(OpenPGP: 0xAB4DFBA4) magnus＠therning．org Jabber: magnus＠therning．org http://therning.org/magnus identi.ca|twitter: magthe ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
On Fri, 2009-02-06 at 01:35 +0100, David Waern wrote: I received this question from Lennart Augustsson (via Simon M) and thought I'd send out an inquiry to the Haskell community in general (Lennart, I hope you don't mind): Lennart writes: We have some local patches for haddock that extends the blah syntax so you can put TeX formulae in the documentation. It looks like, ! LaTeX stuff here !, but I'd like to extend it so you can process the string with any command. Are you interested in folding this into the main branch? So the question is about extending the Haddock markup language. When modifying the language we should think about the tension between familiarity, presentation features (pictures, math, whatever) and visual portability across different mediums (HTML, ghci, IDE tooltips, etc). And here I should say that Haddock already supports pictures using the url syntax. IMHO, adding ! LaTeX ! for TeX math is fine, because: - math in documentation is often useful - if you're going to write math, you need a format, even when the medium is plain text as in ghci. - TeX formulae seem to be relatively widely used and understood. My comment isn't related to the wider implications of third-party hooks into Haddock, but just for the (La?)TeX stuff itself. I think that the TeX *language* is great for writing mathematics, but that we should be wary of blindly incorporating TeX *output* into Haddock. Most of Haddock's documentation is currently HTML-based, and if we add TeX mathematics in the usual way (i.e. embedding images) it is very ‘inaccessible content’ (no selection, scaling, and a myriad of other small niggles) compared to the rest of the HTML file. My thoughts would be to use the TeX engine itself for when generating high-quality PDF documentation, and have something else translate TeX to (e.g.) MathML for the HTML pages. There are various programs to do this (or it could be done in Haskell :D!) Thanks, - George signature.asc Description: This is a digitally signed message part ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
Am Freitag, 6. Februar 2009 11:31 schrieb George Pollard: I think that the TeX *language* is great for writing mathematics, but that we should be wary of blindly incorporating TeX *output* into Haddock. Most of Haddock's documentation is currently HTML-based, and if we add TeX mathematics in the usual way (i.e. embedding images) it is very ‘inaccessible content’ (no selection, scaling, and a myriad of other small niggles) compared to the rest of the HTML file. My thoughts would be to use the TeX engine itself for when generating high-quality PDF documentation, and have something else translate TeX to (e.g.) MathML for the HTML pages. There are various programs to do this (or it could be done in Haskell :D!) TeX is not so great for mathematics and especially not for conversion into MathML (which would be needed for HTML output). The TeX math language provides rather little semantic information. As input language for the concrete software named TeX this is mostly okay since the concrete rendering algorithm of TeX doesn’t need certain information (for example, about implicit bracketing). However, even for rendering with TeX, you sometimes have to ressort to ugly tricks since TeX sometimes misinterprets what you wrote. Knuth gives some examples in chapter 18 of The TeXbook. For conversion into MathML, a TeX source generally doesn’t have enough information since even presentation MathML code contains much more structure than ordinary TeX source code does. So using TeX as a general language for math is a very bad idea, in my opinion. The problem is that there is no good language which provides enough structural information for conversion into MathML and is at the same time simple to write and read. Maybe, both requirements contradict. Best wishes, Wolfgang ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
2009/2/6 Wolfgang Jeltsch g9ks1...@acme.softbase.org: So using TeX as a general language for math is a very bad idea, in my opinion. The problem is that there is no good language which provides enough structural information for conversion into MathML and is at the same time simple to write and read. Maybe, both requirements contradict. ASCIIMathML [1] is designed to do this. It doesn't cover everything in Presentation MathML, and makes no attempt to handle Content MathML, but you can do quite a lot with it. The notation has a formally defined grammar and rules for conversion to MathML [2]. [1] http://www1.chapman.edu/~jipsen/asciimath.html [2] http://www1.chapman.edu/~jipsen/mathml/asciimathsyntax.html Andy ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
It doesn't really matter if TeX is a good or bad idea for writing maths. For our users, they might do a formula if it's TeX, they won't if it's something else. -- Lennart On Fri, Feb 6, 2009 at 4:03 PM, Wolfgang Jeltsch g9ks1...@acme.softbase.org wrote: Am Freitag, 6. Februar 2009 11:31 schrieb George Pollard: I think that the TeX *language* is great for writing mathematics, but that we should be wary of blindly incorporating TeX *output* into Haddock. Most of Haddock's documentation is currently HTML-based, and if we add TeX mathematics in the usual way (i.e. embedding images) it is very 'inaccessible content' (no selection, scaling, and a myriad of other small niggles) compared to the rest of the HTML file. My thoughts would be to use the TeX engine itself for when generating high-quality PDF documentation, and have something else translate TeX to (e.g.) MathML for the HTML pages. There are various programs to do this (or it could be done in Haskell :D!) TeX is not so great for mathematics and especially not for conversion into MathML (which would be needed for HTML output). The TeX math language provides rather little semantic information. As input language for the concrete software named TeX this is mostly okay since the concrete rendering algorithm of TeX doesn't need certain information (for example, about implicit bracketing). However, even for rendering with TeX, you sometimes have to ressort to ugly tricks since TeX sometimes misinterprets what you wrote. Knuth gives some examples in chapter 18 of The TeXbook. For conversion into MathML, a TeX source generally doesn't have enough information since even presentation MathML code contains much more structure than ordinary TeX source code does. So using TeX as a general language for math is a very bad idea, in my opinion. The problem is that there is no good language which provides enough structural information for conversion into MathML and is at the same time simple to write and read. Maybe, both requirements contradict. Best wishes, Wolfgang ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Markup
On Fri, Feb 6, 2009 at 12:17 PM, Lennart Augustsson lenn...@augustsson.net wrote: It doesn't really matter if TeX is a good or bad idea for writing maths. For our users, they might do a formula if it's TeX, they won't if it's something else. Generally, I'd agree, but I just took a look at AsciiMathML, and it's pretty TeX-like. Personally, I'd consider using it, if it meant I could get decent-looking formulae in my HTML Haddocks. -- Lennart --Max ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
