doc/todo/transient_pages.mdwn

   1 On [[todo/auto-create_tag_pages_according_to_a_template]], [[chrysn]]
   2 suggests:
   3
   4 > Instead of creating a file that gets checked in into the RCS, the
   5 > source files could be left out and the output files be written as
   6 > long as there is no physical source file (think of a virtual underlay).
   7 > Something similar would be required to implement alias directive,
   8 > which couldn't be easily done by writing to the RCS as the page's
   9 > contents can change depending on which other pages claim it as an alias.
  10
  11 `add_autofile` could be adapted to do this, or a similar API could be
  12 added.
  13
  14 This would also be useful for autoindex, as suggested on
  15 [[plugins/autoindex/discussion]]. I'd also like to use it for
  16 [[plugins/contrib/album]].
  17
  18 One refinement I'd suggest is that if the transient page is edited,
  19 its transient contents are evaluated and used as the initial
  20 content for the edit box; after that, it'd become a static page. --[[smcv]]
  21
  22 --------------------------
  23
  24 [[!template id=gitbranch branch=smcv/ready/transient author="[[smcv]]"]]
  25 [[!tag patch]]
  26
  27 I think this branch is now enough to be useful. It adds the following:
  28
  29 If the `transient` plugin is loaded, `$srcdir/.ikiwiki/transient` is added
  30 as an underlay.
  31
  32 Pages with the default extension in the transient underlay are automatically
  33 deleted if a page of the same name is created in the srcdir (or an underlay
  34 closer to the srcdir in stacking order).
  35
  36 `tag` enables `transient`, and if `tag_autocreate_commit` is set to 0
  37 (default 1), autocreated tags are written to the transient underlay.
  38
  39 `autoindex` uses autofiles. It also enables `transient`, and if
  40 `autoindex_commit` is set to 0 (default 1), autoindexes are written to
  41 the transient underlay.
  42
  43 autoindex ignores pages in the transient underlay when deciding whether
  44 to generate an index.
  45
  46 Not done yet:
  47
  48 `remove` can't remove transient pages: this turns out to be harder than
  49 I'd hoped, because I don't want to introduce a vulnerability in the
  50 non-regular-file detection...
  51
  52 Transient tags that don't match any pages aren't deleted: I'm not sure
  53 that that's a good idea anyway, though. Similarly, transient autoindexes
  54 of directories that become empty aren't deleted.
  55
  56 Recent changes and aggregated files could conceivably go in the transient
  57 underlay too.
  58
  59 > I can confirm that the behavior of autoindex, at least, is excellent.
  60 > Haven't tried tag. Joey, can you merge transient and autoindex? --JoeRayhawk
  61
  62 --------------------------
  63
  64 ## An earlier version
  65
  66 I had a look at implementing this. It turns out to be harder than I thought
  67 to have purely in-memory pages (several plugins want to be able to access the
  68 source file as a file), but I did get this proof-of-concept branch
  69 to write tag and autoindex pages into an underlay.
  70
  71 This loses the ability to delete the auto-created pages (although they don't
  72 clutter up git this way, at least), and a lot of the code in autoindex is
  73 probably now redundant, so this is probably not quite ready for merge, but
  74 I'd welcome opinions.
  75
  76 Usage: set `tag_underlay` and/or `autoindex_underlay` to an absolute path,
  77 which you must create beforehand. I suggest *srcdir* + `/.ikiwiki/transient`.
  78
  79 Refinements that could be made if this approach seems reasonable:
  80
  81 * make these options boolean, and have the path always be `.ikiwiki/transient`
  82 * improve the `remove` plugin so it also deletes from this special underlay
  83
  84 >> Perhaps it should be something more generic, so that other plugins could use it (such as "album" mentioned above).
  85 >> The `.ikiwiki/transient` would suit this, but instead of saying "tag_underlay" or "autoindex_underlay" have "use_transient_underlay" or something like that?
  86 >> Or to make it more flexible, have just one option "transient_underlay" which is set to an absolute path, and if it is set, then one is using a transient-underlay.
  87 >> --[[KathrynAndersen]]
  88
  89 >>> What I had in mind was more like `tag_autocreate_transient => 1` or
  90 >>> `autoindex_transient => 1`; you might conceivably want tags to be
  91 >>> checked in but autoindices to be transient, and it's fine for each
  92 >>> plugin to make its own decision. Going from that to one boolean
  93 >>> (or just always-transient if people don't think that's too
  94 >>> astonishing) would be trivial, though.
  95 >>>
  96 >>> I don't think relocating the transient underlay really makes sense,
  97 >>> except for prototyping: you only want one, and `.ikiwiki` is as good
  98 >>> a place as any (ikiwiki already needs to be able to write there).
  99 >>>
 100 >>> For [[plugins/contrib/album]] I think I'd just make the photo viewer
 101 >>> pages always-transient - you can always make a transient page
 102 >>> permanent by editing it, after all.
 103 >>>
 104 >>> Do you think this approach has enough potential that I should
 105 >>> continue to hack on it? Any thoughts on the implementation? --[[smcv]]
 106
 107 >>>> Ah, now I understand what you're getting at. Yes, it makes sense to put transient pages under `.ikiwiki`.
 108 >>>> I haven't looked at the code, but I'd be interested in seeing whether it's generic enough to be used by other plugins (such as `album`) without too much fuss.
 109 >>>> The idea of a transient underlay gives us a desirable feature for free: that if someone edits the transient page, it is made permanent and added to the repository.
 110 >>>>
 111 >>>> I think the tricky thing with removing these transient underlay pages is the question of how to prevent whatever auto-generated the pages in the first place from generating them again - or, conversely, how to force whatever auto-generated those pages to regenerate them if you've changed your mind.
 112 >>>> I think you'd need something similar to `will_render` so that transient pages would be automatically removed if whatever auto-generated them is no longer around.
 113 >>>> -- [[KathrynAndersen]]