more html5
[ikiwiki] / doc / users / jasonblevins.mdwn
1 [[!meta title="Jason Blevins"]]
2
3 I'm currently hosting a private ikiwiki for keeping research notes
4 which, with some patches and a plugin (below), will
5 convert inline [[todo/LaTeX]] expressions to [[MathML]].  I'm working towards a
6 patchset and instructions for others to do the same.
7
8 I've setup a test ikiwiki [here](http://xbeta.org/colab/) where I've
9 started keeping a few notes on my progress.  There is an example of
10 inline [[todo/SVG]] on the homepage (note that the logo scales along with the
11 font size).  There are a few example mathematical expressions in the
12 [sandbox](http://xbeta.org/colab/sandbox/).  The MathML is generated
13 automatically from inline LaTeX expressions using an experimental
14 plugin I'm working on.
15
16 My (also MathML-enabled) homepage: <http://jblevins.org/> (still using
17 Blosxom...maybe one day I'll convert it to ikiwiki...)
18
19 Current ikiwki issues of interest:
20
21  * [[bugs/recentchanges_feed_links]]
22  * [[bugs/HTML_inlined_into_Atom_not_necessarily_well-formed]]
23  * [[plugins/toc/discussion]]
24  * [[todo/BibTeX]]
25  * [[todo/svg]]
26  * [[todo/Option_to_make_title_an_h1?]]
27  * [[bugs/SVG_files_not_recognized_as_images]]
28
29 ## Plugins
30
31 These plugins are experimental.  Use them at your own risk.  Read the
32 perldoc documentation for more details.  Patches and suggestions are
33 welcome.
34
35  * [mdwn_itex][] - Works with the [[`mdwn`|plugins/mdwn]] plugin to convert inline [[todo/LaTeX]]
36    expressions to [[MathML]] using `itex2MML`.
37
38  * [h1title][] - If present, use the leading level 1 Markdown header to
39    set the page title and remove it from the page body.
40
41  * [code][] - Whole file and inline code snippet [[todo/syntax highlighting]]
42    via GNU Source-highlight.  The list of supported file extensions is
43    configurable.  There is also some preliminary [documentation][code-doc].
44    See the [FortranWiki](http://fortranwiki.org) for examples.
45
46  * [metamail][] - a plugin for loading metadata from [[email]]-style
47    headers at top of a file (e.g., `title: Page Title` or
48    `date: November 2, 2008 11:14 EST`).
49
50  * [pandoc][] - [[ikiwiki/Markdown]] page processing via [Pandoc](http://johnmacfarlane.net/pandoc/) (a Haskell library for converting from one markup format to another).  [[todo/LaTeX]] and
51    [[reStructuredText|plugins/rst]] are optional.
52
53  * [path][] - Provides path-specific template conditionals such as
54    `IS_HOMEPAGE` and `IN_DIR_SUBDIR`.
55
56  [mdwn_itex]: http://code.jblevins.org/ikiwiki/plugins.git/plain/mdwn_itex.pm
57  [h1title]: http://code.jblevins.org/ikiwiki/plugins.git/plain/h1title.pm
58  [code]: http://code.jblevins.org/ikiwiki/plugins.git/plain/code.pm
59  [code-doc]: http://code.jblevins.org/ikiwiki/plugins.git/plain/code.text
60  [metamail]: http://code.jblevins.org/ikiwiki/plugins.git/plain/metamail.pm
61  [pandoc]: http://code.jblevins.org/ikiwiki/plugins.git/plain/pandoc.pm
62  [path]: http://code.jblevins.org/ikiwiki/plugins.git/plain/path.pm
63
64
65 ## MathML and SVG support
66
67 So far, I've made some notes on sanitizing MathML and SVG via
68 htmlscrubber on the [[todo/svg]] todo item.
69
70 I've also worked out some content-negotiation issues.  First of all,
71 one needs to modify the default templates to use the
72 XHTML+MathML+SVG doctype (see e.g., this [patch][template-patch]).
73 For most browsers, the content type of the pages should be
74 `application/xhtml+xml`.  The solution is easy if you want to
75 just send `application/xhtml+xml` to everybody:
76 just change the content type of `.html` files across the board.
77
78 However, if you want to support browsers that don't accept
79 `application/xhtml+xml` (and those that will but say they
80 don't, such as IE with the MathPlayer plugin), then one
81 needs a `mod_rewrite` rule like the following:
82
83     RewriteCond %{HTTP_ACCEPT} application\/xhtml\+xml [OR]
84     RewriteCond %{HTTP_USER_AGENT} (W3C.*Validator|MathPlayer)
85     RewriteRule \.html$ - [T=application/xhtml+xml]
86
87 This solves the problem of MathML and inline SVG in static pages
88 but some additional work is required for dynamically generated
89 pages, like page previews, that are generated by `ikiwiki.cgi`.
90 We need to allow `ikiwiki.cgi` to set the content type dynamically
91 based on the `HTTP_CONTENT_TYPE` environment variable
92 (e.g., with the following [patch][cgi-patch]).  Then, the following
93 rewrite rules can pass the correct content type to ikiwiki:
94
95     RewriteCond %{HTTP_ACCEPT} application\/xhtml\+xml [OR]
96     RewriteCond %{HTTP_USER_AGENT} (W3C.*Validator|MathPlayer)
97     RewriteRule ikiwiki.cgi$ - [T=application/xhtml+xml]
98
99 One final critical issue is that a production-ready setup needs to
100 implement some sort of on-the-fly error handling.  If a user submits
101 an invalid LaTeX expression or SVG code (not malicious, just invalid)
102 and saves the page, then browsers like Firefox will halt processing of
103 the page, preventing any further viewing or editing.  A less than
104 optimal solution is to force users to preview the page before saving.
105 That way if someone introduces invalid XHTML then they can't save the
106 page in the first place (unless they post directly to the right URL).
107
108  [template-patch]: http://xbeta.org/gitweb/?p=xbeta/ikiwiki.git;a=blobdiff;f=templates/page.tmpl;h=380ef699fa72223744eb5c1ee655fb79aa6bce5b;hp=9084ba7e11e92a10528b2ab12c9b73cf7b0f40a7;hb=416d5d1b15b94e604442e4e209a30dee4b77b684;hpb=ececf4fb8766a4ff7eff943b3ef600be81a0df49
109  [cgi-patch]: http://xbeta.org/gitweb/?p=xbeta/ikiwiki.git;a=commitdiff;h=fa538c375250ab08f396634135f7d79fce2a9d36