doc/todo/inline_raw_files.mdwn

   1 [[!template id=gitbranch branch=wtk/raw_inline author="[[wtk]]"]]
   2
   3 summary
   4 =======
   5
   6 Extend inlining to handle raw files (files with unrecognized extensions).
   7
   8 Also raise an error in `IkiWiki::pagetype($file)` if `$file` is blank, which avoids trying to do much with missing files, etc.
   9
  10 I'm using the new code in my [blog][].
  11
  12 [blog]: http://blog.tremily.us/posts/yacc2dot/
  13
  14 usage
  15 =====
  16
  17     \[[!inline pagenames="somefile.txt" template="raw" feeds="no"]]
  18
  19
  20 > But inline already supports raw files in two ways:
  21 >
  22 > * setting raw=yes will cause a page to be inlined raw without
  23 >   using any template, as if it were part of the page at the location
  24 >   of the inline
  25 > * otherwise, the file becomes an enclosure in the rss feed, for use with
  26 >    podcasting.
  27 >
  28 > So I don't see the point of your patch. Although since your text
  29 > editor seems to like to make lots of whitespace changes, it's possible
  30 > I missed something in the large quantity of noise introduced by it.
  31 > --[[Joey]]
  32
  33 >> As I understand it, setting `raw=yes` causes the page to be inlined
  34 >> as if the page contents had appeared in place of the directive.  The
  35 >> content is then processed by whatever `htmlize()` applies to the
  36 >> inlining page.  I want the inlined page to be unprocessed, and
  37 >> wrapped in `<pre><code>...</code></pre>` (as they are on the blog
  38 >> post I link to above).
  39 >>
  40 >> Enclosures do not include the page contents at all, just a link to
  41 >> them.  I'm trying to inline the content so I can comment on it from
  42 >> the inlining page.
  43 >>
  44 >> Apologies for my cluttered version history, I should have branched my
  45 >> earlier changes off to make things clearer.  I tried to isolate my
  46 >> whitespace changes (fixes?) in c9ae012d245154c3374d155958fcb0b60fda57ce.
  47 >> 157389355d01224b2d3c3f6e4c1eb42a20ec8a90 should hold all the content
  48 >> changes.
  49 >>
  50 >> A list of other things globbed into my master branch that should have
  51 >> been separate branches:
  52 >>
  53 >> * Make it easy to select a Markdown executable for mdwn.pm.
  54 >> * Included an updated form of
  55 >>   [[Javier Rojas' linktoimgonly.pm|forum/link_to_an_image_inside_the_wiki_without_inlining_it]].
  56 >> * Included an updated form of
  57 >>   [Jason Blevins' mdwn_itex.pm](http://jblevins.org/git/ikiwiki/plugins.git/plain/mdwn_itex.pm).
  58 >> * Assorted minor documentation changes.
  59 >>
  60 >> --[[wtk]]
  61
  62 >>> I haven't heard anything in a while, so I've reorganized my version
  63 >>> history and rebased it on the current ikiwiki head.  Perhaps now it
  64 >>> will be easier to merge or reject.  Note the new branch name:
  65 >>> `raw_inline`. I'll open separate todo items for items mentioned in my
  66 >>> previous comment. --[[wtk]]
  67
  68 ----
  69
  70 Reviewing your patch the first thing I see is this:
  71
  72 <pre>
  73 +        if (! $file) {
  74 +               error("Missing file.");
  75 +        }
  76 </pre>
  77
  78 This fails if the filename is "0". Also, `pagetype()`
  79 currently cannot fail; allowing it to crash the entire
  80 wiki build if the filename is somehow undefined seems
  81 unwise.
  82
  83 I didn't look much further, because it seems to me what you're trying to do
  84 can be better accomplished by using the highlight plugin. Assuming the raw
  85 file you want to inline and comment on is some source-code-like thing,
  86 which seems likely.
  87
  88 Or, another way to do it would be to use the templates plugin, and make
  89 a template there that puts an inline directive inside pre tags.
  90  --[[Joey]] [[!tag reviewed]]
  91
  92 ----
  93
  94 If `pagetype()` cannot fail, then I suppose that check has to go ;).
  95
  96 I was under the impression that [[plugins/highlight]] didn't support
  97 inlining code.  It looks like it supports highlighing stand-alone
  98 files or embedded code.  Perhaps I should extend it to support inlined
  99 code instead of pushing this patch?
 100
 101 > If you configure highlight to support standalone files, then you can
 102 > inline the resulting pages and get nicely highlighted source code
 103 > inlined into the page. --[[Joey]]
 104
 105 The `raw.tmpl` included in the patch *does* include the inlined
 106 content inside `pre` tags.  The problem is that the current inline
 107 code insists on running `htmlize()` on the content before inserting it
 108 in the template.  The heart of my patch is an altered
 109 `get_inline_content()` that makes the `htmlize()` call dependent on a
 110 `$read_raw` flag.  If the flag is set, the raw (non-htmlized) content
 111 is used instead.
 112
 113 I just rebased my patches against the current Ikiwiki trunk (no major
 114 changes) to make them easier to review.
 115  --[[wtk]]