Merge remote branch 'smcv/ready/transient-tag'
[ikiwiki] / doc / todo / latex.mdwn
1 How about a plugin adding a
2 [[preprocessor_directive|ikiwiki/directive]] to render some given LaTeX
3 and include it in the page?  This could either render the LaTeX as a PNG via
4 [[!debpkg dvipng]] and include the resulting image in the page, or perhaps
5 render via [HeVeA](http://pauillac.inria.fr/~maranget/hevea/index.html),
6 [TeX2page](http://www.ccs.neu.edu/~dorai/tex2page/tex2page-doc.html), or
7 similar. Useful for mathematics, as well as for stuff like the LaTeX version
8 of the ikiwiki [[/logo]].
9
10 > [[users/JasonBlevins]] has also a plugin for including [[LaTeX]] expressions (by means of `itex2MML`) -- [[plugins/mdwn_itex]] (look at his page for the link). --Ivan Z.
11
12 >> I've [[updated|mdwn_itex]] Jason's plugin for ikiwiki 3.x.  --[[wtk]]
13
14 ----
15
16 ikiwiki could also support LaTeX as a document type, again rendering to HTML.
17
18 > [[users/JasonBlevins]] has also a [[plugins/pandoc]] plugin (look at his page for the link): in principle, [Pandoc](http://johnmacfarlane.net/pandoc/) can read and write [[LaTeX]]. --Ivan Z.
19
20 ----
21
22 Conversely, how about adding a plugin to support exporting to LaTeX?
23
24 >> I did some tests with using Markdown and a customized HTML::Latex and html2latex
25 >> and it appears it will work for me now. (I hope to use ikiwiki for many
26 >> to collaborate on a printed book that will be generated at least once per day in PDF format.)
27 >>
28 >> --JeremyReed
29
30 >>> Have a look at [pandoc](http://code.google.com/p/pandoc/).  It can make PDFs via pdflatex. --[[roktas]]
31
32 >>>> Interesting, just yesterday I was playing with pandoc to make PDFs from my Markdown. Could someone advise me on how to embed these PDFs into ikiwiki? I need some guidance in implementing this. --[[JosephTurian]]
33
34 >>>> [[users/JasonBlevins]] has a [[plugins/pandoc]] plugin (look at his page for the link). --Ivan Z.
35
36 ----
37
38 [here](http://ng.l4x.org/gitweb/gitweb.cgi?p=ikiwiki.git/.git;a=blob;f=IkiWiki/Plugin/latex.pm) is a first stab at
39 a latex plugin. Examples [here](http://ng.l4x.org/latex/). Currently without image support for hevea. And the latex2html
40 output has the wrong charset and no command line switch to change that. Dreamland.
41
42 As this link is not working, I setted a mirror here: <a href="http://satangoss.sarava.org/ikiwiki/latex.pm">http://satangoss.sarava.org/ikiwiki/latex.pm</a>.
43
44
45 ----
46
47 Okay, now is the time for a mid term report i think.
48
49 The LaTeX Plugin for ikiwiki is now usable, except for the security check. This means at the moment the latex code is not validated, but only added into a very basic latex template. and the image is generated via this path: latex -> dvips -> convert (.tex -> .dvi -> .ps -> .png).
50 The resulting .png is moved into the imagefolder. The name of this image is the md5hash of the code the user wrote into the wiki. So on a second run there is no need to recreate this image, if it exists. This will fasten up all but the first generation of the page. 
51 The generation of the image is done in an temporary folder in /tmp created with tempdir from File::Temp. The tmp-folder name is something like: $md5sumdigest.XXXXXXXX. if there is an .tex file already in this dir it will be overwritten. 
52
53 So until now i finished the basic things, now the most important task is to make an good input validation.
54 This is a bit eased since it is not possible to execute shell commands in perl. Furthermore adding additional packages won't work since the code comes from the user is inserted after \begin{document}. Therefore this will result in an error (and this will stop latex from working --> no image is created).
55
56 So my task for the next weeks is to write an good input validation. 
57 I think this progress is okay, since I'll had to learn the last 5-6 weeks for my final exams in university therefore I can't do anything. From now on I have 3 months of freetime and I'll use them to work heavily on this plugin. 
58 So I think I'm inside my own timetable. :)
59
60 ps: Since I found nothere the possibility to upload an file, here is an link to my page where you can have a look. Comments are very welcome ;-)
61 https://www.der-winnie.de/~winnie/gsoc07/tex.pm
62
63 You'll find an demo site here:
64 https://www.der-winnie.de/wiki/opensource/gsoc2007/
65 I'll add some more complex formulas over the days. But this is basically only pure latex. ;-)
66
67 -- Patrick Winnertz
68
69 > Looks like you're very well on schedule.
70
71 > But I wonder: Do you have any plans to work on the latex to html side of
72 > things too? This page kinda combines both uses of latex; creating gifs
73 > for formulas etc, and creating html. Dreamland already has a latex2html
74 > using plugin submitted above, but it still needs some work, and
75 > particularly, needs the same input validation stuff. And then there's the
76 > idea of using html2latex, to convert an ikiwiki site into a book. Any
77 > plans to work on that too? I guess I'm not sure what the scope is of what
78 > you plan to do as part of GSoC.
79
80 >> Yes I plan to write an html -> tex (or pdf) plugin as well. But I think it is better to work first on the first one and complete it and then work and complete the second one. If it is in the scope of GSoC i don't know, but I'll write it since it is fun to write on an Opensource project ;-)
81
82 >> For latex-> html:
83 >> I have the problem that I don't really see the sense to create html code (this means text or charts) from latex code. But if you like I can also add this variant to create html code. In my eyes it is much more important that it is possible to have complex chemical/physical & math formulas on the website without the need to use extern programs. (and upload the pictures manually).
84
85 >>> Well, I suppose someone might just like latex and want to use it as the
86 >>> markup for their wiki, rather than learning markdown. I guess Midnight
87 >>> wanted it enough to write his plugin. But the use case is not too
88 >>> compelling to me either, honestly. --[[Joey]]
89
90 ### code review
91
92 > The main problem I see with the code is that you seem to unnecessarily create a dummy div tag
93 > in preprocess, and then in format you call create(), which generates an img tag. So, why not 
94 > just create the img tag in preprocess?
95
96 >> Mh okay, I'll improve this. 
97
98 Fixed
99
100 > Another problem: Looks like if latex fails to create the image, the user won't be shown any
101 > of its error message, but just "failed to generate image from code". I suspect that in this 
102 > case being able to see the error message would be important.
103
104 >> Yes, that's true. It would be _very_ hard to provide the user the output of latex since this is really very much. For an simple formula as \frac{1}{2} this could be 2 printed out.
105
106 >>> YM 2 printed pages? Yes, I'm familar with latex's insane errors. :-)
107 >>> However, IMHO, it's worth considering this and doing something. Perhaps
108 >>> put the error inside some kind of box in the html so it's delimited
109 >>> from the rest of the page. (Actually, ikiwiki preprocessor directives in
110 >>> general could mark up their errors better.)
111
112 Okay, I'll provide the log as an link in the wiki. But there should be a kind of mechanism how they can be removed. This could lead to an DOS (create via a bot so much nonsense code that the disk is full.)
113
114 Fixed, the log is now provided if latex will fail.
115
116 > The url handling could stand to be improved. Currently it uses $config{url}, so it depends on that being set. Some ikiwiki builds don't have an url set. The thing to do is to use urlto(), to generate a nice relative url from the page to the image. 
117
118 >> Mh... i choose one single dir explizitly since if you use on several pages the same formula  this would really improve the time to generate the formulas and it would waste extra space if you store every formula 3-4 times. But if you really like I'll change this behaviour. 
119
120 >>> No, that makes sense! (My comments about $config{url} still stand
121 >>> though.
122
123 Yes of course, I'll improve the url handling. My comment was only about the several folder ;-)
124
125 Fixed. Now I use urlto and will_render.
126
127 > Another (minor) problem with the url handling is that you put all the images in a "teximages" directory in the toplevel of the wiki. I think it would be better to put each image in the subdirectory for the page that created it. See how the `img` and `sparkline` plugins handle this.
128
129 > It looks like if the tempdir already exists, tempdir() will croak(), thus crashing ikiwiki. It would be good to catch a failure there and fail more gracefully.
130
131 >> Okay, I'll improve this behaviour. Maybe: if tempdir croak rerun it to get another not existing dir? (But only x times so that this is no endless loop, with x maybe = 3). 
132 >> Then it would not be necessary to inform the user about not generating the image. 
133
134 >>> Or just propigate up an error message. If it's failing, someone is
135 >>> probably trying to DOS ikiwiki or something. :-)
136
137 Fixed. I now use eval { create_tmp } and then:  if ($?) { $returncode = 0 } else { save .tex file ... } ...
138
139
140 > I'm not sure why you're sanitising the PATH before calling latex. This could be problimatic on systems where latex is not in /bin or /usr/bin
141
142 >> Okay what do you suggest to use as PATH? 
143 >> I'll have to change the default settings, since we ikiwiki runs in taint mode. (which is good ;-))
144
145 >>> But, ikiwiki already sanitises path and deletes the IFS and CDPATH etc.
146 >>> See ikiwiki.in.
147
148 Fixed. I'll removed these two lines completly.
149
150 -----
151 Okay here an short timetable how I want to proceed further:
152
153 * Until weekend (21-22. July) I'll try to fix all errors above. (done)
154 * From 22.July until 29. July I'll try to set up a first security check
155   My plans are two parts of a security check:
156     * One with an array of blacklisted regular expression. (This would blacklist all the well known and easy to fetch things like \include {/path/to/something} and things like closing the math formula environment ($$). (done)
157     * the second step will be based on Tom::latex, which will help to parse and get a tree view of the code.
158
159 Okay what do you think of this procedure?
160
161 > --[[Joey]]
162
163 >> -- [[PatrickWinnertz]]
164
165 ----
166
167 > It would be nice if it would output image tags with style="height:1em;" so that the formulas scale
168 > with the rest of the text if you change the font size in your browser (ctrl + +/-).
169
170
171 Thanks for the comment.. is fixed. 
172 Mh... not really fixed :S I added it into the return but it is somehow ignored. I'll figure out why.
173
174 -----
175
176 Okay, the last version of the tex plugin for ikiwiki can be downloaded [here](https://www.der-winnie.de/~winnie/gsoc07/tex.pm). 
177
178 > I've looked this over, fixed the indenting, fixed some variable names
179 > ("$foo" is a bad variable name), removed a gratuotuous use of `tie`,
180 > fixed a bug (the first time it was run, it tried to write the png file
181 > before the teximages/ directory existed) and checked the result in.
182
183 > Can you please flesh out [[plugins/teximg]] with
184 > whatever documentation people who know tex will expect to see?
185
186 Okay, I'll fill this up today I think with information about the plugin
187
188 Done. Is that docu fine with you?
189
190 >> Perhaps add some documentation about the kind of tex code that can be
191 >> used, or a link to some documentation so people who don't know latex
192 >> well can figure this out?
193
194 > Also, please review my changes. In particular, I changed the @badthings
195 > array to use qr//, which is much clearer, but it needs to be tested that
196 > I didn't break the checking code when I did it. It would be nice to write
197 > a test case that tries to feed it bad code and makes sure it rejects it.
198
199 I'll test this now on my server. I'll report here later.
200 Okay, checked. it works fine. My blacklist tests were successfull.
201
202 >
203 > Does it really make sense to have an alt tag for the image
204 > that contains the tex code? Will that make any sense when browsing
205 > without images?
206
207 Mh.. For people who know latex very well this would be enough to imagine how the image would look like. 
208 This are of course the minority of people (but I guess also the minority of people are using non-gui browsers).
209
210
211
212 > I'm thinking about renameing the preprocessor directive to teximg.
213 > \[[!teximg code="" alt="foo"]] makes sense.. Would it make sense to rename
214 > the whole plugin, or do you think that other tex stuff should go in this
215 > same plugin?
216
217 I'll think over this until I'm at work ;) Only for rendering images... not for generating .tex files .../wiki/
218 the name is all the same i think. If you like teximg better than switch :)
219
220
221 > Note: I removed the style= attribute, since as I've told you, the
222 > htmlsanitizer strips those since they can be used to insert javascript. I
223 > put in a class=teximage instead; the style sheet could be modified to
224 > style that, if you want to send a patch for that.
225
226 Ah yes.. sorry forgot to update the plugin in my public_html folder %-). This was my last change in this plugin :) Sorry.
227
228
229
230 > --[[Joey]]
231
232 [[!tag soc]]
233 [[!tag wishlist]]