summaryrefslogtreecommitdiff
path: root/doc/todo/format_escape.mdwn
blob: 315b2d88f1631d11b32349fa7ea602192352e7f9 (plain)

Since some preprocessor directives insert raw HTML, it would be good to specify, per-format, how to pass HTML so that it goes through the format OK. With Markdown we cross our fingers; with reST we use the "raw" directive.

I added an extra named parameter to the htmlize hook, which feels sort of wrong, since none of the other hooks take parameters. Let me know what you think. --Ethan

Seems fairly reasonable, actually. Shouldn't the $type come from $page instead of $destpage though? Only other obvious change is to make the escape parameter optional, and only call it if set. --[[Joey]]

I couldn't figure out what to make it from, but thinking it through, yeah, it should be $page. Revised patch follows. --Ethan

I've updated the patch some more, but I think it's incomplete. ikiwiki emits raw html when expanding WikiLinks too, and it would need to escape those. Assuming that escaping html embedded in the middle of a sentence works.. --[[Joey]]

Revised again. I get around this by making another hook, htmlescapelink, which is called to generate links in whatever language. In addition, it doesn't (can't?) generate spans, and it doesn't handle inlineable image links. If these were desired, the approach to take would probably be to use substitution definitions, which would require generating two bits of code for each link/html snippet, and putting one at the end of the paragraph (or maybe the document?). To specify that (for example) Discussion links are meant to be HTML and not rst or whatever, I added a "genhtml" parameter to htmllink. It seems to work -- see http://ikidev.betacantrips.com/blah.html for an example. --Ethan

Alternative solution

Here is a patch largely inspired from the one below, which is up to date and written with [[todo/multiple_output_formats]] in mind. "htmlize" hooks are generalized to "convert" ones, which can be registered for any pair of filename extensions.

Preprocessor directives are allowed to return the content to be inserted as a hash, in any format they want, provided they provide htmlize hooks for it. Pseudo filename extensions (such as "_link") can also be introduced, which aren't used as real extensions but provide useful intermediate types.

--[[JeremieKoenig]]

Wow, this is in many ways a beautiful patch. I did notice one problem, if a link is converted to rst and then from there to a hyperlink, the styling info usially added to such a link is lost. I wonder if it would be better to lose _link stuff and just create link html that is fed into the rst,html converter. Other advantage to doing that is that link creation has a rather complex interface, with selflink, attrs, url, and content parameters.

--[[Joey]]

Thanks for the compliment. I must confess that I'm not too familiar with rst. I am using this todo item somewhat as a pretext to get the conversion stuff in, which I need to implement some other stuff. As a result I was less careful with the rst plugin than with the rest of the patch. I just updated the patch to fix some other problems which I found with more testing, and document the current limitations.

Rst cannot embed raw html in the middle of a paragraph, which is why "_link" was necessary. Rst links are themselves tricky and can't be made to work inside of words without knowledge about the context. Both problems could be fixed by inserting marks instead of the html/link, which would be replaced at a later stage (htmlize, format), somewhat similiar to the way the toc plugin works. When I get more time I will try to fix the remaining glitches this way.

Also, I think it would be useful if ikiwiki had an option to export the preprocessed source. This way you can use docutils to convert your rst documents to other formats. Raw html would be loosed in such a process (both with directives and marks), which is another argument for "_link" and other intermediate forms. I think I can come up with a way for rst's convert_link to be used only for export purposes, though.

--[[JeremieKoenig]]

Another problem with this approach is when there is some html (say a table), that contains a wikilink. If the link is left up to the markup lamguage to handle, it will never convert it to a link, since the table will be processed as a chunk of raw html. --[[Joey]]

Updated patch

I've created an updated patch against the current revision. No real functionality changes, except for a small test script, one minor bugfix (put a "join" around a scalar-context "map" in convert_link), and some wrangling to get it merged properly; I thought it might be helpful for anyone else who wants to work on the code.

(With that out of the way, I think I'm going to take a stab at Jeremie's plan to use marks which would be replaced post-htmlization. I've also got an eye towards [[todo/multiple_output_formats]].)

--Ryan Koppenhaver

Original patch

[[!tag patch]]